NAME

IPC::Semaphore::Set

DESCRIPTION

An abstract interface to semaphores sets and their resources

A semaphore is a tool to help control access to common resources. Generally when interfacing with semaphores in Perl, you refer to things with numbers and use old IPC calls like semop, semget, e.t.c. The point of this module is to let you think of semaphores in terms of the key objects, and the resource objects those keys have.

This module also tries to "Do The Right Thing". It assumes a lot about what you're looking for if you're using it, and basically assumes that what you want is to have a semaphore with at least one resource that has at least an availability of 1. If this assumption is wrong for your purposes, pay close attention to the options for '->new'.

SYNOPSIS

To check for resource availability:

my $semset = IPC::Semaphore::Set->new;
if ($semset->resource->lock) {
	# ... can use resource!
} else {
	# ... can't use resource!
}

To wait for resource availability:

my $semset = IPC::Semaphore::Set->new;
$semset->resource->lockWait;
# ... resource is now available

To die if we can't get the resource:

my $semset = IPC::Semaphore::Set->new;
$semset->resource->lockOrDie;
# ... if we're here we have a lock

You can provide arguments to new to use a "word" as the key for the semaphore, and to select how many resources the set has, and the total availability for those resources:

my $semset = IPC::Semaphore::Set->new(
	key_name     => "my_key",
	resources    => 5,
	availability => 2, # If you set this, it wont be overwritten
			   # until ->remove is called, or if you override
			   # it explicitly from the $self->sem object using
			   # ->setall
);

Now you can get the first resource (resource 0):

my $resource = $semset->resource;

Or you can select the resource explicitly:

my $resource = $semset->resource(4);

But note that with 5 resources total, 4 is our last resource because the scalar is 0..X

METHODS

new

Get a new IPC::Semaphore::Set object. If 'key' is provided, get or create a semaphore with that key. if 'key_name' is provided, generate a key based off of the ascii character codes of that name. If neither is provided, a new 'private' semaphore set will be created (note that 'private' is how SysV refers to it, but this is something of a misnomer).

New uses the following flags by default:

S_IRUSR | S_IWUSR | IPC_CREAT | SEM_UNDO

Which means it creates it if it doesn't exist, keeps track of ownership, and will clean up it's changes after exit.

resource

Returns a IPC::Semaphore::Set::Resource object given the resource number, or the last Resource accessed by number.

If a number isn't passed to it, and it hasn't yet encountered a resource, it assumes resource 0 (the first resource in the set) is what you wanted and tries to get that.

resources

Returns a list or arrayref of all the IPC::Semaphore::Set::Resource objects available for this semaphore set.

id

Returns the numeric system ID of the semaphore set.

key

Returns the numeric key if available.

keyName

Returns the 'word' key if used.

remove

Remove the semaphore set entirely from the system.

sem

Returns the internal 'IPC::Semaphore' object.