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
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
Author
Generated automatically by Doxygen for GNU CommonC++ from the source
code.