create_mutexcreate_mutexcreate_mutexCreateMutexCreateMutex (Operator)

Name

create_mutexcreate_mutexcreate_mutexCreateMutexCreateMutex — Create a mutual exclusion synchronization object.

Signature

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

Valref(”)

empty string sets the default attributes.

Valref('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.

Parallelization

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

Parameters

Result

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

Possible Successors

lock_mutexlock_mutexlock_mutexLockMutexLockMutex, clear_mutexclear_mutexclear_mutexClearMutexClearMutex

See also

clear_mutexclear_mutexclear_mutexClearMutexClearMutex

Module

Foundation