TutRwMutexWriteLock

Name

TutRwMutexWriteLock — write-lock a R/W mutex

Synopsis

T_BOOL TutRwMutexWriteLock(rw_mutex) 
T_RW_MUTEX rw_mutex; 

Arguments

rw_mutex — R/W mutex object to lock

Return Values

TRUE if lock was granted, FALSE otherwise.

Diagnostics

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

Description

TutRwMutexWriteLock write-locks a R/W mutex. A write-lock implies that the thread may safely examine and modify the state of the resource protected by the R/W mutex. Write-locks exclude all other threads from accessing the resource. 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.

Like normal mutexes, R/W mutexes can be recursively locked. A thread is never suspended by a recursive lock operation. 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.

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.

Caution

Every call to TutRwMutexWriteLock should be balanced by a subsequent call to TutRwMutexUnlock.

See Also

TutRwMutexCreate, TutRwMutexReadLock, TutRwMutexUnlock, TutRwMutexUpgradeLock

Examples

This example write-locks a R/W mutex:

T_RW_MUTEX rw_mutex; 
. 
. 
. 
if (!TutRwMutexWriteLock(rw_mutex)) { 
  /* error */ 
}