Various documentation updates. Many of them thanks to Shehjar Tikoo. --- cur-root/doc/guide.lyx | 37 +++++++++++++++++++++++++++++++++++++ cur-root/doc/guide.txt | 28 ++++++++++++++++++++++++++-- cur-root/doc/libjio.3 | 20 ++++++++++++-------- cur-root/doc/libjio.lyx | 26 +++++++++++++------------- cur-root/doc/libjio.txt | 34 +++++++++++++++++----------------- 5 files changed, 105 insertions(+), 40 deletions(-) diff -puN doc/libjio.lyx~doc_updates doc/libjio.lyx --- cur/doc/libjio.lyx~doc_updates 2004-08-30 00:51:59.220321208 -0300 +++ cur-root/doc/libjio.lyx 2004-08-30 00:51:59.229319840 -0300 @@ -106,23 +106,23 @@ Inside, there are two kind of files: the The first one is used as a general lock and holds the next transaction ID to assign, and there is only one; the second one holds one transaction, which is composed by a header of fixed size and a variable-size payload, - and can be as many as in-flight transactions. + and can be as many as the number of in-flight transactions. \layout Standard -This impose some restrictions to the kind of operations you can perform +This imposes some restrictions on the kind of operations you can perform over a file while it's currently being used: you can't move it (because the journal directory name depends on the filename) and you can't unlink it (for similar reasons). \layout Standard -This warnings are no different from a normal simultaneous use under classic - UNIX environments, but they are here to remind you that even tho the library - warantees a lot and eases many things from its user (specially from complex - cases, like multiple threads using the file at the same time), you should - still be careful when doing strange things with files while working on - them. +These warnings are no different from a normal simultaneous use under classic + UNIX environments, but they are here to remind you that even though the + library warantees a lot and eases many things for its user (specially from + complex cases, like multiple threads using the file at the same time), + you should still be careful when doing strange things with files while + working on them. \layout Subsection @@ -137,8 +137,8 @@ The header holds basic information about the ID, some flags, and the amount of operations it includes. Then the payload has all the operations one after the other, divided in two parts: the first one includes static information about the operation - (the lenght of the data, the offset of the file where it should be applied, - etc.) and the data itself, which is saved by the library prior applying + (the length of the data, the offset of the file where it should be applied, + etc.) and the data itself, which is saved by the library prior to applying the commit, so transactions can be reapplied if necesary. The last part is just a 32 bit integer with the checksum of all the previous data, used for integrity verification during the recovery process. @@ -192,15 +192,15 @@ jtrans_commit() : \layout Itemize -Lock the file offsets where the commit takes place -\layout Itemize - Open the transaction file \layout Itemize Write the header \layout Itemize +Lock the file offsets where the commit takes place +\layout Itemize + Read all the previous data from the file \layout Itemize diff -puN doc/libjio.txt~doc_updates doc/libjio.txt --- cur/doc/libjio.txt~doc_updates 2004-08-30 00:51:59.221321056 -0300 +++ cur-root/doc/libjio.txt 2004-08-30 00:51:59.229319840 -0300 @@ -71,22 +71,22 @@ lock and holds the next transaction ID t there is only one; the second one holds one transaction, which is composed by a header of fixed size and a variable-size payload, and can be as many as -in-flight transactions. +the number of in-flight transactions. -This impose some restrictions to the kind of operations -you can perform over a file while it's currently being -used: you can't move it (because the journal directory -name depends on the filename) and you can't unlink it -(for similar reasons). +This imposes some restrictions on the kind of +operations you can perform over a file while it's +currently being used: you can't move it (because the +journal directory name depends on the filename) and you +can't unlink it (for similar reasons). -This warnings are no different from a normal +These warnings are no different from a normal simultaneous use under classic UNIX environments, but -they are here to remind you that even tho the library -warantees a lot and eases many things from its user -(specially from complex cases, like multiple threads -using the file at the same time), you should still be -careful when doing strange things with files while -working on them. +they are here to remind you that even though the +library warantees a lot and eases many things for its +user (specially from complex cases, like multiple +threads using the file at the same time), you should +still be careful when doing strange things with files +while working on them. 2.1 The transaction file @@ -98,9 +98,9 @@ transaction itself, including the ID, so the amount of operations it includes. Then the payload has all the operations one after the other, divided in two parts: the first one includes static information -about the operation (the lenght of the data, the offset +about the operation (the length of the data, the offset of the file where it should be applied, etc.) and the -data itself, which is saved by the library prior +data itself, which is saved by the library prior to applying the commit, so transactions can be reapplied if necesary. The last part is just a 32 bit integer with the checksum of all the previous data, used for @@ -134,12 +134,12 @@ Well, so much for talking, now let's get applies commits in a very simple and straightforward way, inside jtrans_commit(): -* Lock the file offsets where the commit takes place - * Open the transaction file * Write the header +* Lock the file offsets where the commit takes place + * Read all the previous data from the file * Write the data in the transaction diff -puN doc/guide.lyx~doc_updates doc/guide.lyx --- cur/doc/guide.lyx~doc_updates 2004-08-30 00:51:59.223320752 -0300 +++ cur-root/doc/guide.lyx 2004-08-30 00:51:59.230319688 -0300 @@ -482,6 +482,43 @@ jiofsck , which can be used from the shell to perform the checking and cleanup. \layout Subsection +Threads and locking +\layout Standard + +The library is completely safe to use in multithreaded applications; however, + there are some very basic and intuitive locking rules you have to bear + in mind. +\layout Standard + +Most is fully threadsafe so you don't need to worry about concurrency; in + fact, a lot of effort has been put in making paralell operation safe and + fast. +\layout Standard + +You need to care only when opening, closing and checking for integrity. + In practise, that means that you shouldn't call +\family typewriter +jopen() +\family default +, +\family typewriter +jclose() +\family default + in paralell with the same jfs structure, or in the middle of an I/O operation, + just like you do when using the normal UNIX calls. + In the case of +\family typewriter +jfsck() +\family default +, you shouldn't invoke it for the same file more than once at the time; + while it will cope with that situation, it's not recommended. +\layout Standard + +All other operations (commiting a transaction, rollbacking it, adding operations +, etc.) and all the wrappers are safe and don't require any special consideration +s. +\layout Subsection + Lingering transactions \layout Standard diff -puN doc/guide.txt~doc_updates doc/guide.txt --- cur/doc/guide.txt~doc_updates 2004-08-30 00:51:59.224320600 -0300 +++ cur-root/doc/guide.txt 2004-08-30 00:51:59.230319688 -0300 @@ -12,7 +12,8 @@ Table of Contents 5.1 Interaction with reads 5.2 Rollback 5.3 Integrity checking and recovery - 5.4 Lingering transactions + 5.4 Threads and locking + 5.5 Lingering transactions 6 Disk layout 7 Other APIs 7.1 UNIX API @@ -234,7 +235,30 @@ You can also do this manually with an ut jiofsck, which can be used from the shell to perform the checking and cleanup. -5.4 Lingering transactions +5.4 Threads and locking + +The library is completely safe to use in multithreaded +applications; however, there are some very basic and +intuitive locking rules you have to bear in mind. + +Most is fully threadsafe so you don't need to worry +about concurrency; in fact, a lot of effort has been +put in making paralell operation safe and fast. + +You need to care only when opening, closing and +checking for integrity. In practise, that means that +you shouldn't call jopen(), jclose() in paralell with +the same jfs structure, or in the middle of an I/O +operation, just like you do when using the normal UNIX +calls. In the case of jfsck(), you shouldn't invoke it +for the same file more than once at the time; while it +will cope with that situation, it's not recommended. + +All other operations (commiting a transaction, +rollbacking it, adding operations, etc.) and all the +wrappers are safe and don't require any special considerations. + +5.5 Lingering transactions If you need to increase performance, you can use lingering transactions. In this mode, transactions take diff -puN doc/libjio.3~doc_updates doc/libjio.3 --- cur/doc/libjio.3~doc_updates 2004-08-30 00:51:59.226320296 -0300 +++ cur-root/doc/libjio.3 2004-08-30 01:30:31.226824232 -0300 @@ -20,6 +20,8 @@ libjio - A library for Journaled I/O .BI "ssize_t jwritev(struct jfs *" fs ", const struct iovec *" vector ", int " count " ); +.BI "off_t jlseek(struct jfs *" fs ", off_t " offset ", int " whence " );" + .BI "int jtruncate(struct jfs *" fs ", off_t " lenght " ); .BI "int jsync(struct jfs *" fs " ); @@ -38,7 +40,7 @@ libjio - A library for Journaled I/O .BI "int jfsck(const char *" name ", struct jfsck_result *" res " ); -.BI "int jfsck_cleanup(const char *" name" );" +.BI "int jfsck_cleanup(const char *" name" ); .SH STRUCTURES .PP @@ -48,9 +50,7 @@ libjio - A library for Journaled I/O struct jfs { int fd; /* main file descriptor */ char *name; /* and its name */ - int jfd; /* journal's lock file descriptor */ int flags; /* journal mode options used in jopen() */ - pthread_mutex_t lock; /* a soft lock used in some operations */ ... }; .FI @@ -123,9 +123,12 @@ jfsck_cleanup(). The first one, jfsck(), is used to perform journal checking and recovery in case of a crash. It must be performed when nobody else is using the file (like in the case of a filesystem which can't be mounted), and it returns 0 if -success or -1 in case of a failure. If it succeed, a structure jfsck_result -that summarizes the outcome of the operation. There is also a program named -jiofsck which is just a simple human frontend to this function. +success or a positive number indicating the error in case of a failure. If it +succeed, a structure jfsck_result that summarizes the outcome of the +operation. There is also a program named jiofsck which is just a simple human +frontend to this function. The error values can be J_ENOENT (No such file), +J_ENOJOURNAL (No journal associated with the file), and J_ENOMEM (not enough +free memory). The second, jfsck_cleanup(), is intended to be used after jfsck() by programs wanting to remove all the stall transaction files and leave the journal @@ -137,8 +140,9 @@ if it succeeded. .SH UNIX API The UNIX API, as explained before, consists of the functions jread(), -jpread(), jreadv(), jwrite(), jpwrite(), jwritev(), jtruncate(). In most cases -you will only need to use this, because they're simple and familiar. +jpread(), jreadv(), jwrite(), jpwrite(), jwritev(), jtruncate() and jlseek(). +In most cases you will only need to use this, because they're simple and +familiar. They are all exactly like the UNIX equivalent (if you still don't get it, take the initial 'j' out), and behave the same way, with the only exception that _