Nginx 双向链表 ngx_queue_t
目录
一、基本概述
二、数据结构
三、接口描述与实现
1、相关宏接口
2、ngx_queue_middle
3、ngx_queue_sort
四、使用案例
整理自 nginx 1.9.2 源码 和 《深入理解 Nginx：模块开发与架构解析》
一、基本概述
双向链表的优势是可以快速进行数据插入、删除与合并操作，但其查询操作没有数组性能高。
nginx 下 ngx_queue_t 还具备如下优点：
（1）实现了排序功能；
（2）不负责节点元素的内存分配操作，只提供轻量级的节点管理功能；
（3）内存空间占用较小，每个节点元素只占用两个指针的内存损耗；
二、数据结构
typedef struct ngx_queue_s ngx_queue_t;
struct ngx_queue_s {ngx_queue_t *prev;ngx_queue_t *next;
}; Nginx 在设计 ngx_queue_t 时，由于容器与元素共用了 ngx_queue_t 结构体，为了避免 ngx_queue_t 结构体成员的意义混乱，Nginx封装了链表容器与元素的所有方法，这种情况非常少见，其他容器都需要直接使用成员变量来访问，唯有 ngx_queue_t 双向链表只能使用 API 接口进行数据访问。
三、接口描述与实现
接口大多使用宏进行封装。
1、相关宏接口
// 初始化链表容器 q，并置为空
#define ngx_queue_init(q) \(q)->prev = q; \(q)->next = q// 检测链表容器是否为空，返回结果为 0 表示链表为空
#define ngx_queue_empty(h) \(h == (h)->prev)// 将 x 节点插到 h 节点的后面一位
#define ngx_queue_insert_head(h, x) \(x)->next = (h)->next; \(x)->next->prev = x; \(x)->prev = h; \(h)->next = x// 将 x 节点插入 q 节点之后，此处可以直接复用 ngx_queue_insert_head
#define ngx_queue_insert_after ngx_queue_insert_head// 将 x 插入 h 节点前面，链表首尾相连
#define ngx_queue_insert_tail(h, x) \(x)->prev = (h)->prev; \(x)->prev->next = x; \(x)->next = h; \(h)->prev = x// 返回链表容器 h 中的第一个元素节点 ngx_queue_t 指针
#define ngx_queue_head(h) \(h)->next// 返回链表容器 h 中最后一个元素节点 ngx_queue_t 指针
#define ngx_queue_last(h) \(h)->prev// 返回容器链表结构体的指针
#define ngx_queue_sentinel(h) \(h)// 返回 q 元素的下一个元素
#define ngx_queue_next(q) \(q)->next// 返回 q 元素的前一个元素
#define ngx_queue_prev(q) \(q)->prev// 从链表中移除 x 节点，注意因为是双向链表，所以只需要 x 节点作为参数即可
#define ngx_queue_remove(x) \(x)->next->prev = (x)->prev; \(x)->prev->next = (x)->next/* h 为链表容器，q 为链表 h 中的一个元素，这个方法可以将链表 h 以元素 q 为界拆分为两个链表 h 和n，其中 h 由原链表的前半部分组成（不包含 q），而 n 由后半部分组成，q 为首元素,如果以前 n 有成员，则新的 n 为从 h 中拆分的部分加上 n 原有的数据
*/
#define ngx_queue_split(h, q, n) \(n)->prev = (h)->prev; \(n)->prev->next = n; \(n)->next = q; \(h)->prev = (q)->prev; \(h)->prev->next = h; \(q)->prev = n;// 将链表 n 合并到 h 链表的末尾
#define ngx_queue_add(h, n) \(h)->prev->next = (n)->next; \(n)->next->prev = (h)->prev; \(h)->prev = (n)->prev; \(h)->prev->next = h;/*返回 q 元素(ngx_queue_t类型)所属结构体的地址。q 为链表中某个节点指针 ngx_queue_t 类型；type 为链表元素的结构体类型名称(该结构体中必须包含 ngx_queue_t 类型的成员)；1ink 是上面这个结构体中 ngx_queue_t 类型的成员名字；例如：typedef struct {u_char* str;ngx_queue_t qEle;int num;} TestNode;
*//* Offset of member MEMBER in a struct of type TYPE. */
#define offsetof(TYPE, MEMBER) __builtin_offsetof (TYPE, MEMBER)
#define ngx_queue_data(q, type, link) \(type *) ((u_char *) q - offsetof(type, link))2、ngx_queue_middle
返回链表的中心元素，例如链表共有 N 个元素，则 ngx_queue_middle 将返回第（N/2 + 1）个元素。
ngx_queue_t *
ngx_queue_middle(ngx_queue_t *queue)
{ngx_queue_t *middle, *next;middle = ngx_queue_head(queue);if (middle == ngx_queue_last(queue)) {return middle;}next = ngx_queue_head(queue);/*middle 指针每次循环探索一步、next 指针每次循环探索两步；当 next 抵达链表尾部时，middle 正好在链表中心位置。*/for ( ;; ) {middle = ngx_queue_next(middle);next = ngx_queue_next(next);if (next == ngx_queue_last(queue)) {return middle;}next = ngx_queue_next(next);if (next == ngx_queue_last(queue)) {return middle;}}
}3、ngx_queue_sort
void
ngx_queue_sort(ngx_queue_t *queue,ngx_int_t (*cmp)(const ngx_queue_t *, const ngx_queue_t *))
{ngx_queue_t *q, *prev, *next;q = ngx_queue_head(queue);if (q == ngx_queue_last(queue)) {return;}for (q = ngx_queue_next(q); q != ngx_queue_sentinel(queue); q = next) {prev = ngx_queue_prev(q);next = ngx_queue_next(q);// q 节点是当前需要排序的节点ngx_queue_remove(q); // 下面循环将决定把 q 节点插入到什么位置；// 从 q 节点的前面节点开始比较，找到合适的位置再插入。do {// 自定义排序函数，可以降序或升序if (cmp(prev, q) <= 0) {break;}prev = ngx_queue_prev(prev);} while (prev != ngx_queue_sentinel(queue)); //查找这个元素需要插入到前面依据拍好序的队列的那个地方// 找到合适位置后插入该节点ngx_queue_insert_after(prev, q);}
}四、使用案例
定义一个简单的链表，并使用 ngx_queue_sort 方法对所有元素排序。在这个例子中，可以看到如何定义、初始化 ngx_queue_t 容器，如何定义任意类型的链表元素，如何遍历链表，如何自定义排序方法并执行排序。
// 链表元素结构体中必须包含 ngx_queue_t 类型的成员，它可以在任意位置
typedef struct
{u_char* str;ngx_queue_t qEle;int num;
} TestNode;// 升序排序
ngx_int_t compTestNode(const ngx_queue_t* a, const ngx_queue_t* b)
{/*首先使用 ngx_queue_data 方法由 ngx_queue_t 变量获取元素结构体 TestNode 的地址 */TestNode* aNode = ngx_queue_data(a, TestNode, qEle);TestNode* bNode = ngx_queue_data(b, TestNode, qEle);//返回 num 成员的比较结果return aNode->num > bNode->num;
}// 定义双向链表容器 queueContainer，并将其初始化为空链表
// 注意，ngx_queue_t 结构体遍历必须使用 ngx_queue_init 初始化
ngx_queue_t queueContainer;
ngx_queue_init(&queueContainer); ngx_queue_t 双向链表是完全不负责分配内存的，每一个链表元素必须自己管理自己所占用的内存。因此，本例在进程栈中定义了 5 个 TestNode 结构体作为链表元素，并把它们的 num 成员初始化为 0,1,2,3,4, 如下所示。
int i = 0;
TestNode node[5];
for (; i <5; i++)
{node[i].num = i;
} 下面把这 5 个 TestNode 结构体添加到 queueContainer 链表中，注意，这里同时使用了ngx_queue_insert_tail、ngx_queue_insert_head、ngx_queue_insert_after 3 个添加方法，链表中元素顺序以 num 标识应该为：3、1、0、2、4。
ngx_queue_insert_tail(&queueContainer, &node[0] qEle);
ngx_queue_insert_head(&queueContainer, &node[1].qEle);
ngx_queue_insert_tail(&queueContainer, &node[2].qEle);
// 在头节点之后插入
ngx_queue_insert_after(&queueContainer, &node[3].qEle);
ngx_queue_insert_tail(&queueContainer, &node[4].qEle);先排序，再从链表头部遍历到链表尾部。反向遍历可以使用 ngx_queue_last 和 ngx_queue_prev 实现。
// 升序排序
ngx_queue_sort(&queueContainer, compTestNode);
// 遍历链表
ngx_queue_t* q;
for (q = ngx_queue_head(&queueContainer); q != ngx_queue_sentinel(&queueContainer);q = ngx_queue_next(q))
{TestNode* eleNode = ngx_queue_data(q, TestNode, qEle);// 处理当前的链表元素 eleNode// ...
}
使用案例还可以参考：Nginx 源码学习-ngx的基本容器-ngx_queue-xueliangfei-ChinaUnix博客