barrier(3synch)                                      barrier(3synch)


       NAME
             barrier: barrier_init, barrier_wait, barrier_destroy,
             _barrier_spin_init, _barrier_spin, _barrier_spin_destroy -
             overview of barrier synchronization routines

       SYNOPSIS
             cc [options] -Kthread file
             #include <synch.h>
             int barrier_init(barrier_t *barrier, int count, int type, void *arg);
             int barrier_wait(barrier_t *barrier);
             int barrier_destroy(barrier_t *barrier);
             int _barrier_spin_init(barrier_spin_t *barrier, int count, void *arg)
             int _barrier_spin(barrier_spin_t *barrier);
             int _barrier_spin_destroy(barrier_spin_t *barrier);

          Parameters
             barrier
                    pointer to barrier to be initialized, waited at, or
                    destroyed

             count  number of threads to use the barrier for
                    synchronization

             type   USYNC_THREAD or USYNC_PROCESS

             arg    NULL (reserved for future use)

       DESCRIPTION
             Barriers provide a simple coordination mechanism for threads.
             Threads wait at a barrier until a specified number of threads
             have reached the barrier, then they all resume execution.

             There are two types of barriers: blocking and spinning.
             Threads waiting at a blocking barrier are put to sleep, or
             blocked, until the specified number of threads have reached
             the barrier.  Threads waiting at a spinning barrier busy-wait,
             or spin, until the specified number of threads have reached
             the barrier.

             When a thread calls barrier_wait (for a blocking barrier) or
             _barrier_spin (for a spinning barrier) it is said to have
             reached the barrier.

             The Threads Library provides three routines for blocking
             barriers and three for spinning barriers.  These are outlined
             below and described in more detail on individual manual pages.


                           Copyright 1994 Novell, Inc.               Page 1

      barrier(3synch)                                      barrier(3synch)


         Blocking Barrier Routines
         barrier_init
            barrier_init initializes the blocking barrier pointed to by
            barrier to be of type type and to synchronize count threads.

            Blocking barriers are initialized to be one of two types:
            USYNC_THREAD or USYNC_PROCESS.  USYNC_THREAD barriers are
            available only to threads within the current process.
            USYNC_PROCESS barriers can be used by threads in different
            processes.

         barrier_wait
            barrier_wait blocks the calling thread at a blocking barrier
            until count threads reach the barrier.  When the last thread
            reaches the barrier, all count blocked threads are released
            from the barrier and are allowed to resume execution.  The
            barrier is reset after the waiting threads are released.

         barrier_destroy
            barrier_destroy destroys the blocking barrier pointed to by
            barrier.  This includes invalidating the barrier and freeing
            any associated implementation-allocated dynamic resources.

         Spinning Barrier Routines
         _barrier_spin_init
            _barrier_spin_init initializes the spinning barrier pointed to
            by barrier to synchronize count threads.

         _barrier_spin
            _barrier_spin makes the calling thread busy-wait, or spin, at
            a spinning barrier until count threads reach the barrier.
            When the last thread reaches the barrier, all count spinning
            threads are released from the barrier and allowed to resume
            execution.  The barrier is reset after the waiting threads are
            released.

         _barrier_spin_destroy
            _barrier_spin_destroy destroys the barrier pointed to by
            barrier.  This includes invalidating the barrier and freeing
            any associated implementation-allocated dynamic resources.

      USAGE
            Because spinning barriers waste resources, most applications
            should use blocking barriers instead of spinning barriers.
            Spinning barriers should only be used when all participating
            threads will reach the barrier at approximately the same time.


                          Copyright 1994 Novell, Inc.               Page 2

       barrier(3synch)                                      barrier(3synch)


          Warnings
             Spinning barriers should never be used on a uniprocessor.

       REFERENCES
             barrier_init(3synch), barrier_destroy(3synch),
             _barrier_spin(3synch), _barrier_spin_destroy(3synch),
             _barrier_spin_init(3synch), barrier_wait(3synch),
             synch(3synch)








































                           Copyright 1994 Novell, Inc.               Page 3