redis6.0.5之Rax阅读笔记4-Iterator(迭代器)

/* Optional callback used for iterators and be notified on each rax node,
 * including nodes not representing keys. If the callback returns true
 * the callback changed the node pointer in the iterator structure, and the
 * iterator implementation will have to replace the pointer in the radix tree
 * internals. This allows the callback to reallocate the node to perform
 * very special operations, normally not needed by normal applications.
这个函数是迭代器可选的回调函数，每个基树的节点都会被通知到，包括哪些不是键的节点。
回调返回真，如果回调改变了迭代器结构中额节点指针。迭代器的实现将替换基树内部的指针。
这个就允许回调函数可以重新分配节点内存执行一个特殊的操作，正常情况下不需要。
 * This callback is used to perform very low level analysis of the radix tree
 * structure, scanning each possible node (but the root node), or in order to
 * reallocate the nodes to reduce the allocation fragmentation (this is the
 * Redis application for this callback).
这个回调函数用来执行基树结构的底层分析，扫描每个可能的节点(除了根节点)，
或者为了重新分配节点内存从而减少分配的内存碎片(这个就是回调在redis的应用)
 * This is currently only supported in forward iterations (raxNext) */
这个函数目前只支持向前的迭代
typedef int (*raxNodeCallback)(raxNode **noderef);

/* Radix tree iterator state is encapsulated into this data structure. */
基树迭代状态都封装在下面这个数据结构中
#define RAX_ITER_STATIC_LEN 128
#define RAX_ITER_JUST_SEEKED (1<<0) /* Iterator was just seeked. Return current
                                       element for the first iteration and
                                       clear the flag. */
迭代器被找到，返回当前的第一次迭代当前元素，同时清除标志                                    
#define RAX_ITER_EOF (1<<1)    /* End of iteration reached. */   达到迭代结束
#define RAX_ITER_SAFE (1<<2)   /* Safe iterator, allows operations while
                                  iterating. But it is slower. */
安全迭代器，迭代的时候允许操作，但是这个比较慢（这个版本的代码没有看到怎么用）
typedef struct raxIterator {
    int flags;
    rax *rt;                /* Radix tree we are iterating. */  迭代的基树
    unsigned char *key;     /* The current string. */  当前字符串
    void *data;             /* Data associated to this key. */   键对应的值
    size_t key_len;         /* Current key length. */ 当前长度
    size_t key_max;         /* Max key len the current key buffer can hold. */  当前最大的可以缓存键的长度
    unsigned char key_static_string[RAX_ITER_STATIC_LEN];  初始化数组
    raxNode *node;          /* Current node. Only for unsafe iteration. */  当前节点，只针对不安全迭代
    raxStack stack;         /* Stack used for unsafe iteration. */  非安全迭代使用的栈
    raxNodeCallback node_cb; /* Optional node callback. Normally set to NULL. */ 可选节点回调函数。正常设置为空
} raxIterator;

**************************************************************************
/* Initialize a Rax iterator. This call should be performed a single time
 * to initialize the iterator, and must be followed by a raxSeek() call,
 * otherwise the raxPrev()/raxNext() functions will just return EOF. */
初始化一个rax迭代器。本调用只能在初始化的时候执行一次，而且必须随后调用函数raxSeek()，
否则函数raxPrev()/raxNext()会返回EOF
void raxStart(raxIterator *it, rax *rt) {
    it->flags = RAX_ITER_EOF; /* No crash if the iterator is not seeked. */
    不至于奔溃如果迭代器没有找到
    it->rt = rt;  基树
    it->key_len = 0;  
    it->key = it->key_static_string;
    it->key_max = RAX_ITER_STATIC_LEN; 
    it->data = NULL;
    it->node_cb = NULL;
    raxStackInit(&it->stack);
}
**************************************************************************
/* Append characters at the current key string of the iterator 'it'. This
 * is a low level function used to implement the iterator, not callable by
 * the user. Returns 0 on out of memory, otherwise 1 is returned. */
