TutRwMutexUpgradeLock

Name

TutRwMutexUpgradeLock — upgrade a read-lock on a R/W mutex to a write-lock

Synopsis

T_BOOL TutRwMutexUpgradeLock(rw_mutex, timeout) 
T_RW_MUTEX rw_mutex; 
T_REAL8 timeout;

Arguments

rw_mutex — R/W mutex object to update

timeout — maximum number of seconds to wait for write-lock

Return Values

TRUE if lock was upgraded, FALSE otherwise.

Diagnostics

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

T_ERR_OS — an operating system error has occurred. Call the function TutErrNumGetOs to obtain the related OS-specific error value.

T_ERR_TIMEOUT_REACHED — the timeout period was reached

T_ERR_TYPE_MISMATCH — the platform does not support threads

T_ERR_VAL_INVALID — rw_mutex was not a valid R/W mutex object

Description

TutRwMutexUpgradeLock allows a thread to explicitly upgrade from a read-lock on a R/W mutex to a write-lock. The upgrade operation does not acquire a new nested locking level— it does not need to be balanced by a call to TutRwMutexUnlock. TutRwMutexUpgradeLock also takes a timeout, making it useful for acquiring write-locks in time-sensitive scenarios.

To complete this operation, the calling thread may be suspended until all other reader-threads have released their locks (or until a timeout is occurs). Once the R/W mutex is available (upgrades preempt normal write-lock acquisitions and are FIFO with respect to other upgraders), the thread is granted a write-lock. The thread is then a writer-thread and remains a writer-thread until all of its locks have been released.

Caution

None

Examples

This example uses TutRwMutexReadLock, followed by TutRwMutexUpgradeLock, to try for five seconds to obtain a write-lock on the R/W mutex:

T_RW_MUTEX rw_mutex 
. 
. 
. 
if (!TutRwMutexReadLock(rw_mutex)) { 
  /* error */ 
} 
if (!TutRwMutexUpgradeLock(rw_mutex, 5.0)) { 
  if (T_ERR_TIMEOUT_REACHED != TutErrNumGet()) { 
    /* error */ 
  } 
  /* timeout */ 
  . 
  . 
  . 
} 
. 
. 
.