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 rank argument 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_RECURSIVE when 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 option OPC_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_CHECK flag is set for a mutex) by running the simulation with the parallel_sim.mutex_rank_ignore preference 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 flags OPC_MT_MUTEX_READER_WRITER and OPC_MT_MUTEX_RECURSIVE are 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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com