wxSemaphore Class Reference
[Threading]

#include <wx/thread.h>

List of all members.

---

Detailed Description

wxSemaphore is a counter limiting the number of threads concurrently accessing a shared resource. This counter is always between 0 and the maximum value specified during the semaphore creation. When the counter is strictly greater than 0, a call to wxSemaphore::Wait() returns immediately and decrements the counter. As soon as it reaches 0, any subsequent calls to wxSemaphore::Wait block and only return when the semaphore counter becomes strictly positive again as the result of calling wxSemaphore::Post which increments the counter.

In general, semaphores are useful to restrict access to a shared resource which can only be accessed by some fixed number of clients at the same time. For example, when modeling a hotel reservation system a semaphore with the counter equal to the total number of available rooms could be created. Each time a room is reserved, the semaphore should be acquired by calling wxSemaphore::Wait and each time a room is freed it should be released by calling wxSemaphore::Post.

Library:  wxBase

Category:  Threading

Public Member Functions
	wxSemaphore (int initialcount=0, int maxcount=0)
	~wxSemaphore ()
wxSemaError	Post ()
wxSemaError	TryWait ()
wxSemaError	Wait ()
wxSemaError	WaitTimeout (unsigned long timeout_millis)

---

Constructor & Destructor Documentation

wxSemaphore::wxSemaphore	(	int	initialcount = 0,
		int	maxcount = 0
	)

Specifying a maxcount of 0 actually makes wxSemaphore behave as if there is no upper limit. If maxcount is 1, the semaphore behaves almost as a mutex (but unlike a mutex it can be released by a thread different from the one which acquired it).

initialcount is the initial value of the semaphore which must be between 0 and maxcount (if it is not set to 0).

wxSemaphore::~wxSemaphore

(

)

Destructor is not virtual, don't use this class polymorphically.

---

Member Function Documentation

wxSemaError wxSemaphore::Post

(

)

Increments the semaphore count and signals one of the waiting threads in an atomic way. Returns wxSEMA_OVERFLOW if the count would increase the counter past the maximum.

Returns:

One of:

• wxSEMA_NO_ERROR: There was no error.
• wxSEMA_INVALID : Semaphore hasn't been initialized successfully.
• wxSEMA_OVERFLOW: Post() would increase counter past the max.
• wxSEMA_MISC_ERROR: Miscellaneous error.

wxSemaError wxSemaphore::TryWait

(

)

Same as Wait(), but returns immediately.

Returns:

One of:

• wxSEMA_NO_ERROR: There was no error.
• wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
• wxSEMA_BUSY: Returned by TryWait() if Wait() would block, i.e. the count is zero.
• wxSEMA_MISC_ERROR: Miscellaneous error.

wxSemaError wxSemaphore::Wait

(

)

Wait indefinitely until the semaphore count becomes strictly positive and then decrement it and return.

Returns:

One of:

• wxSEMA_NO_ERROR: There was no error.
• wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
• wxSEMA_MISC_ERROR: Miscellaneous error.

wxSemaError wxSemaphore::WaitTimeout

(

unsigned long

timeout_millis

)

Same as Wait(), but with a timeout limit.

Returns:

One of:

• wxSEMA_NO_ERROR: There was no error.
• wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
• wxSEMA_TIMEOUT: Timeout occurred without receiving semaphore.
• wxSEMA_MISC_ERROR: Miscellaneous error.