在当前迭代器it的键字符串添加字符。这是一个底层的函数用来实现迭代器，
不是由使用者调用(潜在意思就是内部调用，不对外暴露)。
返回0如果OOM，其它情况返回1
int raxIteratorAddChars(raxIterator *it, unsigned char *s, size_t len) {
    if (it->key_max < it->key_len+len) { 
    如果当前可以容量最大的字符串长度小于当前已存字符串长度和将要添加的字符串长度之和，
    意味着需要开辟新的大空间，即扩容
        unsigned char *old = (it->key == it->key_static_string) ? NULL :
                                                                  it->key;
判断使用的是否是初始化的初始化空间，是说明原来没有在堆上新分配过空间(可以新分配空间)，
否则就是分配过(需要在这个基础上扩张)                                                                  
        size_t new_max = (it->key_len+len)*2;  空间大小翻倍
        it->key = rax_realloc(old,new_max);
        if (it->key == NULL) {   内存分配失败
            it->key = (!old) ? it->key_static_string : old;
            old为空说明原来用的是初始化字符串，不为空就是分配过的堆空间
            errno = ENOMEM;
            return 0;
        }
        如果能到这里，表示内存分配成功
        if (old == NULL) memcpy(it->key,it->key_static_string,it->key_len);
        old为空的情况下。从初始化字符串数组拷贝原来数据到新分配的空间
        it->key_max = new_max; 更新最大容量
    }
    /* Use memmove since there could be an overlap between 's' and
     * it->key when we use the current key in order to re-seek. */
    在内存充足的情况下，使用函数memmove进行字符串拷贝。
    因为在使用当前键在重新查找时，字符串s和it->key之间可能存在重叠
    memmove(it->key+it->key_len,s,len);
    it->key_len += len; 键长度增加len
    return 1;
}
**************************************************************************
/* Remove the specified number of chars from the right of the current
 * iterator key. */
从当前迭代器键的右边移除特定数字的字符
void raxIteratorDelChars(raxIterator *it, size_t count) {
    it->key_len -= count; 只是减去键长度，后面的字符还是存在的
}
**************************************************************************
/* Do an iteration step towards the next element. At the end of the step the
 * iterator key will represent the (new) current key. If it is not possible
 * to step in the specified direction since there are no longer elements, the
 * iterator is flagged with RAX_ITER_EOF.
做一个向前迭代步骤到下一个元素。在这个步骤的结尾，迭代器的键将表示当前键(即新找到的键)
如果在特定方向不能向前进，因为那里没有元素了，迭代器被标记为RAX_ITER_EOF
 * If 'noup' is true the function starts directly scanning for the next
 * lexicographically smaller children, and the current node is already assumed
 * to be the parent of the last key node, so the first operation to go back to
 * the parent will be skipped. This option is used by raxSeek() when
 * implementing seeking a non existing element with the ">" or "<" options:
 * the starting node is not a key in that particular case, so we start the scan
 * from a node that does not represent the key set.
如果noup的值为真，那么这个函数从下一个字典序较小的子节点开始扫描，
当前节点被假设为最后一个一个键节点的父节点，所以第一步操作回溯到父节点课可以跳过。
这个选项被函数raxSeek在实现使用>或者<符号查找不存在元素的时候：在这个特殊情况下，
开始节点不是一个键，所以我们从一个不属于键表示的集合开始扫描
 * The function returns 1 on success or 0 on out of memory. */
