NAME

App::ResourceLocker::IPCLocker - locking shared resources using IPC::Locker

SYNOPSIS

    use App;

    $context = App->context();
    $srs = $context->service("ResourceLocker");  # or ...
    $srs = $context->shared_resource_set();

DESCRIPTION

A ResourceLocker service represents a collection of "advisory" (or "cooperative") resource locks. The IPCLocker implementation uses the IPC::Locker distribution available on CPAN. Locking is implemented by a Locker Daemon (lockerd), so that locking may be effectively achieved across an entire network.

Class: App::ResourceLocker::IPCLocker

A ResourceLocker service represents a collection of "advisory" (or "cooperative") resource locks. These can be used to synchronize access to and modification of shared resources such as are stored in a SharedDatastore.

 * Throws: App::Exception::ResourceLocker
 * Since:  0.01

The ResourceLocker may be configured with the following parameters, which govern all locks accessed in the ResourceLocker (as per IPC::Locker).

    family      IPC (fifo) family to communicate with the lock server
                INET: use TCP/IP networking
                UNIX: use Unix named pipes (created with "mknod p /path/to/fifo")
                default: INET
    host        default: localhost (only needed for INET family)
    port        default for INET: 1751 (or as defined in /etc/services for "lockerd")
                default for UNIX: /var/locks/lockerd
    timeout     Time at which the server will release the lock if not explicitly
                unlocked by then
                default: 600 sec (10 min) (0 is "unlimited")
    autounlock  Allow the locker daemon to break the lock if the locking process
                is no longer running. (Note that there is an implicit promise
                that the locking process is running on the same server as the
                locker daemon.)
    random      Lock a random resource from the pool when a pool is specified

Constructor Methods:

new()

The constructor is inherited from App::Service.

Public Methods:

lock()

    * Signature: $resource_name = $srs->lock($resource_pool);
    * Signature: $resource_name = $srs->lock($resource_set);
    * Signature: $resource_name = $srs->lock($named);
    * Param:     $resource_pool          string
    * Param:     $resource_set           []
    * Param:     resourcePool            string
    * Param:     nonBlocking             boolean
    * Param:     nonExclusive            boolean
    * Param:     maxWaitTimeMS           integer
    * Return:    $resource_name          string
    * Throws:    App::Exception::ResourceLocker
    * Since:     0.01

    Sample Usage: 

    $context = App->context();
    $srs = $context->service("ResourceLocker");
    $srs->lock("shmem01");

The lock() method on a ResourceLocker is for the purposes of cooperative resource locking.

The "nonBlocking" option works in this implementation. However, all locks are exclusive (the nonExclusive option is ignored). The "maxWaitTimeMS" option is not yet implemented.

unlock()

    * Signature: $srs->unlock($resource_name);
    * Param:     $resource_name          string
    * Return:    void
    * Throws:    App::Exception::ResourceLocker
    * Since:     0.01

    Sample Usage: 

    $context = App->context();
    $srs = $context->service("ResourceLocker");
    $srs->unlock("shmem01");

ACKNOWLEDGEMENTS

 * Author:  Stephen Adkins <spadkins@gmail.com>
 * License: This is free software. It is licensed under the same terms as Perl itself.

SEE ALSO

App::ResourceLocker, App::Context, App::Service