redis原始碼分析（9）redis原始碼連結串列學習總結 adlist.h adlist.c

adlist的實現就比較常規了，比較ziplist簡單多了。

每個連結串列節點使用一個 adlist.h/listNode 結構來表示：

typedef struct listNode {

    // 前置節點
    struct listNode *prev;
    
    // 後置節點
    struct listNode *next;

    // 節點的值
    void *value;

} listNode;

使用list的結構體來操作list

typedef struct list {

    // 表頭節點
    listNode *head;

    // 表尾節點
    listNode *tail;

    // 連結串列所包含的節點數量
    unsigned long len;

    // 節點值複製函式
    void *(*dup)(void *ptr);

    // 節點值釋放函式
    void (*free)(void *ptr);

    // 節點值對比函式
    int (*match)(void *ptr, void *key);

} list;

list 結構為連結串列提供了表頭指標 head 、表尾指標 tail ， 以及連結串列長度計數器 len ， 而 dup 、 free 和 match 成員則是用於實現多型連結串列所需的型別特定函式：

• dup 函式用於複製連結串列節點所儲存的值；
• free 函式用於釋放連結串列節點所儲存的值；
• match 函式則用於對比連結串列節點所儲存的值和另一個輸入值是否相等。

Redis 的連結串列實現的特性可以總結如下：

• 雙端： 連結串列節點帶有 prev 和 next 指標， 獲取某個節點的前置節點和後置節點的複雜度都是 O(1) 。
• 無環： 表頭節點的 prev 指標和表尾節點的 next 指標都指向 NULL ， 對連結串列的訪問以 NULL 為終點。
• 帶表頭指標和表尾指標： 通過 list 結構的 head 指標和 tail 指標， 程式獲取連結串列的表頭節點和表尾節點的複雜度為 O(1) 。
• 帶連結串列長度計數器： 程式使用 list 結構的 len 屬性來對 list 持有的連結串列節點進行計數， 程式獲取連結串列中節點數量的複雜度為 O(1) 。
• 多型： 連結串列節點使用 void* 指標來儲存節點值， 並且可以通過 list 結構的 dup 、 free 、 match 三個屬性為節點值設定型別特定函式， 所以連結串列可以用於儲存各種不同型別的值。

/* adlist.c - A generic doubly linked list implementation
 *
 * Copyright (c) 2006-2010, Salvatore Sanfilippo <antirez at gmail dot com>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   * Redistributions of source code must retain the above copyright notice,
 *     this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *   * Neither the name of Redis nor the names of its contributors may be used
 *     to endorse or promote products derived from this software without
 *     specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */


#include <stdlib.h>
#include "adlist.h"
#include "zmalloc.h"

/* Create a new list. The created list can be freed with
 * AlFreeList(), but private value of every node need to be freed
 * by the user before to call AlFreeList().
 *
 * On error, NULL is returned. Otherwise the pointer to the new list. */
//初始化一個list
list *listCreate(void)
{
    struct list *list;

    if ((list = zmalloc(sizeof(*list))) == NULL)
        return NULL;
    list->head = list->tail = NULL;
    list->len = 0;
    list->dup = NULL;
    list->free = NULL;
    list->match = NULL;
    return list;
}

/* Remove all the elements from the list without destroying the list itself. */
//釋放整個連結串列，以及連結串列中所有節點
void listEmpty(list *list)
{
    unsigned long len;
    listNode *current, *next;

    current = list->head;
    len = list->len;
    while(len--) {
        next = current->next;
        if (list->free) list->free(current->value);
        zfree(current);
        current = next;
    }
    list->head = list->tail = NULL;
    list->len = 0;
}

/* Free the whole list.
 *
 * This function can't fail. */
//釋放整個連結串列，以及連結串列中所有節點
void listRelease(list *list)
{
    listEmpty(list);
    zfree(list);
}

/* Add a new node to the list, to head, containing the specified 'value'
 * pointer as value.
 *
 * On error, NULL is returned and no operation is performed (i.e. the
 * list remains unaltered).
 * On success the 'list' pointer you pass to the function is returned. 
 * 將一個包含有給定值指標 value 的新節點新增到連結串列的表頭
 *
 * 如果為新節點分配記憶體出錯，那麼不執行任何動作，僅返回 NULL
 *
 * 如果執行成功，返回傳入的連結串列指標
 */

list *listAddNodeHead(list *list, void *value)
{
    listNode *node;

    if ((node = zmalloc(sizeof(*node))) == NULL)
        return NULL;
    node->value = value;
    if (list->len == 0) {
        list->head = list->tail = node;
        node->prev = node->next = NULL;
    } else {
        node->prev = NULL;
        node->next = list->head;
        list->head->prev = node;
        list->head = node;
    }
    list->len++;
    return list;
}

