pthread_rwlock_rdlock(), pthread_rwlock_tryrdlock()

lock a read-write lock object for reading 

Advanced Realtime Threads


SYNOPSIS

#include <pthread.h>

int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock);

int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock);


DESCRIPTION

The pthread_rwlock_rdlock() function applies a read lock to the read-write lock pointed to by the rwlock argument. When the lock is not already held by a writer and there are no writers blocked on the thread, the read lock is acquired by the calling thread.

The calling thread acquires the lock when a writer does not hold the lock and there are writers blocked on the lock. When a writer holds the lock, the calling thread does not acquire the read lock. When the read lock is not acquired, the calling thread blocks until the lock can be acquired. The calling thread may detect a deadlock (and return EDEADLK) if at the time the call is made it holds a write lock.

A thread may hold multiple concurrent read locks on the specified rwlock argument (that is, it can successfully call the pthread_rwlock_rdlock() function n times). In this case, the application should ensure that the thread also performs matching unlocks (that is, it call the pthread_rwlock_unlock() function n times).

No more than sizeof(unsigned long) simultaneous read locks can be applied to a read-write lock.

The pthread_rwlock_tryrdlock() function applies a read lock as in the pthread_rwlock_rdlock() function, except that the function fails if the equivalent pthread_rwlock_rdlock() call would have blocked the calling thread. The pthread_rwlock_tryrdlock() function never blocks; it either acquires the lock or fails and returns immediately.

When a thread waiting for a read-write lock for reading receives a signal, that thread, upon return from the signal handler, resumes waiting for the read-write lock for reading as if no interruption occurred.


PARAMETERS

rwlock 

Points to a read-write lock.


RETURN VALUES

On success, the pthread_rwlock_rdlock() and pthread_rwlock_tryrdlock() functions return zero. On failure, these functions return one of the following error numbers:

EAGAIN 

No read lock was acquired because the maximum number of read locks for rwlock was exceeded.

EBUSY 

A writer holds the lock and thus, the read-write lock could not be acquired.

EDEADLK 

The current thread already owns the read-write lock for writing.

EINVAL 

The rwlock attribute points to a value that is not an initialized read-write lock object.


CONFORMANCE

UNIX 03.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

Currently, sizeof(unsigned long) is 32 bits for all systems on which the NuTCRACKER Platform runs.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
pthread_rwlock_destroy(), pthread_rwlock_timedrdlock(), pthread_rwlock_timedwrlock(), pthread_rwlock_trywrlock(), pthread_rwlock_unlock(), pthread_rwlock_wrlock()


PTC MKS Toolkit 10.5 Documentation Build 40.