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()移除子隊列中所有的包。