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.

NAME
    IPC::Semaphore::Set::Resource;

DESCRIPTION
    A simple interface to resources available in a semaphore set.

    It assumes to use SEM_UNDO in all cases, so when the program exits it
    should give up its locks.

SYNOPSIS
    Get a resource from a IPC::Semaphore::Set object:

            my $semset   = IPC::Semaphore::Set->new;
            my $resource = $semset->resource($number);

    Attempt to get a lock on the resource:

            if ($resource->lock) {
                    # ... got a lock
            } else {
                    # ... couldn't lock resource
            }

METHODS
    new Return a new IPC::Semaphore::Set::Resource, but you probably want to
        be calling '->resource' on an IPC::Semaphore::Set object to get
        this.

    available
        Returns the value of the resource (current availability in terms of
        greater than 0)

    lock
        Returns boolean as to whether a lock was possible.

    lockWait
        Returns boolean, but waits for the resource to become available.

    lockOrDie
        Returns 1 or dies if lock can not be made.

    number
        Returns the resources's number in the semaphore set.

    set Returns the IPC::Semaphore::Set object the resource belongs to.

    unlock
        Returns 1 or dies if we for some reason can't unlock on the
        resource.

    value
        Same thing as available, but uses the traditional nomenclature.