NAME

       ost::Semaphore - A semaphore is generally used as a synchronization object between
       multiple threads or to protect a limited and finite resource such as a memory or thread
       pool.

SYNOPSIS

       #include <thread.h>

       Inherited by ost::ThreadQueue.

   Public Member Functions
       Semaphore (unsigned resource=0)
           The initial value of the semaphore can be specified.
       virtual ~Semaphore ()
           Destroying a semaphore also removes any system resources associated with it.
       bool wait (timeout_t timeout=0)
           Wait is used to keep a thread held until the semaphore counter is greater than 0.
       void post (void)
           Posting to a semaphore increments its current value and releases the first thread
           waiting for the semaphore if it is currently at 0.
       void force_unlock_after_cancellation ()
           Call it after a deferred cancellation to avoid deadlocks.

Detailed Description

       A semaphore is generally used as a synchronization object between multiple threads or to
       protect a limited and finite resource such as a memory or thread pool.

       The semaphore has a counter which only permits access by one or more threads when the
       value of the semaphore is non-zero. Each access reduces the current value of the semaphore
       by 1. One or more threads can wait on a semaphore until it is no longer 0, and hence the
       semaphore can be used as a simple thread synchronization object to enable one thread to
       pause others until the thread is ready or has provided data for them. Semaphores are
       typically used as a counter for protecting or limiting concurrent access to a given
       resource, such as to permitting at most 'x' number of threads to use resource 'y', for
       example.

       Author:
           David Sugar dyfet@ostel.com Semaphore counter for thread synchronization.

       Examples:
           tcpservice.cpp.

Constructor & Destructor Documentation

   ost::Semaphore::Semaphore (unsigned resource = 0)
       The initial value of the semaphore can be specified. An initial value is often used When
       used to lock a finite resource or to specify the maximum number of thread instances that
       can access a specified resource.

       Parameters:
           resource specify initial resource count or 0 default.

   virtual ost::Semaphore::~Semaphore () [virtual]
       Destroying a semaphore also removes any system resources associated with it. If a
       semaphore has threads currently waiting on it, those threads will all continue when a
       semaphore is destroyed.

Member Function Documentation

   void ost::Semaphore::force_unlock_after_cancellation ()
       Call it after a deferred cancellation to avoid deadlocks. From PTHREAD_COND_TIMEDWAIT(3P):
       A condition wait (whether timed or not) is a cancellation point. When the cancelability
       enable state of a thread is set to PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a
       cancellation request while in a condition wait is that the mutex is (in effect) re-
       acquired before calling the first cancellation cleanup handler.

   void ost::Semaphore::post (void)
       Posting to a semaphore increments its current value and releases the first thread waiting
       for the semaphore if it is currently at 0. Interestingly, there is no support to increment
       a semaphore by any value greater than 1 to release multiple waiting threads in either
       pthread or the win32 API. Hence, if one wants to release a semaphore to enable multiple
       threads to execute, one must perform multiple post operations.

       See also:
           wait

       Examples:
           tcpservice.cpp.

       Referenced by ost::SemaphoreLock::~SemaphoreLock().

   bool ost::Semaphore::wait (timeout_t timeout = 0)
       Wait is used to keep a thread held until the semaphore counter is greater than 0. If the
       current thread is held, then another thread must increment the semaphore. Once the thread
       is accepted, the semaphore is automatically decremented, and the thread continues
       execution.

       The pthread semaphore object does not support a timed 'wait', and hence to maintain
       consistancy, neither the posix nor win32 source trees support 'timed' semaphore objects.

       Returns:
           false if timed out

       Parameters:
           timeout period in milliseconds to wait

       See also:
           post

       Referenced by ost::SemaphoreLock::SemaphoreLock().

Author

       Generated automatically by Doxygen for GNU CommonC++ from the source code.