/ 
App-Context-0.968
River stage one • 2 direct dependents • 2 total dependents
/ App::ResourceLocker::IPCSemaphore

NAME

App::ResourceLocker::IPCSemaphore - 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 IPCSemaphore 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::IPCSemaphore

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

Generally speaking, this module only works on Unix platforms, because they support the System V semaphore API on which the IPC::Semaphore module is built.

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

semkey      an 8-digit hex key (i.e. 0x1234FA78) uniquely identifying the
            semaphore set (or may be "private", not shared with any other
            processes, useful only for multi-threaded applications).
            If the ResourceLocker needs more than one semaphore set,
            it will allocation additional sets with keys incremented by
            1 from this semkey.
            default: 0x95EE10CC
nsems       number of semaphores to get (limited by kernel settings)
            in each semaphore set
            default: 100
create      boolean whether to create the semaphore set if it does not
            exist already
            default: 1
mode        permissions mode with which to create the semaphore set
            default: 0600

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");

Protected Methods:

_init()

* Signature: $self->_init();
* Param:     void
* Return:    void
* Throws:    App::Exception::ResourceLocker
* Since:     0.01

Sample Usage: 

$self->_init();

The _init() method is called from within the constructor to allow the class to customize itself.

allocate()

* Signature: ($semset, $semnum) = $self->allocate($resource_name);
* Param:     $resource_name    string
* Return:    $semset           IPC::Semaphore
* Return:    $semnum           integer
* Throws:    App::Exception::ResourceLocker
* Since:     0.01

Sample Usage: 

($semset, $semnum) = $self->allocate($resource_name);

The allocate() method is called when $self->{semset}{$resource_name} is not defined in order to allocate an appropriate ($semset, $semnum) pair for a $resource_name.

free()

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

Sample Usage: 

$self->free($resource_name);

The free() method frees up a resource name so that its physical semaphore may be reused for some other resource.

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