create_mutexT_create_mutexCreateMutexCreateMutexcreate_mutex (Operator)
Name
create_mutexT_create_mutexCreateMutexCreateMutexcreate_mutex — Create a mutual exclusion synchronization object.
Signature
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)
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_mutexCreateMutexCreateMutexCreateMutexcreate_mutex allocates and initializes the mutex object according to
the attributes specified in AttribNameAttribNameAttribNameAttribNameattribNameattrib_name and AttribValueAttribValueAttribValueAttribValueattribValueattrib_value.
AttribNameAttribNameAttribNameAttribNameattribNameattrib_name specifies the attribute class and AttribValueAttribValueAttribValueAttribValueattribValueattrib_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""type"
-
specifies what happens if a thread attempts to lock a
mutex that is already owned:
- 'sleep'"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""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""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
AttribNameAttribNameAttribNameAttribNameattribNameattrib_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 value: []
List of values: 'type'"type""type""type""type""type"
AttribValueAttribValueAttribValueAttribValueattribValueattrib_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 value: []
List of values: 'recursive'"recursive""recursive""recursive""recursive""recursive", 'sleep'"sleep""sleep""sleep""sleep""sleep", 'spin'"spin""spin""spin""spin""spin"
MutexHandleMutexHandleMutexHandleMutexHandlemutexHandlemutex_handle (output_control) mutex → HMutex, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)
Mutex synchronization object.
Result
create_mutexcreate_mutexCreateMutexCreateMutexCreateMutexcreate_mutex returns 2 (H_MSG_TRUE) if all parameters are correct.
If necessary, an exception is raised.
Possible Successors
lock_mutexlock_mutexLockMutexLockMutexLockMutexlock_mutex,
clear_mutexclear_mutexClearMutexClearMutexClearMutexclear_mutex
See also
clear_mutexclear_mutexClearMutexClearMutexClearMutexclear_mutex
Module
Foundation