view release on metacpan or  search on metacpan

lib/Parallel/ForkManager.pm  view on Meta::CPAN

=item waitpid_blocking_sleep

Returns the sleep period, in seconds, of the pseudo-blocking calls. The sleep
period can be a fraction of second.

Returns C<0> if disabled.

Defaults to 1 second.

See I<BLOCKING CALLS> for more details.

=item set_waitpid_blocking_sleep $seconds

Sets the the sleep period, in seconds, of the pseudo-blocking calls.
Set to C<0> to disable.

See I<BLOCKING CALLS> for more details.

=back

=head1 CALLBACKS

You can define callbacks in the code, which are called on events like starting
a process or upon finish. Declare these before the first call to start().

The callbacks can be defined with the following methods:

=over 4

=item run_on_finish $code [, $pid ]

You can define a subroutine which is called when a child is terminated. It is
called in the parent process.

The parameters of the $code are the following:

  - pid of the process, which is terminated
  - exit code of the program
  - identification of the process (if provided in the "start" method)
  - exit signal (0-127: signal name)
  - core dump (1 if there was core dump at exit)
  - datastructure reference or undef (see RETRIEVING DATASTRUCTURES)

=item run_on_start $code

You can define a subroutine which is called when a child is started. It called
after the successful startup of a child in the parent process.

The parameters of the $code are the following:

  - pid of the process which has been started
  - identification of the process (if provided in the "start" method)

=item run_on_wait $code, [$period]

You can define a subroutine which is called when the child process needs to wait
for the startup. If $period is not defined, then one call is done per
child. If $period is defined, then $code is called periodically and the
module waits for $period seconds between the two calls. Note, $period can be
fractional number also. The exact "$period seconds" is not guaranteed,
signals can shorten and the process scheduler can make it longer (on busy
systems).

The $code called in the "start" and the "wait_all_children" method also.

No parameters are passed to the $code on the call.

=back

=head1 BLOCKING CALLS

When it comes to waiting for child processes to terminate, C<Parallel::ForkManager> is between
a fork and a hard place (if you excuse the terrible pun). The underlying Perl C<waitpid> function
that the module relies on can block until either one specific or any child process
terminate, but not for a process part of a given group.

This means that the module can do one of two things when it waits for
one of its child processes to terminate:

=over

=item Only wait for its own child processes

This is done via a loop using a C<waitpid> non-blocking call and a sleep statement.
The code does something along the lines of

    while(1) {
        if ( any of the P::FM child process terminated ) {
            return its pid
        }

        sleep $sleep_period
    }

This is the default behavior that the module will use.
This is not the most efficient way to wait for child processes, but it's
the safest way to ensure that C<Parallel::ForkManager> won't interfere with
any other part of the codebase.

The sleep period is set via the method C<set_waitpid_blocking_sleep>.

=item Block until any process terminate

Alternatively, C<Parallel::ForkManager> can call C<waitpid> such that it will
block until any child process terminate. If the child process was not one of
the monitored subprocesses, the wait will resume. This is more efficient, but mean
that C<P::FM> can captures (and discards) the termination notification that a different
part of the code might be waiting for.

If this is a race condition
that doesn't apply to your codebase, you can set the
I<waitpid_blocking_sleep> period to C<0>, which will enable C<waitpid> call blocking.

    my $pm = Parallel::ForkManager->new( 4 );

    $pm->set_waitpid_blocking_sleep(0);  # true blocking calls enabled

    for ( 1..100 ) {
        $pm->start and next;

        ...; # do work