KallistiOS
##version##
|
Definition for a reader/writer semaphore. More...
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_t * | rwsem_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... | |
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).
#define RWSEM_INITIALIZER { 1, 0, NULL, NULL } |
Initializer for a transient reader/writer semaphore.
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.
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().
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.
s | The r/w semaphore to destroy. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
int rwsem_init | ( | rw_semaphore_t * | s | ) |
Initialize a reader/writer semaphore.
This function initializes a new reader/writer semaphore for use.
0 | On 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.
s | The r/w semaphore to count the readers on. |
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.
s | The r/w semaphore to lock. |
0 | On success |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to lock. |
timeout | The maximum time to wait (in milliseconds). |
0 | On success |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to attempt to lock. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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!
s | The r/w semaphore to upgrade. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to release the read lock on. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to upgrade. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to upgrade. |
timeout | The maximum time to wait (in milliseconds). |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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!
s | The r/w semaphore to release the lock on. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to lock. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to lock. |
timeout | The maximum time to wait (in milliseconds). |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to check the writer status on. |
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.
s | The r/w semaphore to attempt to lock. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |
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.
s | The r/w semaphore to release the write lock on. |
0 | On success. |
-1 | On error, errno will be set as appropriate. |