vl_mutex.h File Reference

#include "vl_numtypes.h"

Include dependency graph for vl_mutex.h:

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

Go to the source code of this file.

Macros
#define	VL_MUTEX_NULL   0

Typedefs
typedef struct vl_mutex_ *	vl_mutex

Functions
VL_API vl_mutex	vlMutexNew (void)
	Creates a new instance of a mutex.
VL_API void	vlMutexDelete (vl_mutex mutex)
	De-initializes and deletes the specified mutex.
VL_API void	vlMutexObtain (vl_mutex mutex)
	Obtains an exclusive lock on the specified mutex.
VL_API vl_bool_t	vlMutexTryObtain (vl_mutex mutex)
	Attempts to obtain an exclusive lock on the specified mutex without blocking.
VL_API void	vlMutexRelease (vl_mutex mutex)
	Releases an exclusive lock on the specified mutex.

Macro Definition Documentation

VL_MUTEX_NULL

#define VL_MUTEX_NULL   0

██ ██ ██ █████ ███████ █████ ██████ ███ ██ █████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ███████ ███████ ███████ ██ ███ ██ ██ ██ ███████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ████ ███████ ██ ██ ███████ ██ ██ ██████ ██ ████ ██ ██ ====—: A Data Structure and Algorithms library for C11. :—====

Copyright 2026 Jesse Walker, released under the MIT license. Git Repository: https://github.com/walkerje/veritable_lasagna

Typedef Documentation

vl_mutex

typedef struct vl_mutex_* vl_mutex

Function Documentation

vlMutexDelete()

VL_API 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.

Here is the caller graph for this function:

vlMutexNew()

VL_API vl_mutex vlMutexNew

(

void

)

Creates a new instance of a mutex.

Contract

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

Note

May return VL_MUTEX_NULL on failure.

Returns

mutex handle

Creates a new instance of a mutex.

https://github.com/markwaterman/MutexShootout

Here is the caller graph for this function:

vlMutexObtain()

VL_API 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.

Here is the caller graph for this function:

vlMutexRelease()

VL_API 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.

Here is the caller graph for this function:

vlMutexTryObtain()

VL_API 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.