op_prg_list_remove()
摘要
从指定列表的指定位置移除一个元素,并返回指向该元素的指针。
注意: 该内核过程是一个仅为向后兼容而保留的宏调用。新代码应使用 prg_list_remove()。
语法
op_prg_list_remove (list_ptr, pos_index)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
List* |
指向目标列表的指针 [列表指针可以从多个内核过程获得:空列表可由 op_prg_list_create() 获得;表示文件内容的列表可由 op_prg_gdf_read() 获得;列表可由用户代码分配并通过 op_prg_list_init() 初始化。]。 |
pos_index |
int |
待访问元素在列表中的数字位置索引 [位置索引从列表表头的 0 开始,逐次加 1 直到表尾。除明确的数字位置索引外,也可以指定抽象的列表位置索引;可取的值为 OPC_LISTPOS_HEAD 和 OPC_LISTPOS_TAIL。] |
返回类型
void*
指向从指定列表中移除的元素的指针。
[如果指定的位置索引大于指定列表表尾元素的索引,或者索引小于零,将返回由符号常量 OPC_NIL 代表的特殊值。]
示例
摘自:示例模型(std/ip);外部 C 文件(ip_frag_sup.ex.c);函数(ip_frag_sup_insert())。
/* Test if this completes the overall datagram. */
if (ifl_ptr->total_bytes_rcvd == ifl_ptr->total_bytes_reqd)
{
/* --trace "if" statement removed from example-- */
/* Extract the overall ip datagram so that it can be returned. */
ip_pkptr = ifl_ptr->ip_pkptr;
/* remove the ip fragment record from the datagram list. */
op_prg_list_remove (dl_ptr->dgram_list_ptr, i);
/* Deallocate its memory */
op_prg_mem_free (ifl_ptr);
FRET (ip_pkptr)
}
详情
元素可以按任意顺序从列表中移除,通过 pos_index 参数确定移除位置。当从列表表尾以外的位置移除元素时,移除点与表尾之间的元素的位置索引会依次减一。若尝试在负的位置索引或大于列表大小的位置索引处移除元素,则不会移除任何元素,并返回一个空指针(OPC_NIL)。
本内核过程返回的指针值应被转换为合适的数据类型,以访问元素的内容。下面的例子展示了这一点,其中数据结构类型 block 的实例被存储在列表中:
struct block *bptr;
bptr = (struct block *) op_prg_list_remove (list_ptr, OPC_LISTPOS_HEAD);
注意: 该内核过程不是 MT 安全的,如 “Multi-Threading Safety“ 第 11 页所述。对共享列表的访问必须由外部串行化。
用途
提供一种从列表中移除元素并访问该元素的机制。通常用于顺序处理列表的内容。列表处理可以先通过内核过程 op_prg_list_size() 确定列表中的元素数量,然后构造一个循环,通过调用 op_prg_list_remove() 每次从列表表头移除一个元素。
错误
- 程序中止:段错误。(由于列表指针无效或列表格式错误)
- 可恢复错误:列表位置(
<pos_index>)超出范围。
参考
- 使用内核过程 op_prg_list_insert() 向列表中插入新元素
- 使用内核过程 op_prg_list_access() 获取列表中某元素的指针而不将其移除
- 使用内核过程 op_prg_list_size() 确定列表中的元素数量