Read-write lock. More...
Go to the source code of this file.
Typedefs | |
| typedef typedefP_BEGIN_DECLS struct PRWLock_ | PRWLock |
| Read-write lock opaque data structure. More... | |
Functions | |
| P_LIB_API PRWLock * | p_rwlock_new (void) |
| Creates a new PRWLock object. More... | |
| P_LIB_API pboolean | p_rwlock_reader_lock (PRWLock *lock) |
| Locks a read-write lock for reading. More... | |
| P_LIB_API pboolean | p_rwlock_reader_trylock (PRWLock *lock) |
| Tries to lock a read-write lock for reading immediately. More... | |
| P_LIB_API pboolean | p_rwlock_reader_unlock (PRWLock *lock) |
| Releases a locked for reading read-write lock. More... | |
| P_LIB_API pboolean | p_rwlock_writer_lock (PRWLock *lock) |
| Locks a read-write lock for writing. More... | |
| P_LIB_API pboolean | p_rwlock_writer_trylock (PRWLock *lock) |
| Tries to lock a read-write lock immediately. More... | |
| P_LIB_API pboolean | p_rwlock_writer_unlock (PRWLock *lock) |
| Releases a locked for writing read-write lock. More... | |
| P_LIB_API void | p_rwlock_free (PRWLock *lock) |
| Frees a PRWLock object. More... | |
Detailed Description
Read-write lock.
A read-write lock is a synchronization primitive which allows access to a critical section to not only the one thread, but instead it splits all threads into the two groups:
- reader threads which perform only the reading operations without any shared data modifications;
- writer threads which may perform the shared data modifitcations as well as its reading.
When there are only the reader threads inside a critical section it is called a shared lock - actually you do not need any locking mechanism and all the threads share the lock. In this situation an arbitrary number of reader threads can perform shared data reading.
The situation changes when a writer thread requests access to the same critical section. It will wait until all the current readers finish executing the critical section before acquiring the lock in exclusive manner: no one else can access the critical section until the writer finishes with it. Even another writer thread will have to wait for the lock to be released by the first writer before entering the critical section.
To prevent writer startvation usually writers are in favor over readers, which is actually implementation dependent, though most operating systems try to follow this rule.
A read-write lock is usually used when the writing operations are not performed too frequently, or when the number of reader threads is a way more than writer ones.
A reader enters a critical section with p_rwlock_reader_lock() or p_rwlock_reader_trylock() and exits with p_rwlock_reader_unlock().
A writer enters the critical section with p_rwlock_writer_lock() or p_rwlock_writer_trylock() and exits with p_rwlock_writer_unlock().
Typedef Documentation
◆ PRWLock
| typedef typedefP_BEGIN_DECLS struct PRWLock_ PRWLock |
Read-write lock opaque data structure.
Function Documentation
◆ p_rwlock_free()
◆ p_rwlock_new()
◆ p_rwlock_reader_lock()
Locks a read-write lock for reading.
- Parameters
-
lock PRWLock to lock.
- Returns
- TRUE in case of success, FALSE otherwise.
- Since
- 0.0.1
- Warning
- Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).
Forces the calling thread to sleep until the lock becomes available for locking.
◆ p_rwlock_reader_trylock()
Tries to lock a read-write lock for reading immediately.
- Parameters
-
lock PRWLock to lock.
- Returns
- TRUE in case of success, FALSE otherwise.
- Since
- 0.0.1
- Warning
- Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).
Tries to lock the lock and returns immediately if it is not available for locking.
◆ p_rwlock_reader_unlock()
Releases a locked for reading read-write lock.
- Parameters
-
lock PRWLock to release.
- Returns
- TRUE in case of success, FALSE otherwise.
- Since
- 0.0.1
- Warning
- Do not use this function on non-locked read-write locks - behavior may be unpredictable.
- Do not use this function to unlock a read-write lock which was locked for writing.
If the lock was previously locked for reading then it becomes unlocked.
It's implementation dependent whether only the same thread can lock and unlock the same read-write lock.
◆ p_rwlock_writer_lock()
Locks a read-write lock for writing.
- Parameters
-
lock PRWLock to lock.
- Returns
- TRUE in case of success, FALSE otherwise.
- Since
- 0.0.1
- Warning
- Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).
Forces the calling thread to sleep until the lock becomes available for locking.
◆ p_rwlock_writer_trylock()
Tries to lock a read-write lock immediately.
- Parameters
-
lock PRWLock to lock.
- Returns
- TRUE in case of success, FALSE otherwise.
- Since
- 0.0.1
- Warning
- Do not lock a read-write lock recursively - it may lead to an application deadlock (implementation dependent).
Tries to lock the lock and returns immediately if it is not available for locking.
◆ p_rwlock_writer_unlock()
Releases a locked for writing read-write lock.
- Parameters
-
lock PRWLock to release.
- Returns
- TRUE in case of success, FALSE otherwise.
- Since
- 0.0.1
- Warning
- Do not use this function on non-locked read-write locks - behavior may be unpredictable.
- Do not use this function to unlock a read-write lock which was locked for reading.
If the lock was previously locked for writing then it becomes unlocked.
It's implementation dependent whether only the same thread can lock and unlock the same read-write lock.
