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.

METHODS

• new STORE, KEY, [MODE]

  (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. If undefined, defaults to SH (for a shared lock).

  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.

  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.