本函数正常返回1如果出现OOM返回0
int raxIteratorNextStep(raxIterator *it, int noup) {
    if (it->flags & RAX_ITER_EOF) { 如果标志是RAX_ITER_EOF，结束迭代
        return 1;
    } else if (it->flags & RAX_ITER_JUST_SEEKED) {  
    如果标志是RAX_ITER_JUST_SEEKED，清除标志，返回
        it->flags &= ~RAX_ITER_JUST_SEEKED;
        return 1;
    }
    /* Save key len, stack items and the node where we are currently
     * so that on iterator EOF we can restore the current key and state. */
    保存当前的键的长度，栈元素和节点。
    这样在迭代结束的时候我们可以恢复当前的节点和状态
    size_t orig_key_len = it->key_len;
    size_t orig_stack_items = it->stack.items;
    raxNode *orig_node = it->node;

    while(1) {
        int children = it->node->iscompr ? 1 : it->node->size; 子节点个数
        if (!noup && children) {  
        noup为真的意思就是不向上回溯，只查当前节点下面的子树，!noup表示可以向上回溯
            debugf("GO DEEPER\n");
            /* Seek the lexicographically smaller key in this subtree, which
             * is the first one found always going torwards the first child
             * of every successive node. */
在子树中查找字典序较小的键，对这些连续的节点来说，第一个被找到的总是每个节点的第一个孩子
            if (!raxStackPush(&it->stack,it->node)) return 0;  压栈
            raxNode **cp = raxNodeFirstChildPtr(it->node); 
            第一个子节点(因为第一个子节点字典序上最小，遍历从小到大)
            if (!raxIteratorAddChars(it,it->node->data,
                it->node->iscompr ? it->node->size : 1)) return 0; 拼接迭代器字符串
                
            memcpy(&it->node,cp,sizeof(it->node));  迭代子节点，供循环使用
            
            /* Call the node callback if any, and replace the node pointer
             * if the callback returns true. */
如果存在回调函数，调用节点的回调函数，替换节点的指针如果回调函数返回为真
            if (it->node_cb && it->node_cb(&it->node))
                memcpy(cp,&it->node,sizeof(it->node));
                
            /* For "next" step, stop every time we find a key along the
             * way, since the key is lexicograhically smaller compared to
             * what follows in the sub-children. */
             对下一步，我们每次都停在沿着这条上的一个键节点，
             因为这个键在词典序上小于接下来的子节点上的键
             (意思就是我们是按照字典序从小到大进行遍历的，后面发现的键都大于这个键，)
            if (it->node->iskey) {
                it->data = raxGetData(it->node);  获取当前这个键的值，返回
                return 1;
            }
        } else {
            /* If we finished exporing the previous sub-tree, switch to the
             * new one: go upper until a node is found where there are
             * children representing keys lexicographically greater than the
             * current key. */
             如果我们结束了遍历当前的子树，切换到一个新的子树，一直向上回溯直到找到
             一个子节点表示的键，字典序上大于当前的键
            while(1) {
                int old_noup = noup;

                /* Already on head? Can't go up, iteration finished. */
                已经到达头节点，不能再向上，迭代结束
                if (!noup && it->node == it->rt->head) {  已经到头节点
                    it->flags |= RAX_ITER_EOF;  设置结束标志
                    it->stack.items = orig_stack_items;  恢复初始状态
                    it->key_len = orig_key_len;
                    it->node = orig_node;
                    return 1;
                }
                /* If there are no children at the current node, try parent's
                 * next child. */
                 如果当前节点没有子节点，尝试父节点的另外一个子节点
                unsigned char prevchild = it->key[it->key_len-1];
                if (!noup) {
                    it->node = raxStackPop(&it->stack);  
                    这里的作用是没有找到的情况下，一直往上退，直到头节点
                } else {
                    noup = 0;
                }
                /* Adjust the current key to represent the node we are
                 * at. */
                 调整当前键来表示我们的所在的节点
                int todel = it->node->iscompr ? it->node->size : 1;
                raxIteratorDelChars(it,todel);  退掉相应的字符个数

                /* Try visiting the next child if there was at least one
                 * additional child. */
                 尝试遍历下一个子节点，如果至少还存在额外一个子节点
                if (!it->node->iscompr && it->node->size > (old_noup ? 0 : 1)) {
                非压缩节点  多余一个子节点点或者在不向上回溯的情况下跳过父节点这一步骤
                    raxNode **cp = raxNodeFirstChildPtr(it->node);
                    int i = 0;
                    while (i < it->node->size) { 查找比之前的子节点字典序上大的第一个子节点
                        debugf("SCAN NEXT %c\n", it->node->data[i]);
                        if (it->node->data[i] > prevchild) break;
                        i++;  下一个字符
                        cp++; 下一个节点
                    }
                    if (i != it->node->size) {  
                    不等于，意味着提前退出，即找到了所要求的的字符，否则就会循环到结尾位置
                        debugf("SCAN found a new node\n");
                        raxIteratorAddChars(it,it->node->data+i,1); 拼接新的字符串
                        if (!raxStackPush(&it->stack,it->node)) return 0; 重新压栈
                        
                        memcpy(&it->node,cp,sizeof(it->node)); 将找到的节点赋值给当前节点
                        
                        /* Call the node callback if any, and replace the node
                         * pointer if the callback returns true. */
                如果存在回调函数，调用节点的回调函数，替换节点的指针如果回调函数返回为真
                        if (it->node_cb && it->node_cb(&it->node))
                            memcpy(cp,&it->node,sizeof(it->node));
                            
                        if (it->node->iskey) { 如果是一个键
                            it->data = raxGetData(it->node); 获取这个键的值，返回
                            return 1;
                        }
                        break;
                    }
                }
            }
        }
    }
}
**************************************************************************
/* Like raxIteratorNextStep() but implements an iteration step moving
 * to the lexicographically previous element. The 'noup' option has a similar
 * effect to the one of raxIteratorNextStep(). */
