xiiSemaphore Class Reference

Copyright (c) Theophilus Eriata. All Rights Reserved. More...

#include <Semaphore.h>

Public Member Functions
	xiiSemaphore ()
	Copyright (c) Theophilus Eriata. All Rights Reserved.
xiiResult	Create (xiiUInt32 uiInitialTokenCount=0, xiiStringView sSharedName=xiiStringView())
xiiResult	Open (xiiStringView sSharedName)
void	AcquireToken ()
void	ReturnToken ()
xiiResult	TryAcquireToken (xiiTime timeout=xiiTime::MakeZero())
	Same as AcquireToken() but returns immediately with XII_FAILURE, if currently not tokens are available.

Detailed Description

Copyright (c) Theophilus Eriata. All Rights Reserved.

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

There are three main differences to a mutex:

1. The thread that acquires a token from a semaphore and the one that returns a token, don't have to be the same.
2. 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.
3. 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.

See also

xiiMutex, xiiConditionVariable

Member Function Documentation

AcquireToken()

void xiiSemaphore::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.

Create()

xiiResult xiiSemaphore::Create	(	xiiUInt32	uiInitialTokenCount = 0,
		xiiStringView	sSharedName = xiiStringView() )

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

If sSharedName 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 xiiSemaphore::Open() instead.

Open()

xiiResult xiiSemaphore::Open

(

xiiStringView

sSharedName

)

Attempts to open an existing named semaphore.

Fails if no such semaphore exists.

ReturnToken()

void xiiSemaphore::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:

• /home/runner/work/XII/XII/Source/Engine/Foundation/Threading/Semaphore.h
• /home/runner/work/XII/XII/Source/Engine/Foundation/Platform/Implementation/Posix/Semaphore_posix.h
• /home/runner/work/XII/XII/Source/Engine/Foundation/Platform/Implementation/Windows/Semaphore_win.h