TutMutexCreate

Name

TutMutexCreate — create a mutex object

Synopsis

T_MUTEX TutMutexCreate(initial_state) 
T_BOOL initial_state;

Arguments

initial_state — TRUE if mutex is to be initially locked

Return Values

Mutex object if successful, T_INVALID_MUTEX otherwise.

Diagnostics

If TutMutexCreate fails, it returns T_INVALID_MUTEX 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 error value.

T_ERR_TYPE_MISMATCH — the platform does not support threads.

T_ERR_VAL_INVALID — initial_state was not a valid boolean value.

Description

TutMutexCreate creates a mutual exclusion synchronization (mutex) object. Mutexes provide the mechanism by which a thread can secure exclusive access to a shared resource. All threads that wish to use the resource must first obey the convention of calling TutMutexLock with the associated mutex before accessing the resource and TutMutexUnlock with the mutex when they are finished.

The mutexes implemented by this API are recursive. This means that a thread that has locked a mutex can safely lock the same mutex again without deadlocking. The thread continues to own the mutex until each of its calls to TutMutexLock has been balanced by a call to TutMutexUnlock.

Destroy the mutex object when it is no longer needed by calling TutMutexDestroy.

Caution

None

Examples

This example creates a mutex, locks it around a protected region of code, and then destroys the mutex:

T_MUTEX mutex; 
T_BOOL status; 
 
mutex = TutMutexCreate(FALSE); 
if (T_INVALID_MUTEX == mutex) { 
  /* error */ 
} 
 
/* lock the mutex */ 
if (!TutMutexLock(mutex, T_TIMEOUT_FOREVER)) { 
  /* error */ 
} 
 
... 
 
/* unlock the mutex */ 
if (!TutMutexUnlock(mutex)) { 
  /* error */ 
} 
 
if (!TutMutexDestroy(mutex)) { 
  /* error */ 
}