view release on metacpan or  search on metacpan

lib/App/ResourceLocker/IPCSemaphore.pm  view on Meta::CPAN

#############################################################################

package App::ResourceLocker::IPCSemaphore;
$VERSION = (q$Revision: 6783 $ =~ /(\d[\d\.]*)/)[0];  # VERSION numbers generated by svn

use App;
use App::ResourceLocker;
@ISA = ( "App::ResourceLocker" );

use IPC::SysV qw(IPC_PRIVATE IPC_CREAT IPC_EXCL IPC_NOWAIT SEM_UNDO);
use IPC::Semaphore;

use strict;

=head1 NAME

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

=head1 SYNOPSIS

    use App;

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

=head1 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.

=cut

#############################################################################
# CLASS
#############################################################################

=head1 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

=cut

#############################################################################
# CONSTRUCTOR METHODS
#############################################################################

=head1 Constructor Methods:

=cut

#############################################################################
# new()
#############################################################################

=head2 new()

The constructor is inherited from
L<C<App::Service>|App::Service/"new()">.

=cut

#############################################################################
# PUBLIC METHODS
#############################################################################

=head1 Public Methods:

=cut

#############################################################################
# lock()
#############################################################################

=head2 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