Provided by: libio-lockedfile-perl_0.23+d030220-5_all bug

NAME

       IO::LockedFile - supply object methods for locking files

SYNOPSIS

         use IO::LockedFile;

         # create new locked file object. $file will hold a file handle.
         # if the file is already locked, the method will not return until the
         # file is unlocked
         my $file = new IO::LockedFile(">locked1.txt");

         # when we close the file - it become unlocked.
         $file->close();

         # suppose we did not have the line above, we can also delete the
         # object, and the file is automatically unlocked and closed.
         $file = undef;

DESCRIPTION

       In its simplistic use, the IO::LockedFile class gives us the same interface of the
       IO::File class with the unique difference that the files we deal with are locked using the
       Flock mechanism (using the "flock" function).

       If during the running of the process, it crashed - the file will be automatically
       unlocked. Actually - if the IO::LockedFile object goes out of scope, the file is
       automatically closed and unlocked.

       So, if you are just interested in having locked files with "flock", you can skip most of
       the documentation below.

       If, on the other hand, you are interested in locking files with other schemes then Flock,
       or you want to control the behavior of the locking (having non blocking lock for example),
       read on.

       Actually the class IO::LockedFile is kind of abstract class.

       Why abstract? Because methods of this class call the methods "lock" and "unlock". But
       those methods are not really implemented in this class.  They suppose to be implemented in
       the derived classes of IO::LockedFile.

       Why "kind" of abstract? Because the constructor of this class will return an object!

       How abstract class can create objects? This is done by having the constructor returning
       object that is actually an object of one of the derived classes of IO::LockedFile.

       So by default the constructor of IO::LockedFile will return an object of
       IO::LockedFile::Flock. For example, the following:

          use IO::LockedFile;
          $lock = new IO::LockedFile(">bla");
          print ref($lock);

       Will give:

          IO::LockedFile::Flock

       So what are the conclusions here?

       First of all - do not be surprised to get object of derived class from the constructor of
       IO::LockedFile.

       Secondly - by changing the default behavior of the constructor of IO::LockedFile, we can
       get object of other class which means that we have a locked file that is locked with other
       scheme.

       The default behavior of the constructor is determined by the global options.

       We can access this global options, or the options per object using the method "set_option"
       and "get_option".

       We can set the global options in the use line:

         use IO::LockedFile 'Flock'; # set the default scheme to be Flock

         use IO::LockedFile ( scheme => Flock );

       We can also set the options of a new object by passing the options to the constructor, as
       we will see below. We can change the options of an existing object by using the
       "set_option" method.

       Which options are available?

       scheme
           The scheme let us define which derived class we use for the object we create.  See
           below which derived classes are available. The default scheme is 'Flock'.

       block
           The block option can be 1 or 0 (true or false). If it is 1, a call to the "open"
           method or to the constructor will be blocked if the file we try to open is already
           locked. This means that those methods will not return till the file is unlocked. If
           the value of the block option is 0, the "open" and the constructor will return
           immediately in any case. If the file is locked, those methods will return undef. The
           default value of the block option is 1.

       lock
           The lock option can be 1 or 0 (true or false). It defines if the file we open when we
           create the object will be opened locked. Sometimes, we want to have a file that can be
           locked, yet we do not want to open it locked from the beginning. For example if we
           want to print into a log file, usually we want to lock that file only when we print
           into it. Yet, it might be that when we open the file in the beginning we do not print
           into it immediately.  In that case we will prefer to open the file as unlocked, and
           later we will lock it when needed. The default value of the lock option is 1.

       There might be extra options that are used by one of the derived classes. So according to
       the scheme you choose to use, please look in the manual page of the class that implement
       that scheme.

       Finally, some information that is connected to a certain scheme will be found in the
       classes that are derived from this class. For example, compatibility issues will be
       discussed in each derived classes.

       The classes that currently implement the interface that IO::LockedFile defines are:

       •   IO::LockedFile::Flock

