ClassesClasses | | Operators

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::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)

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


ClassesClasses | | Operators