NAME

POSIX::RT::Semaphore - Perl interface to POSIX.1b semaphores

SYNOPSIS

use POSIX::RT::Semaphore;
use Fcntl;            # O_CREAT, O_EXCL for named semaphore creation

## unnamed semaphore, initial value 1
$sem = POSIX::RT::Semaphore->init(0, 1);

## named semaphore, initial value 1
$nsem = POSIX::RT::Semaphore->open("/mysem", O_CREAT, 0660, 1);

## method synopsis

$sem->wait;                             # down (P) operation
... protected section ...
$sem->post;                             # up (V) operation

if ($sem->trywait) {                    # non-blocking wait (trydown)
  ... protected section ...
  $sem->post;
}

$sem->timedwait(time() + 10);           # wait up to 10 seconds

DESCRIPTION

POSIX::RT::Semaphore provides an object-oriented Perl interface to POSIX.1b Realtime semaphores, as supported by your system. A POSIX semaphore (herein: psem) is a high-performance, persistent synchronization device.

Unnamed psems are typically used for synchronization between the threads of a single process, or between a set of related processes which have inherited the psem from a common ancestor. Named psems are typically used for interprocess synchronization, but may also serve interthreaded designs.

CLASS METHODS

Unless otherwise specified, all methods return the undefined value on failure (setting $!), and a true value on success.

init PSHARED, VALUE

A convenience for the POSIX::RT::Semaphore::Unnamed->init class method.

Return a new POSIX::RT::Semaphore::Unnamed object, initialized to VALUE. If PSHARED is non-zero, the psem may be shared between processes (subject to implementation CAVEATS, below).

Unnamed semaphores persist until explicitly released by calling their destroy method.

open NAME

open NAME, OFLAGS

open NAME, OFLAGS, MODE

open NAME, OFLAGS, MODE, VALUE

A convenience for the POSIX::RT::Semaphore::Named->open class method.

Return a new POSIX::RT::Semaphore::Named object, referring to the underlying semaphore NAME. Other processes may attempt to access the same psem by that NAME.

OFLAGS may specify O_CREAT and O_EXCL, imported from the Fcntl module, to create a new system semaphore. A filesystem-like MODE, defaulting to 0666, and an initial VALUE, defaulting to 1, may be supplied.

Named semaphores persist until explicitly removed by a call to the unlink class method. A subsequent open of that NAME will return a new system psem.

unlink NAME

Remove the named semaphore identified by NAME. Analogous to unlinking a file on UNIX-like systems, removal does not invalidate psems already held open by other processes.

SEMAPHORE OBJECT METHODS

Common Methods

getvalue

Return the current value of the semaphore, or, if the value is zero, a negative number whose absolute value is the number of currently waiting processes.

name

Return the object's associated name as set by "open", or undef if created by "init". Deprecated for unnamed psems.

post

Atomically increment the semaphore, allowing waiters to proceed if the new counter value is greater than zero.

timedwait ABSOLUTE_TIMEOUT

Attempt atomically to decrement the semaphore, waiting until ABSOLUTE_TIMEOUT before failing.

$sem->timedwait(time() + .5);  # wait half a second

trywait

Atomically decrement the semaphore, failing immediately if the counter is at or below zero.

wait

Atomically decrement the semaphore, blocking indefinitely until successful.

POSIX::RT::Semaphore::Unnamed Methods

destroy

Invalidate the underlying semaphore. Subsequent method calls on the psem will simply croak. Operations on a destroyed psem by another process, one which has inherited the now-defunct semaphore, for example, are undefined.

This method may fail if any processes is blocked on the underlying semaphore.

Note that this is distinct from Perl's DESTROY.

POSIX::RT::Semaphore::Named Methods

close

Close the named semaphore for the calling process; subsequent method calls on the object will simply croak. The underlying psem, however, is not removed until a call to POSIX::RT::Semaphore-unlink()>, nor does the call to close affect any other process' connection to the same semaphore.

This method is called implicitly when the last object representing a particular semaphore in a process is DESTROYed.

CAVEATS

PERSISTENCE

POSIX semaphores are system constructs existing apart from the processes that use them. For named psems in particular, this means that the value of a newly opened semaphore may not be that VALUE specified in the "open" call.

Depending on the application, it may be advisable to "unlink" psems before opening them, or to specify O_EXCL, to avoid opening a pre-existing psem.

ENOSYS AND WORSE

Implementation details vary; consult your system documentation.

Interprocess semaphore support varies. In the simplest cases, "open" may simply return undef, setting $! to ENOSYS, as might "init" with a non-zero PSHARED value.

More subtly, "init" with a non-zero PSHARED may succeed, but the resultant psem might be copied, rather than shared, across processes. Some systems require PSHARED psems to be initialized in user-supplied shared memory, for which POSIX::RT::Semaphore currently has no support.

Semaphore name semantics, specifically their relationship to filesystem entities, is implementation defined. POSIX conservatives will use only pathname-like names with a single, leading slash (e.g., "/my_sem").

"getvalue" may not support the special negative semantics, and "timedwait" may not be supported at all.

MISC

wait/post are known by many names: down/up, acquire/release, P/V, and lock/unlock to name a few.

TODO

Extend init() to support shared memory objects.

SEE ALSO

IPC::Semaphore, Thread::Semaphore

AUTHOR

Michael J. Pomraning

Please report bugs to <mjp-perl AT pilcrow.madison.wi.us>

COPYRIGHT AND LICENSE

Copyright 2006 by Michael J. Pomraning

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.