rwsem.h File Reference

Definition for a reader/writer semaphore. More...

#include <kos/cdefs.h>
#include <stddef.h>
#include <kos/thread.h>

Go to the source code of this file.

Data Structures
struct	rw_semaphore_t
	Reader/writer semaphore structure. More...

Macros
#define	RWSEM_INITIALIZER   { 0, 0, NULL, NULL }
	Initializer for a transient reader/writer semaphore.

Functions
rw_semaphore_t *	rwsem_create (void) __depr("Use rwsem_init or RWSEM_INITIALIZER.")
	Allocate a reader/writer semaphore.
int	rwsem_init (rw_semaphore_t *s)
	Initialize a reader/writer semaphore.
int	rwsem_destroy (rw_semaphore_t *s)
	Destroy a reader/writer semaphore.
int	rwsem_read_lock_timed (rw_semaphore_t *s, int timeout)
	Lock a reader/writer semaphore for reading (with a timeout).
int	rwsem_read_lock (rw_semaphore_t *s)
	Lock a reader/writer semaphore for reading.
int	rwsem_read_lock_irqsafe (rw_semaphore_t *s)
	Lock a reader/writer semaphore for reading.
int	rwsem_write_lock_timed (rw_semaphore_t *s, int timeout)
	Lock a reader/writer semaphore for writing (with a timeout).
int	rwsem_write_lock (rw_semaphore_t *s)
	Lock a reader/writer semaphore for writing.
int	rwsem_write_lock_irqsafe (rw_semaphore_t *s)
	Lock a reader/writer semaphore for writing.
int	rwsem_read_unlock (rw_semaphore_t *s)
	Unlock a reader/writer semaphore from a read lock.
int	rwsem_write_unlock (rw_semaphore_t *s)
	Unlock a reader/writer semaphore from a write lock.
int	rwsem_unlock (rw_semaphore_t *s)
	Unlock a reader/writer semaphore.
int	rwsem_read_trylock (rw_semaphore_t *s)
	Attempt to lock a reader/writer semaphore for reading.
int	rwsem_write_trylock (rw_semaphore_t *s)
	Attempt to lock a reader/writer semaphore for writing.
int	rwsem_read_upgrade_timed (rw_semaphore_t *s, int timeout)
	Upgrade a thread from reader status to writer status (with a timeout).
int	rwsem_read_upgrade (rw_semaphore_t *s)
	Upgrade a thread from reader status to writer status.
int	rwsem_read_tryupgrade (rw_semaphore_t *s)
	Attempt to upgrade a thread from reader status to writer status.
int	rwsem_read_count (rw_semaphore_t *s)
	Read the reader count on the reader/writer semaphore.
int	rwsem_write_locked (rw_semaphore_t *s)
	Read the state of the writer lock on the reader/writer semaphore.

Detailed Description

Definition for a reader/writer semaphore.

This file defines a concept of reader/writer semaphores. Basically, this type of lock allows an unlimited number of "readers" to acquire the lock at a time, but only one "writer" (and only if no readers hold the lock). Readers, by definition, should not change any global data (since they are defined to only be reading), and since this is the case it is safe to allow multiple readers to access global data that is shared amongst threads. Writers on the other hand require exclusive access since they will be changing global data in the critical section, and they cannot share with a reader either (since the reader might attempt to read while the writer is changing data).

Author

Lawrence Sebald

Macro Definition Documentation

RWSEM_INITIALIZER

#define RWSEM_INITIALIZER   { 0, 0, NULL, NULL }

Initializer for a transient reader/writer semaphore.

Function Documentation

rwsem_create()

rw_semaphore_t * rwsem_create

(

void

)

Allocate a reader/writer semaphore.

This function allocates a new reader/writer lock that is initially not locked either for reading or writing.

Deprecated

This function is formally deprecated, and should not be used in newly written code. Instead, please use rwsem_init().

Returns

The created semaphore, or NULL on failure (errno will be set as appropriate).

Error Conditions:

ENOMEM - out of memory

rwsem_destroy()

int rwsem_destroy

(

rw_semaphore_t *

s

)

Destroy a reader/writer semaphore.

This function cleans up a reader/writer semaphore. It is an error to attempt to destroy a r/w semaphore that is locked either for reading or writing.

Parameters

s	The r/w semaphore to destroy.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EBUSY - the semaphore is still locked

rwsem_init()

int rwsem_init

(

rw_semaphore_t *

s

)

Initialize a reader/writer semaphore.