/* Add a new node to the list, to tail, containing the specified 'value'
 * pointer as value.
 *
 * On error, NULL is returned and no operation is performed (i.e. the
 * list remains unaltered).
 * On success the 'list' pointer you pass to the function is returned. 
 * 將一個包含有給定值指標 value 的新節點新增到連結串列的表尾
 *
 * 如果為新節點分配記憶體出錯，那麼不執行任何動作，僅返回 NULL
 *
 * 如果執行成功，返回傳入的連結串列指標
 */
list *listAddNodeTail(list *list, void *value)
{
    listNode *node;

    if ((node = zmalloc(sizeof(*node))) == NULL)
        return NULL;
    node->value = value;
    if (list->len == 0) {
        list->head = list->tail = node;
        node->prev = node->next = NULL;
    } else {
        node->prev = list->tail;
        node->next = NULL;
        list->tail->next = node;
        list->tail = node;
    }
    list->len++;
    return list;
}

/*
 * 建立一個包含值 value 的新節點，並將它插入到 old_node 的之前或之後
 *
 * 如果 after 為 0 ，將新節點插入到 old_node 之前。
 * 如果 after 為 1 ，將新節點插入到 old_node 之後。
 *
 * T = O(1)
 */
list *listInsertNode(list *list, listNode *old_node, void *value, int after) {
    listNode *node;

    if ((node = zmalloc(sizeof(*node))) == NULL)
        return NULL;
    node->value = value;
    if (after) {
        node->prev = old_node;
        node->next = old_node->next;
        if (list->tail == old_node) {
            list->tail = node;
        }
    } else {
        node->next = old_node;
        node->prev = old_node->prev;
        if (list->head == old_node) {
            list->head = node;
        }
    }
    if (node->prev != NULL) {
        node->prev->next = node;
    }
    if (node->next != NULL) {
        node->next->prev = node;
    }
    list->len++;
    return list;
}

/* Remove the specified node from the specified list.
 * It's up to the caller to free the private value of the node.
 *
 * This function can't fail. 
 * 從連結串列 list 中刪除給定節點 node 
 * 
 * 對節點私有值(private value of the node)的釋放工作由呼叫者進行。
 *
 * T = O(1)*/
void listDelNode(list *list, listNode *node)
{
    if (node->prev)
        node->prev->next = node->next;
    else
        list->head = node->next;
    if (node->next)
        node->next->prev = node->prev;
    else
        list->tail = node->prev;
    if (list->free) list->free(node->value);
    zfree(node);
    list->len--;
}

/* Returns a list iterator 'iter'. After the initialization every
 * call to listNext() will return the next element of the list.
 *
 * This function can't fail. 
 * 為給定連結串列建立一個迭代器，
 * 之後每次對這個迭代器呼叫 listNext 都返回被迭代到的連結串列節點
 *
 * direction 引數決定了迭代器的迭代方向：
 *  AL_START_HEAD ：從表頭向表尾迭代
 *  AL_START_TAIL ：從表尾想表頭迭代
 */
listIter *listGetIterator(list *list, int direction)
{
    listIter *iter;

    if ((iter = zmalloc(sizeof(*iter))) == NULL) return NULL;
    if (direction == AL_START_HEAD)
        iter->next = list->head;
    else
        iter->next = list->tail;
    iter->direction = direction;
    return iter;
}

/* Release the iterator memory 
釋放迭代器
*/
void listReleaseIterator(listIter *iter) {
    zfree(iter);
}

/* Create an iterator in the list private iterator structure 
 * 將迭代器的方向設定為 AL_START_HEAD ，
 * 並將迭代指標重新指向表頭節點。
 */
void listRewind(list *list, listIter *li) {
    li->next = list->head;
    li->direction = AL_START_HEAD;
}

/*
 * 將迭代器的方向設定為 AL_START_TAIL ，
 * 並將迭代指標重新指向表尾節點。
 *
 * T = O(1)
 */
void listRewindTail(list *list, listIter *li) {
    li->next = list->tail;
    li->direction = AL_START_TAIL;
}

/* Return the next element of an iterator.
 * It's valid to remove the currently returned element using
 * listDelNode(), but not to remove other elements.
 *
 * The function returns a pointer to the next element of the list,
 * or NULL if there are no more elements, so the classical usage patter
 * is:
 * * 返回迭代器當前所指向的節點。
 *
 * 刪除當前節點是允許的，但不能修改連結串列裡的其他節點。
 *
 * 函式要麼返回一個節點，要麼返回 NULL ，常見的用法是：
 * iter = listGetIterator(list,<direction>);
 * while ((node = listNext(iter)) != NULL) {
 *     doSomethingWith(listNodeValue(node));
 * }
 *
 * */
