view release on metacpan or  search on metacpan

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

Lingering transactions
----------------------

If you need to increase performance, you can use lingering transactions. In
this mode, transactions take up more disk space but allows you to do the
synchronous write only once, making commits much faster. To use them, just add
*J_LINGER* to the *jflags* parameter in *jopen()*. You should call *jsync()*
frequently to avoid using up too much space, or start an asynchronous thread
that calls *jsync()* automatically using *jfs_autosync_start()*. Note that
files opened with this mode must not be opened by more than one process at the
same time.


Disk layout
-----------

The library creates a single directory for each file opened, named after it.
So if we open a file *output*, a directory named *.output.jio* will be
created. We call it the journal directory, and it's used internally by the
library to save temporary data; **you shouldn't modify any of the files that
are inside it, nor move it while it's in use**.

It doesn't grow much (it only uses space for transactions that are in the
process of committing) and gets automatically cleaned while working with it so
you can (and should) ignore it. Besides that, the file you work with has no
special modification and is just like any other file, all the internal stuff
is kept isolated on the journal directory.


ANSI C alike API
----------------

Besides the UNIX-alike API you can find an ANSI C alike API, which emulates
the traditional *fread()*, *fwrite()*, etc. It's still in development and has
not been tested carefully, so I won't spend time documenting them. Let me know
if you need them.


Compiling and linking
---------------------

If you have *pkg-config* in your build environment, then you can get the build
flags you need to use when building and linking against the library by
running::

  pkg-config --cflags --libs libjio

If *pkg-config* is not available, you have to make sure your application uses
the Large File Support (*"LFS"* from now on), to be able to handle large files
properly. This means that you will have to pass some special standard flags to
the compiler, so your C library uses the same data types as the library. For
instance, on 32-bit platforms (like x86), when using LFS, offsets are usually
64 bits, as opposed to the usual 32.

The library is always built with LFS; however, linking it against an
application without LFS support could lead to serious problems because this
kind of size differences and ABI compatibility.

The Single Unix Specification standard proposes a simple and practical way to
get the flags you need to pass your C compiler to tell you want to compile
your application with LFS: use a program called "getconf" which should be
called like "getconf LFS_CFLAGS", and it outputs the appropiate parameters.

In the end, the command line would be something like::

  gcc `getconf LFS_CFLAGS` app.c -ljio -o app

If you want more detailed information or examples, you can check out how the
library and sample applications get built.


Where to go from here
---------------------

If you're still interested in learning more, you can find some small and clean
samples are in the *samples* directory (*full.c* is a simple and complete
one), other more advanced examples can be found in the web page, as well as
modifications to well known software to make use of the library. For more
information about the inner workings of the library, you can read the "libjio"
document, the internal API reference, and the source code.