类似函数raxIteratorNextStep，实现了一个字典序上回退的迭代器。
这个noup标志的作用类似函数raxIteratorNextStep中的那个(noup).
我们这里只注释不同于函数raxIteratorNextStep部分
int raxIteratorPrevStep(raxIterator *it, int noup) {
    if (it->flags & RAX_ITER_EOF) {
        return 1;
    } else if (it->flags & RAX_ITER_JUST_SEEKED) {
        it->flags &= ~RAX_ITER_JUST_SEEKED;
        return 1;
    }

    /* Save key len, stack items and the node where we are currently
     * so that on iterator EOF we can restore the current key and state. */
    size_t orig_key_len = it->key_len;
    size_t orig_stack_items = it->stack.items;
    raxNode *orig_node = it->node;

    while(1) {
        int old_noup = noup;

        /* Already on head? Can't go up, iteration finished. */
        if (!noup && it->node == it->rt->head) {
            it->flags |= RAX_ITER_EOF;
            it->stack.items = orig_stack_items;
            it->key_len = orig_key_len;
            it->node = orig_node;
            return 1;
        }

        unsigned char prevchild = it->key[it->key_len-1];
        if (!noup) {
            it->node = raxStackPop(&it->stack);
        } else {
            noup = 0;
        }

        /* Adjust the current key to represent the node we are
         * at. */
        int todel = it->node->iscompr ? it->node->size : 1;
        raxIteratorDelChars(it,todel);

        /* Try visiting the prev child if there is at least one
         * child. */
        if (!it->node->iscompr && it->node->size > (old_noup ? 0 : 1)) {
        这里的作用是从后往前查找，第一个小于当前节点的子节点
            raxNode **cp = raxNodeLastChildPtr(it->node);
            int i = it->node->size-1;
            while (i >= 0) {  从后往前
                debugf("SCAN PREV %c\n", it->node->data[i]);
                if (it->node->data[i] < prevchild) break;  小于当前子节点
                i--;
                cp--;
            }
            /* If we found a new subtree to explore in this node,
             * go deeper following all the last children in order to
             * find the key lexicographically greater. */
             如果我们在这个节点发现了一棵新子树，在子树最深处找到字典序最大的那个键值
            if (i != -1) { 不等于-1表示找到了一个满足条件的节点
                debugf("SCAN found a new node\n");
                /* Enter the node we just found. */
                if (!raxIteratorAddChars(it,it->node->data+i,1)) return 0; 拼接找到节点的字符串
                if (!raxStackPush(&it->stack,it->node)) return 0;
                memcpy(&it->node,cp,sizeof(it->node));
                /* Seek sub-tree max. */
                if (!raxSeekGreatest(it)) return 0;  找当前节点下面字典序上最大的键
            }
        }

        /* Return the key: this could be the key we found scanning a new
         * subtree, or if we did not find a new subtree to explore here,
         * before giving up with this node, check if it's a key itself. */
         返回找到的键：这个值可能是我们从新的子树扫描找到的
         或者我们没有找到一棵新子树，在要离开这个节点前，判断这个节点本身是否是一个键
        if (it->node->iskey) {
            it->data = raxGetData(it->node);
            return 1;
        }
    }
}
**************************************************************************
/* Seek an iterator at the specified element.
 * Return 0 if the seek failed for syntax error or out of memory. Otherwise
 * 1 is returned. When 0 is returned for out of memory, errno is set to
 * the ENOMEM value. */
