op_prg_mt_mutex_create()
Abstract
Creates and initializes a mutex.
Syntax
op_prg_mt_mutex_create (options, rank, description)
| Argument | Type | Description |
|---|---|---|
options |
int |
Options for mutex behavior (see Details or Table 62 “Mutex Creation Options Symbolic Constants“ on page 17 for more information). |
rank |
int |
Rank for the new mutex. If the OPC_MT_MUTEX_RANK_CHECK option is specified, this value is checked when locking or unlocking occurs to ensure no lower-ranked mutex is already locked. |
description |
const char * |
Name for the mutex. Should be descriptive of the specified options. |
Return Type
PrgT_Mutex *
Newly created mutex.
Example
/* Create the mutex that will be used to serialize the accessing of roaming */
/* information between the receiver's power stage and MAC. Since each MAC- */
/* receiver pair will have its own mutex, include the MAC's address in the */
/* name of the mutex. */
sprintf (name_str, "MAC %d Roaming Info Mutex", my_address);
roam_state_ptr->roam_info_mutex =
op_prg_mt_mutex_create (OPC_MT_MUTEX_NO_OPTIONS, 0, name_str);
/* Lock the mutex. It will be locked at the beginning of exit execs, and */
/* unlocked at the end of enter execs, of each unforced state excluding the */
/* initialization states. */
op_prg_mt_mutex_lock (roam_state_ptr->roam_info_mutex, 0);
Details
options can be OPC_MT_MUTEX_NO_OPTIONS or a combination of the following symbolic constants:
| Symbolic Constant | Description |
|---|---|
OPC_MT_MUTEX_RANK_CHECK |
Rank is meaningful—mutex hierarchy checking should be enabled. |
OPC_MT_MUTEX_READER_WRITER¹ |
Mutex is a reader/writer—multiple readers are allowed in parallel. |
OPC_MT_MUTEX_RECURSIVE¹ |
Mutex is recursive—multiple locks by the same thread without unlocks will not generate errors. If multiple locks are performed, an equal number of unlocks are needed before the mutex is actually unlocked. |
Note 1: OPC_MT_MUTEX_READER_WRITER and OPC_MT_MUTEX_RECURSIVE are mutually exclusive and should not be specified together.
If you invoke op_prg_mt_mutex_create() multiple times with the same rank and description, a single mutex is created and the same pointer is returned. This behavior is useful when multiple threads of code all need to create the same mutex. One thread creates the mutex. When the other threads make their op_prg_mt_mutex_create() calls, the same pointer is returned and no new mutex is created. This means that you need to make only one call to op_prg_mt_mutex_destroy().
When using multiple mutexes, take care to avoid deadlock, in which two or more objects are prevented from completing the locking or unlocking of their respective mutexes. See “Mutexes“ on page 420 for more information about deadlock.
You can take advantage of these techniques to detect and avoid possible deadlocks:
- Use the
rankargument when you create the mutex. This argument assigns a numeric rank to each mutex. Locking a ranked mutex fails if a higher-numbered mutex has already been locked by the same thread of code, thus flagging potential sources of deadlock. - Be cautious in using the value
OPC_MT_MUTEX_RECURSIVEwhen you create a mutex. If you do not use this option, locking fails if a thread attempts to lock a mutex it has already locked. This failure flags a possible error (the previous lock is not affected). However, if the mutex was created with the optionOPC_MT_MUTEX_RECURSIVE, locking succeeds and no error is flagged. The mutex must then be unlocked the same number of times it was locked before other threads can access the mutex. - Globally disable the checking of mutex ranks (whether or not the
OPC_MT_MUTEX_RANK_CHECKflag is set for a mutex) by running the simulation with theparallel_sim.mutex_rank_ignorepreference set to TRUE.
The rank argument can be any integer value. If you use rank, make sure the options argument contains the flag OPC_MT_MUTEX_RANK_CHECK. Using the description argument makes it easy to identify the mutex in question when debugging.
Purpose
Provides a way to create a new mutex.
Errors
- Recoverable Error: Mutex (
<description>): creation flagsOPC_MT_MUTEX_READER_WRITERandOPC_MT_MUTEX_RECURSIVEare mutually exclusive - Recoverable Error: Invalid mutex rank (
<rank>) for (<description>) - Recoverable Error: Duplicate mutex rank (
<rank>) for (<description>) - Recoverable Error: Empty mutex description
- Recoverable Error: Null mutex description
- Recoverable Error: Mutex (
<description>) has already been created with different options (<existing_options>vs<new_options>) - Recoverable Error: Mutex (
<description>) has already been created with a different rank (<existing_rank>vs<new_rank>)
Reference
- Use the KP op_prg_mt_mutex_destroy() to destroy an unneeded mutex
- Use the KP op_prg_mt_mutex_lock() to lock a specific mutex
- Use the KP op_prg_mt_mutex_unlock() to unlock a specific mutex