KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Macros | Typedefs | Functions
rwsem.h File Reference

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

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

Go to the source code of this file.

Data Structures

struct  rw_semaphore
 Reader/writer semaphore structure. More...
 

Macros

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

Typedefs

typedef struct rw_semaphore rw_semaphore_t
 Reader/writer semaphore structure. More...
 

Functions

rw_semaphore_trwsem_create () __attribute__((deprecated))
 Allocate a reader/writer semaphore. More...
 
int rwsem_init (rw_semaphore_t *s)
 Initialize a reader/writer semaphore. More...
 
int rwsem_destroy (rw_semaphore_t *s)
 Destroy a reader/writer semaphore. More...
 
int rwsem_read_lock_timed (rw_semaphore_t *s, int timeout)
 Lock a reader/writer semaphore for reading (with a timeout). More...
 
int rwsem_read_lock (rw_semaphore_t *s)
 Lock a reader/writer semaphore for reading. More...
 
int rwsem_write_lock_timed (rw_semaphore_t *s, int timeout)
 Lock a reader/writer semaphore for writing (with a timeout). More...
 
int rwsem_write_lock (rw_semaphore_t *s)
 Lock a reader/writer semaphore for writing. More...
 
int rwsem_read_unlock (rw_semaphore_t *s)
 Unlock a reader/writer semaphore from a read lock. More...
 
int rwsem_write_unlock (rw_semaphore_t *s)
 Unlock a reader/writer semaphore from a write lock. More...
 
int rwsem_unlock (rw_semaphore_t *s)
 Unlock a reader/writer semaphore. More...
 
int rwsem_read_trylock (rw_semaphore_t *s)
 Attempt to lock a reader/writer semaphore for reading. More...
 
int rwsem_write_trylock (rw_semaphore_t *s)
 Attempt to lock a reader/writer semaphore for writing. More...
 
int rwsem_read_upgrade_timed (rw_semaphore_t *s, int timeout)
 Upgrade a thread from reader status to writer status (with a timeout). More...
 
int rwsem_read_upgrade (rw_semaphore_t *s)
 Upgrade a thread from reader status to writer status. More...
 
int rwsem_read_tryupgrade (rw_semaphore_t *s)
 Attempt to upgrade a thread from reader status to writer status. More...
 
int rwsem_read_count (rw_semaphore_t *s)
 Read the reader count on the reader/writer semaphore. More...
 
int rwsem_write_locked (rw_semaphore_t *s)
 Read the state of the writer lock on the reader/writer semaphore. More...
 

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

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

Initializer for a transient reader/writer semaphore.

Typedef Documentation

typedef struct rw_semaphore rw_semaphore_t

Reader/writer semaphore structure.

All members of this structure should be considered to be private, it is not safe to change anything in here yourself.

Function Documentation

rw_semaphore_t* rwsem_create ( )

Allocate a reader/writer semaphore.

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

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
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
sThe r/w semaphore to destroy.
Return values
0On success.
-1On error, errno will be set as appropriate.
Error Conditions:
EBUSY - the semaphore is still locked
int rwsem_init ( rw_semaphore_t s)

Initialize a reader/writer semaphore.

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

Return values
0On success (no error conditions currently defined).
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
sThe r/w semaphore to count the readers on.
Returns
The number of readers holding the r/w semaphore.
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.

Parameters
sThe r/w semaphore to lock.
Return values
0On success
-1On error, errno will be set as appropriate.
Error Conditions:
EPERM - called inside an interrupt
EINVAL - the semaphore is not initialized
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
sThe r/w semaphore to lock.
timeoutThe maximum time to wait (in milliseconds).
Return values
0On success
-1On 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
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
sThe r/w semaphore to attempt to lock.
Return values
0On success.
-1On error, errno will be set as appropriate.
Error Conditions:
EWOULDBLOCK - a call to rwsem_read_lock would block
EINVAL - the semaphore is not initialized
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
sThe r/w semaphore to upgrade.
Return values
0On success.
-1On 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 sempahore is not initialized
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
sThe r/w semaphore to release the read lock on.
Return values
0On success.
-1On error, errno will be set as appropriate.
Error Conditions:
EPERM - the read lock is not currently held
EINVAL - the semaphore is not initialized
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
sThe r/w semaphore to upgrade.
Return values
0On success.
-1On 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
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
sThe r/w semaphore to upgrade.
timeoutThe maximum time to wait (in milliseconds).
Return values
0On success.
-1On 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
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
sThe r/w semaphore to release the lock on.
Return values
0On success.
-1On 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
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.

Parameters
sThe r/w semaphore to lock.
Return values
0On success.
-1On error, errno will be set as appropriate.
Error conditions:
EPERM - called inside an interrupt
EINVAL - the semaphore is not initialized
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
sThe r/w semaphore to lock.
timeoutThe maximum time to wait (in milliseconds).
Return values
0On success.
-1On 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
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
sThe r/w semaphore to check the writer status on.
Returns
The status of the writer lock of the r/w semaphore.
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
sThe r/w semaphore to attempt to lock.
Return values
0On success.
-1On error, errno will be set as appropriate.
Error Conditions:
EWOULDBLOCK - a call to rwsem_write_lock would block
EINVAL - the semaphore is not initialized
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
sThe r/w semaphore to release the write lock on.
Return values
0On success.
-1On 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