ZThread::Semaphore

ZThread::Semaphore Class Reference

#include <Semaphore.h>

Inheritance diagram for ZThread::Semaphore:


Public Member Functions
	Semaphore (int count=1, unsigned int maxCount=1)
virtual	~Semaphore ()
	Destroy the Semaphore.
void	wait ()
bool	tryWait (unsigned long timeout)
void	post ()
virtual int	count ()
virtual bool	tryAcquire (unsigned long timeout)
virtual void	acquire ()
virtual void	release ()

Detailed Description

Author:: Eric Crahen <http://www.code-foo.com>

Date:: <2003-07-16T15:28:01-0400>

Version:: 2.2.1

A Semaphore is an owner-less Lockable object. Its probably best described as a set of 'permits'. A Semaphore is initialized with an initial count and a maximum count, these would correspond to the number of 'permits' currently available and the number of' permits' in total.

Acquiring the Semaphore means taking a permit, but if there are none (the count is 0) the Semaphore will block the calling thread.

Releasing the Semaphore means returning a permit, unblocking a thread waiting for one.

A Semaphore with an initial value of 1 and maximum value of 1 will act as a Mutex.

Threads blocked on a Semaphore are resumed in FIFO order.

Constructor & Destructor Documentation

ZThread::Semaphore::Semaphore	(	int	count = `1`,
		unsigned int	maxCount = `1`
	)

Create a new Semaphore.

Parameters:

	count	initial count
	maxCount	maximum count

Member Function Documentation

void ZThread::Semaphore::acquire ( ) [virtual]

Decrement the count, blocking that calling thread if the count becomes 0 or less than 0. The calling thread will remain blocked until the count is raised above 0 or if an exception is thrown.

Exceptions:

Interrupted_Exception

thrown when the calling thread is interrupted. A thread may be interrupted at any time, prematurely ending any wait.

See also:: Lockable::acquire()

Implements ZThread::Lockable.

int ZThread::Semaphore::count ( ) [virtual]

Get the current count of the semaphore.

This value may change immediately after this function returns to the calling thread.

Returns:: int count

void ZThread::Semaphore::post ( )

Provided to reflect the traditional Semaphore semantics

See also:: release()

void ZThread::Semaphore::release ( ) [virtual]

Increment the count, unblocking one thread if count is positive.

Exceptions:

InvalidOp_Exception

thrown if the maximum count would be exceeded.

See also:: Lockable::release()

Implements ZThread::Lockable.

bool ZThread::Semaphore::tryAcquire ( unsigned long timeout ) [virtual]

Decrement the count, blocking that calling thread if the count becomes 0 or less than 0. The calling thread will remain blocked until the count is raised above 0, an exception is thrown or the given amount of time expires.

Parameters:

timeout

maximum amount of time (milliseconds) this method could block

Returns: