/ 
IPC-Concurrency-0.5
River stage zero No dependents
/ IPC::Concurrency

NAME

IPC::Concurrency - Concurrency guard for processes.

VERSION

Version 0.5

SYNOPSIS

This module allows you to specify how many processes of given kind you want to run in parallel.

May be usefull when you want to prevent machine overload or provide exclusive access to some resource.

This is NOT a forker.

use IPC::Concurrency;

my $name = 'PROC';
my $c = IPC::Concurrency->new($name);

# your process will end if there are already 4 processes registered as 'PROC' running
exit unless $c->get_slot(4);

# otherwise it will run as usual
do_some_tasks();

System requirements

Your system must support SysV IPC shared memory and semaphores as well as kill command.

If you pass the test suite for IPC::ShareLite then you're ready to go :)

Containers

Containers are used to name and group processes (like 'PROC' in SYNOPSIS). They are located in shared memory and are accessible by any user.

Containers must be named as exactly 4 characters from A-Z range (uppercase).

FAQ

Q: Can i change $0 variable?

A: Yes. You can change $0 variable during runtime if you want. Finding amount of running processes of given kind is totally 'ps ux' independent.

--

Q: Can i use the same $name for processes running on different users?

A: Yes. For example you can restrict them to access some shared device one at a time.

Example:

package Scanner::GUI;

use IPC::Concurrency;

my $c = IPC::Concurrency->new('SCNR');

while (not $c->get_slot(1)) {
    print 'Scanner is busy', $/;
    sleep 4;
}

run_scanner_gui();

This code will wait till every other 'SCNR' processes are not active. It's much more simple approach than grepping 'ps aux' table or creating lockfiles.

--

Q: Can i register my process under many names?

A: Yes. For example you may want to run no more that 4 parsers and no more than 32 processes on some machine.

Example:

package Parser;

use IPC::Concurrency;

my $c1 = IPC::Concurrency->new('PARS');
my $c2 = IPC::Concurrency->new('GLOB');

exit unless $c1->get_slot(4) and $c2->get_slot(32);

--

Q: What is the limit for number of containers?

A: You can make as many containers as your system allows. You will get Carp::confess('No space left on device') if you exceed available memory or semaphores.

--

Q: What is the limit for number of processes registered in one container?

A: You can request $c2->get_slot(1024) max.

--

Q: Can i use this module for limiting child processes?

A: Yes. In the following example child process doesn't know how many other child processes have been spawned. But it can use get_slot() to prevent exceeding 10 live child processes.

Example:

package Scraper;

use IPC::Concurrency;

my $c1 = IPC::Concurrency->new('SCRA');

unless ( my $pid = fork() ) {
    exit unless $c1->get_slot(10);
}

FUNCTIONS

new

my $name = 'PROC';
my $c = IPC::Concurrency->new($name);

Creates new object and allocates Shared Memory container under $name.

Carp::confess will be called on failure.

get_slot

$count = 1;
exit unless $c->get_slot($count);

Request slot. You will get it if there are no more than $count - 1 processes registered under given $name.

AUTHOR

Pawel (bbkr) Pabian, <cpan at bbkr.org>

Private website: http://bbkr.org

Company website: http://implix.com

BUGS

Please report any bugs or feature requests to bug-ipc-concurrency at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IPC-Concurrency. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

PID rollover problem

PIDs of processes are stored in containers. Once get_slot() is called it checks how many processes are still active. This is done by sending kill 0, PID signals to all processes on ths list. Not responding PIDS are cleared from container and slot is gained if number of PIDs left is smaller than number of concurrent processes required. That makes logic vulnerable to PIDs rollover.

TODO

Encrypt/validate container content.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc IPC::Concurrency

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Pawel bbkr Pabian, all rights reserved.

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