vl_srwlock_pthread.c File Reference

#include <pthread.h>

Include dependency graph for vl_srwlock_pthread.c:

Functions
vl_srwlock	vlSRWLockNew (void)
	Creates a new instance of a lock.
void	vlSRWLockDelete (vl_srwlock lock)
	Deletes the specified lock.
void	vlSRWLockObtainShared (vl_srwlock lock)
	Obtain a shared lock on the specified lock.
vl_bool_t	vlSRWLockTryObtainShared (vl_srwlock lock)
	Attempts to obtain a shared lock from the specified lock.
void	vlSRWLockReleaseShared (vl_srwlock lock)
	Releases a shared lock on the specified lock.
void	vlSRWLockObtainExclusive (vl_srwlock lock)
	Obtains an exclusive lock on the specified lock.
vl_bool_t	vlSRWLockTryObtainExclusive (vl_srwlock lock)
	Attempts to obtain an exclusive lock on the specified lock.
void	vlSRWLockReleaseExclusive (vl_srwlock lock)
	Releases an exclusive lock on the specified lock.

Function Documentation

vlSRWLockDelete()

void vlSRWLockDelete

(

vl_srwlock

lock

)

Deletes the specified lock.

Contract

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

Warning

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

Parameters

lock	The lock handle to delete.

vlSRWLockNew()

vl_srwlock vlSRWLockNew

(

void

)

Creates a new instance of a lock.

Contract

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

Note

May return VL_SRWLOCK_NULL on failure.

Returns

lock handle

vlSRWLockObtainExclusive()

void vlSRWLockObtainExclusive

(

vl_srwlock

lock

)

Obtains an exclusive lock on the specified lock.

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_SRWLOCK_NULL (no-op).
• Error Conditions: Potential deadlock if not used carefully.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

lock	The lock handle.

vlSRWLockObtainShared()

void vlSRWLockObtainShared

(

vl_srwlock

lock

)

Obtain a shared lock on the specified lock.

Multiple threads may obtain a shared lock at any given time. This is more suitable for concurrent read operations.

Contract

• Ownership: Unchanged. The calling thread gains shared logical ownership of the lock.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (blocking).
• Nullability: Safe to call with VL_SRWLOCK_NULL (no-op).
• Error Conditions: Potential deadlock if not used carefully.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

lock	The lock handle.

vlSRWLockReleaseExclusive()

void vlSRWLockReleaseExclusive

(

vl_srwlock

lock

)

Releases an exclusive lock on the specified lock.

Contract

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

Parameters

lock	The lock handle.

vlSRWLockReleaseShared()

void vlSRWLockReleaseShared

(

vl_srwlock

lock

)

Releases a shared lock on the specified lock.

Contract

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

Parameters

lock	The lock handle.

vlSRWLockTryObtainExclusive()

vl_bool_t vlSRWLockTryObtainExclusive

(

vl_srwlock

lock

)

Attempts to obtain an exclusive lock on the specified lock.

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_SRWLOCK_NULL (returns VL_FALSE).
• Error Conditions: Returns VL_FALSE if any lock (shared or exclusive) is already held by other threads.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns VL_TRUE if the exclusive lock was successfully obtained, VL_FALSE otherwise.

Note

This function is non-blocking.

Parameters

lock	The lock handle.

Returns

a boolean indicating whether or not the lock was obtained.

vlSRWLockTryObtainShared()

vl_bool_t vlSRWLockTryObtainShared

(

vl_srwlock

lock

)

Attempts to obtain a shared lock from the specified lock.

Contract

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

Note

This function is non-blocking.

Parameters

lock	The lock handle.

Returns

a boolean indicating whether or not the shared lock was obtained