vl_semaphore.h File Reference

#include "vl_numtypes.h"

Include dependency graph for vl_semaphore.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
VL_API vl_semaphore	vlSemaphoreNew (vl_uint_t initialCount)
	Creates a new semaphore with the specified initial count.
VL_API void	vlSemaphoreDelete (vl_semaphore sem)
	Deletes a semaphore handle and releases associated resources.
VL_API vl_bool_t	vlSemaphoreWait (vl_semaphore sem, vl_uint_t timeoutMs)
	Decrements (acquires) the semaphore count.
VL_API void	vlSemaphorePost (vl_semaphore sem)
	Increments (releases) the semaphore count.
VL_API vl_bool_t	vlSemaphoreTryWait (vl_semaphore sem)
	Attempts to decrement (acquire) the semaphore without blocking.
VL_API vl_uint_t	vlSemaphoreGetCount (vl_semaphore sem)
	Gets the current semaphore count.

Function Documentation

vlSemaphoreDelete()

VL_API void vlSemaphoreDelete

(

vl_semaphore

sem

)

Deletes a semaphore handle and releases associated resources.

Contract

• Ownership: Releases ownership of the semaphore handle and its associated resources.
• Lifetime: The semaphore handle becomes invalid immediately after this call.
• Thread Safety: Safe to call from any thread, provided no other thread is using the semaphore.
• Nullability: Passing NULL results in undefined behavior (will attempt to destroy a null pointer).
• Error Conditions: None.
• Undefined Behavior: Passing NULL. Deleting a semaphore that still has threads waiting on it. Double deletion.
• Memory Allocation Expectations: Deallocates heap-allocated resources.
• Return-value Semantics: None (void).

Parameters

sem	Semaphore handle to delete

Here is the caller graph for this function:

vlSemaphoreGetCount()

VL_API vl_uint_t vlSemaphoreGetCount

(

vl_semaphore

sem

)

Gets the current semaphore count.

Contract

• Ownership: None.
• Lifetime: Unchanged.
• Thread Safety: Safe to call, but the returned value is a point-in-time snapshot.
• Nullability: sem must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns the current non-negative count of the semaphore.

Parameters

sem	Semaphore handle

Returns

Current count value

Note

This value may change immediately after reading

vlSemaphoreNew()

VL_API vl_semaphore vlSemaphoreNew

(

vl_uint_t

initialCount

)

Creates a new semaphore with the specified initial count.

Contract

• Ownership: The caller owns the returned vl_semaphore handle and is responsible for calling vlSemaphoreDelete.
• Lifetime: The semaphore remains valid until vlSemaphoreDelete.
• Thread Safety: This function is thread-safe.
• Nullability: Returns VL_SEMAPHORE_NULL if the semaphore could not be created.
• Error Conditions: Returns VL_SEMAPHORE_NULL if heap allocation fails or platform-specific initialization fails.
• Undefined Behavior: None.
• Memory Allocation Expectations: Allocates semaphore metadata on the heap.
• Return-value Semantics: Returns an opaque handle to the new semaphore, or NULL on failure.

Parameters

initialCount

Initial number of available resources

Returns

Semaphore handle or VL_SEMAPHORE_NULL on failure

Here is the caller graph for this function:

vlSemaphorePost()

VL_API void vlSemaphorePost

(

vl_semaphore

sem

)

Increments (releases) the semaphore count.

If threads are waiting, one will be unblocked.

Contract

• Ownership: The calling thread relinquishes logical "access" to a resource.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe.
• Nullability: sem must not be NULL.
• Error Conditions: None.
• Undefined Behavior: Incrementing the count beyond its platform-defined maximum. Passing NULL.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

sem	Semaphore handle

Here is the caller graph for this function:

vlSemaphoreTryWait()

VL_API vl_bool_t vlSemaphoreTryWait

(

vl_semaphore

sem

)

Attempts to decrement (acquire) the semaphore without blocking.

Contract

• Ownership: If successful, the calling thread gains logical access to a resource.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (non-blocking).
• Nullability: sem must not be NULL.
• Error Conditions: Returns VL_FALSE if the count is zero.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns VL_TRUE if the semaphore was successfully acquired, VL_FALSE otherwise.

Parameters

sem	Semaphore handle

Returns

VL_TRUE if acquired, VL_FALSE if would block

vlSemaphoreWait()

VL_API vl_bool_t vlSemaphoreWait	(	vl_semaphore	sem,
		vl_uint_t	timeoutMs
	)

Decrements (acquires) the semaphore count.

If the count is zero, blocks until either:

• Another thread increments the count
• The specified timeout expires

Contract

• Ownership: Unchanged. The calling thread gains logical "access" to a pooled resource.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (blocking).
• Nullability: sem must not be NULL.
• Error Conditions: Returns VL_FALSE if the timeout expires before the semaphore is acquired.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns VL_TRUE if the semaphore was successfully acquired, VL_FALSE on timeout or error.

Parameters

sem	Semaphore handle
timeoutMs	Maximum time to wait in milliseconds. Note: 0 results in an immediate return if the semaphore is not available.

Returns

VL_TRUE if acquired, VL_FALSE if timeout occurred

Here is the caller graph for this function: