NAME

Store::Directories::Lock - Represents a lock on a Store::Directories entry that releases itself when out-of-scope.

SYNOPSIS

    use Store::Directories;

    # Please use Store::Directories's "lock_*" methods for creating
    # new locks
    my $store = Store::Directories->init("path/to/store");

    {
        my $lock = $store->lock_sh('foo');
        # $lock now asserts a shared lock on the directory with key 'foo'

        # You can now read the contents of the directory knowing that no
        # other processes can modify it (but you may not modify it either)
    }

    # The lock is released once it is out-of-scope

    {
        my $lock = $store->lock_ex('foo')
        # $lock now asserts an exclusive lock on the directory with key 'foo'

        # You can now modify the contents of the directory knowing that no
        # other processes can modify or read it.
    }

    # Once again, released once out-of-scope

DESCRIPTION

Instances of this class are returned by Store::Direcotries's lock_ex and lock_sh methods. The existence of one of these instances asserts that this process has either a shared or exclusive lock (to borrow flock(2) terminology) over an entry in the corresponding Store::Directories database.

A process can have only one lock for a given entry at a time. Attempting to create a new lock on the same entry will result in an error.

NOTE: Locks lose their power over forks. That means a lock asserts itself only for the process that it was created in and only for the lifetime of the copy of itself in that process. The copy of a lock in a child process does not gaurentee that the lock still holds (nor will it remove the lock when it goes out-of-scope).

WARNING: This package (optionally) exports the constants UN,SH and EX. While these have similiar meanings to the Fcntl constants with similiar names, they are NOT EQUIVALENT to one another.

GLOBALS

• Store::Directories::Lock::wait_time (number)

  If this is set, then any blocking attempt to obtain a lock will bail out after waiting at least this number of seconds. If a bail-out occurs, then calls to the lock_ex and lock_sh methods of Store::Directories will return undef, and calls to methods like get_or_add or get_or_set will croak.

• Store::Directories::Lock::wait_callback (subroutine ref)

  If this and wait_time are set, then instead of bailing out, this method will be called once the wait_time has passed. The subroutine is called with the name of key being waited on as the first argument,a boolean representing whether the lock is exclusive or not as the second argument and the time (in seconds) that it's been waiting as the third argument. If the subroutine returns a false value, then a bail-out will occur. Otherwise, the wait for the lock will continue.

METHODS

• new STORE, KEY, MODE [NOBLOCK]

  (You can call this method if you like, but you really should use the lock_sh or lock_ex methods on Store::Directories instead).

  Create a new lock that asserts this process has a lock over the directory with KEY in the Store::Directories referred to by STORE. MODE is one of the constants (EX or SH) specifying which kind of lock to create.

  This will block until the desired lock can be obtained. For a shared lock, this means the function will wait until any processes with exclusive locks release them and for an exclusive lock, it will wait until any other processes release all of their locks on the key. However, if NOBLOCK is true, then this won't block but instead return undef if the lock could not be obtained.

  This will croak if this process already has a lock for that key, or if the key does not exist in the store (or if a database error occurs).

• exclusive

  Returns true/false indicating whether the lock is exclusive or not. This can NOT be used to set the status of the lock.

• DESTROY

  Release this lock. Naturally, you shouldn't call this directly and let the garbage-collector do it for you.