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 );

Library:

libc

Description:

The pthread_rwlock_init() function initializes the read-write lock referenced by rwl with the attributes of attr. Read-write locks must be initialized before use. 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 may be used on subsequent calls to pthread_rwlock_destroy(), pthread_rwlock_rdlock(), pthread_rwlock_tryrdlock(), pthread_rwlock_trywrlock(), and pthread_rwlock_wrlock(). This lock remains usable until the read-write lock is destroyed with pthread_rwlock_destroy().

If the read-write lock is statically allocated it can be initialized 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:

Standard Unix

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 Neutrino microkernel has no knowledge of read-write locks and therefore cannot boost the low-priority thread to prevent the priority inversion.

See also:

pthread_rwlockattr_init(), pthread_rwlock_destroy() pthread_rwlock_rdlock(), pthread_rwlock_tryrdlock(), pthread_rwlock_trywrlock(), pthread_rwlock_wrlock(). pthread_rwlock_unlock()