The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
IO-Journal-0.2
River stage zero No dependents
++
/ IO::Journal

NAME

IO::Journal - Perl module providing durable transaction-oriented I/O

VERSION

Version 0.2 ($Id: Journal.pm 8239 2009-07-26 03:28:55Z FREQUENCY@cpan.org $)

DESCRIPTION

To ensure reliability, some file systems and databases provide support for something known as journalling. The idea is to ensure data consistency by creating a log of actions to be taken (called a Write Ahead Log) before committing them to disk. That way, if a transaction were to fail due to a system crash or other unexpected event, the write ahead log could be used to finish writing the data.

While this functionality is often available with networked databases, it can be a rather memory- and processor-intensive solution, even where reliable writes are important. In other cases, the filesystem does not provide native journalling support, so other tricks may be used to ensure data integrity, such as writing to a separate temporary file and then overwriting the file instead of modifying it in-place. Unfortunately, this method cannot handle threaded operations appropriately.

Thankfully, Alberto Bertogli published a userspace C library called libjio that can provide these features in a small (less than 1500 lines of code) library with no external dependencies.

NOTICE

This module is currently a preview release. Please, please, PLEASE don't use it for production use yet, until all the kinks have been found and sorted out.

SYNOPSIS

  use IO::Journal;

  my $journal = IO::Journal->open('>', 'filename.txt');

  # Start a new transaction
  my $trans = $journal->begin_transaction();
  $trans->syswrite("Hello");
  $trans->syswrite("World\n");
  $trans->commit;
  # File now contains "Hello World\n"

  $trans->rollback;
  # File is now blank

COMPATIBILITY

This module was tested under Perl 5.10.0, using Debian Linux. It provides some convenience methods similar to IO::Handle, but most of the work is based on libjio, which may be installed automatically during this module's build process through Alien::Libjio.

If you encounter any problems on a different version or architecture, please contact the maintainer.

METHODS

IO::Journal->open( $mode, $filename )

Creates a IO::Journal object on top of libjio's file handle system (an opaque jfs_t struct). This method opens the given file referenced by filename using the given Perl-like mode string, which behaves similarly to Perl's standard open function.

Note that, unlike Perl's open, this method does not support the one-parameter variant where a mode and filename are specified in the same string.

Example code:

  my $journal = IO::Journal->open('>>', 'filename');

This method will return an appropriate IO::Journal::Transaction object or throw an exception on error.

$journal->begin_transaction()

This method starts a new transaction, which is essentially the same as libjio's jtrans_new function. In order to understand how to work with transactions, you'll need to look at IO::Journal::Transaction.

For now, this is really just a nicer way of constructing a new Transaction object, similar in nature to:

  my $trans = IO::Journal::Transaction->new($journal);
  # looks messier & is longer to type than
  my $trans = $journal->begin_transaction();

It returns a newly created IO::Journal::Transaction object, or throws an exception on error.

IO::Journal->sysopen( $filename, $mode, [ $permissions ] )

This function is the same as open, but is instead closer to the usual Unix system call, requiring a set of octal flags (those provided by fcntl.h and exposed to Perl in Fcntl).

As a result, it's much less convenient than using open and doesn't have as much error checking either, since it's implemented completely in XS.

One useful feature of sysopen is that it optionally supports giving an octal specification of permissions to use in case the file doesn't yet exist. By default, new files are created with the permissions 0666 (rw-rw-rw-) but the actual file created will vary based on your running umask.

AUTHOR

Jonathan Yu <frequency@cpan.org>

CONTRIBUTORS

Your name here ;-)

ACKNOWLEDGEMENTS

  • Special thanks to Alberto Bertogli <albertito@blitiri.com.ar> for developing this useful library and for releasing it into the public domain. He was very patient while developing this library, and was always open to new ideas.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc IO::Journal

You can also look for information at:

REPOSITORY

You can access the most recent development version of this module at:

http://svn.ali.as/cpan/trunk/IO-Journal

If you are a CPAN developer and would like to make modifications to the code base, please contact Adam Kennedy <adamk@cpan.org>, the repository administrator. I only ask that you contact me first to discuss the changes you wish to make to the distribution.

FEEDBACK

Please send relevant comments, rotten tomatoes and suggestions directly to the maintainer noted above.

If you have a bug report or feature request, please file them on the CPAN Request Tracker at http://rt.cpan.org. If you are able to submit your bug report in the form of failing unit tests, you are strongly encouraged to do so. Regular bug reports are always accepted and appreciated via the CPAN bug tracker.

SEE ALSO

Alien::Libjio, a Perl module for installing and finding libjio.

http://blitiri.com.ar/p/libjio/, Alberto Bertogli's page about libjio, which explains the purpose and features of libjio.

CAVEATS

I have never developed an IO:: type module before this one, so I'm not completely aware of the interfaces yet. I hope to make it compatible with conventional interfaces like IO::Handle, but I might make a mistake.

KNOWN BUGS

There are no known bugs as of this release.

LICENSE

In a perfect world, I could just say that this package and all of the code it contains is Public Domain. It's a bit more complicated than that; you'll have to read the included LICENSE file to get the full details.

DISCLAIMER OF WARRANTY

The software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.