CONSTRUCTOR

       new ( FILENAME [,MODE [,PERMS]] )
           Creates an object that belong to one of the derived classes of "IO::LockedFile". If it
           receives any parameters, they are passed to the method "open". if the "open" fails,
           the object is destroyed.  Otherwise, it is returned to the caller. The object will be
           the file handle of that opened file.

       new ( OPTIONS, FILENAME [,MODE [,PERMS]] )
           This version of the constructor is the same as above, with the difference that we send
           as the first parameter a reference to a hash - OPTIONS. This hash let us change for
           this object only, the options from the default options. So for example if we want to
           change the lock option from its default we can do it as follow:
             $file = new IO::LockedFile( { lock => 0 },
                                         ">locked_later.txt" );

METHODS

       open ( FILENAME [,MODE [,PERMS]] )
           The method let us open the file FILENAME. By default, the file will be opened as a
           locked file, and if the file that is opened is already locked, the method will not
           return until the file is unlocked. Of course this default behavior can be controlled
           by setting other options. The object will be the file handle of that opened file. The
           parameters that should be provided to this method are the same as the parameters that
           the method "open" of IO::File accepts. (like ">file.txt" for example).  Note that the
           open method checks if the file is opened for reading or for writing, and only then
           calls the lock method of the derived class that is being used. This way, for example,
           when using the Flock scheme, the lock will be a shared lock for a file that is being
           read, and exclusive lock for a file that is opened to be write.

       close ( )
           The file will be closed and unlocked. The method returns the same as the close method
           of IO::File.

       lock ( )
           Practically this method does nothing, and returns 1 (true). This method will be
           overridden by the derived class that implements the scheme we use.  When it is
           overridden, the method suppose to lock the file according to the scheme we use. If the
           file is already locked, and the block option is 1 (true), the method will not return
           until the file is unlocked, and locked again by the method. If the block option is 0
           (false), the method will return 0 immediately. Besides, the lock method is aware if
           the file was opened for reading or for writing. Thus, for example, when using the
           Flock scheme, the method will create a shared lock for a file that is being read, and
           exclusive lock for a file that is opened to be write.

       unlock ( )
           Practically this method does nothing, and returns 1 (true). This method will be
           overridden by the derived class that implements the scheme we use.  When it is
           overridden, the method suppose to unlock the file according to the scheme we use, and
           return 1 (true) on success and 0 (false) on failure.

       have_lock ( )
           Will return 1 (true) if the file is already locked by this object. Will return 0
           (false) otherwise. Note that this will not tell us anything about the situation of the
           file itself - thus we should not use this method in order to check if the file is
           locked by someone else.

       print ( )
           This method is exactly like the "print" method of IO::Handle, with the difference that
           when using this method, if the file is unlocked, then before printing to it, it will
           be locked and afterward it will be unlocked.

       truncate ( )
           This method is exactly like the "truncate" method of IO::Handle, with the difference
           that when using this method, if the file is unlocked, then before truncating it, it
           will be locked and afterward it will be unlocked.

       is_writable ( )
           This method will return 1 (true) if the file was opened to write.  Will return 0
           (false) otherwise.

       should_block ( )
           This method will return 1 (true) if the block option set to 1.  Will return 0 (false)
           otherwise.

       should_lock ( )
           This method will return 1 (true) if the lock option set to 1.  Will return 0 (false)
           otherwise.

       get_scheme ( )
           This method will return the name of the scheme that is currently used.

AUTHORS

       Rani Pinchuk, rani@cpan.org

       Rob Napier, rnapier@employees.org

COPYRIGHT

       Copyright (c) 2001-2002 Ockham Technology N.V. & Rani Pinchuk.  All rights reserved.  This
       package is free software; you can redistribute it and/or modify it under the same terms as
       Perl itself.

SEE ALSO

       IO::File(3), IO::LockedFile::Flock(3)