Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

FileHandle::Rollback
FileHandle with commit, rollback, and journaled crash recovery

FileHandle::Rollback - FileHandle with commit, rollback, and journaled crash recovery


SYNOPSIS


  use FileHandle::Rollback;

  my ($fh);

  

  # open file handle

  $fh = FileHandle::Rollback->new("+< $path")

    or die "cannot open filehandle: $!";

  

  # put some data at a specific address

  $fh->seek(80, 0);

  print $fh '1500';

  

  # read some data, partially including data 

  # that was written in this rollback segment

  $fh->seek(70, 0);

  $fh->read($data, 100);

  

  # if you want to cancel the changes:

  $fh->rollback;

  

  # or, if you want save the changes:

  $fh->commit;


INSTALLATION

FileHandle::Rollback can be installed with the usual routine:


        perl Makefile.PL

        make

        make test

        make install

You can also just copy Rollback.pm into the FileHandle/ directory of one of your library trees.




=head1 DESCRIPTION

FileHandle::Rollback allows you to open a filehandle, write data to that handle, read the data back exactly as if it were already in the file, then cancel the whole transaction if you choose. FileHandle::Rollback works like FileHandle, with a few important differences, most notably the addition of rollback() and commit(). Those additions and differences are noted below.

$fh->rollback()

Cancels all changes since the last rollback, commit, or since you opened the file handle.

$fh->commit()

Writes changes to the file.

$fh->flock($mode)

The flock method locks the file like the built-in flock command. Use the same mode arguments: LOCK_SH, LOCK_EX, and LOCK_UN.


  use Fcntl ':flock';

  

  unless ($fh->flock(LOCK_EX))

    {die "cannot lock filehandle: $!"}

binmode

FileHandle::Rollback only works in binmode, so it will automatically put itself into binmode.

read/write

FileHandle::Rollback only works in read/write mode. Regardless of what you begin the file path with (+<, +>, >, >>, etc) FileHandle::Rollback opens the file with +< . However, if > is anywhere in the path then FileHandle::Rollback will create the file if it doesn't already exist.

autmatic crash recovery

This feature journals the data being written to your file so that if there is a server crash while the data is being written, FileHandle::Rollback automatically finishes the data write. In short, crash recovery protects you against invalid data formats: either all the data is written or none of it is.

To implement crash recovery, simply add the journal option to the new command. journal consists of an anonymous array containing two elements:


 $fh = FileHandle::Rollback->new('members.db', journal=>['members.journal', 'members.sem'])

    or die $!;

The first element is the file name of a ``journal'' file, a file where data is temporarily stored before being written to the real data file. The second element is the file name of a ``semaphore'' file whose existence indicates that data is being written to the data file.

When a FileHandle::Rollback object is created with journaling, the first thing it does is check if the semaphore file exists. If that file does exist, then the object knows that there was a crash the last time the data was being written. The object pulls the stored data from the journal file and tries again to write the data to the data file. Once the data is fully written, it deletes the semaphore and journal files.

This form of crash recovery is dependent on the atomicity of file creation and deletion on your computer, so on some systems (particularly NFS) there is a small chance that crash recovery will not work properly. Caveat programmer.


VERSION


  Version 1.00, June 29, 2002

  First public release

  

  Version 1.01, June 30, 2002

  Minor tweaks to 1.00

  

  Version 1.02, June 30, 2002

  Small but important correction to documentation

  

  Version 1.03, July 1, 2002

  Another small but important correction to documentation.

  

  Version 1.04, July 10, 2002

  Yet another small but important correction to documentation.  Sheesh.

  

  and then a long time went by...

  

  Version 1.05, June 12, 2003

  Added journaled automatic crash recovery




  Version 1.06, July 28, 2007

  No changes to module, changed bogus package for CPAN






=cut





Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy