Wefts::Semaphore Class Reference
[Advanced Syncronization constructs]

#include <wefts_semaphore.h>

Inheritance diagram for Wefts::Semaphore:

[legend]Collaboration diagram for Wefts::Semaphore:

[legend]List of all members.

---

Detailed Description

Semaphore semantic.

Semaphores are counters for resources shared between threads. The basic operations on semaphores are: increment the counter atomically, and wait until the counter is non-zero and decrement it atomically.

Wefts semaphores have some added ability with respect of posix version: timed waits are allowed, and an internal count of waiters is held.

Wait (both timed and infinite) is considered a cancellation point. A cleanup routine will be called and the thread will be termianted if a cancellation request is issued while the thread is waiting for the semaphore to become available.

Public Member Functions
	Semaphore (int initial_count=1)
	Initializes the semaphore.
int	value ()
	Gets the current value of the semaphore.
int	waiters ()
	Gets the current amount of threads waiting for this resource.
void	post (int amount=1)
	Increments the semaphore count.
void	wait (CleanupHandler *handler=0, int position=0)
	Wait endlessy until the resource is available.
bool	wait (double seconds, CleanupHandler *handler=0, int position=0)
	Wait until the resource is available, with a given timeout.
bool	tryWait ()
	Test if the resource is free, and if it is, it decrements resource count.
virtual void	handleCleanup (int code, void *caller=0)
Private Attributes
int	m_count
int	m_waiting
FastCondition	m_cond

---

Constructor & Destructor Documentation

Wefts::Semaphore::Semaphore (  int  initial_count = 1  )  [inline]

Initializes the semaphore. The initial count value is 1 by default. This will make the first wait request on the semaphore to suceed and the second one to be blocked, thus making the semaphore acting effectively as a non-reentrant mutex. Use a different initialization value if the semaphore is a counter for a shared resource that may be assigned to a given amount of threads before to block other requests. In particular, 0 may be used to prevent the first wait request to proceed, providing a shared resource count that can be risen by other threads as resources becomes available. With initial count equal to 0, the semaphore acts similarily to a condition variable. Parameters: initial_count  amount of wait() calls allowed before the calling thread is blocked.

---

Member Function Documentation

void Wefts::Semaphore::handleCleanup (  int  code, void *  caller = 0 )  [virtual]

Implements Wefts::CleanupHandler.

void Wefts::Semaphore::post (  int  amount = 1  )  [inline]

Increments the semaphore count. This is done by a thread when it wants to state that it is not holding the shared resource anymore. If the count reaches 1 or above and there are waiting threads, a signal is issued to wake them. If the current thread is responible for more than one shared resource accounted by the semaphore, it can call post() with a number greater than one, representing the amount of shared resources released. Parameters: amount  Quantity by which the semaphore is risen.

bool Wefts::Semaphore::tryWait (   )  [inline]

Test if the resource is free, and if it is, it decrements resource count. As tryWait() does a fast check on the semaphore, it is not considered a cancellation point; the count of waiting threads is not changed and if the resource cannot be acquired, it returns immediately. Returns: true if the resource has been acquired, false otherwise.

int Wefts::Semaphore::value (   )  [inline]

Gets the current value of the semaphore. Notice that unless the caller can guarantee that no other thread may change this value in the meanwhile, the returned value is meaningless, as it may change before the thread has the chance to evalute it. Returns: current semaphore value.

bool Wefts::Semaphore::wait (  double  seconds, CleanupHandler *  handler = 0, int  position = 0 )

Wait until the resource is available, with a given timeout. This means, until the count becomes 1. If seconds is set to 0, it exits almost immediately, but tryWait() should be used instead: the test is faster and lighter, and tryWait is NOT a cancellation point (while wait is). See also: wait(CleanupHandler *, int) for cancellation issues Parameters: seconds  wait in seconds before exiting. handler  the object that will take care of cleaning the mutex wait. position  a value to determine alternative actions in the cleanup routine. Returns: true if sucessful, false if timeout expired.

void Wefts::Semaphore::wait (  CleanupHandler *  handler = 0, int  position = 0 )

Wait endlessy until the resource is available. This means, until the count becomes 1. If the current thread is canceled during wait, then the cleanup handler passed as a parameter is called. By default, the cleanup action of this class unlocks the internal mutex and removes itself from the count of waiting threads. If another cleanup routine is used, Semaphore::handleCleanup() must be anyway called at its end, to ensure that waiting list is correctly updated. Anyhow, application level threads should use Thread::pushCleanup(); this method is meant only to hook subclasses or provide specialized semaphores. Parameters: handler  the object that will take care of cleaning the mutex wait. position  a value to determine alternative actions in the cleanup routine.

int Wefts::Semaphore::waiters (   )  [inline]

Gets the current amount of threads waiting for this resource. Notice that unless the caller can guarantee that no other thread may change this value in the meanwhile, the returned value is meaningless, as it may change before the thread has the chance to evalute it. Returns: threads that are currently waiting for the resource to become available.

---

Member Data Documentation

FastCondition Wefts::Semaphore::m_cond [private]

int Wefts::Semaphore::m_count [private]

int Wefts::Semaphore::m_waiting [private]

---

The documentation for this class was generated from the following files:

• wefts_semaphore.h
• wefts_semaphore.cpp

---