Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Thread::Barrier
thread execution barrier

Thread::Barrier - thread execution barrier


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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy