view release on metacpan or  search on metacpan

libjio/doc/libjio.rst  view on Meta::CPAN

simultaneous operations (either across threads or processes). They are
described in detail in the manual pages, we'll only list them here for
completion:

 - jopen()
 - jread(), jpread(), jreadv()
 - jwrite(), jpwrite(), jwritev()
 - jtruncate()
 - jclose()


ACID warranties
---------------

Database people like ACID (well, that's not news for anybody), which they say
mean "Atomicity, Consistency, Isolation, Durability".

So, even when libjio is not a purely database thing, its transactions provide
those properties. Let's take a look one by one:

Atomicity
  In a transaction involving two or more discrete pieces of information,
  either all of the pieces are committed or none are. This has been talked
  before and we've seen how the library achieves this point, mostly based on
  locks and relying on a commit procedure.

Consistency
  A transaction either creates a new and valid state of data, or, if any
  failure occurs, returns all data to its state before the transaction was
  started. This, like atomicity, has been discussed before, specially in the
  recovery section, when we saw how in case of a crash we end up with a fully
  applied transaction, or no transaction applied at all.

Isolation
  A transaction in process and not yet committed must remain isolated from any
  other transaction. This comes as a side effect of doing proper locking on
  the sections each transaction affect, and guarantees that there can't be two
  transactions working on the same section at the same time.

Durability
  Committed data is saved by the system such that, even in the event of a
  failure, the data is available in a correct state. To provide this, libjio
  relies on the disk as a method of permanent storage, and expects that when
  it does syncronous I/O, data is safely written and can be recovered after a
  crash.


Working from outside
--------------------

If you want, and are careful enough, you can safely use the library and still
do I/O using the regular UNIX calls.

This section provides some general guidelines that you need to follow in order
to prevent corruption. Of course you can bend or break them according to your
use, this is just a general overview on how to interact from outside.

 - Lock the sections you want to use: the library, as we have already exposed,
   relies on fcntl() locking; so, if you intend to operate on parts on the
   file while using it, you should lock them.
 - Don't truncate, unlink or rename: these operations have serious
   implications when they're done while using the library, because the library
   itself assumes that names don't change, and files don't disappear from
   underneath it. It could potentially lead to corruption, although most of
   the time you would just get errors from every call.