TutRwMutexCreate

Name

TutRwMutexCreate — create a multiple-reader/single-writer (R/W) mutex

Synopsis

T_RW_MUTEX TutRwMutexCreate(initial_state, read_quota) 
T_BOOL initial_state; 
T_INT4 read_quota; 

Arguments

initial_state — TRUE if R/W mutex is to be initially write-locked

read_quota — initial number of simultaneous readers to be supported

Return Values

R/W mutex object if successful, T_INVALID_RW_MUTEX otherwise.

Diagnostics

If TutRwMutexCreate fails, it returns T_INVALID_RW_MUTEX and sets the global SmartSockets error number to one of:

Description

TutRwMutexCreate creates a multiple-reader/single-writer mutex. R/W mutexes are useful for protecting a shared resource in scenarios where multiple threads need to examine the state of the resource concurrently, but exclusive access must still be available so that the state can be safely changed.

Normal mutexes have only one locking operation (TutMutexLock) and can only be locked by one thread. R/W mutexes have two different locking operations: TutRwMutexReadLock and TutRwMutexWriteLock. TutRwMutexReadLock is used to obtain a read-lock, making the calling thread a reader-thread. Likewise, TutRwMutexWriteLock is used to obtain a write-lock and makes the caller a writer-thread. Up to T_MAX_READ_QUOTA reader-threads are allowed to lock a R/W mutex concurrently. In contrast, only one writer-thread is allowed at a time, and it excludes access to all other reader-threads and writer-threads for as long as it holds a lock. This defines the priority of locks — write-locks are of greater priority than read-locks.

Because there is no mechanism for taking a lock away from a thread once it has been granted, TutRwMutexWriteLock may need to suspend the calling thread until all of the read-locks have been released. If new read-locks were granted during this time, the thread calling TutRwMutexWriteLock might wait indefinitely, never getting a chance to update the protected resource. For that reason, waiting writer-threads preempt new reader threads. Threads calling TutRwMutexReadLock are suspended until waiting writer-threads have had their turn (unless the thread calling TutRwMutexReadLock already has a lock).

Like normal mutexes, R/W mutexes can be recursively locked. A thread is never suspended by a recursive lock operation, which for a R/W mutex is specially defined as a lock operation of equal or lesser priority to a lock already granted. This means that a thread already granted a read-lock always succeeds immediately in obtaining another read-lock, and a thread already granted a write-lock succeeds immediately in obtaining either a read-lock or a write-lock. A single thread holding multiple read-locks is still only a single reader-thread so far as the quota is concerned.

If a reader-thread attempts to write-lock the R/W mutex, it automatically has its read-lock upgraded. This means the thread is suspended (if necessary) until all other reader-threads have released their locks, and then is granted a write-lock (upgrades preempt normal write-lock acquisitions and are FIFO with respect to other upgraders). The thread is then a writer-thread and remains a writer-thread until all of its locks have been released. It is possible to explicitly upgrade to a write-lock with TutRwMutexUpgradeLock. TutRwMutexUpgradeLock also takes a timeout, making it useful for acquiring write-locks in time-sensitive scenarios.

Caution

None

See Also

TutRwMutexDestroy, TutRwMutexReadLock, TutRwMutexUnlock, TutRwMutexUpgradeLock, TutRwMutexWriteLock

Examples

This example creates a R/W mutex:

T_RW_MUTEX rw_mutex; 
 
rw_mutex = TutRwMutexCreate(FALSE, 4); 
if (T_INVALID_RW_MUTEX == rw_mutex) { 
  /* error */ 
}