TutMutexLock

Name

TutMutexLock — lock a mutex object

Synopsis

T_BOOL TutMutexLock(mutex, timeout) 
T_MUTEX mutex; 
T_REAL8 timeout;

Arguments

mutex — mutex object to lock

timeout — maximum number of seconds to wait for mutex

Return Values

TRUE if mutex object was successfully locked, FALSE otherwise.

Diagnostics

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

T_ERR_OS — call an operating system to obtain the related OS 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 — mutex was not a valid mutex object.

Description

TutMutexLock attempts to lock a mutex object. If mutex is not immediately available, the calling thread is suspended until the mutex becomes available or until the timeout period specified has expired. The reserved timeout value T_TIMEOUT_FOREVER may be used to specify an indefinite wait.

Caution

Every call to TutMutexLock should be balanced by a subsequent call to TutMutexUnlock.

Examples

This example attempts to lock a mutex object with a one-second timeout:

T_MUTEX mutex; 
... 
if (!TutMutexLock(mutex, 1.0)) { 
  if (T_ERR_TIMEOUT_REACHED != TutErrNumGet()) { 
    /* error */ 
  } 
  /* timeout */ 
  ... 
} 
...