lwpa_rwlock

Overview

A reader-writer lock object.

Sometimes also referred to as a shared-exclusive lock or multi-reader lock. When implemented to protect a resource, allows multiple "readers" to access the resource at the same time for read-only purposes.

These are implemented as "write-preferring" reader-writer locks; this means that new readers are blocked from acquiring a read lock if any context is currently waiting for a write lock.

Typedefs
typedef UNDEFINED	lwpa_rwlock_t
	The read-write lock identifier. More...

Functions
bool	lwpa_rwlock_create (lwpa_rwlock_t *id)
	Create a new read-write lock. More...
bool	lwpa_rwlock_readlock (lwpa_rwlock_t *id, int wait_ms)
	Access a read-write lock for reading. More...
void	lwpa_rwlock_readunlock (lwpa_rwlock_t *id)
	Release a read lock on a read-write lock object. More...
bool	lwpa_rwlock_writelock (lwpa_rwlock_t *id, int wait_ms)
	Access a read-write lock for writing. More...
void	lwpa_rwlock_writeunlock (lwpa_rwlock_t *id)
	Release a write lock on a read-write lock object. More...
void	lwpa_rwlock_destroy (lwpa_rwlock_t *id)
	Destroy a read-write lock object. More...

Typedef Documentation

lwpa_rwlock_t

typedef UNDEFINED lwpa_rwlock_t

The read-write lock identifier.

This is highly likely to be a struct.

Function Documentation

lwpa_rwlock_create()

bool lwpa_rwlock_create

(

lwpa_rwlock_t *

id

)

Create a new read-write lock.

Parameters

[in,out]

id

Read-write lock identifier on which to create a read-write lock. If this function returns true, id becomes valid for calls to lwpa_rwlock_readlock(), lwpa_rwlock_writelock(), etc.

Returns

true (the read-write lock was created) or false (the read-write lock was not created).

lwpa_rwlock_destroy()

void lwpa_rwlock_destroy

(

lwpa_rwlock_t *

id

)

Destroy a read-write lock object.

Parameters

[in]

id

Identifier for the read-write lock object to destroy.

lwpa_rwlock_readlock()

bool lwpa_rwlock_readlock	(	lwpa_rwlock_t *	id,
		int	wait_ms
	)

Access a read-write lock for reading.

Blocks until any write lock has been released. Multiple contexts may have a read lock simultaneously. In typical usage, the resource protected by this lock should only be read, not modified, while inside a read lock.

Parameters

[in]	id	Identifier for the read-write lock on which to acquire a read lock.
[in]	wait_ms	How long to wait to acquire the read lock, in milliseconds (use LWPA_WAIT_FOREVER to wait indefinitely).

Returns

true (the read lock was acquired) or false (timeout or failure while waiting to acquire the read lock).

lwpa_rwlock_readunlock()

void lwpa_rwlock_readunlock

(

lwpa_rwlock_t *

id

)

Release a read lock on a read-write lock object.

Parameters

[in]

id

Identifier for the read-write lock on which to release the read lock.

lwpa_rwlock_writelock()

bool lwpa_rwlock_writelock	(	lwpa_rwlock_t *	id,
		int	wait_ms
	)

Access a read-write lock for writing.

Blocks until all read and write locks have been released. No new read locks are allowed while this function is being blocked on.

Parameters

[in]	id	Identifier for the read-write lock on which to acquire a write lock.
[in]	wait_ms	How long to wait to acquire the write lock, in milliseconds (use LWPA_WAIT_FOREVER to wait indefinitely).

Returns

true (the write lock was acquired) or false (timeout or failure while waiting to acquire the write lock).

lwpa_rwlock_writeunlock()

void lwpa_rwlock_writeunlock

(

lwpa_rwlock_t *

id

)

Release a write lock on a read-write lock object.

Parameters

[in]

id

Identifier for the read-write lock on which to release the write lock.