NAME

       Lucy::Store::Lock - Abstract class representing an interprocess mutex lock.

SYNOPSIS

           my $lock = $lock_factory->make_lock(
               name    => 'write',
               timeout => 5000,
           );
           $lock->obtain or die "can't get lock for " . $lock->get_name;
           do_stuff();
           $lock->release;

DESCRIPTION

       The Lock class produces an interprocess mutex lock.  The default subclass uses dot-lock
       files, but alternative implementations are possible.

       Each lock must have a name which is unique per resource to be locked.  Each lock also has
       a "host" id which should be unique per machine; it is used to help clear away stale locks.

CONSTRUCTORS

   new( [labeled params] )
           my $lock = Lucy::Store::Lock->new(
               name     => 'commit',     # required
               folder   => $folder,      # required
               host     => $hostname,    # required
               timeout  => 5000,         # default: 0
               interval => 1000,         # default: 100
           );

       Abstract constructor.

       •   folder - A Folder.

       •   name - String identifying the resource to be locked, which must consist solely of
           characters matching [-_.A-Za-z0-9].

       •   host - A unique per-machine identifier.

       •   timeout - Time in milliseconds to keep retrying before abandoning the attempt to
           obtain() a lock.

       •   interval - Time in milliseconds between retries.

ABSTRACT METHODS

   request()
       Make one attempt to acquire the lock.

       The semantics of request() differ depending on whether shared() returns true.  If the Lock
       is shared(), then request() should not fail if another lock is held against the resource
       identified by "name" (though it might fail for other reasons).  If it is not shared() --
       i.e. it's an exclusive (write) lock -- then other locks should cause request() to fail.

       Returns: true on success, false on failure (sets Lucy->error).

   release()
       Release the lock.

   is_locked()
       Indicate whether the resource identified by this lock's name is currently locked.

       Returns: true if the resource is locked, false otherwise.

   clear_stale()
       Release all locks that meet the following three conditions: the lock name matches, the
       host id matches, and the process id that the lock was created under no longer identifies
       an active process.

METHODS

   obtain()
       Call request() once per "interval" until request() returns success or the "timeout" has
       been reached.

       Returns: true on success, false on failure (sets Lucy->error).

INHERITANCE

       Lucy::Store::Lock isa Lucy::Object::Obj.