NAME

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

SYNOPSIS

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

## unnamed semaphore, inital 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 a Perl interface to POSIX 1b Realtime semaphores, as supported by your system.

POSIX::RT::Semaphore objects are handles to underlying system resources, much as IO::Handle objects are handles to underlying system resources.

N.B.: threads::shared must be used before POSIX::RT::Semaphore is loaded, if any semaphore objects will be visible to more than one thread.

METHODS

All functions return the undefined value on failure (setting $!), and true on success. A return value of zero is mapped to the true string "0 but true".

UNNAMED SEMAPHORES

init PSHARED, VALUE

The init class method returns a new, unnamed semaphore object, initialized to value VALUE. If PSHARED is non-zero, the sem is shared between processes (but see CAVEATS, below).

Unnamed sems are never implicitly destroyed -- the memory for the POSIX::RT::Semaphore object is deallocated during DESTROY, but the underlying system sem remains unless "destroy" is invoked.

destroy

Invalidate the unnamed sem; future operations on it will fail. This function fails if other processes are blocked on the underlying semaphore.

Note that this is distinct from Perl's DESTROY.

NAMED SEMAPHORES

open NAME

open NAME, OFLAG

open NAME, OFLAG, MODE, VALUE

The open class methods creates a new POSIX::RT::Semaphore object referring to the underlying named semaphore NAME. Other processes may attempt to access the same sem by that NAME.

OFLAG may specify O_CREAT and O_EXCL, imported from the Fcntl module, to create a new system semaphore. In these cases, a filesystem-like MODE and initial VALUE are needed.

close

Close the named semaphore for the calling process; future operations on the object will fail. The underlying sem, however, is not invalidated.

If not called explicitly, the semaphore is closed when its last reference goes away.

unlink

This class method removes the named semaphore. Analogous to unlinking a file, this does not invalidate already open sems.

GENERAL SEMAPHORE USE

getvalue

Returns 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

This method returns the object's associated name as set by "open", or undef if created by "init".

post

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

timedwait ABSOLUTE_TIMEOUT

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

trywait

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

wait

Atomically decrement the semaphore, blocking indefinitely until successful.

CAVEATS

ENOSYS AND WORSE

Implementation details vary; consult your system documentation.

Interprocess semaphores may not be supported, for example, causing "open" or "init" with a positive PSHARED value to return undef and set $! to "Function not implemented". Worse, PSHARED might mean "inherited across fork" or "shared via shared memory." In the latter case, you're out of luck, as this module provides no means of supplying pre-shared memory to the "init" constructor.

Named semaphore 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. consult your system documentation.

PERL ITHREADS

Presently under threads, objects are DESTROYed at every applicable scope clearance in every thread, whether they are shared or unshared (that is, copied) across threads. This means that an object merely visible to a thread will suffer destruction when that thread finishes, even if the object is alive and well in other threads.

When threads::shared is detected, POSIX::RT::Semaphore plays tricks to ensure that its objects are DESTROYed only once, and then only when appropriate. See source for details.

MISC

wait/post are known by many names: down/up, acquire/release, P/V, and lock/unlock (not to be confused with Perl's lock keyword) to name a few.

TODO

Attempted compilation in multiple environments (currently only linux/LinuxThreads tested) and testing, testing, testing.

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 2003 by Michael J. Pomraning

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