在特定元素查找迭代器，返回0如果因为格式原因或者OOM查找失败。
其它情况下返回1.因为OOM返回0的时候，errno的值被设置
int raxSeek(raxIterator *it, const char *op, unsigned char *ele, size_t len) {
    int eq = 0, lt = 0, gt = 0, first = 0, last = 0;
    初始化参数
    it->stack.items = 0; /* Just resetting. Intialized by raxStart(). */
    it->flags |= RAX_ITER_JUST_SEEKED;
    it->flags &= ~RAX_ITER_EOF;
    it->key_len = 0;
    it->node = NULL;

    /* Set flags according to the operator used to perform the seek. */
    根据查找符号设置标志去执行查找
    if (op[0] == '>') {
        gt = 1;  大于
        if (op[1] == '=') eq = 1;  等于
    } else if (op[0] == '<') {
        lt = 1;  小于
        if (op[1] == '=') eq = 1; 等于
    } else if (op[0] == '=') {
        eq = 1; 等于
    } else if (op[0] == '^') {
        first = 1; 从头开始
    } else if (op[0] == '$') {
        last = 1;  从尾部开始
    } else {
        errno = 0;  不认识的查找格式
        return 0; /* Error. */
    }

    /* If there are no elements, set the EOF condition immediately and
     * return. */
树中没有元素，直接设置结束条件同时返回
    if (it->rt->numele == 0) {
        it->flags |= RAX_ITER_EOF;
        return 1;
    }

    if (first) { 将从头开始转化为大于等于空元素
        /* Seeking the first key greater or equal to the empty string
         * is equivalent to seeking the smaller key available. */
         查找第一个大于等于空字符串的键，等同于查找能找到的满足条件的最小的键
        return raxSeek(it,">=",NULL,0);
    }

    if (last) { 如果是从尾巴开始查找
        /* Find the greatest key taking always the last child till a
         * final node is found. */
         最大的键总是在每个节点的最后子节点这个分支上。查找直到没有最后一个节点为止
        it->node = it->rt->head;
        if (!raxSeekGreatest(it)) return 0; 从树的头节点开始查找，找出最大的键
        assert(it->node->iskey);
        it->data = raxGetData(it->node);  
        return 1;
    }

    /* We need to seek the specified key. What we do here is to actually
     * perform a lookup, and later invoke the prev/next key code that
     * we already use for iteration. */
    int splitpos = 0;
    size_t i = raxLowWalk(it->rt,ele,len,&it->node,NULL,&splitpos,&it->stack);
    查找树中是否存在这样的节点

    /* Return OOM on incomplete stack info. */
    if (it->stack.oom) return 0;

    if (eq && i == len && (!it->node->iscompr || splitpos == 0) &&
        it->node->iskey)
    {符号中有等号 非压缩节点或者压缩节点但是不在中间 并且是一个键
     那么我们就根据要求找到了这个节点
        /* We found our node, since the key matches and we have an
         * "equal" condition. */
        if (!raxIteratorAddChars(it,ele,len)) return 0; /* OOM. */  
        添加查找字符串就可以返回了
        it->data = raxGetData(it->node);
    } else if (lt || gt) {
        /* Exact key not found or eq flag not set. We have to set as current
         * key the one represented by the node we stopped at, and perform
         * a next/prev operation to seek. To reconstruct the key at this node
         * we start from the parent and go to the current node, accumulating
         * the characters found along the way. */
精准的键没有找到或者等号没有设置，我们必须设置停下的节点作为当前的节点，
然后执行前进或者后退操作去寻找。为了重建这个节点的键，我们需要从父节点开始知道当前节点，
累积这路上遇到的所有字符
        if (!raxStackPush(&it->stack,it->node)) return 0; 
        for (size_t j = 1; j < it->stack.items; j++) { 从头开始拼接字符串
            raxNode *parent = it->stack.stack[j-1];
            raxNode *child = it->stack.stack[j];
            if (parent->iscompr) { 压缩节点
                if (!raxIteratorAddChars(it,parent->data,parent->size))
                    return 0;
            } else { 非压缩节点
                raxNode **cp = raxNodeFirstChildPtr(parent);
                unsigned char *p = parent->data;
                while(1) {
                    raxNode *aux;
                    memcpy(&aux,cp,sizeof(aux));
                    if (aux == child) break; 找到对应的子节点位置
                    cp++; 节点指针加1
                    p++;字符指针加1
                }
                if (!raxIteratorAddChars(it,p,1)) return 0; 
                添加这个节点的字符到迭代器键中
            }
        }
        raxStackPop(&it->stack);

        /* We need to set the iterator in the correct state to call next/prev
         * step in order to seek the desired element. */
    我们需要设置迭代器在正确的状态，从而调用向前/向后操作查找目标元素
        debugf("After initial seek: i=%d len=%d key=%.*s\n",
            (int)i, (int)len, (int)it->key_len, it->key);
        if (i != len && !it->node->iscompr) {  没有精确匹配 并且 非压缩节点
            /* If we stopped in the middle of a normal node because of a
             * mismatch, add the mismatching character to the current key
             * and call the iterator with the 'noup' flag so that it will try
             * to seek the next/prev child in the current node directly based
             * on the mismatching character. */
我们停留在了一个正常节点的中间，添加不匹配字符到当前的节点，
并且调用带有noup标志的迭代器，这样就可以基于不匹配字符在当前节点尝试查找next/prev子节点。
            if (!raxIteratorAddChars(it,ele+i,1)) return 0; 
            先将当前节点的字符添加到迭代器的键中
            debugf("Seek normal node on mismatch: %.*s\n",
                (int)it->key_len, (char*)it->key);

            it->flags &= ~RAX_ITER_JUST_SEEKED;
            if (lt && !raxIteratorPrevStep(it,1)) return 0; 如果是小于，那么后退一步
            if (gt && !raxIteratorNextStep(it,1)) return 0; 如果是大于，那么前进一步
            it->flags |= RAX_ITER_JUST_SEEKED; /* Ignore next call. */
        } else if (i != len && it->node->iscompr) {
        停留在了一个压缩节点的中间
            debugf("Compressed mismatch: %.*s\n",
                (int)it->key_len, (char*)it->key);
            /* In case of a mismatch within a compressed node. */    
            int nodechar = it->node->data[splitpos];
            int keychar = ele[i];
            it->flags &= ~RAX_ITER_JUST_SEEKED;
            if (gt) {
                /* If the key the compressed node represents is greater
                 * than our seek element, continue forward, otherwise set the
                 * state in order to go back to the next sub-tree. */
                 如果压缩节点表示的键大于我们要查找的键，继续向前一步。
                 否则设置迭代器的状态回溯接下来的子树。
                if (nodechar > keychar) {
                  那么下一个遇到的节点就是我们所需要的
                    if (!raxIteratorNextStep(it,0)) return 0;
                } else {
                    if (!raxIteratorAddChars(it,it->node->data,it->node->size))     return 0;
                    因为在下面的步骤中有一个删除上述拼接字符串的操作
                    (在函数raxIteratorNextStep(it,1))有如下操作
                        int todel = it->node->iscompr ? it->node->size : 1;
                        raxIteratorDelChars(it,todel);
                    )
                    
                    if (!raxIteratorNextStep(it,1)) return 0; 
                    查找停止节点的父节点下，大于停止节点所在的子树的第一个节点(子树最小节点)
                    (该子树的全部节点都是大于我们所有查找元素的)
                }
            }
            if (lt) {
                /* If the key the compressed node represents is smaller
                 * than our seek element, seek the greater key in this
                 * subtree, otherwise set the state in order to go back to
                 * the previous sub-tree. */
                如果压缩节点的键小于我们要查找的元素，
                把子树中最大的键找出来(这个键就是小于我们要查找的最接近的一个键)。
                否则设置迭代器状态返回到之前的子树，(即从子树中查找最小值，那就是最接近所寻找元素)
                if (nodechar < keychar) {    小于当前节点的当前字符            
                    if (!raxSeekGreatest(it)) return 0;   
                    找子树中最大的键就是要小于要查找元素的最接近元素
                    it->data = raxGetData(it->node);
                } else {
                    if (!raxIteratorAddChars(it,it->node->data,it->node->size)) return 0;
                    这里的作用同上述gt情况一样
                    if (!raxIteratorPrevStep(it,1)) return 0;
                    查找停止节点的父节点下，小于停止节点所在的子树的最后一个节点(子树最大节点)
                }
            }
            it->flags |= RAX_ITER_JUST_SEEKED; /* Ignore next call. */ 
            设置表示已经找到，下次查找的时候直接返回即可
        } else {  长度等于的情况下
            debugf("No mismatch: %.*s\n",
                (int)it->key_len, (char*)it->key);
            /* If there was no mismatch we are into a node representing the
             * key, (but which is not a key or the seek operator does not
             * include 'eq'), or we stopped in the middle of a compressed node
             * after processing all the key. Continue iterating as this was
             * a legitimate key we stopped at. */
             如果全部匹配停留在一个节点的键上(排除该节点不是键或者没有相等的查找操作)，
             或者如果我们处理了整个键，但是停留在一个压缩节点的内部。
             继续迭代，因为我们停留在一个合法的键上
            it->flags &= ~RAX_ITER_JUST_SEEKED;
            if (it->node->iscompr && it->node->iskey && splitpos && lt) {
                    压缩节点   是键   在内部   符号是小于
                /* If we stopped in the middle of a compressed node with
                 * perfect match, and the condition is to seek a key "<" than
                 * the specified one, then if this node is a key it already
                 * represents our match. For instance we may have nodes:
                 如果我们全部匹配，但是停留在一个压缩节点的内部，查询的条件是小于特定的值，
                 那么这个节点就是我们要查找的节点。举例如下
                 * "f" -> "oobar" = 1 -> "" = 2
                 *
                 * Representing keys "f" = 1, "foobar" = 2. A seek for
                 * the key < "foo" will stop in the middle of the "oobar"
                 * node, but will be our match, representing the key "f".
                 表示键 "f" = 1, "foobar" = 2.如果查找键小于"foo"将会停止在"oobar"节点中，
                 但是签好匹配我们所需，即表示键"f"
                 * So in that case, we don't seek backward. */
                 在这种情况下，我们不需要回溯，直接取数据即可
                it->data = raxGetData(it->node);
            } else {
                if (gt && !raxIteratorNextStep(it,0)) return 0; 大于就向前一步
                if (lt && !raxIteratorPrevStep(it,0)) return 0;  小于就退后一步
            }
            it->flags |= RAX_ITER_JUST_SEEKED; /* Ignore next call. */
            设置表示已经找到，下次查找的时候直接返回即可
        }
    } else {
        /* If we are here just eq was set but no match was found. */
        如果设置了相等，但是没有匹配找到，就返回结束
        it->flags |= RAX_ITER_EOF;
        return 1;
    }
    return 1;
}
**************************************************************************
/* Seek the greatest key in the subtree at the current node. Return 0 on
 * out of memory, otherwise 1. This is an helper function for different
 * iteration functions below. */
