Initializing Read-Write Locks With Intraprocess Scope

#include <thread.h>

rwlock_t rwlp;
int ret;

/* to be used within this process only */
ret = rwlock_init(&rwlp, USYNC_THREAD, 0); 

Initializing Read-Write Locks With Interprocess Scope

#include <thread.h>

rwlock_t rwlp;
int ret;

/* to be used among all processes */
ret = rwlock_init(&rwlp, USYNC_PROCESS, 0); 

Return Values

rwlock_init() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

Invalid argument.

EFAULT

rwlp or arg points to an illegal address.

Acquire a Read Lock

rw_rdlock(3THR)

#include <synch.h> (or #include <thread.h>)

int rw_rdlock(rwlock_t *rwlp);

Use rw_rdlock(3THR) to acquire a read lock on the read-write lock pointed to by rwlp. When the read-write lock is already locked for writing, the calling thread blocks until the write lock is released. Otherwise, the read lock is acquired. (For POSIX threads, see "pthread_rwlock_rdlock(3THR)".)

Return Values

rw_rdlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

Invalid argument.

EFAULT

rwlp points to an illegal address.

Try to Acquire a Read Lock

rw_tryrdlock(3THR)

#include <synch.h>  (or #include <thread.h>)

int rw_tryrdlock(rwlock_t *rwlp);

Use rw_tryrdlock(3THR) to attempt to acquire a read lock on the read-write lock pointed to by rwlp. When the read-write lock is already locked for writing, it returns an error. Otherwise, the read lock is acquired. (For POSIX threads, see "pthread_rwlock_tryrdlock(3THR)".)

Return Values

rw_tryrdlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

Invalid argument.

EFAULT

rwlp points to an illegal address.

EBUSY

The read-write lock pointed to by rwlp was already locked.

Acquire a Write Lock

rw_wrlock(3THR)

#include <synch.h>  (or #include <thread.h>)

int rw_wrlock(rwlock_t *rwlp);

Use rw_wrlock(3THR) to acquire a write lock on the read-write lock pointed to by rwlp. When the read-write lock is already locked for reading or writing, the calling thread blocks until all the read locks and write locks are released. Only one thread at a time can hold a write lock on a read-write lock. (For POSIX threads, see "pthread_rwlock_wrlock(3THR)".)

Return Values

rw_wrlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

Invalid argument.

EFAULT

rwlp points to an illegal address.

Try to Acquire a Write Lock

rw_trywrlock(3THR)

#include <synch.h>  (or #include <thread.h>)

int rw_trywrlock(rwlock_t *rwlp);

Use rw_trywrlock(3THR) to attempt to acquire a write lock on the read-write lock pointed to by rwlp. When the read-write lock is already locked for reading or writing, it returns an error. (For POSIX threads, see "pthread_rwlock_trywrlock(3THR)".)

Return Values

rw_trywrlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

Invalid argument.

EFAULT

rwlp points to an illegal address.

EBUSY

The read-write lock pointed to by rwlp was already locked.

Unlock a Read-Write Lock

rw_unlock(3THR)

#include <synch.h>  (or #include <thread.h>)

int rw_unlock(rwlock_t *rwlp);

Use rw_unlock(3THR) to unlock a read-write lock pointed to by rwlp. The read-write lock must be locked and the calling thread must hold the lock either for reading or writing. When any other threads are waiting for the read-write lock to become available, one of them is unblocked. (For POSIX threads, see "pthread_rwlock_unlock(3THR)".)

Return Values

rw_unlock() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

Invalid argument.

EFAULT

rwlp points to an illegal address.

Destroy Read-Write Lock State

rwlock_destroy(3THR)

#include <synch.h>  (or #include <thread.h>)

int rwlock_destroy(rwlock_t *rwlp);

Use rwlock_destroy(3THR) to destroy any state associated with the read-write lock pointed to by rlwp. The space for storing the read-write lock is not freed. (For POSIX threads, see "pthread_rwlock_destroy(3THR)".)

Return Values

rwlock_destroy() returns zero after completing successfully. Any other return value indicates that an error occurred. When any of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

Invalid argument.

EFAULT

rwlp points to an illegal address.

Read-Write Lock Example

Example 8-1 uses a bank account to demonstrate read-write locks. While the program could allow multiple threads to have concurrent read-only access to the account balance, only a single writer is allowed. Note that the get_balance() function needs the lock to ensure that the addition of the checking and saving balances occurs atomically.

Example 8-1 Read-Write Bank Account

rwlock_t account_lock;
float checking_balance = 100.0;
float saving_balance = 100.0;
...
rwlock_init(&account_lock, 0, NULL);
...

float
get_balance() {
    float bal;

    rw_rdlock(&account_lock);
    bal = checking_balance + saving_balance;
    rw_unlock(&account_lock);
    return(bal);
}

void
transfer_checking_to_savings(float amount) {
    rw_wrlock(&account_lock);
    checking_balance = checking_balance - amount;
    saving_balance = saving_balance + amount;
    rw_unlock(&account_lock);
}