Overview

Class-Group

Class

Use

Tree

P5EEx-Blue-0.01

PREV NEXT

FRAMES NO FRAMES

P5EEx::Blue::SharedResourceSet::IPCSemaphore

NAME
SYNOPSIS
DESCRIPTION
Class: P5EEx::Blue::SharedResourceSet::IPCSemaphore
Constructor Methods:

new()

Public Methods:

lock()
unlock()

Protected Methods:

init()
allocate()
free()

ACKNOWLEDGEMENTS
SEE ALSO

NAME

P5EEx::Blue::SharedResourceSet::IPCSemaphore - locking shared resources using IPC::Locker

SYNOPSIS

    use P5EEx::Blue::P5EE;

    $context = P5EEx::Blue::P5EE->context();
    $srs = $context->service("SharedResourceSet");  # or ...
    $srs = $context->shared_resource_set();

DESCRIPTION

A SharedResourceSet 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: P5EEx::Blue::SharedResourceSet::IPCSemaphore

A SharedResourceSet 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: P5EEx::Blue::Exception::SharedResourceSet
 * 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 SharedResourceSet may be configured with the following parameters, which govern all locks accessed in the SharedResourceSet (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 SharedResourceSet 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 P5EEx::Blue::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:    P5EEx::Blue::Exception::SharedResourceSet
    * Since:     0.01

    Sample Usage:

    $context = P5EEx::Blue::P5EE->context();
    $srs = $context->service("SharedResourceSet");
    $srs->lock("shmem01");

The lock() method on a SharedResourceSet 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:    P5EEx::Blue::Exception::SharedResourceSet
    * Since:     0.01

    Sample Usage:

    $context = P5EEx::Blue::P5EE->context();
    $srs = $context->service("SharedResourceSet");
    $srs->unlock("shmem01");

Protected Methods:

`init()`

    * Signature: $self->init();
    * Param:     void
    * Return:    void
    * Throws:    P5EEx::Blue::Exception::SharedResourceSet
    * 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:    P5EEx::Blue::Exception::SharedResourceSet
    * 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:    P5EEx::Blue::Exception::SharedResourceSet
    * 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 <stephen.adkins@officevision.com>
 * License: This is free software. It is licensed under the same terms as Perl itself.