vlink::SysSemaphore Class Reference

Counting semaphore that can be shared across processes through an OS name. More...

#include <sys_semaphore.h>

Collaboration diagram for vlink::SysSemaphore:

Public Member Functions
	SysSemaphore (size_t count=0)
	Constructs the wrapper with the initial count used when attach() creates the kernel object. More...
	~SysSemaphore ()
	Destructor. Invokes detach(false) when the wrapper is still attached. More...
bool	attach (const std::string &name)
	Creates or opens the kernel object identified by name. More...
bool	detach (bool force=true)
	Releases the kernel handle and optionally unlinks the named object. More...
bool	acquire (size_t n=1, int timeout_ms=kInfinite)
	Decrements the kernel counter by n, blocking when permits are unavailable. More...
void	release (size_t n=1)
	Increments the kernel counter by n, waking blocked acquirers. More...
bool	is_attached () const
	Reports whether the wrapper currently owns a kernel handle. More...
size_t	get_count () const
	Returns a non-atomic snapshot of the current counter value. More...

Static Public Attributes
static constexpr int	kInfinite {-1}
	Sentinel value for acquire() meaning wait indefinitely. More...

Detailed Description

Counting semaphore that can be shared across processes through an OS name.

Resolves to a POSIX named semaphore, a Win32 named semaphore or a macOS dispatch semaphore depending on the host platform.

Constructor & Destructor Documentation

SysSemaphore()

vlink::SysSemaphore::SysSemaphore ( size_t  count = 0 )

explicit

Constructs the wrapper with the initial count used when attach() creates the kernel object.

Parameters

count

Initial permit count for first creation. Default: 0.

~SysSemaphore()

vlink::SysSemaphore::~SysSemaphore

(

)

Destructor. Invokes detach(false) when the wrapper is still attached.

Member Function Documentation

acquire()

bool vlink::SysSemaphore::acquire	(	size_t	n = 1,
		int	timeout_ms = kInfinite
	)

Decrements the kernel counter by n, blocking when permits are unavailable.

Parameters

n	Number of permits requested. Default: 1.
timeout_ms	Maximum wait in milliseconds; kInfinite waits forever.

Returns

true when the permits were acquired; false on timeout or error.

Precondition

is_attached() must be true.

attach()

bool vlink::SysSemaphore::attach

(

const std::string &

name

)

Creates or opens the kernel object identified by name.

When the kernel object already exists the constructor-supplied initial count is ignored. POSIX backends require name to begin with '/'. macOS ignores name and produces a fresh in-process dispatch semaphore.

Parameters

name	Platform-specific semaphore name.

Returns

true on success, false otherwise.

detach()

bool vlink::SysSemaphore::detach

(

bool

force = true

)

Releases the kernel handle and optionally unlinks the named object.

Parameters

force

When true, POSIX backends unlink the name so it disappears from the kernel namespace. Ignored on Windows and macOS. Default: true.

Returns

true on success.

get_count()

size_t vlink::SysSemaphore::get_count

(

)

const

Returns a non-atomic snapshot of the current counter value.

Some backends (notably macOS dispatch) do not expose the counter; 0 is returned in that case.

Returns

Current permit count snapshot.

is_attached()

bool vlink::SysSemaphore::is_attached

(

)

const

Reports whether the wrapper currently owns a kernel handle.

Returns

true when attach() succeeded and detach() has not been called yet.

release()

void vlink::SysSemaphore::release

(

size_t

n = 1

)

Increments the kernel counter by n, waking blocked acquirers.

Parameters

n	Number of permits to add. Default: 1.

Precondition

is_attached() must be true.

Member Data Documentation

kInfinite

constexpr int vlink::SysSemaphore::kInfinite {-1}

staticconstexpr

Sentinel value for acquire() meaning wait indefinitely.

---

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

• include/vlink/base/sys_semaphore.h