| new_rwlock, rwlock_writers_have_priority, rwlock_readers_have_priority, rwlock_enter_read, rwlock_enter_write, rwlock_try_enter_read, rwlock_try_enter_write, rwlock_leave - multiple reader / single writer locks (rwlocks) |
#include <pthr_rwlock.h> rwlock new_rwlock (pool); void rwlock_writers_have_priority (rwlock); void rwlock_readers_have_priority (rwlock); void rwlock_enter_read (rwlock, pseudothread); void rwlock_enter_write (rwlock, pseudothread); int rwlock_try_enter_read (rwlock, pseudothread); int rwlock_try_enter_write (rwlock, pseudothread); void rwlock_leave (rwlock, pseudothread); |
| Multiple reader / single writer locks (rwlocks) do what they say. They allow either many readers to access a critical section or a single writer (but not both). If instead you require simple mutex semantics, then please see <pthr_mutex.h>. |
| RWlocks are automatically released if they are being held when the thread exits. |
| RWlocks are not ``upgradable''. The implementation is too complex to justify that. |
| Note that there are possible deadlocks when using locks. To avoid deadlocks, always ensure every thread acquires locks in the same order. |
| new_rwlock creates a new rwlock object. |
| rwlock_writers_have_priority changes the nature of the lock so that writers have priority over readers. If this is the case then new readers will not be able to enter a critical section if there are writers waiting to enter. [NB: This is the default.] |
| rwlock_readers_have_priority changes the nature of the lock so that readers have priority over writers. Note that if this is the case then writers are likely to be starved if the lock is frequently read. |
| rwlock_enter_read enters the critical section as a reader. Any number of readers are allowed to enter a critical section at the same time. This function may block. |
| rwlock_enter_write enters the critical section as a writer. Only a single writer is allowed to enter a critical section, and then only if there are no readers. This function may block. |
| rwlock_try_enter_read is identical to rwlock_enter_read, but it does not block. It returns true if the lock was successfully acquired, or false if the operation would block. |
| rwlock_try_enter_write is identical to rwlock_enter_write, but it does not block. It returns true if the lock was successfully acquired, or false if the operation would block. |
| rwlock_leave leaves the critical section. |
| A common mistake is to accidentally call rwlock_leave when you are not holding the lock. This generally causes the library to crash. |
| Richard Jones <rich@annexia.org> |
| GNU LGPL (see http://www.gnu.org/) |
| pthrlib-3.0.3 |