/ 
IPC-Semaphore-Concurrency-0.01
River stage zero No dependents
/ IPC::Semaphore::Concurrency

NAME

IPC::Semaphore::Concurrency - Concurrency guard using semaphores

SYNOPSIS

use IPC::Semaphore::Concurrency;

my $c = IPC::Semaphore::Concurrency->new('/tmp/sem_file');

if ($c->acquire()) {
    print "Do work\n";
} else {
    print "Pass our turn\n";
}


my $c = IPC::Semaphore::Concurrency->new(
    path  => /tmp/sem_file,
    count => 2,
    value => $sem_max,
    );

if ($c->acquire(0, 1, 0)) {
    print "Do work\n";
} else {
    print "Error: Another process is already locked\n";
}

if ($c->acquire(1)) {
    print "Do other work\n";
}

DESCRIPTION

This module allows you to limit concurrency of specific portions of your code. It can be used to limit resource usage or to give exclusive access to specific resources.

This module is similar in functionality to IPC::Concurrency with the main differences being that is uses SysV Semaphores, and allow queuing up processes while others hold the semaphore. There are other difference which gives more flexibility in some cases.

Generally, errors messages on failures can be retriever with $!.

EXPORTS

None for now (could change before first Beta)

CONSTRUCTOR

IPC::Semaphore::Concurrency->new( $path );

IPC::Semaphore::Concurrency->new(
    path    => $path
    project => $proj_id
    count   => $sem_count
    value   => $sem_value
    touch   => $touch_path
    );
path

The path to combine with the project id for creating the semaphore key. This file is only used for the inode and device numbers. Will be created if missing.

project

The project_id used for generating the key. If nothing else, the semaphore value can be used as changing the count will force generating a new semaphore. Defaults to 0.

count

Number of semaphores to create. Default is 1.

value

Value assigned to the semaphore at creation time. Default is 1.

touch

If true, tough the path when creating the semaphore. This can be used to ensure a file in /tmp do not get removed because it is too old.

FUNCTIONS

getall

getval

getncnt

id

setall

setval

stat

remove

These functions are wrapper of the same functions in IPC::Semaphore.

For getval and getncnt, if no argument is given the default is 0.

key

$c->key();

Return the key used to create the semaphore.

acquire

$c->acquire();

$c->acquire($sem_number, $wait, $max, $undo);

$c->acquire(
    sem  => $sem_number,
    wait => $wait,
    max  => $max,
    undo => $undo,
    );

Acquire a semaphore lock. Return true if the lock was acquired.

sem

The semaphore number to get. Defaults to 0.

wait

If true, block on semaphore acquisition.

max

If wait is true, don't block if b<max> processes or more are waiting for the semaphore. Defaults to -1 (unlimited).

You may want to set it to some decent value if blocking on the semaphore to ensure processes don't add up infinitely.

undo

If defined and false, the semaphore won't be released automatically when process exits. You can manually release the semaphore with $c->release().

Use with caution as you can block semaphore slots if the process crash or gets killed. If used together with wait blocked process could eventually stack up leading to resources exhaustion.

release

$c->release();

$c->release($sem_number);

Useful only if you turn off the undo option in acquire function; increment the semaphore by one.

TODO

Allow private semaphores

Allow passing an array of values

BUGS

semop(3) and semop(3p) man pages both indicate that errno should be set to EAGAIN if the call would block and IPC_NOWAIT is used, yet in my tests under Linux errno was set to EWOULDBLOCK. See example.pl and example2.pl for examples of paranoiac error checking. YMMV.

Please report bugs to tguyot@gmail.com.

SEE ALSO

IPC::Semaphore - The module this is based on.

The code repository is mirrored on http://repo.or.cz/w/IPC-Semaphore-Concurrency.git

AUTHOR

Thomas Guyot-Sionnest <tguyot@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 Thomas Guyot-Sionnest <tguyot@gmail.com>

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.