NAME
   File::NFSLock - perl module to do NFS (or not) locking

SYNOPSIS
     use File::NFSLock qw(uncache);
     use Fcntl qw(LOCK_EX LOCK_NB);

     my $file = "somefile";

     ### set up a lock - lasts until object looses scope
     if (my $lock = new File::NFSLock {
       file      => $file,
       lock_type => LOCK_EX|LOCK_NB,
       blocking_timeout   => 10,      # 10 sec
       stale_lock_timeout => 30 * 60, # 30 min
     }) {

       ### OR
       ### my $lock = File::NFSLock->new($file,LOCK_EX|LOCK_NB,10,30*60);

       ### do write protected stuff on $file
       ### at this point $file is uncached from NFS (most recent)
       open(FILE, "+<$file") || die $!;

       ### or open it any way you like
       ### my $fh = IO::File->open( $file, 'w' ) || die $!

       ### update (uncache across NFS) other files
       uncache("someotherfile1");
       uncache("someotherfile2");
       # open(FILE2,"someotherfile1");

       ### unlock it
       $lock->unlock();
       ### OR
       ### undef $lock;
       ### OR let $lock go out of scope
     }else{
       die "I couldn't lock the file [$File::NFSLock::errstr]";
     }

DESCRIPTION
   Program based of concept of hard linking of files being atomic across
   NFS. This concept was mentioned in Mail::Box::Locker (which was
   originally presented in Mail::Folder::Maildir). Some routine flow is
   taken from there -- particularly the idea of creating a random local
   file, hard linking a common file to the local file, and then checking
   the nlink status. Some ideologies were not complete (uncache mechanism,
   shared locking) and some coding was even incorrect (wrong stat index).
   File::NFSLock was written to be light, generic, and fast.

USAGE
   Locking occurs by creating a File::NFSLock object. If the object is
   created successfully, a lock is currently in place and remains in place
   until the lock object goes out of scope (or calls the unlock method).

   A lock object is created by calling the new method and passing two to
   four parameters in the following manner:

     my $lock = File::NFSLock->new($file,
                                   $lock_type,
                                   $blocking_timeout,
                                   $stale_lock_timeout,
                                   );

   Additionally, parameters may be passed as a hashref:

     my $lock = File::NFSLock->new({
       file               => $file,
       lock_type          => $lock_type,
       blocking_timeout   => $blocking_timeout,
       stale_lock_timeout => $stale_lock_timeout,
     });

PARAMETERS
   Parameter 1: file
       Filename of the file upon which it is anticipated that a write will
       happen to. Locking will provide the most recent version (uncached)
       of this file upon a successful file lock. It is not necessary for
       this file to exist.

   Parameter 2: lock_type
       Lock type must be one of the following:

         BLOCKING
         BL
         EXCLUSIVE (BLOCKING)
         EX
         NONBLOCKING
         NB
         SHARED
         SH

       Or else one or more of the following joined with '|':

         Fcntl::LOCK_EX() (BLOCKING)
         Fcntl::LOCK_NB() (NONBLOCKING)
         Fcntl::LOCK_SH() (SHARED)

       Lock type determines whether the lock will be blocking, non
       blocking, or shared. Blocking locks will wait until other locks are
       removed before the process continues. Non blocking locks will return
       undef if another process currently has the lock. Shared will allow
       other process to do a shared lock at the same time as long as there
       is not already an exclusive lock obtained.

   Parameter 3: blocking_timeout (optional)
       Timeout is used in conjunction with a blocking timeout. If
       specified, File::NFSLock will block up to the number of seconds
       specified in timeout before returning undef (could not get a lock).

   Parameter 4: stale_lock_timeout (optional)
       Timeout is used to see if an existing lock file is older than the
       stale lock timeout. If do_lock fails to get a lock, the modified
       time is checked and do_lock is attempted again. If the
       stale_lock_timeout is set to low, a recursion load could exist so
       do_lock will only recurse 10 times (this is only a problem if the
       stale_lock_timeout is set too low -- on the order of one or two
       seconds).

METHODS
       After the $lock object is instantiated with new, as outlined above,
       some methods may be used for additional functionality.

 unlock
         $lock->unlock;

       This method may be used to explicitly release a lock that is
       aquired. In most cases, it is not necessary to call unlock directly
       since it will implicitly be called when the object leaves whatever
       scope it is in.

 uncache
         $lock->uncache;
         $lock->uncache("otherfile1");
         uncache("otherfile2");

       This method is used to freshen up the contents of a file across NFS,
       ignoring what is contained in the NFS client cache. It is always
       called from within the new constructor on the file that the lock is
       being attempted. uncache may be used as either an object method or
       as a stand alone subroutine.

 newpid
         my $pid = fork;
         if (defined $pid) {
           # Fork Failed
         } elsif ($pid) {
           $lock->newpid; # Parent
         } else {
           $lock->newpid; # Child
         }

       If fork() is called after a lock has been aquired, then when the
       lock object leaves scope in either the parent or child, it will be
       released. This behavior may be inappropriate for your application.
       To delegate ownership of the lock from the parent to the child, both
       the parent and child process must call the newpid() method after a
       successful fork() call. This will prevent the parent from releasing
       the lock when unlock is called or when the lock object leaves scope.
       This is also useful to allow the parent to fail on subsequent lock
       attempts if the child lock is still aquired.

FAILURE
       On failure, a global variable, $File::NFSLock::errstr, should be set
       and should contain the cause for the failure to get a lock. Useful
       primarily for debugging.

LOCK_EXTENSION
       By default File::NFSLock will use a lock file extenstion of
       ".NFSLock". This is in a global variable
       $File::NFSLock::LOCK_EXTENSION that may be changed to suit other
       purposes (such as compatibility in mail systems).

BUGS
       Notify [email protected] or [email protected] if you spot anything.

 FIFO
       Locks are not necessarily obtained on a first come first serve
       basis. Not only does this not seem fair to new processes trying to
       obtain a lock, but it may cause a process starvation condition on
       heavily locked files.

 DIRECTORIES
       Locks cannot be obtained on directory nodes, nor can a directory
       node be uncached with the uncache routine because hard links do not
       work with directory nodes. Some other algorithm might be used to
       uncache a directory, but I am unaware of the best way to do it. The
       biggest use I can see would be to avoid NFS cache of directory
       modified and last accessed timestamps.

INSTALL
       Download and extract tarball before running these commands in its
       base directory:

         perl Makefile.PL
         make
         make test
         make install

       For RPM installation, download tarball before running these commands
       in your _topdir:

         rpm -ta SOURCES/File-NFSLock-*.tar.gz
         rpm -ih RPMS/noarch/perl-File-NFSLock-*.rpm

AUTHORS
       Paul T Seamons ([email protected]) - Performed majority of the
       programming with copious amounts of input from Rob Brown.

       Rob B Brown ([email protected]) - In addition to helping in the
       programming, Rob Brown provided most of the core testing to make
       sure implementation worked properly. He is now the current
       maintainer.

       Also Mark Overmeer ([email protected]) - Author of
       Mail::Box::Locker, from which some key concepts for File::NFSLock
       were taken.

       Also Kevin Johnson ([email protected]) - Author of
       Mail::Folder::Maildir, from which Mark Overmeer based
       Mail::Box::Locker.

COPYRIGHT
         Copyright (C) 2001
         Paul T Seamons
         [email protected]
         http://seamons.com/

         Copyright (C) 2002-2003,
         Rob B Brown
         [email protected]

         This package may be distributed under the terms of either the
         GNU General Public License
           or the
         Perl Artistic License

         All rights reserved.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.