NAME

Thread::Barrier - thread execution barrier

SYNOPSIS

  use Thread::Barrier;

  my $br = Thread::Barrier->new($thr_cnt);
  
  $br->wait; 

  if ($br->wait) }
      # executed by only one released thread
      ...
  }

ABSTRACT

Execution barrier for multiple threads.

DESCRIPTION

Thread barriers provide a mechanism for synchronization of multiple threads. All threads issuing a wait on the barrier will block until the count of waiting threads meets some threshold value. When the threshold is met, the threads will be released and the barrier reset, ready to be used again. This mechanism proves quite useful in situations where processing progresses in stages and completion of the current stage by all threads is the entry criteria for the next stage.

METHODS

new

new COUNT

new creates a new barrier and initializes the threshold count to COUNT. If COUNT is not specified, the threshold is set to 0.

set_threshold COUNT

set_threshold specifies the threshold count for the barrier, must be zero or a positive integer. If the value of COUNT is less than or equal to the number of threads blocking on the barrier when init is called, the barrier is released and reset.

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

wait

wait causes the thread to block 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.

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

threshold

Returns the currently configured threshold.

count

Returns the instantaneous count of threads blocking on the barrier.

WARNING: This is an accessor method that is intended for debugging purposes only, the lock on the barrier object is released when the method returns.

EXAMPLES

The return code from wait may be used to serialize a single-threaded action upon release, executing the action only after all threads have arrived at (and are released from) the barrier:

    sub worker {            # Thr routine: threads->create(\&worker, ...)
        my $br = shift;     # $br->isa('Thread::Barrier')

        get_ready();

        if ($br->wait) {
            do_log("All ready");    # Called only once
        }

       do_work();
    }

Of course, the operating system may schedule the single-threaded action to occur at any time. That is, in the example above, do_log() may run before, during or after other released threads' calls to do_work(). To further serialize this action to complete before peer threads do anything else, simply re-use the same barrier:

    sub worker {
        my $br = shift;

        get_ready();

        if ($br->wait) {
            init_globals();     # Must run after all get_ready() 
                                # calls complete
        }

        $br->wait;              # Prevents do_work() from running
                                # before init_globals() finishes.
        do_work();
    }

SEE ALSO

perlthrtut.

NOTES

Many thanks to Michael Pomraning for providing a workaround for a race condition in the wait() method that also helped to clean up the code and for additional suggestions.

AUTHOR

Mark Rogaski, <mrogaski@cpan.org>

If you find this module useful or have any questions, comments, or suggestions please send me an email message.

COPYRIGHT AND LICENSE

Copyright 2002-2003, 2005, 2007 by Mark Rogaski, mrogaski@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.