NAME
    Lazy::Lockfile - File locking for the lazy.

SYNOPSIS
     use Lazy::Lockfile;

     my $lockfile = Lazy::Lockfile->new() || die "Couldn't get lock!";
     ...
     # Lock is released when $lockfile goes out of scope or your program exits.

DESCRIPTION
    Lazy::Lockfile is a module designed for simple locking, requiring very
    little of the user. Once the object is instanced, the lock will be held
    as long as object is in scope. When the object is destroyed, the lock is
    released.

    Lazy::Lockfile is smart enough to detect stale lockfiles from PIDs no
    longer on the system.

NOTES
    Lazy::Lockfile is not safe for use on NFS volumes.

    When not using the no_pid option, Lazy::Lockfile is unable to detect a
    process running as a user different than the current process (unless the
    current process is running as root). This is due to the way in which
    Lazy::Lockfile checks for a running process. In this scenario, it is
    recommended that users use the no_pid option.

USAGE
    All of the magic in Lazy::Lockfile is done through the constructor and
    destructor.

METHODS
  new
    Constructor for Lazy::Lockfile.

   Parameters
    Accepts a single optional parameter, a hashref containing the following
    options:

   location
    Specifies the full path to the location of the lockfile. Defaults to:

     '/tmp/' . (fileparse($0))[0] . '.pid'

    I.e., the name of the program being run, with a .pid extension, in
    /tmp/.

   no_pid
    If true, instead of writing the PID file, a value of "0" is written
    instead. When read by another instance of Lazy::Lockfile attempting to
    aquire the lock, no PID check will be performed and the lock will be
    assumed to be active as long as the file exists. Defaults to false.

   delete_on_destroy
    If true, sets the "delete on destroy" flag. This flag defaults to true,
    which causes the lockfile to be removed when the object is destroyed.
    Generally, this is the desired behavior. When set to false, this flag
    prevents the lockfile from being removed automatically when the object
    is destroyed. See also "delete_on_destroy".

   Compatibility
    For compatability with older versions of Lazy::Lockfile (pre-1.0), a
    single optional parameter is accepted, the path to the lockfile. This
    parameter functions the same as the 'location' parameter described
    above.

   Return value
    If the lock can not be obtained, undef is returned (and $! will contain
    useful information). Otherwise, the lock is exclusive to this process,
    as long as the object exists.

  name
    Returns the file name of the lockfile.

  delete_on_destroy
    Gets or sets the "delete on destroy" flag.

    If called without a parameter (or with undef), delete_on_destroy will
    return the current state of the "delete on destroy" flag. If called with
    a parameter, this flag will be set.

  unlock
    Explicitly removes the lockfile, just as if the object were destroyed.
    Once this has been called, delete_on_destroy will be set to false, since
    the lock has already been deleted. Once this method is called, there is
    not much use left for the object, so the user may as well delete it now.

    unlock should be used when the lockfile needs to be removed
    deterministicly while the program is running. If you simply remove all
    references to the Lazy::Lockfile object, the lock will be freed when
    garbage collection is run, which is not guaranteed to happen until the
    program exits (though it will likely happen immediately).

    Returns a true value if the lockfile was found and removed, false
    otherwise.

CHANGES
  2010-06-22, 1.17 - jeagle
    Update unlock to return a useful status.

  2010-06-22, 1.16 - jeagle
    Version bumps for migration to CPAN.

  2009-12-03, 1.14 - jeagle
    Fix a bug causing lockfiles with no_pid to not be deleted on
    destroy/unlink.

  2009-12-03, 1.13 - jeagle
    Add the unlock method, to allow for deterministic lockfile removal at
    runtime.

  2009-11-30, 1.12 - jeagle
    Update documentation to clarify delete_on_destroy parameter default
    setting.

  2009-07-06, 1.11 - jeagle
    Fix error thrown when running with taint checking enabled.

  2009-07-06, 1.10 - jeagle
    Fix a bug with lockfile location being overwritten with the default.

  2009-07-06, 1.9 - jeagle
    Add new parameter, no_pid, which disabled active lockfile checks.

    Allow constructor to accept multiple parameters via hashref.

  2009-06-10, 0.4 - jeagle
    Introduce the delete_on_destroy flag.

  2009-06-03, 0.3 - jeagle
    Open pid file with O_NOFOLLOW, to avoid symlink attacks.

    Change default pid file location from /var/tmp to /tmp.

    Correct dates in CHANGES section.

    Add useful error indicators, documentation on error detection.

  2009-04-27, 0.2 - jeagle
    Fix a bug with unspecified lockfile paths trying to create impossible
    file names.

  2009-04-06, v0.1 - jeagle
    Inital release.

