list
list 提供双向链表和哈希链表的基础操作,包括节点插入、删除、替换、移动、旋转、切割、合并,以及链表空/单节点判断等功能。
头文件清单
接口清单
Functions
OSAL_INIT_LIST_HEAD
头文件清单
功能说明
- 初始化双向链表头节点,将其next和prev指针均指向自身
- 适用于创建新的空链表或重置已有链表头
- 入参为NULL时函数直接返回,不做任何操作
前置条件
- list指针应指向已分配的有效内存空间
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 指向待初始化的链表头节点指针 | 非NULL |
osal___list_add
void osal___list_add(struct osal_list_head *_new, struct osal_list_head *prev, struct osal_list_head *next)
头文件清单
功能说明
- 在两个已知连续节点之间插入新节点,用于内部链表操作
- 当已知prev和next节点时,可直接插入避免遍历查找
- 任一入参为NULL时函数直接返回,不做任何操作
前置条件
- prev和next必须为同一链表中相邻的连续节点
- _new应指向已分配的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| _new | struct osal_list_head * | 待插入的新节点指针 | 非NULL |
| prev | struct osal_list_head * | 新节点的前驱节点指针 | 非NULL |
| next | struct osal_list_head * | 新节点的后继节点指针 | 非NULL |
osal_list_add
头文件清单
功能说明
- 在指定链表头节点之后插入新节点,适用于栈结构的实现
- 新节点插入后成为链表中的第一个有效节点
- 内部调用osal___list_add完成实际插入操作
前置条件
- head应指向已初始化的链表头节点
- cur应指向已分配的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| cur | struct osal_list_head * | 待插入的新节点指针 | 非NULL |
| head | struct osal_list_head * | 链表头节点指针,新节点插入其后 | 非NULL |
osal_list_add_tail
头文件清单
功能说明
- 在指定链表头节点之前插入新节点,适用于队列结构的实现
- 新节点插入后成为链表中的最后一个有效节点
- 内部调用osal___list_add完成实际插入操作
前置条件
- head应指向已初始化的链表头节点
- cur应指向已分配的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| cur | struct osal_list_head * | 待插入的新节点指针 | 非NULL |
| head | struct osal_list_head * | 链表头节点指针,新节点插入其前 | 非NULL |
osal___list_del
头文件清单
功能说明
- 通过使前后节点互相指向对方来删除链表中间节点,用于内部链表操作
- 删除操作后prev和next形成直接链接关系
- 任一入参为NULL时函数直接返回,不做任何操作
前置条件
- prev和next必须为同一链表中的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| prev | struct osal_list_head * | 待删除节点的前驱节点指针 | 非NULL |
| next | struct osal_list_head * | 待删除节点的后继节点指针 | 非NULL |
osal___list_del_entry
头文件清单
功能说明
- 从链表中删除指定节点,使前后节点互相指向对方
- 删除后entry节点脱离链表但未被置为无效状态
- entry为NULL时函数直接返回,不做任何操作
前置条件
- entry应处于已链接的链表节点中
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| entry | struct osal_list_head * | 待删除的链表节点指针 | 非NULL |
osal_list_del
头文件清单
功能说明
- 从链表中删除节点并将其next和prev指针置为POISON值,标记为无效状态
- 删除后entry节点处于未定义状态,不可再用于链表操作
- entry为NULL时函数直接返回,不做任何操作
前置条件
- entry应处于已链接的链表节点中
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| entry | struct osal_list_head * | 待删除的链表节点指针 | 非NULL |
osal_list_replace
头文件清单
功能说明
- 用新节点替换链表中的旧节点,新节点继承旧节点的链表位置
- 替换后旧节点的next和prev指针保持不变,但已脱离链表
- 适用于链表节点的原地替换场景
前置条件
- old应处于已链接的链表节点中
- _new应指向已分配的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| old | struct osal_list_head * | 被替换的旧节点指针 | 非NULL |
| _new | struct osal_list_head * | 替换的新节点指针 | 非NULL |
osal_list_replace_init
头文件清单
功能说明
- 用新节点替换链表中的旧节点并重新初始化旧节点
- 替换后旧节点的next和prev均指向自身,恢复为初始空链表状态
- 适用于需要替换节点并复用旧节点的场景
前置条件
- old应处于已链接的链表节点中
- _new应指向已分配的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| old | struct osal_list_head * | 被替换的旧节点指针 | 非NULL |
| _new | struct osal_list_head * | 替换的新节点指针 | 非NULL |
osal_list_del_init
头文件清单
功能说明
- 从链表中删除节点并重新初始化该节点,使其next和prev指向自身
- 删除后entry节点恢复为初始空链表状态,可安全重新加入链表
- 适用于需要将节点从一个链表移出并准备加入其他链表的场景
前置条件
- entry应处于已链接的链表节点中
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| entry | struct osal_list_head * | 待删除并重新初始化的链表节点指针 | 非NULL |
osal_list_move
头文件清单
功能说明
- 将节点从原链表删除并添加到目标链表头部
- 移动后节点成为目标链表中的第一个有效节点
- 适用于在链表之间迁移节点的场景
前置条件
- list应处于已链接的链表节点中
- head应指向已初始化的目标链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 待移动的链表节点指针 | 非NULL |
| head | struct osal_list_head * | 目标链表头节点指针 | 非NULL |
osal_list_move_tail
头文件清单
功能说明
- 将节点从原链表删除并添加到目标链表尾部
- 移动后节点成为目标链表中的最后一个有效节点
- 适用于在链表之间迁移节点并保持FIFO顺序的场景
前置条件
- list应处于已链接的链表节点中
- head应指向已初始化的目标链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 待移动的链表节点指针 | 非NULL |
| head | struct osal_list_head * | 目标链表头节点指针 | 非NULL |
osal_list_is_last
头文件清单
功能说明
- 判断指定节点是否为链表的最后一个节点
- 通过比较节点的next指针是否指向链表头来判断
- 任一入参为NULL时返回-1
前置条件
- list应处于已链接的链表节点中
- head应指向已初始化的链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | const struct osal_list_head * | 待判断的链表节点指针 | 非NULL |
| head | const struct osal_list_head * | 链表头节点指针 | 非NULL |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 1 | 该节点是链表的最后一个节点 | list->next == head |
| 0 | 该节点不是链表的最后一个节点 | list->next != head |
| -1 | 入参为NULL | list或head为NULL |
osal_list_empty
头文件清单
功能说明
- 判断链表是否为空
- 通过比较链表头的next指针是否指向自身来判断
- 入参为NULL时返回-1
前置条件
- head应指向已初始化的链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| head | const struct osal_list_head * | 待判断的链表头节点指针 | 非NULL |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 1 | 链表为空 | head->next == head |
| 0 | 链表不为空 | head->next != head |
| -1 | 入参为NULL | head为NULL |
osal_list_empty_careful
头文件清单
功能说明
- 安全判断链表是否为空且未被其他CPU修改
- 同时检查链表头的next和prev是否均指向自身,确保没有并发修改操作
- 适用于无同步机制下判断链表状态的场景,仅当链表操作仅为list_del_init时安全
- 入参为NULL时返回-1
前置条件
- head应指向已初始化的链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| head | const struct osal_list_head * | 待判断的链表头节点指针 | 非NULL |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 1 | 链表为空且未被修改 | head->next == head && head->next == head->prev |
| 0 | 链表不为空或正在被修改 | head->next != head 或 head->next != head->prev |
| -1 | 入参为NULL | head为NULL |
osal_list_rotate_left
头文件清单
功能说明
- 将链表向左旋转,即把第一个节点移动到链表尾部
- 链表为空时不做任何操作
前置条件
- head应指向已初始化的链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| head | struct osal_list_head * | 链表头节点指针 | 非NULL |
osal_list_is_singular
头文件清单
功能说明
- 判断链表是否仅包含一个节点
- 链表不为空且头节点的next和prev指向同一节点时返回1
前置条件
- head应指向已初始化的链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| head | const struct osal_list_head * | 待判断的链表头节点指针 | 非NULL |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 1 | 链表仅包含一个节点 | 链表不为空且head->next == head->prev |
| 0 | 链表为空或包含多个节点 | 链表为空或head->next != head->prev |
osal___list_cut_position
void osal___list_cut_position(struct osal_list_head *list, struct osal_list_head *head, struct osal_list_head *entry)
头文件清单
功能说明
- 在指定位置切割链表,将head链表从开头到entry之间的节点移至list链表
- 用于内部链表操作,调用者应确保前置条件已满足
前置条件
- head链表不为空
- list应为空链表或可丢弃数据的链表
- entry应处于head链表中的节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 接收被切割节点的新链表头指针 | 非NULL |
| head | struct osal_list_head * | 原链表头指针 | 非NULL |
| entry | struct osal_list_head * | 切割位置节点指针 | 非NULL |
osal_list_cut_position
void osal_list_cut_position(struct osal_list_head *list, struct osal_list_head *head, struct osal_list_head *entry)
头文件清单
功能说明
- 将链表从指定位置切割为两个链表,把head链表从开头到entry的节点移至list链表
- 链表为空时不做任何操作
- 链表仅有一个节点且entry既不是该节点也不是head时,不做任何操作
- entry等于head时仅初始化list为空链表
前置条件
- list应为空链表或可丢弃数据的链表
- head应指向已初始化的链表头节点
- entry应处于head链表中的节点或等于head
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 接收被切割节点的新链表头指针 | 非NULL |
| head | struct osal_list_head * | 原链表头指针 | 非NULL |
| entry | struct osal_list_head * | 切割位置节点指针,可为head | 非NULL |
osal___list_splice
void osal___list_splice(const struct osal_list_head *list, struct osal_list_head *prev, struct osal_list_head *next)
头文件清单
功能说明
- 将一个链表合并到另一个链表中两个已知节点之间,用于内部链表操作
- 把list链表的所有节点插入到prev和next之间
前置条件
- list链表不为空
- prev和next为目标链表中的相邻节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | const struct osal_list_head * | 待合并的源链表头指针 | 非NULL,链表不为空 |
| prev | struct osal_list_head * | 插入位置的前驱节点指针 | 非NULL |
| next | struct osal_list_head * | 插入位置的后继节点指针 | 非NULL |
osal_list_splice
头文件清单
功能说明
- 将一个链表合并到另一个链表头部,适用于栈结构
- list链表不为空时执行合并,将list的所有节点插入到head之后
- list链表为空时不做任何操作
前置条件
- list应指向已初始化的链表头节点
- head应指向已初始化的目标链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | const struct osal_list_head * | 待合并的源链表头指针 | 非NULL |
| head | struct osal_list_head * | 目标链表头指针,源链表插入其后 | 非NULL |
osal_list_splice_tail
头文件清单
功能说明
- 将一个链表合并到另一个链表尾部,适用于队列结构
- list链表不为空时执行合并,将list的所有节点插入到head之前
- list链表为空时不做任何操作
前置条件
- list应指向已初始化的链表头节点
- head应指向已初始化的目标链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 待合并的源链表头指针 | 非NULL |
| head | struct osal_list_head * | 目标链表头指针,源链表插入其前 | 非NULL |
osal_list_splice_init
头文件清单
功能说明
- 合并两个链表并重新初始化被合并的链表
- list不为空时将list的所有节点插入到head之后,并将list重新初始化为空链表
- list为空时不做任何操作
前置条件
- list应指向已初始化的链表头节点
- head应指向已初始化的目标链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 待合并的源链表头指针,合并后将被重新初始化 | 非NULL |
| head | struct osal_list_head * | 目标链表头指针,源链表插入其后 | 非NULL |
osal_list_splice_tail_init
头文件清单
功能说明
- 合并两个链表到尾部并重新初始化被合并的链表,适用于队列结构
- list不为空时将list的所有节点插入到head之前,并将list重新初始化为空链表
- list为空时不做任何操作
前置条件
- list应指向已初始化的链表头节点
- head应指向已初始化的目标链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| list | struct osal_list_head * | 待合并的源链表头指针,合并后将被重新初始化 | 非NULL |
| head | struct osal_list_head * | 目标链表头指针,源链表插入其前 | 非NULL |
INIT_OSAL_HLIST_NODE
头文件清单
功能说明
- 初始化哈希链表节点,将其next和pprev指针置为NULL
- 适用于创建新的哈希链表节点或重置已有节点
前置条件
- h应指向已分配的有效内存空间
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| h | struct osal_hlist_node * | 待初始化的哈希链表节点指针 | 非NULL |
osal_hlist_unhashed
头文件清单
功能说明
- 判断哈希链表节点是否未被链接到任何哈希链表中
- 通过检查节点的pprev指针是否为NULL来判断
前置条件
- h应指向已初始化的哈希链表节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| h | const struct osal_hlist_node * | 待判断的哈希链表节点指针 | 非NULL |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 1 | 节点未被链接到哈希链表 | h->pprev == NULL |
| 0 | 节点已被链接到哈希链表 | h->pprev != NULL |
osal_hlist_empty
头文件清单
功能说明
- 判断哈希链表是否为空
- 通过检查链表头的first指针是否为NULL来判断
前置条件
- h应指向已初始化的哈希链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| h | const struct osal_hlist_head * | 待判断的哈希链表头指针 | 非NULL |
返回值
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 1 | 哈希链表为空 | h->first == NULL |
| 0 | 哈希链表不为空 | h->first != NULL |
osal___hlist_del
头文件清单
功能说明
- 从哈希链表中删除指定节点,使前后节点重新链接
- 删除后节点的pprev指针所指位置更新为后继节点,后继节点的pprev指向正确的前驱位置
前置条件
- n应处于已链接的哈希链表节点中
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| n | struct osal_hlist_node * | 待删除的哈希链表节点指针 | 非NULL |
osal_hlist_del
头文件清单
功能说明
- 从哈希链表中删除节点并将其next和pprev指针置为POISON值,标记为无效状态
- 删除后节点处于未定义状态,不可再用于哈希链表操作
前置条件
- n应处于已链接的哈希链表节点中
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| n | struct osal_hlist_node * | 待删除的哈希链表节点指针 | 非NULL |
osal_hlist_del_init
头文件清单
功能说明
- 从哈希链表中删除节点并重新初始化该节点
- 仅当节点处于已链接状态时执行删除和初始化操作
- 删除后节点恢复为初始状态,可安全重新加入哈希链表
前置条件
- n应指向已初始化的哈希链表节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| n | struct osal_hlist_node * | 待删除并重新初始化的哈希链表节点指针 | 非NULL |
osal_hlist_add_head
头文件清单
功能说明
- 在哈希链表头部添加节点,新节点成为链表的第一个节点
- 若原链表不为空,则更新原第一个节点的pprev指针
前置条件
- n应指向已分配的有效节点
- h应指向已初始化的哈希链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| n | struct osal_hlist_node * | 待添加的哈希链表节点指针 | 非NULL |
| h | struct osal_hlist_head * | 哈希链表头指针 | 非NULL |
osal_hlist_add_before
头文件清单
功能说明
- 在指定哈希链表节点之前添加新节点
- next节点必须不为NULL
前置条件
- n应指向已分配的有效节点
- next应处于已链接的哈希链表节点中且不为NULL
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| n | struct osal_hlist_node * | 待添加的哈希链表节点指针 | 非NULL |
| next | struct osal_hlist_node * | 参考节点指针,新节点插入其前 | 非NULL |
osal_hlist_add_after
头文件清单
功能说明
- 在指定哈希链表节点之后添加新节点
- 若n节点存在后继节点,则更新后继节点的pprev指针
前置条件
- n应处于已链接的哈希链表节点中
- next应指向已分配的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| n | struct osal_hlist_node * | 参考节点指针,新节点插入其后 | 非NULL |
| next | struct osal_hlist_node * | 待添加的哈希链表节点指针 | 非NULL |
osal_hlist_add_fake
头文件清单
功能说明
- 为哈希链表节点设置虚假的pprev指针,使其看起来已链接到哈希链表中
- 设置后可安全调用osal_hlist_del删除该节点
前置条件
- n应指向已分配的有效节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| n | struct osal_hlist_node * | 待设置虚假pprev的哈希链表节点指针 | 非NULL |
osal_hlist_move_list
头文件清单
功能说明
- 将哈希链表从一个链表头移动到另一个链表头
- 移动后原链表头的first指针置为NULL
- 若链表不为空,则更新第一个节点的pprev指针指向新链表头的first
前置条件
- old应指向已初始化的源哈希链表头节点
- cur应指向已分配的目标哈希链表头节点
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| old | struct osal_hlist_head * | 源哈希链表头指针 | 非NULL |
| cur | struct osal_hlist_head * | 目标哈希链表头指针 | 非NULL |
Structures
struct osal_list_head
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| next | struct osal_list_head * | 指向后继节点的指针 |
| prev | struct osal_list_head * | 指向前驱节点的指针 |
struct osal_hlist_node
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| next | struct osal_hlist_node * | 指向后继节点的指针 |
| pprev | struct osal_hlist_node ** | 指向前一节点next指针的地址 |
struct osal_hlist_head
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| first | struct osal_hlist_node * | 指向哈希链表第一个节点的指针 |
Macros
OSAL_LIST_POISON1
#ifndef OSAL_LIST_POISON_NULL
#define OSAL_LIST_POISON1 0x00100100
#else
#define OSAL_LIST_POISON1 0
#endif