在当前节点的子树中查找最大的键，如果OOM返回0，否则返回1. 
这个为了下面多个不同迭代函数的一个帮助函数
int raxSeekGreatest(raxIterator *it) {
    while(it->node->size) {  存在元素
        if (it->node->iscompr) {  压缩节点
            if (!raxIteratorAddChars(it,it->node->data,
                it->node->size)) return 0;  全部拷贝
        } else {
            if (!raxIteratorAddChars(it,it->node->data+it->node->size-1,1))
                return 0; 非压缩节点，只拷贝最后一个字符
        }
        raxNode **cp = raxNodeLastChildPtr(it->node); 查找最大的子节点
        if (!raxStackPush(&it->stack,it->node)) return 0;  将父节点入栈
        memcpy(&it->node,cp,sizeof(it->node)); 用子节点代替父节点，继续循环，直到结束
    }
    return 1;
}
**************************************************************************
/* Go to the next element in the scope of the iterator 'it'.
 * If EOF (or out of memory) is reached, 0 is returned, otherwise 1 is
 * returned. In case 0 is returned because of OOM, errno is set to ENOMEM. */
到达迭代器it范围内的下一个元素。
如果遇到结尾或者OOM，返回0，否则返回1
在返回0的情况中，如果是OOM,还需要设置标志errno为ENOMEM
int raxNext(raxIterator *it) {
    if (!raxIteratorNextStep(it,0)) {
        errno = ENOMEM;
        return 0;
    }
    if (it->flags & RAX_ITER_EOF) {
        errno = 0;
        return 0;
    }
    return 1;
}
**************************************************************************
/* Go to the previous element in the scope of the iterator 'it'.
 * If EOF (or out of memory) is reached, 0 is returned, otherwise 1 is
 * returned. In case 0 is returned because of OOM, errno is set to ENOMEM. */