listNode *listNext(listIter *iter)
{
    listNode *current = iter->next;

    if (current != NULL) {
        if (iter->direction == AL_START_HEAD)
            iter->next = current->next;
        else
            iter->next = current->prev;
    }
    return current;
}

/* Duplicate the whole list. On out of memory NULL is returned.
 * On success a copy of the original list is returned.
 *
 * The 'Dup' method set with listSetDupMethod() function is used
 * to copy the node value. Otherwise the same pointer value of
 * the original node is used as value of the copied node.
 *
 * The original list both on success or error is never modified. 
 * 複製整個連結串列。
 *
 * 複製成功返回輸入連結串列的副本，
 * 如果因為記憶體不足而造成複製失敗，返回 NULL 。
 *
 * 如果連結串列有設定值複製函式 dup ，那麼對值的複製將使用複製函式進行，
 * 否則，新節點將和舊節點共享同一個指標。
 *
 * 無論複製是成功還是失敗，輸入節點都不會修改。
 */
list *listDup(list *orig)
{
    list *copy;
    listIter iter;
    listNode *node;

    if ((copy = listCreate()) == NULL)
        return NULL;
    copy->dup = orig->dup;
    copy->free = orig->free;
    copy->match = orig->match;
    listRewind(orig, &iter);
    while((node = listNext(&iter)) != NULL) {
        void *value;

        if (copy->dup) {
            value = copy->dup(node->value);
            if (value == NULL) {
                listRelease(copy);
                return NULL;
            }
        } else
            value = node->value;
        if (listAddNodeTail(copy, value) == NULL) {
            listRelease(copy);
            return NULL;
        }
    }
    return copy;
}

/* Search the list for a node matching a given key.
 * The match is performed using the 'match' method
 * set with listSetMatchMethod(). If no 'match' method
 * is set, the 'value' pointer of every node is directly
 * compared with the 'key' pointer.
 *
 * On success the first matching node pointer is returned
 * (search starts from head). If no matching node exists
 * NULL is returned. 
 * 查詢連結串列 list 中值和 key 匹配的節點。
 * 
 * 對比操作由連結串列的 match 函式負責進行，
 * 如果沒有設定 match 函式，
 * 那麼直接通過對比值的指標來決定是否匹配。
 *
 * 如果匹配成功，那麼第一個匹配的節點會被返回。
 * 如果沒有匹配任何節點，那麼返回 NULL 。
 */
listNode *listSearchKey(list *list, void *key)
{
    listIter iter;
    listNode *node;

    listRewind(list, &iter);
    while((node = listNext(&iter)) != NULL) {
        if (list->match) {
            if (list->match(node->value, key)) {
                return node;
            }
        } else {
            if (key == node->value) {
                return node;
            }
        }
    }
    return NULL;
}

/* Return the element at the specified zero-based index
 * where 0 is the head, 1 is the element next to head
 * and so on. Negative integers are used in order to count
 * from the tail, -1 is the last element, -2 the penultimate
 * and so on. If the index is out of range NULL is returned. 
 * 返回連結串列在給定索引上的值。
 *
 * 索引以 0 為起始，也可以是負數， -1 表示連結串列最後一個節點，諸如此類。
 *
 * 如果索引超出範圍（out of range），返回 NULL 
 */
listNode *listIndex(list *list, long index) {
    listNode *n;

    if (index < 0) {
        index = (-index)-1;
        n = list->tail;
        while(index-- && n) n = n->prev;
    } else {
        n = list->head;
        while(index-- && n) n = n->next;
    }
    return n;
}

/* Rotate the list removing the tail node and inserting it to the head. 

取出連結串列的表尾節點，並將它移動到表頭，成為新的表頭節點。
*/
void listRotate(list *list) {
    listNode *tail = list->tail;

    if (listLength(list) <= 1) return;

    /* Detach current tail */
    list->tail = tail->prev;
    list->tail->next = NULL;
    /* Move it as head */
    list->head->prev = tail;
    tail->prev = NULL;
    tail->next = list->head;
    list->head = tail;
}

/* Add all the elements of the list 'o' at the end of the
 * list 'l'. The list 'other' remains empty but otherwise valid. */
void listJoin(list *l, list *o) {
    if (o->head)
        o->head->prev = l->tail;

    if (l->tail)
        l->tail->next = o->head;
    else
        l->head = o->head;

    l->tail = o->tail;
    l->len += o->len;

    /* Setup other as an empty list. */
    o->head = o->tail = NULL;
    o->len = 0;
}