This function initializes a new reader/writer semaphore for use.

Return values

0	On success (no error conditions currently defined).

rwsem_read_count()

int rwsem_read_count

(

rw_semaphore_t *

s

)

Read the reader count on the reader/writer semaphore.

This function is not a safe way to see if the lock will be locked by any readers when you get around to locking it, so do not use it in this way.

Parameters

s	The r/w semaphore to count the readers on.

Returns

The number of readers holding the r/w semaphore.

rwsem_read_lock()

int rwsem_read_lock

(

rw_semaphore_t *

s

)

Lock a reader/writer semaphore for reading.

This function attempts to lock the r/w semaphore for reading. If the semaphore is locked for writing, this function will block until it is possible to obtain the lock for reading. This function is NOT safe to call inside of an interrupt; use rwsem_read_lock_irqsafe instead.

Parameters

s	The r/w semaphore to lock.

Return values

0	On success
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - called inside an interrupt
EINVAL - the semaphore is not initialized

rwsem_read_lock_irqsafe()

int rwsem_read_lock_irqsafe

(

rw_semaphore_t *

s

)

Lock a reader/writer semaphore for reading.

This function attempts to lock the r/w semaphore for reading. If the semaphore is locked for writing, this function will block until it is possible to obtain the lock for reading. If called within an interrupt context, and the semaphore is already locked, this function will return an error.

Parameters

s	The r/w semaphore to lock.

Return values

0	On success
-1	On error, errno will be set as appropriate.

Error Conditions:

EINVAL - the semaphore is not initialized
EWOULDBLOCK - called inside an interrupt and the semaphore was already locked

rwsem_read_lock_timed()

int rwsem_read_lock_timed	(	rw_semaphore_t *	s,
		int	timeout )

Lock a reader/writer semaphore for reading (with a timeout).

This function attempts to lock the r/w semaphore for reading. If the semaphore is locked for writing, this function will block until it is possible to obtain the lock for reading or the timeout expires. This function is NOT safe to call inside of an interrupt.

Parameters

s	The r/w semaphore to lock.
timeout	The maximum time to wait (in milliseconds).

Return values

0	On success
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - called inside an interrupt
ETIMEDOUT - the timeout expires before the lock can be acquired
EINVAL - the timeout value is invalid
EINVAL - the semaphore is not initialized

rwsem_read_trylock()

int rwsem_read_trylock

(

rw_semaphore_t *

s

)

Attempt to lock a reader/writer semaphore for reading.

This function attempts to lock the r/w semaphore for reading. If for any reason rwsem_read_lock would normally block, this function will return an error. This function is safe to call inside an interrupt.

Parameters

s	The r/w semaphore to attempt to lock.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EWOULDBLOCK - a call to rwsem_read_lock would block
EINVAL - the semaphore is not initialized

rwsem_read_tryupgrade()

int rwsem_read_tryupgrade

(

rw_semaphore_t *

s

)

Attempt to upgrade a thread from reader status to writer status.

This function will attempt to upgrade the lock on the calling thread to writer status. If for any reason rwsem_read_upgrade would block, this function will return an error. This function is safe to call inside an interrupt. Note that on error, the read lock is still held!

Parameters

s	The r/w semaphore to upgrade.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EWOULDBLOCK - a call to rwsem_read_upgrade would block
EBUSY - another reader has already requested an upgrade
EINVAL - the semaphore is not initialized

rwsem_read_unlock()

int rwsem_read_unlock

(

rw_semaphore_t *

s

)

Unlock a reader/writer semaphore from a read lock.

This function releases one instance of the read lock on the r/w semaphore.

Parameters

s	The r/w semaphore to release the read lock on.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - the read lock is not currently held
EINVAL - the semaphore is not initialized

rwsem_read_upgrade()

int rwsem_read_upgrade

(

rw_semaphore_t *

s

)

Upgrade a thread from reader status to writer status.

This function will upgrade the lock on the calling thread from a reader state to a writer state. If it cannot do this at the moment, it will block until it is possible. This function is NOT safe to call inside an interrupt.

You can only have one reader waiting to upgrade at a time, otherwise the state would potentially become corrupted between when this is called and when you get the lock. If you get -1 back from this, you must not assume that you can write safely! On error, the calling thread will still hold a read lock.

Parameters

s	The r/w semaphore to upgrade.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - called inside an interrupt
EINVAL - the semaphore is not initialized
EBUSY - another reader has already requested an upgrade

rwsem_read_upgrade_timed()

