op_subq_pk_insert()
摘要
将指定的数据包插入指定的子队列中的指定位置。
语法
op_subq_pk_insert (subq_index, pkptr, pos_index)
| 参数 | 类型 | 说明 |
|---|---|---|
subq_index |
int |
目标子队列的数字索引 [子队列流索引从 0 开始,依次递增 1。子队列的数量没有上限。除了显式的子队列索引,还可以指定抽象子队列选择索引。抽象子队列选择索引通过某个子队列独有的属性来指定该子队列。可接受的抽象子队列选择索引列于表 85“Subqueue Selection Index Symbolic Constants“ 第 26 页。] |
pkptr |
Packet* |
指向目标数据包的指针 |
pos_index |
int |
指定数据包要插入到的子队列内的数字位置索引 [位置索引从队列头部处的 0 开始,依次递增 1 直到尾部。除了显式的位置索引,还可以指定抽象子队列位置索引(参见表 84“Subqueue Position Index Symbolic Constants“ 第 25 页);可接受的取值为 OPC_QPOS_HEAD、OPC_QPOS_TAIL 和 OPC_QPOS_PRIO。] |
返回类型
int
插入代码,指示插入操作是否成功完成。该数字代码可与以下符号常量比较:OPC_QINS_OK、OPC_QINS_FAIL、OPC_QINS_PK_ERROR、OPC_QINS_SEL_ERROR;更多信息参见表 83“Subqueue Insertion Code Symbolic Constants“ 第 25 页。
示例
摘自:示例模型(models/std/fddi);进程模型(fddi_mac);状态(ENCAP);enter execs。
/* Compose a mac frame from all these elements */
mac_frame_ptr = op_pk_create_fmt ("fddi_mac_fr");
op_pk_nfd_set (mac_frame_ptr, "svc_class", svc_class);
op_pk_nfd_set (mac_frame_ptr, "dest_addr", dest_addr);
op_pk_nfd_set (mac_frame_ptr, "src_addr", my_address);
op_pk_nfd_set (mac_frame_ptr, "info", pdu_ptr);
if (svc_class == FDDI_SVC_ASYNC)
{
op_pk_nfd_set (mac_frame_ptr, "tk_class", req_tk_class);
op_pk_nfd_set (mac_frame_ptr, "pri", req_pri);
}
/* Assign the frame control field... */
op_pk_nfd_set (mac_frame_ptr, "fc", FDDI_FC_FRAME);
/* Enqueue the frame at the tail of the queue. */
op_subq_pk_insert (0, mac_frame_ptr, OPC_QPOS_TAIL);
详情
如果为 pos_index 指定的值不是受支持的符号常量 OPC_QPOS_PRIO、OPC_QPOS_HEAD 或 OPC_QPOS_TAIL 之一,且该值小于零,本 KP 将把数据包插入到子队列头部。类似地,如果 pos_index 大于或等于子队列中数据包的数量,本 KP 将把数据包插入到子队列尾部。
如果 pos_index 的值为 OPC_QPOS_PRIO,则数据包按照其优先级(使用 op_pk_priority_set() 赋值)插入。优先级较高的数据包比优先级较低的数据包插入得更靠近子队列头部;未指定优先级(OPC_PRIO_NOT_SET)的数据包排在最后。例如,优先级为 10.0 的数据包将插入到优先级为 5.0 的数据包之前,但排在优先级为 20.0 的数据包之后。如果子队列中已存在一个或多个优先级相同的数据包,新数据包将紧接在它们之后插入。
注意: 在使用 OPC_QPOS_PRIO 插入数据包之前,必须先对子队列按优先级排序(使用 op_subq_sort())。
子队列初始时为空。数据包通过 KP op_subq_pk_insert() 加入子队列,并通过 KP op_subq_pk_remove()、op_subq_flush() 或 op_q_flush() 从中移除。
由于子队列在可容纳的数据包数量或比特数上可能受到限制,本 KP 可能无法完成插入指定包的目标(参见下面的错误一节)。当发生此类失败时,数据包的状态不受影响,进程可以灵活地决定如何处理该情况(例如销毁数据包、将其发回源点等)。
用途
提供一种向子队列插入数据包的机制。这是数据包进入子队列的唯一方式(即仿真内核没有让数据包自动进入子队列的机制)。即使是所提供的基干排队模型,也必须显式地从其输入流中提取数据包并使用本 KP 将其插入子队列。位置索引参数为决定指定数据包应插入到哪里提供了灵活性;它可以是一个具体的数字位置(包括方便指定的头部或尾部位置),也可以是由数据包的优先级属性相对于其他数据包所决定的位置。
错误
- 程序中止:KP 需要队列上下文。
- 程序中止:数据包指针为 NIL。
- 程序中止:数据包指针引用了已被销毁的数据包。
- 程序中止:数据包指针引用了静态数据包。
- 程序中止:段违例。(由于格式错误的数据包)
- 可恢复错误:子队列选择标志(
<flag>)无法识别。(此时返回特殊常量 OPC_QINS_SEL_ERROR) - 可恢复错误:数据包(
<pk_id>)已经入队于子队列(<subq_index>)中。(此时返回特殊常量 OPC_QINS_PK_ERROR)
注意: 如果由于队列或子队列的存储容量不足导致数据包插入失败,将返回常量 OPC_QINS_FAIL;但这不被视为错误。
参考
- 使用 KP op_subq_pk_access() 获取子队列中数据包的指针,而不将数据包从子队列移除
- 使用 KP op_subq_pk_remove() 从子队列移除一个数据包,并获取其指针
- 使用 KP op_subq_pk_swap() 交换子队列中的两个数据包
- 使用 KP op_subq_flush() 移除子队列中的所有数据包