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>)创建
参考
- 使用内核过程 op_prg_mt_mutex_destroy() 销毁不再需要的互斥锁
- 使用内核过程 op_prg_mt_mutex_lock() 锁定特定互斥锁
- 使用内核过程 op_prg_mt_mutex_unlock() 解锁特定互斥锁