到达迭代器it范围内的前一个元素
如果遇到结尾或者OOM，返回0，否则返回1
在返回0的情况中，如果是OOM,还需要设置标志errno为ENOMEM
int raxPrev(raxIterator *it) {
    if (!raxIteratorPrevStep(it,0)) {
        errno = ENOMEM;
        return 0;
    }
    if (it->flags & RAX_ITER_EOF) {
        errno = 0;
        return 0;
    }
    return 1;
}
**************************************************************************
/* Perform a random walk starting in the current position of the iterator.
 * Return 0 if the tree is empty or on out of memory. Otherwise 1 is returned
 * and the iterator is set to the node reached after doing a random walk
 * of 'steps' steps. If the 'steps' argument is 0, the random walk is performed
 * using a random number of steps between 1 and two times the logarithm of
 * the number of elements.
执行随机遍历从迭代器的当前位置开始。返回0如果树是空的或者发生OOM，否则返回1，
迭代器设置成经过随机遍历steps步数到达的节点。如果参数steps为0，那么随机遍历使用的步数
为在1到对元素总数取对数两倍长的一个随机的数字。
 * NOTE: if you use this function to generate random elements from the radix
 * tree, expect a disappointing distribution. A random walk produces good
 * random elements if the tree is not sparse, however in the case of a radix
 * tree certain keys will be reported much more often than others. At least
 * this function should be able to expore every possible element eventually. */
