NAME

Forks::Super::Sync - portable interprocess synchronization object

VERSION

0.68

SYNOPSIS

    $locks = Forks::Super::Sync->new( count => 4, initial => ['P','C','N','N'] )
    $pid = fork(); $locks->releaseAfterFork();
    if ($pid == 0) { # child
        $locks->acquire(0);
        $locks->release(1);
        $locks->acquireAndRelease(2, 0.5);
    } else {         # parent
        $locks->acquire(2);
        $locks->release(0);
        $locks->acquire(1, 0.0);
        $locks->release(2);
    }

DESCRIPTION

Forks::Super::Sync provides synchronization objects that can be shared by parent and child processes and used to coordinate action between the parent and child.

For example, a parent process might provide input to a child process, but the child process should wait until input is ready before beginning to process that input. One way to solve this problem would be for the parent to acquire some shared resource either before or immediately after the child process is spawned. When the parent process is ready to send input to the child, the parent releases the shared resource. The child process waits until the shared resource is available before carrying out its function.

SUBROUTINES/METHODS

$sync = Forks::Super::Sync->new( %args )

Constructs a new synchronization object. Recognized key-value pairs in %args are:

count => $count

Specifies the number of separate resources this synchronization object will manage. [default: 1] The "acquire" and "release" methods will expect an argument between 0 and $count-1.

initial => [ @initial ]

initial => $string

A list of $count (see "count", above) items, or a string with $count characters, that specifies which process will possess access to a shared resource after a fork. Each list element or character is expected to be one of:

P - after fork, the parent process should have a lock on the resource

C - after fork, the child process should have a lock on the resource

N - after fork, neither process should have a lock on the resource. The first process to call "acquire" on the resource will get a lock on that resource.

Both of these examples construct a new synchronization object with 3 different locks. After fork, control of the first resource (resource #0) will be held by the parent process, the second resource will be held by the child process, and neither process will hold the third resource.

    $sync = Forks::Super::Sync->new(count => 3, initial => [ 'P', 'C', 'N' ]);
    $sync = Forks::Super::Sync->new(count => 3, initial => 'PCN');

[Default is for all resources to be unlocked and available after fork.]

implementation => $implementation

Specifies an implementation of Forks::Super::Sync to use to synchronize actions between a parent and child process. Recognized implementations are

Semaphlock

Uses Forks::Super::Sync::Semaphlock, an implementation that uses Perl's flock function and advisory file locking. This is implemented just about everywhere, but it also ties up precious filehandle resources.

Win32

Uses Win32::Semaphore objects. As you might expect, only works on Windows (including Cygwin).

Win32Mutex / Win32::Mutex

Another Windows/Cygwin specific synchronization implementation, based on Win32::Mutex objects.

IPCSemaphore

Uses IPC::Semaphore objects. Works on most Unix-y systems (though not Cygwin, for whatever reason).

[Default is Forks::Super::Sync::Semaphlock, which ought to work just about anywhere.]

Implementations of Forks::Super::Sync must include

$result = $sync->acquire($n)

$result = $sync->acquire($n,$timeout)

Acquire exclusive access to shared resource $n. If a $timeout argument is provided, the function waits up to $timeout seconds to acquire the resource, returning zero if the function times out before the resource is acquired. If no $timeout is specified, the subroutine waits indefinitely.

Returns 1 on success, 0 on failure to acquire the resource, -1 if the sync object believes that the process calling acquire for the resource already possesses the resource, "0 but true" if the resource is available because the partner process has quit unexpectedly, or undef for invalid choices of $n. Note that some implementations may use values of $n less than zero for internal use, so choices of $n < 0 may or may not be valid values.

$result = $sync->release($n)

Releases shared resource $n, allowing it to be acquire'd in another process. Returns 1 on success, or undef if called on a resource that is not currently possessed by the calling process.

$result = $sync->acquireAndRelease($n)

$result = $sync->acquireAndRelease($n, $timeout)

Acquires and releases a resource, with an optional timeout on acquiring the resource. Not unlike calling

    $sync->acquire($n [,$timeout]) && $sync->release($n)

DISCLAIMER

Implementations use and abuse subsets of features of file locking and semaphores for the narrow purposes of the Forks::Super distribution. It is probably not a good idea to try to use or extend this module for other purposes.

SEE ALSO

Forks::Super

Various implementations based on "flock" in perlfunc, IPC::Semaphore, Win32::Semaphore, or Win32::Mutex.

AUTHOR

Marty O'Brien, <mob@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2009-2013, Marty O'Brien.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

See http://dev.perl.org/licenses/ for more information.

cpanm Forks::Super

perl -MCPAN -e shell
install Forks::Super