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.

You should allocate synchronization objects only in normal memory mappings. On certain processors (e.g. some PPC ones), atomic operations such as locking will cause a fault if the control structure is allocated in uncached memory.

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:

POSIX 1003.1 THR

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.

Related links