pthread_rwlock_init()
Initialize a read-write lock
Synopsis:
#include <pthread.h> int pthread_rwlock_init( pthread_rwlock_t * rwl, const pthread_rwlockattr_t * attr );
Arguments:
- rwl
- A pointer to a pthread_rwlock_t object that you want to initialize.
- attr
- NULL, or a pointer to a pthread_rwlockattr_t object that specifies the attributes you want to use for the read-write lock; see pthread_rwlockattr_init() .
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The pthread_rwlock_init() function initializes the read-write lock referenced by rwl with the attributes of attr. You must initialize read-write locks before using them. If attr is NULL, rwl is initialized with the default values for the attributes.
Following a successful call to pthread_rwlock_init(), the read-write lock is unlocked, and you can use it in subsequent calls to pthread_rwlock_destroy() , pthread_rwlock_rdlock() , pthread_rwlock_tryrdlock() , pthread_rwlock_trywrlock() , and pthread_rwlock_wrlock() . This lock remains usable until you destroy it by calling pthread_rwlock_destroy().
If the read-write lock is statically allocated, you can initialize it with the default values by setting it to PTHREAD_RWLOCK_INITIALIZER.
More than one thread may hold a shared lock at any time, but only one thread may hold an exclusive lock. This avoids reader and writer starvation during frequent contention by:
- favoring blocked readers over writers after a writer has just released an exclusive lock, and
- favoring writers over readers when there are no blocked readers.
Under heavy contention, the lock alternates between a single exclusive lock followed by a batch of shared locks.
Returns:
- EOK
- Success.
- EAGAIN
- Insufficient system resources to initialize the read-write lock.
- EBUSY
- The read-write lock rwl has been initialized or unsuccessfully destroyed.
- EFAULT
- A fault occurred when the kernel tried to access rwl or attr.
- EINVAL
- Invalid read-write lock attribute object attr.
Classification:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |
Caveats:
Beware of priority inversion when using read-write locks. A high-priority thread may be blocked waiting on a read-write lock locked by a low-priority thread.
The microkernel has no knowledge of read-write locks, and therefore can't boost the low-priority thread to prevent the priority inversion.