vl_mutex_win32.c File Reference

#include <windows.h>

Include dependency graph for vl_mutex_win32.c:

Macros
#define	WIN32_LEAN_AND_MEAN

Functions
vl_mutex	vlMutexNew ()
	Mutex primitives are implemented using the Windows SRWLOCK API. This is due to Win32 mutexes being "heavyweight" and being historically less performant than other comparable APIs within the same process. (E.g, if inter-process sharing isn't needed, then SRWLOCK is a good choice.)
void	vlMutexDelete (vl_mutex mutex)
	De-initializes and deletes the specified mutex.
void	vlMutexObtain (vl_mutex mutex)
	Obtains an exclusive lock on the specified mutex.
vl_bool_t	vlMutexTryObtain (vl_mutex mutex)
	Attempts to obtain an exclusive lock on the specified mutex without blocking.
void	vlMutexRelease (vl_mutex mutex)
	Releases an exclusive lock on the specified mutex.

Macro Definition Documentation

WIN32_LEAN_AND_MEAN

#define WIN32_LEAN_AND_MEAN

Function Documentation

vlMutexDelete()

void vlMutexDelete

(

vl_mutex

mutex

)

De-initializes and deletes the specified mutex.

Contract

• Ownership: Releases ownership of the mutex handle and its associated resources.
• Lifetime: The mutex handle becomes invalid immediately after this call.
• Thread Safety: Safe to call from any thread, provided no other thread is using the mutex.
• Nullability: Safe to call with VL_MUTEX_NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: Deleting a mutex that is currently locked or has threads waiting on it. Double deletion.
• Memory Allocation Expectations: Deallocates heap-allocated resources.
• Return-value Semantics: None (void).

Warning

Be certain the mutex is no longer obtained by the time this function is called.

Parameters

mutex

The mutex handle to delete.

vlMutexNew()

vl_mutex vlMutexNew

(

void

)

Mutex primitives are implemented using the Windows SRWLOCK API. This is due to Win32 mutexes being "heavyweight" and being historically less performant than other comparable APIs within the same process. (E.g, if inter-process sharing isn't needed, then SRWLOCK is a good choice.)

Creates a new instance of a mutex.

https://github.com/markwaterman/MutexShootout

vlMutexObtain()

void vlMutexObtain

(

vl_mutex

mutex

)

Obtains an exclusive lock on the specified mutex.

Only a single thread may obtain an exclusive lock at any given time. This is more suitable for write operations.

Contract

• Ownership: Unchanged. The calling thread gains exclusive logical ownership of the lock.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (blocking).
• Nullability: Safe to call with VL_MUTEX_NULL (no-op).
• Error Conditions: Deadlock if the same thread attempts to obtain a non-recursive mutex it already holds.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

mutex

The mutex handle.

vlMutexRelease()

void vlMutexRelease

(

vl_mutex

mutex

)

Releases an exclusive lock on the specified mutex.

Contract

• Ownership: The calling thread relinquishes logical ownership of the lock.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe.
• Nullability: Safe to call with VL_MUTEX_NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: Releasing a mutex not held by the calling thread.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

mutex

The mutex handle.

vlMutexTryObtain()

vl_bool_t vlMutexTryObtain

(

vl_mutex

mutex

)

Attempts to obtain an exclusive lock on the specified mutex without blocking.

Contract

• Ownership: If successful, the calling thread gains exclusive logical ownership of the lock.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (non-blocking).
• Nullability: Safe to call with VL_MUTEX_NULL (returns VL_FALSE).
• Error Conditions: Returns VL_FALSE if the lock is already held by another thread.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns VL_TRUE if the lock was successfully obtained, VL_FALSE otherwise.

Note

This function is non-blocking.

Parameters

mutex

The mutex handle.

Returns

a boolean indicating whether or not the lock was obtained.