NAME

Thread::Barrier - thread execution barrier

SYNOPSIS

use Thread::Barrier;

my $br = Thread::Barrier->new($n);
...
$br->wait();               # Wait for $n threads to arrive, then all
                           # are released at the same time.
...
if ($br->wait()) {         # As above, but one and only one thread
  log("Everyone arrived"); # logs after release.
}

my $br = Thread::Barrier->new($n, Action => \&mysub);
...
$br->wait();               # mysub() will be called once after $n
                           # threads arrive but before any are
                           # released.

$br->wait($n);             # Wait for $n threads, but not forever.

ABSTRACT

Execution barrier for multiple threads.

DESCRIPTION

A barrier allows a set of threads to wait for each other to arrive at the same point of execution, proceeding only when all of them have arrived. After releasing the threads, a Thread::Barrier object is reset and ready to be used again.

Sometimes it is convenient to have one thread from the waiting set perform some action when all parties have arrived. Thread::Barrier objects support this functionality in two ways, either just before release (via an 'Action' parameter to "new") or just after release (via the serialized return value from "wait").

Waiting threads may also pass a timeout value to "wait" if they don't wish to block indefinitely.

METHODS

new THRESHOLD

new THRESHOLD OPTION => VALUE

Returns a new Thread::Barrier object with a release threshold of THRESHOLD. THRESHOLD must be an integer greater than or equal to 1.

Optional parameters may be specified in a hash-like fashion. At present the supported options are:

Action => CODEref

A code reference to be run by one thread just before barrier release. Precisely which thread runs the action is unspecified. The default is undef, meaning no action will be taken.

RaiseError => boolean

A boolean parameter controlling whether broken barriers raise an exception or simply return undef as described under "BROKENNESS". The default is true, meaning broken barriers raise exceptions.

set_threshold COUNT

set_threshold specifies the threshold count for the barrier, which must be zero or a positive integer. (Note that a threshold of zero or one is rather a degenerate case barrier.) If the new value of COUNT is less than or equal to the number of threads blocked on the barrier, the barrier is released.

Returns true if the barrier is released because of the adjustment, false otherwise.

wait

wait TIMEOUT

wait blocks the calling thread until the number of threads blocking on the barrier meets the threshold. When the blocked threads are released, the barrier is reset to its initial state and ready for re-use.

The calling thread may optionally block for up to TIMEOUT seconds. If any blocked thread times out, the barrier is broken as described under "BROKENNESS", below.

This method returns a true value to one of the released threads, and false to all others. Precisely which thread receives the true value is unspecified.

threshold

Returns the current threshold.

count

Returns the instantaneous count of threads blocking on the barrier.

BROKENNESS

In this context, brokenness is a feature. Thread::Barrier objects may break for one of two reasons: either because the barrier "Action" die()d, or because a call to "wait" timed out. In either case, the program logic behind the barrier has been violated, and it is usually very difficult to re-synchronize the program once this has happened.

When a Thread::Barrier object is broken, pending and subsequent calls to "wait" immediately raise an exception or return undef depending on the value of "RaiseError".

SEE ALSO

perlthrtut.

AUTHORS

Mark Rogaski, <mrogaski@cpan.org> Mike Pomraning, <mjp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2002-2003, 2005, 2007 by Mark Rogaski, mrogaski@cpan.org; 2013 by Mark Rogaski and Mike Pomraning, mjp@cpan.org; all rights reserved.

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the README file distributed with Perl for further details.