phpman > perldoc > File::NFSLock(3pm)

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 acquired. 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.

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

    fork() is a convenience method that acts just like the normal CORE::fork() except it safely
    ensures the lock is retained within both parent and child processes. WITHOUT this, then when
    either the parent or child process releases the lock, then the entire lock will be lost,
    allowing external processes to re-acquire a lock on the same file, even if the other process
    still has the lock object in scope. This can cause corruption since both processes might think
    they have exclusive access to the file.

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

    The newpid() synopsis shown above is equivalent to the one used for the fork() method, but it's
    not intended to be called directly. It is called internally by the fork() method. To be safe, it
    is recommended to use $lock->fork() from now on.

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 extension 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).

REPO
    The source is now on github:

    git clone https://github.com/hookbot/File-NFSLock

BUGS
    If you spot anything, please submit a pull request on github and/or submit a ticket with RT:
    https://rt.cpan.org/Dist/Display.html?Queue=File-NFSLock

  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 (paul AT seamons.com) - Performed majority of the programming with copious amounts
    of input from Rob Brown.

    Rob B Brown (bbb AT cpan.org) - 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 (mark AT overmeer.net) - Author of Mail::Box::Locker, from which some key
    concepts for File::NFSLock were taken.

    Also Kevin Johnson (kjj AT pobox.com) - Author of Mail::Folder::Maildir, from which Mark Overmeer
    based Mail::Box::Locker.

COPYRIGHT
      Copyright (C) 2001
      Paul T Seamons
      paul AT seamons.com
      http://seamons.com/

      Copyright (C) 2002-2018,
      Rob B Brown
      bbb AT cpan.org

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

      All rights reserved.