op_prg_mt_mutex_create()

摘要

创建并初始化一个互斥锁。

语法

op_prg_mt_mutex_create (options, rank, description)
参数 类型 说明
options int 互斥锁行为选项(更多信息见详情一节或表 62 “Mutex Creation Options Symbolic Constants“ 第 17 页)。
rank int 新互斥锁的等级(rank)。若指定了 OPC_MT_MUTEX_RANK_CHECK 选项,则在加锁或解锁时会检查该值,以确保没有等级更低的互斥锁已被锁定。
description const char * 互斥锁的名称,应能描述所指定的选项。

返回类型

PrgT_Mutex *

新创建的互斥锁。

示例

/* 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);

详情

options 可以是 OPC_MT_MUTEX_NO_OPTIONS,或以下符号常量的组合:

符号常量 说明
OPC_MT_MUTEX_RANK_CHECK 等级有意义——应启用互斥锁层次检查。
OPC_MT_MUTEX_READER_WRITER¹ 该互斥锁为读/写锁——允许多个读者并行。
OPC_MT_MUTEX_RECURSIVE¹ 该互斥锁是可重入的——同一线程多次加锁而不解锁不会产生错误。若进行了多次加锁,则需要相同次数的解锁才能真正解锁该互斥锁。

注 1:OPC_MT_MUTEX_READER_WRITER 与 OPC_MT_MUTEX_RECURSIVE 互斥,不应同时指定。

若以相同的等级和描述多次调用 op_prg_mt_mutex_create(),只会创建一个互斥锁并返回同一个指针。这一行为在多个代码线程都需要创建同一个互斥锁时非常有用。一个线程创建该互斥锁;当其他线程调用 op_prg_mt_mutex_create() 时,返回的是同一个指针,不会创建新的互斥锁。这意味着只需调用一次 op_prg_mt_mutex_destroy()。

使用多个互斥锁时,应注意避免死锁——即两个或更多对象相互阻碍,无法完成各自互斥锁的加锁或解锁。有关死锁的更多信息,参见“Mutexes“ 第 420 页。

可以利用以下技术来检测和避免可能的死锁:

  • 创建互斥锁时使用 rank 参数。该参数为每个互斥锁指定一个数字等级。若同一代码线程已经锁定了编号更高的互斥锁,则对带等级的互斥锁加锁会失败,从而标记出潜在的死锁来源。
  • 创建互斥锁时,谨慎使用 OPC_MT_MUTEX_RECURSIVE 这一取值。若不使用该选项,当线程试图锁定它已经锁定的互斥锁时,加锁会失败。这一失败会标记出可能的错误(先前的加锁不受影响)。但若互斥锁创建时带有 OPC_MT_MUTEX_RECURSIVE 选项,加锁会成功且不标记错误;此时该互斥锁必须被解锁与加锁相同的次数后,其他线程才能访问它。
  • 通过将仿真的 parallel_sim.mutex_rank_ignore 首选项设置为 TRUE,可全局禁用互斥锁等级检查(无论某个互斥锁是否设置了 OPC_MT_MUTEX_RANK_CHECK 标志)。

rank 参数可以是任意整数值。如果使用 rank,请确保 options 参数包含 OPC_MT_MUTEX_RANK_CHECK 标志。使用 description 参数可以在调试时方便地识别出相关的互斥锁。

用途

提供了一种创建新互斥锁的方法。

错误

  • 可恢复错误:互斥锁(<description>):创建标志 OPC_MT_MUTEX_READER_WRITER 与 OPC_MT_MUTEX_RECURSIVE 互斥
  • 可恢复错误:(<description>)的互斥锁等级(<rank>)无效
  • 可恢复错误:(<description>)的互斥锁等级(<rank>)重复
  • 可恢复错误:互斥锁描述为空
  • 可恢复错误:互斥锁描述为空指针
  • 可恢复错误:互斥锁(<description>)已以不同的选项(<existing_options> 与 <new_options>)创建
  • 可恢复错误:互斥锁(<description>)已以不同的等级(<existing_rank> 与 <new_rank>)创建

参考

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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