view release on metacpan or  search on metacpan

lib/IPC/Concurrency.pm  view on Meta::CPAN

Version 0.5

=cut

our $VERSION = '0.5';

=head1 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();

=head2 System requirements

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

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

=head2 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).

=head1 FAQ

B<Q:> Can i change $0 variable?

B<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.

--

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

B<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.

--

B<Q:> Can i register my process under many names?

B<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);

--

B<Q:> What is the limit for number of containers?

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

--

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

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

--

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

B<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);
    }


=head1 FUNCTIONS