int rwsem_read_upgrade_timed	(	rw_semaphore_t *	s,
		int	timeout )

Upgrade a thread from reader status to writer status (with a timeout).

This function will upgrade the lock on the calling thread from a reader state to a writer state. If it cannot do this at the moment, it will block until it is possible. This function is NOT safe to call inside an interrupt.

You can only have one reader waiting to upgrade at a time, otherwise the state would potentially become corrupted between when this is called and when you get the lock. If you get -1 back from this, you must not assume that you can write safely! On error, the calling thread will still hold a read lock.

Parameters

s	The r/w semaphore to upgrade.
timeout	The maximum time to wait (in milliseconds).

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - called inside an interrupt
EINVAL - the semaphore is not initialized
EINVAL - the timeout value is invalid
EBUSY - another reader has already requested an upgrade
ETIMEDOUT - the timeout expired before the write lock could be acquired

rwsem_unlock()

int rwsem_unlock

(

rw_semaphore_t *

s

)

Unlock a reader/writer semaphore.

This function releases the lock held by the current thread on the specified reader/writer semaphore. This function will automatically determine which lock is held by the calling thread and release it as appropriate.

This function is NOT safe to call (in general) if you do not hold the lock!

Parameters

s	The r/w semaphore to release the lock on.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - the lock is not currently held by the calling thread
EINVAL - the semaphore is not initialized

rwsem_write_lock()

int rwsem_write_lock

(

rw_semaphore_t *

s

)

Lock a reader/writer semaphore for writing.

This function attempts to lock the r/w semaphore for writing. If the semaphore is locked for reading or writing, this function will block until it is possible to obtain the lock for writing. This function is NOT safe to call inside of an interrupt; use rwsem_write_lock_irqsafe instead.

Parameters

s	The r/w semaphore to lock.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error conditions:

EPERM - called inside an interrupt
EINVAL - the semaphore is not initialized

rwsem_write_lock_irqsafe()

int rwsem_write_lock_irqsafe

(

rw_semaphore_t *

s

)

Lock a reader/writer semaphore for writing.

This function attempts to lock the r/w semaphore for writing. If the semaphore is locked for reading or writing, this function will block until it is possible to obtain the lock for writing. If called within an interrupt context, and the semaphore is already locked, this function will return an error.

Parameters

s	The r/w semaphore to lock.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error conditions:

EINVAL - the semaphore is not initialized
EWOULDBLOCK - called inside an interrupt and the semaphore was already locked

rwsem_write_lock_timed()

int rwsem_write_lock_timed	(	rw_semaphore_t *	s,
		int	timeout )

Lock a reader/writer semaphore for writing (with a timeout).

This function attempts to lock the r/w semaphore for writing. If the semaphore is locked for reading or writing, this function will block until it is possible to obtain the lock for writing or the timeout expires. This function is NOT safe to call inside of an interrupt.

Parameters

s	The r/w semaphore to lock.
timeout	The maximum time to wait (in milliseconds).

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - called inside an interrupt
ETIMEDOUT - the timeout expires before the lock can be acquired
EINVAL - the timeout value is invalid
EINVAL - the semaphore is not initialized

rwsem_write_locked()

int rwsem_write_locked

(

rw_semaphore_t *

s

)

Read the state of the writer lock on the reader/writer semaphore.

This function is not a safe way to see if the lock will be locked by a writer by the time you get around to doing something with it, so don't try to use it for that purpose.

Parameters

s	The r/w semaphore to check the writer status on.

Returns

The status of the writer lock of the r/w semaphore.

rwsem_write_trylock()

int rwsem_write_trylock

(

rw_semaphore_t *

s

)

Attempt to lock a reader/writer semaphore for writing.

This function attempts to lock the r/w semaphore for writing. If for any reason rwsem_write_lock would normally block, this function will return an error. This function is safe to call inside an interrupt.

Parameters

s	The r/w semaphore to attempt to lock.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EWOULDBLOCK - a call to rwsem_write_lock would block
EINVAL - the semaphore is not initialized

rwsem_write_unlock()

int rwsem_write_unlock

(

rw_semaphore_t *

s

)

Unlock a reader/writer semaphore from a write lock.

This function releases one instance of the write lock on the r/w semaphore.

Parameters

s	The r/w semaphore to release the write lock on.

Return values

0	On success.
-1	On error, errno will be set as appropriate.

Error Conditions:

EPERM - the write lock is not currently held by the calling thread
EINVAL - the semaphore is not initialized