提示：如果你使用这个函数从基树去生成随机元素，期待一个没有规律的分布。
一个随机遍历可以产生很好的随机元素，如果基树不是稀疏的，然而在某种情况下，
基树中特定的键会比其它键有跟多遍历到的机会。至少这个函数最终应该可以遍历到每个可能的元素
int raxRandomWalk(raxIterator *it, size_t steps) {
   无元素直接返回
    if (it->rt->numele == 0) {
        it->flags |= RAX_ITER_EOF;
        return 0;
    }

    if (steps == 0) {  如果没有设置随机步数值
        size_t fle = 1+floor(log(it->rt->numele));对数取下整 加 1
        fle *= 2;
        steps = 1 + rand() % fle;
    }

    raxNode *n = it->node;  初始节点就是当前迭代器中的节点
    while(steps > 0 || !n->iskey) {   还有遍历的步数 或者  不是当前节点不是键 
        int numchildren = n->iscompr ? 1 : n->size; 根据是否是压缩节点获取子节点个数
        int r = rand() % (numchildren+(n != it->rt->head));  头结点不用回溯

        if (r == numchildren) {  如果恰好是子节点个个数
            /* Go up to parent. */  到达父节点
            n = raxStackPop(&it->stack);
            int todel = n->iscompr ? n->size : 1;
            raxIteratorDelChars(it,todel);
        } else {
            /* Select a random child. */ 从子节点中随机选择一个节点
            if (n->iscompr) { 压缩节点没有选择机会，只有一个子节点
                if (!raxIteratorAddChars(it,n->data,n->size)) return 0;
            } else { 非压缩节点根据随机值拼接
                if (!raxIteratorAddChars(it,n->data+r,1)) return 0;
            }
            raxNode **cp = raxNodeFirstChildPtr(n)+r; 指针指向选中的子节点指针
            if (!raxStackPush(&it->stack,n)) return 0; 将父节点入栈
            memcpy(&n,cp,sizeof(n)); 将子节点设置为当前节点
        }
        if (n->iskey) steps--;  如果这个节点是键，刚好遍历了一个键，步数减去1
    }
    it->node = n;  迭代器指向当前遍历到的节点
    it->data = raxGetData(it->node); 获取键对应的数据
    return 1;
}
**************************************************************************
/* Free the iterator. */ 释放迭代器
对于申请的内存，全部释放
void raxStop(raxIterator *it) {
    if (it->key != it->key_static_string) rax_free(it->key);
    raxStackFree(&it->stack);
}
**************************************************************************
/* Return if the iterator is in an EOF state. This happens when raxSeek()
 * failed to seek an appropriate element, so that raxNext() or raxPrev()
 * will return zero, or when an EOF condition was reached while iterating
 * with raxNext() and raxPrev(). */
如果迭代器处于EOF状态就返回。这个情况发生在当函数raxSeek查找合适元素失败的时候，
所以函数raxNext() 或 raxPrev()返回0或者在raxNext() 和 raxPrev()迭代中满足EOF条件
int raxEOF(raxIterator *it) {
    return it->flags & RAX_ITER_EOF;  设置迭代结束标志
}
**************************************************************************
/* Return the number of elements inside the radix tree. */
返回基树中的总元素个数
uint64_t raxSize(rax *rax) {
    return rax->numele;
}
**************************************************************************
/* Compare the key currently pointed by the iterator to the specified
 * key according to the specified operator. Returns 1 if the comparison is
 * true, otherwise 0 is returned. */
用指定的操作符比较迭代器当前指向的当前键和指定的键。返回1如果比较成功(即满足比较条件)，否则返回0
int raxCompare(raxIterator *iter, const char *op, unsigned char *key, size_t key_len) {
    int eq = 0, lt = 0, gt = 0;

    if (op[0] == '=' || op[1] == '=') eq = 1;
    if (op[0] == '>') gt = 1;
    else if (op[0] == '<') lt = 1;
    else if (op[1] != '=') return 0; /* Syntax error. */

    size_t minlen = key_len < iter->key_len ? key_len : iter->key_len; 找出短的字符串长度
    int cmp = memcmp(iter->key,key,minlen); 比较字符串大小

    /* Handle == */
    if (lt == 0 && gt == 0) return cmp == 0 && key_len == iter->key_len; 相等的情况

    /* Handle >, >=, <, <= */
    if (cmp == 0) { 相等
        /* Same prefix: longer wins. */ 同样前缀，长的赢
        if (eq && key_len == iter->key_len) return 1;  相等
        else if (lt) return iter->key_len < key_len; 
        小于的情况，如果迭代其中的字符串短，那么就满足小的条件，返回1，否则返回0
        else if (gt) return iter->key_len > key_len;
        大于的情况，如果迭代其中的字符串长，那么就满足大的条件，返回1，否则返回0
        else return 0; /* Avoid warning, just 'eq' is handled before. */
    } else if (cmp > 0) { 大于的情况
        return gt ? 1 : 0; 如果是大于就刚好是1
    } else /* (cmp < 0) */ { 小于的情况
        return lt ? 1 : 0; 如果是小于就刚好是1
    }
}
**************************************************************************