Operator Reference

HALCON Operator Reference / System / Multithreading
ClassesClasses | | Operators

create_mutexT_create_mutexCreateMutexCreateMutexcreate_mutex (Operator)

create_mutexT_create_mutexCreateMutexCreateMutexcreate_mutex — 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)

def create_mutex(attrib_name: MaybeSequence[Union[int, float, str]], attrib_value: MaybeSequence[Union[int, float, str]]) -> HHandle

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_mutexCreateMutexCreateMutexcreate_mutex allocates and initializes the mutex object according to the attributes specified in AttribNameAttribNameAttribNameattribNameattrib_name and AttribValueAttribValueAttribValueattribValueattrib_value. AttribNameAttribNameAttribNameattribNameattrib_name specifies the attribute class and AttribValueAttribValueAttribValueattribValueattrib_value 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

  • Multithreading type: independent (runs in parallel even with exclusive operators).
  • Multithreading scope: global (may be called from any thread).
  • Processed without parallelization.

Parameters

AttribNameAttribNameAttribNameattribNameattrib_name (input_control)  number(-array) → HTupleMaybeSequence[Union[int, float, str]]HTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Mutex attribute class.

Default: []

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

AttribValueAttribValueAttribValueattribValueattrib_value (input_control)  number(-array) → HTupleMaybeSequence[Union[int, float, str]]HTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Mutex attribute kind.

Number of elements: AttribValue == AttribName

Default: []

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

MutexHandleMutexHandleMutexHandlemutexHandlemutex_handle (output_control)  mutex → HMutex, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Mutex synchronization object.

Result

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

Possible Successors

lock_mutexlock_mutexLockMutexLockMutexlock_mutex, clear_mutexclear_mutexClearMutexClearMutexclear_mutex

See also

clear_mutexclear_mutexClearMutexClearMutexclear_mutex

Module

Foundation

ClassesClasses | | Operators