A semaphore is used to synchronize threads, similar to a mutex (see plMutex). More...

#include <Semaphore.h>

Public Member Functions
plResult	Create (plUInt32 uiInitialTokenCount=0, plStringView sSharedName=plStringView())
	Attempts to create a new semaphore with an initial number of available tokens.

plResult	Open (plStringView sSharedName)
	Attempts to open an existing named semaphore.

void	AcquireToken ()
	Waits until a token is available and acquires it.

void	ReturnToken ()
	Returns a single token. If another thread is currently waiting for a token, this will wake it up.

plResult	TryAcquireToken (plTime timeout=plTime::MakeZero())
	Same as AcquireToken() but returns immediately with PL_FAILURE, if currently not tokens are available.

Detailed Description

A semaphore is used to synchronize threads, similar to a mutex (see plMutex).

There are three main differences to a mutex:

The thread that acquires a token from a semaphore and the one that returns a token, don't have to be the same.
A semaphore can be locked up to N times by multiple threads in parallel. So it can be used to implement constructs like single-writer / multiple/readers.
A 'named' semaphore can be opened by other processes as well, which allows you to implement the basics for inter process communication (IPC).

Semaphores are quite a bit slower than mutexes (10x or so), so don't use them unless you need the added flexibility.

Member Function Documentation

void plSemaphore::AcquireToken ( )

Waits until a token is available and acquires it.

Use TryAcquireToken() to prevent blocking if desired. AcquireToken() and ReturnToken() may be called from different threads.

plResult plSemaphore::Create	(	plUInt32	uiInitialTokenCount = 0,
		plStringView	sSharedName = plStringView() )

Attempts to create a new semaphore with an initial number of available tokens.

If szSharedName is a non-empty string, a 'named' semaphore is created, which can be opened on other processes as well.

This call can fail, if a semaphore with the same name already exists. Use plSemaphore::Open() instead.

plResult plSemaphore::Open ( plStringView sSharedName )

Attempts to open an existing named semaphore.

Fails if no such semaphore exists.

void plSemaphore::ReturnToken ( )

Returns a single token. If another thread is currently waiting for a token, this will wake it up.

AcquireToken() and ReturnToken() may be called from different threads.

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