create_mutexT_create_mutexCreateMutexCreateMutex (Operator)

Name

create_mutexT_create_mutexCreateMutexCreateMutex — Create a mutual exclusion synchronization object.

Signature

create_mutex( : : AttribName, AttribValue : MutexHandle)

Herror T_create_mutex(const Htuple AttribName, const Htuple AttribValue, Htuple* MutexHandle)

void CreateMutex(const HTuple& AttribName, const HTuple& AttribValue, HTuple* MutexHandle)

void HMutex::HMutex(const HTuple& AttribName, const HTuple& AttribValue)

void HMutex::HMutex(const HString& AttribName, const HString& AttribValue)

void HMutex::HMutex(const char* AttribName, const char* AttribValue)

void HMutex::HMutex(const wchar_t* AttribName, const wchar_t* AttribValue)   (Windows only)

void HMutex::CreateMutex(const HTuple& AttribName, const HTuple& AttribValue)

void HMutex::CreateMutex(const HString& AttribName, const HString& AttribValue)

void HMutex::CreateMutex(const char* AttribName, const char* AttribValue)

void HMutex::CreateMutex(const wchar_t* AttribName, const wchar_t* AttribValue)   (Windows only)

static void HOperatorSet.CreateMutex(HTuple attribName, HTuple attribValue, out HTuple mutexHandle)

public HMutex(HTuple attribName, HTuple attribValue)

public HMutex(string attribName, string attribValue)

void HMutex.CreateMutex(HTuple attribName, HTuple attribValue)

void HMutex.CreateMutex(string attribName, string attribValue)

Description

A mutex is a synchronization object that negotiates mutual exclusion among threads of a single process to avoid simultaneous modifications on common resources such as global variables. A mutex has two possible states: unlocked, i.e., not owned by any thread, and locked, i.e., owned by one certain thread. Threads attempting to lock a mutex that is already owned by another thread, i.e., locked, wait until the owning thread unlocks the mutex first. Unlike events, a thread has to own a mutex to unlock it.

create_mutexcreate_mutexCreateMutexCreateMutexCreateMutex allocates and initializes the mutex object according to the attributes specified in AttribNameAttribNameAttribNameAttribNameattribName and AttribValueAttribValueAttribValueAttribValueattribValue. AttribNameAttribNameAttribNameAttribNameattribName specifies the attribute class and AttribValueAttribValueAttribValueAttribValueattribValue the kind of the mutex. The description beneath lists all mutex kinds supported by following classes:

''""""""""

empty string sets the default attributes.

'type'"type""type""type""type"

specifies what happens if a thread attempts to lock a mutex that is already owned:

'sleep'"sleep""sleep""sleep""sleep"

simply suspends the calling thread (default). The behavior is undefined, if the thread is already owner of the mutex.

'spin'"spin""spin""spin""spin"

a fast mutex implementation that is busy waiting for the signaled mutex. The behavior is undefined, if the thread is already owner of the mutex.

'recursive'"recursive""recursive""recursive""recursive"

suspends the calling thread if the thread is not owner of the mutex. But a recursive mutex can be acquired again by the owning thread. A recursive mutex does not become unlocked until the number of unlock requests equals the number of successful lock requests.

The mutex is unlocked when created.

Execution Information

Parameters

AttribNameAttribNameAttribNameAttribNameattribName (input_control)  number(-array) HTupleHTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Mutex attribute class.

Default value: []

List of values: 'type'"type""type""type""type"

AttribValueAttribValueAttribValueAttribValueattribValue (input_control)  number(-array) HTupleHTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Mutex attribute kind.

Number of elements: AttribValue == AttribName

Default value: []

List of values: 'recursive'"recursive""recursive""recursive""recursive", 'sleep'"sleep""sleep""sleep""sleep", 'spin'"spin""spin""spin""spin"

MutexHandleMutexHandleMutexHandleMutexHandlemutexHandle (output_control)  mutex HMutex, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Mutex synchronization object.

Result

create_mutexcreate_mutexCreateMutexCreateMutexCreateMutex returns 2 (H_MSG_TRUE) if all parameters are correct. If necessary, an exception is raised.

Possible Successors

lock_mutexlock_mutexLockMutexLockMutexLockMutex, clear_mutexclear_mutexClearMutexClearMutexClearMutex

See also

clear_mutexclear_mutexClearMutexClearMutexClearMutex

Module

Foundation