NAME

       Paranoid::IO::Lockfile - Paranoid Lockfile support

VERSION

       $Id: lib/Paranoid/IO/Lockfile.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $

SYNOPSIS

         use Paranoid::IO::Lockfile;
         use Fcntl qw(:flock);  # only needed if you use plock in lieu
                                # of the other functions

         $rv = plock($lockfile);
         $rv = plock($lockfile, LOCK_SH | LOCK_NB);
         $rv = plock($lockfile, LOCK_SH | LOCK_NB, $mode);

         $rv = pexclock($lockfile);
         $rv = pshlock($lockfile);
         $rv = punlock($lockfile);

DESCRIPTION

       This module provides convenience functions for using a lockfile to coordinate multi-process activities.
       While basically just a thin wrapper for Paranoid::IO functions it removes the small tedium of having to
       perform the multiple opens required to ensure all processes are working off the same files while avoiding
       race conditions.

IMPORT LISTS

       This module exports the following symbols by default:

           plock pexclock pshlock punlock

       The following specialized import lists also exist:

           List        Members
           --------------------------------------------------------
           all         @defaults

SUBROUTINES/METHODS

   plock
         $rv = plock($filename);
         $rv = plock($filename, LOCK_EX);
         $rv = plock($filename, LOCK_EX, 0666);

       Creates or opens the requested file while applying the lock condition.  The lock type defaults to LOCK_EX
       if omitted, while the file permissions default to 0660.  As always, umask applies.

       There is one scenario in which one would want to use plock in lieu of pexclock, etc:  if you wish to
       perform non-blocking lock attempts.  All convenience functions are blocking.

   pexclock
         $rv = pexclock($filename);
         $rv = pexclock($filename, $mode);

       A wrapper for plock($filename, LOCK_EX).

   pshlock
         $rv = pshlock($filename);
         $rv = pshlock($filename, $mode);

       A wrapper for plock($filename, LOCK_SH).

   punlock
         $rv = punlock($filename);
         $rv = punlock($filename, $mode);

       A wrapper for plock($filename, LOCK_UN).  This does not close the open file handle to the lock file.  For
       that you need to call Paranoid::IO's pclose function.

DEPENDENCIES

       o   Fcntl

       o   Paranoid

       o   Paranoid::Debug

       o   Paranoid::IO

BUGS AND LIMITATIONS

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This  software  is  free  software.   Similar to Perl, you can redistribute it and/or modify it under the
       terms of either:

         a)     the GNU General Public License
                <https://www.gnu.org/licenses/gpl-1.0.html> as published by the
                Free Software Foundation <http://www.fsf.org/>; either version 1
                <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
                <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
         b)     the Artistic License 2.0
                <https://opensource.org/licenses/Artistic-2.0>,

       subject to the following additional term:  No trademark rights to "Paranoid" have been  or  are  conveyed
       under  any  of  the  above  licenses.  However, "Paranoid" may be used fairly to describe this unmodified
       software, in good faith, but not as a trademark.

       (c)  2005  -  2020,  Arthur  Corliss  (corliss@digitalmages.com)  (tm)  2008  -   2020,   Paranoid   Inc.
       (www.paranoid.com)

perl v5.34.0                                       2022-03-13                        Paranoid::IO::Lockfile(3pm)