In many situations data is read more often than it is modified or written. In these cases it is desirable to allow threads to read concurrently while holding the lock and allow only one thread to hold the lock when data is modified. A multiple-reader single-writer lock (or read-write lock) does this. A read-write lock is acquired either for reading or writing, and then is released. The thread that acquires the read or write lock must be the one that releases it.
The pthread_rwlockattr_init subroutine initializes a read-write lock attributes object (attr). The default value for all attributes are defined by the implementation. Unexpected results can occur if the pthread_rwlockattr_init subroutine is called specifying an already initialized read-write lock attributes object.
The following examples illustrates how to call the pthread_rwlockattr_init subroutine with the attr object:
pthread_rwlockattr_t attr; pthread_rwlockattr_init(&attr);
After a read-write lock attributes object has been used to initialize one or more read-write locks, any function affecting the attributes object (including destruction) does not affect any previously initialized read-write locks.
The pthread_rwlockattr_destroy subroutine destroys a read-write lock attributes object. Unexpected results can occur if the object is used before it is re-initialized by another call to the pthread_rwlockattr_init subroutine. An implementation can cause the pthread_rwlockattr_destroy subroutine to set the object referenced by the attr object to an invalid value.
The pthread_rwlock_init subroutine initializes the read-write lock referenced by the rwlock object with the attributes referenced by the attr object. If the attr object is NULL, the default read-write lock attributes are used; the effect is the same as passing the address of a default read-write lock attributes object. Upon successful initialization, the state of the read-write lock becomes initialized and unlocked. Once initialized, the lock can be used any number of times without being re-initialized. Unexpected results can occur if the pthread_rwlock_init subroutine is called specifying an already initialized read-write lock, or if a read-write lock is used without first being initialized.
If the pthread_rwlock_init subroutine fails, the rwlock object is not initialized and the contents are undefined.
The pthread_rwlock_destroy subroutine destroys the read-write lock object referenced by rwlock and releases any resources used by the lock. Unexpected results can occur in any of the following situations:
In cases where default read-write lock attributes are appropriate, the PTHREAD_RWLOCK_INITIALIZER macro can be used to initialize read-write locks that are statically allocated. For example:
pthread_rwlock_t rwlock1 = PTHREAD_RWLOCK_INITIALIZER;
The effect is similar to dynamic initialization using a call to the pthread_rwlock_init subroutine with the attr parameter specified as NULL, except that no error checks are performed. For example:
pthread_rwlock_init(&rwlock2, NULL);
This example illustrates how to use the pthread_rwlock_init subroutine with the attr parameter initialized. For an example of how to initialize the attr parameter, see Read Write Attributes Object.
pthread_rwlock_init(&rwlock, &attr);
The pthread_rwlock_rdlock subroutine applies a read lock to the read-write lock referenced by rwlock. The calling thread acquires the read lock if a writer does not hold the lock and there are no writers blocked on the lock. It is unspecified whether the calling thread acquires the lock when a writer does not hold the lock and there are writers waiting for the lock. If a writer holds the lock, the calling thread will not acquire the read lock. If the read lock is not acquired, the calling thread does not return from the pthread_rwlock_rdlock call until it can acquire the lock. Results are undefined if the calling thread holds a write lock on rwlock at the time the call is made.
Implementations favor writers over readers to avoid writer starvation.
A thread may hold multiple concurrent read locks on rwlock (that is, successfully call the pthread_rwlock_rdlock subroutine n times). If so, the thread must perform matching unlocks (that is, it must call the pthread_rwlock_unlock subroutine n times).
The pthread_rwlock_tryrdlock subroutine applies a read lock similar to the pthread_rwlock_rdlock subroutine with the exception that the subroutine fails if any thread holds a write lock on rwlock or there are writers blocked on rwlock. Results are undefined if any of these functions are called with an uninitialized read-write lock.
If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the signal handler the thread resumes waiting for the read-write lock for reading as if it was not interrupted.
The pthread_rwlock_wrlock subroutine applies a write lock to the read-write lock referenced by rwlock. The calling thread acquires the write lock if no other thread (reader or writer) holds the read-write lock rwlock. Otherwise, the thread does not return from the pthread_rwlock_wrlock call until it can acquire the lock. Results are undefined if the calling thread holds the read-write lock (whether a read or write lock) at the time the call is made.
Implementations favor writers over readers to avoid writer starvation.
The pthread_rwlock_trywrlock subroutine applies a write lock like the pthread_rwlock_wrlock subroutine, with the exception that the function fails if any thread currently holds rwlock for reading or writing. Results are undefined if any of these functions are called with an uninitialized read-write lock.
If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the signal handler the thread resumes waiting for the read-write lock for writing as if it was not interrupted.
The following sample programs demonstrate how to use locking subroutines. You need the check.h file and makefile in order to run these programs.
check.h file:
#include stdio.h
#include stdio.h
#include stdio.h
#include stdio.h
/* Simple function to check the return code and exit the program
if the function call failed
*/
static void compResults(char *string, int rc) {
if (rc) {
printf("Error on : %s, rc=%d",
string, rc);
exit(EXIT_FAILURE);
}
return;
}
Makefile:
CC_R = xlc_r
TARGETS = test01 test02 test03
OBJS = test01.o test02.o test03.o
SRCS = $(OBJS:.o=.c)
$(TARGETS): $(OBJS)
$(CC_R) -o $@ $@.o
clean:
rm $(OBJS) $(TARGETS)
run:
test01
test02
test03
This example uses the pthread_rwlock_tryrdlock subroutine with a single thread. For an example of using the pthread_rwlock_tryrdlock subroutine with multiple threads, see Multiple Thread Example.
Example: test01.c
#define _MULTI_THREADED
#include pthread.h
#include stdio.h
#include "check.h"
pthread_rwlock_t rwlock = PTHREAD_RWLOCK_INITIALIZER;
void *rdlockThread(void *arg)
{
int rc;
int count=0;
printf("Entered thread, getting read lock with mp wait\n");
Retry:
rc = pthread_rwlock_tryrdlock(&rwlock);
if (rc == EBUSY) {
if (count >= 10) {
printf("Retried too many times, failure!\n");
exit(EXIT_FAILURE);
}
++count;
printf("Could not get lock, do other work, then RETRY...\n");
sleep(1);
goto Retry;
}
compResults("pthread_rwlock_tryrdlock() 1\n", rc);
sleep(2);
printf("unlock the read lock\n");
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("Secondary thread complete\n");
return NULL;
}
int main(int argc, char **argv)
{
int rc=0;
pthread_t thread;
printf("Enter Testcase - %s\n", argv[0]);
printf("Main, get the write lock\n");
rc = pthread_rwlock_wrlock(&rwlock);
compResults("pthread_rwlock_wrlock()\n", rc);
printf("Main, create the try read lock thread\n");
rc = pthread_create(&thread, NULL, rdlockThread, NULL);
compResults("pthread_create\n", rc);
printf("Main, wait a bit holding the write lock\n");
sleep(5);
printf("Main, Now unlock the write lock\n");
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("Main, wait for the thread to end\n");
rc = pthread_join(thread, NULL);
compResults("pthread_join\n", rc);
rc = pthread_rwlock_destroy(&rwlock);
compResults("pthread_rwlock_destroy()\n", rc);
printf("Main completed\n");
return 0;
}
The output for this sample program will be similar to the following:
Enter Testcase - ./test01 Main, get the write lock Main, create the try read lock thread Main, wait a bit holding the write lock Entered thread, getting read lock with mp wait Could not get lock, do other work, then RETRY... Could not get lock, do other work, then RETRY... Could not get lock, do other work, then RETRY... Could not get lock, do other work, then RETRY... Could not get lock, do other work, then RETRY... Main, Now unlock the write lock Main, wait for the thread to end unlock the read lock Secondary thread complete Main completed
This example uses the pthread_rwlock_tryrdlock subroutine with multiple threads. For an example of using the pthread_rwlock_tryrdlock subroutine with a single thread, see Single Thread Example.
Example: test02.c
#define _MULTI_THREADED
#include pthread.h
#include stdio.h
#include "check.h"
pthread_rwlock_t rwlock = PTHREAD_RWLOCK_INITIALIZER;
void *wrlockThread(void *arg)
{
int rc;
int count=0;
printf("%.8x: Entered thread, getting write lock\n",
pthread_self());
Retry:
rc = pthread_rwlock_trywrlock(&rwlock);
if (rc == EBUSY) {
if (count >= 10) {
printf("%.8x: Retried too many times, failure!\n",
pthread_self());
exit(EXIT_FAILURE);
}
++count;
printf("%.8x: Go off an do other work, then RETRY...\n",
pthread_self());
sleep(1);
goto Retry;
}
compResults("pthread_rwlock_trywrlock() 1\n", rc);
printf("%.8x: Got the write lock\n", pthread_self());
sleep(2);
printf("%.8x: Unlock the write lock\n",
pthread_self());
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("%.8x: Secondary thread complete\n",
pthread_self());
return NULL;
}
int main(int argc, char **argv)
{
int rc=0;
pthread_t thread, thread2;
printf("Enter Testcase - %s\n", argv[0]);
printf("Main, get the write lock\n");
rc = pthread_rwlock_wrlock(&rwlock);
compResults("pthread_rwlock_wrlock()\n", rc);
printf("Main, create the timed write lock threads\n");
rc = pthread_create(&thread, NULL, wrlockThread, NULL);
compResults("pthread_create\n", rc);
rc = pthread_create(&thread2, NULL, wrlockThread, NULL);
compResults("pthread_create\n", rc);
printf("Main, wait a bit holding this write lock\n");
sleep(1);
printf("Main, Now unlock the write lock\n");
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("Main, wait for the threads to end\n");
rc = pthread_join(thread, NULL);
compResults("pthread_join\n", rc);
rc = pthread_join(thread2, NULL);
compResults("pthread_join\n", rc);
rc = pthread_rwlock_destroy(&rwlock);
compResults("pthread_rwlock_destroy()\n", rc);
printf("Main completed\n");
return 0;
}
The output for this sample program will be similar to the following:
Enter Testcase - ./test02 Main, get the write lock Main, create the timed write lock threads Main, wait a bit holding this write lock 00000102: Entered thread, getting write lock 00000102: Go off an do other work, then RETRY... 00000203: Entered thread, getting write lock 00000203: Go off an do other work, then RETRY... Main, Now unlock the write lock Main, wait for the threads to end 00000102: Got the write lock 00000203: Go off an do other work, then RETRY... 00000203: Go off an do other work, then RETRY... 00000102: Unlock the write lock 00000102: Secondary thread complete 00000203: Got the write lock 00000203: Unlock the write lock 00000203: Secondary thread complete Main completed
This example demonstrates how to implement read-write read locks using the pthread_rwlock_rdlock subroutine.
Example: test03.c
#define _MULTI_THREADED
#include pthread.h
#include stdio.h
#include "check.h"
pthread_rwlock_t rwlock;
void *rdlockThread(void *arg)
{
int rc;
printf("Entered thread, getting read lock\n");
rc = pthread_rwlock_rdlock(&rwlock);
compResults("pthread_rwlock_rdlock()\n", rc);
printf("got the rwlock read lock\n");
sleep(5);
printf("unlock the read lock\n");
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("Secondary thread unlocked\n");
return NULL;
}
void *wrlockThread(void *arg)
{
int rc;
printf("Entered thread, getting write lock\n");
rc = pthread_rwlock_wrlock(&rwlock);
compResults("pthread_rwlock_wrlock()\n", rc);
printf("Got the rwlock write lock, now unlock\n");
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("Secondary thread unlocked\n");
return NULL;
}
int main(int argc, char **argv)
{
int rc=0;
pthread_t thread, thread1;
printf("Enter Testcase - %s\n", argv[0]);
printf("Main, initialize the read write lock\n");
rc = pthread_rwlock_init(&rwlock, NULL);
compResults("pthread_rwlock_init()\n", rc);
printf("Main, grab a read lock\n");
rc = pthread_rwlock_rdlock(&rwlock);
compResults("pthread_rwlock_rdlock()\n",rc);
printf("Main, grab the same read lock again\n");
rc = pthread_rwlock_rdlock(&rwlock);
compResults("pthread_rwlock_rdlock() second\n", rc);
printf("Main, create the read lock thread\n");
rc = pthread_create(&thread, NULL, rdlockThread, NULL);
compResults("pthread_create\n", rc);
printf("Main - unlock the first read lock\n");
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("Main, create the write lock thread\n");
rc = pthread_create(&thread1, NULL, wrlockThread, NULL);
compResults("pthread_create\n", rc);
sleep(5);
printf("Main - unlock the second read lock\n");
rc = pthread_rwlock_unlock(&rwlock);
compResults("pthread_rwlock_unlock()\n", rc);
printf("Main, wait for the threads\n");
rc = pthread_join(thread, NULL);
compResults("pthread_join\n", rc);
rc = pthread_join(thread1, NULL);
compResults("pthread_join\n", rc);
rc = pthread_rwlock_destroy(&rwlock);
compResults("pthread_rwlock_destroy()\n", rc);
printf("Main completed\n");
return 0;
}
The output for this sample program will be similar to the following:
$ ./test03 Enter Testcase - ./test03 Main, initialize the read write lock Main, grab a read lock Main, grab the same read lock again Main, create the read lock thread Main - unlock the first read lock Main, create the write lock thread Entered thread, getting read lock got the rwlock read lock Entered thread, getting write lock Main - unlock the second read lock Main, wait for the threads unlock the read lock Secondary thread unlocked Got the rwlock write lock, now unlock Secondary thread unlocked Main completed