opnet 基本核心函数 －－－5 子队列函数集

2.11 子队列函数集

Subq（Subqueue）函数集是与队列模块中与单一的队列资源处理相关的核心函数的集合。

 

1. op_subq_pk_insert (subq_index, pkptr, pos_index)

此核心函数的作用是将包插入到给定子队列的指定位置，其参数说明如表2-36所示。

表2-36  op_subq_pk_insert()函数的参数说明

参数	类型	描   述
subq_index	int	给定子队列的索引（子队列索引从0开始，依次加1递增，无上限）
pkptr	Packet*	指向给定包的指针
pos_index	int	子队列中包应插入的位置索引

1）返回值

int——表明插入是否成功的插入代码。该返回代码值包括以下符号常量：OPC_QINS_OK、OPC_QINS_FAIL、OPC_QINS_PK_ERROR、OPC_QINS_SEL_ERROR。

2）详解

如果位置索引小于零或不是系统支持的符号常量（OPC_QPOS_PRID、OPC_QPOS_HEAD或OPC_QPOS_TAIL），那么该函数将把包插入到子队列的队列头。同样，如果位置索引大于等于子队列中包的总数，那么该函数将把包插入到子队列的队列尾。

又若位置索引为OPC_QPOS_PRID，函数将根据包的优先级对其进行插入。优先级越高的包越靠近队列头，没有指定优先级（OPC_PRiO_NOT_SET）的包将被插入到最后。如果子队列中存在一个或多个具有相同优先级的包，则新包将立即被手稿到它们后面。

注意：当采用OPC_QPOS_PRID插入包时，必须首先使用函数op_subq_sort()对子队列进行优先级排序。

子队列初始化为空，可通过函数op_subq_pk_insert()将包插入到子队列中，通过函数op_subq_pk_remove()、op_subq_flush()或op_q_flush(0将包从子队列中移除。由于子队列容量有限，插入包操作可能失败，帮此时进程将对包进行灵活处理（如销毁、回送到源等），包状态不会受到影响。

此外，该核心函数的安全级别为Forced serialization。

3）目的

该核心函数提供了惟一一种将包插入到子队列中的方法。位置索引参数可以灵活地确定给定包插入的位置，既可以是具体的数值，也可以是包的优先级。

4）错误

Program Abort：核心函数需要队列上下文。

Program Abort：包指针为空。

Program Abort：包指针指向已销毁包。

Program Abort：包指针指向静态包。

Program Abort：分段错误（由畸形包引起）。

Recoverable Error：子队列选择标记不可识别（此时返回OPC_QINS_SEL_ERROR）。

Recoverable Error：包已插入到子队列中（引时返回OPC_QINS_PK_ERROR）。

注意：如果由于队列或子队列的容量不够而引起的包插入失败，将返回常量OPC_QINS_FAIL，但这不属于错误。

5）相关函数

采用op_subq_pk_access()获取包在子队列中的指针，但关不将包从子队列中移除。

采用op_subq_pk_remove()将包从子队列中移除，并获取其指针。

采用op_subq_pk_swap()交换两个包在子队列中的位置。

采用op_subq_flush()移除子队列中所有的包。

 

2. op_subq_pk_remove (subq_index, subq_index)

此核心函数的作用是获取包在子队列中的位置指针，并将其从子队列中移除，其参数说明如表2-37所示。

表2-37  op_subq_pk_remove()函数的参数说明

参数	类型	描   述
subq_index	int	相关子队列的索引
subq_index	int	子队列中需移除的包所在位置的索引（队列头的位置索引为0，依次加1递增，直到队列尾）

1）返回值

Packet*——从给定子队列中移除的包的指针，如果发生可恢复错误，则返回OPC_NIL。

2）详解

只能在队列模块中运行的进程上下文中调用该核心函数（或由队列进程调用的函数调用），如果处理器或管道阶段运行的进程调用该函数，那么将发行错误。

如果位置索引为负值，或大于等于队列中包的数目，那么将产生可恢复错误并返回常量OPC_NIL。

此外，该核心函数的安全级别为Forced serialization。

3）目的

提供了惟一一种将包非破坏性地从子队列中移除的机制。通过其他函数，如op_subq_flush()和op_q_flush()也可将包从子队列中移除。位置索引参数可灵活地确定哪个包将被移除，它可以是一个具体的数值，也可以由包的优先级确定，此进高优先级的包无论在哪个位置都将被移除。

4）错误

Program Abort：核心函数需要上下文。

Recoverable Error：子队列选择标记不可识别。

Recoverable Error：位置索引超出子队列范围。

5）相关函数

采用op_subq_pk_access()获取包在子队列中的指针，但关不将包从子队列中移除。

采用op_subq_pk_insert()将包插入到子队列中。

采用op_subq_pk_swap()交换两个包在子队列中的位置。

采用op_subq_flush()移除子队列中所有的包。