【Jabberd2源码剖析系列 xhash】
xhash是jabberd2的哈希表, 并提供了迭代器用于遍历xhash.
解释一下结构体的命名, xht_struct意思是x hash tasble, xhn_struct意思是x hash node, 这样方便理解记忆.
xhn_struct的成员变量顾名思义, 不赘述.
xht_struct中, p是内存池, 负责node的分配等, zen是桶数组, free_list是回收的node内存, iter_bucket和iter_node被用于记录迭代器的位置.
typedef struct xhn_struct { struct xhn_struct *next; struct xhn_struct *prev; const char *key; int keylen; void *val; } *xhn, _xhn; typedef struct xht_struct { pool_t p; int prime; int dirty; int count; struct xhn_struct *zen; struct xhn_struct *free_list; // list of zaped elements to be reused. int iter_bucket; xhn iter_node; int *stat; } *xht, _xht; JABBERD2_API xht xhash_new(int prime); JABBERD2_API void xhash_put(xht h, const char *key, void *val); JABBERD2_API void xhash_putx(xht h, const char *key, int len, void *val); JABBERD2_API void *xhash_get(xht h, const char *key); JABBERD2_API void *xhash_getx(xht h, const char *key, int len); JABBERD2_API void xhash_zap(xht h, const char *key); JABBERD2_API void xhash_zapx(xht h, const char *key, int len); JABBERD2_API void xhash_stat(xht h); JABBERD2_API void xhash_free(xht h); typedef void (*xhash_walker)(const char *key, int keylen, void *val, void *arg); JABBERD2_API void xhash_walk(xht h, xhash_walker w, void *arg); JABBERD2_API int xhash_dirty(xht h); JABBERD2_API int xhash_count(xht h); JABBERD2_API pool_t xhash_pool(xht h); /* iteration functions */ JABBERD2_API int xhash_iter_first(xht h); JABBERD2_API int xhash_iter_next(xht h); JABBERD2_API void xhash_iter_zap(xht h); JABBERD2_API int xhash_iter_get(xht h, const char **key, int *keylen, void **val);
首先是二进制哈希函数, 会根据一段内存算出哈希值.
/* Generates a hash code for a string. * This function uses the ELF hashing algorithm as reprinted in * Andrew Binstock, "Hashing Rehashed," Dr. Dobb's Journal, April 1996. */ static int _xhasher(const char *s, int len) { /* ELF hash uses unsigned chars and unsigned arithmetic for portability */ const unsigned char *name = (const unsigned char *)s; unsigned long h = 0, g; int i; for(i=0;i<len;i++) { /* do some fancy bitwanking on the string */ h = (h << 4) + (unsigned long)(name[i]); if ((g = (h & 0xF0000000UL))!=0) h ^= (g >> 24); h &= ~g; } return (int)h; }
xhash_new创建了一个预分配内存的pool, 尺寸满足了创建哈希桶数组以及哈希表自身, Prime是哈希桶的个数, 从命名来看作者希望传入的prime是素数, 但这在实现上来说并不是必须的.
xht xhash_new(int prime) { xht xnew; pool_t p; /* log_debug(ZONE,"creating new hash table of size %d",prime); */ /** * NOTE: * all xhash's memory should be allocated from the pool by using pmalloco()/pmallocx(), * so that the xhash_free() can just call pool_free() simply. */ p = pool_heap(sizeof(_xhn)*prime + sizeof(_xht)); xnew = pmalloco(p, sizeof(_xht)); xnew->prime = prime; xnew->p = p; xnew->zen = pmalloco(p, sizeof(_xhn)*prime); /* array of xhn size of prime */ xnew->free_list = NULL; xnew->iter_bucket = -1; xnew->iter_node = NULL; #ifdef XHASH_DEBUG xnew->stat = pmalloco(p, sizeof(int)*prime ); #else xnew->stat = NULL; #endif return xnew; }
释放xhash则直接释放pool即可, 这一点不必多说...
void xhash_free(xht h) { /* log_debug(ZONE,"hash free %X",h); */ /// want to do more things? Please see the note in xhash_new() first. if(h) pool_free(h->p); }
分配node采用的如下方法: 在实现上可能有一点迷惑性, 需要注意到哈希桶是实实在在分配了内存的数组, 而不是指针数组, 所以创建一个新的node时, 会先检查哈希桶那个Node是否被使用了, 如果没有使用则直接返回给用户使用. 否则, 需要另外获取一个新的Node, 此时优先检查free_list, 没有free_list则pmalloc重新分配一个node, 之后将该node插入到哈希桶的第一个结点之后(第一个结点是静态分配的).
另外, 哈希桶链表是双向的.
static xhn _xhash_node_new(xht h, int index) { xhn n; int i = index % h->prime; /* track total */ h->count++; #ifdef XHASH_DEBUG h->stat[i]++; #endif // if the zen[i] is empty, reuse it, else get a new one. n = &h->zen[i]; if( n->key != NULL ) { if( h->free_list ) { n = h->free_list; h->free_list = h->free_list->next; }else n = pmalloco(h->p, sizeof(_xhn)); //add it to the bucket list head. n->prev = &h->zen[i]; n->next = h->zen[i].next; if( n->next ) n->next->prev = n; h->zen[i].next = n; } return n; }
下面的函数给定哈希值index, 将会定位到特定的哈希桶里顺序查找给定的key, 特别注意到, n->key != NULL 的判断, 一方面哈希桶的第一个node用key = NULL来表示未被使用, 另一方面, 当删除一个正在被迭代器指向的node时, 为了不影响接下来的迭代, 也会令key=NULL来表示删除.
static xhn _xhash_node_get(xht h, const char *key, int len, int index) { xhn n; int i = index % h->prime; for(n = &h->zen[i]; n != NULL; n = n->next) if(n->key != NULL && (n->keylen==len) && (strncmp(key, n->key, len) == 0)) return n; return NULL; }
插入一个元素到哈希表, 采用如下接口: 先_xhasher计算出key的哈希值index, 之后_xhash_node_get查找该key是否已经存在,如果已存在则直接替换其中的内容即可返回.
如果不存在, 则分配一个node(从free_list 或者 pool 中), 赋值其中的内容即可.
两个接口的区别就是: 后者调用前者, 前者支持指定key的长度, 但实际上, 我发现这个哈希表只能支持字符串key, 因为_xhash_node_get里竟然用的是strncmp, 并且xhash_put里也是strlen计算的key长度.
void xhash_putx(xht h, const char *key, int len, void *val) { int index; xhn n; if(h == NULL || key == NULL) return; index = _xhasher(key,len); /* dirty the xht */ h->dirty++; /* if existing key, replace it */ if((n = _xhash_node_get(h, key, len, index)) != NULL) { /* log_debug(ZONE,"replacing %s with new val %X",key,val); */ n->key = key; n->keylen = len; n->val = val; return; } /* log_debug(ZONE,"saving %s val %X",key,val); */ /* new node */ n = _xhash_node_new(h, index); n->key = key; n->keylen = len; n->val = val; } void xhash_put(xht h, const char *key, void *val) { if(h == NULL || key == NULL) return; xhash_putx(h,key,strlen(key),val); }
查询更加简单, 内部调用了上面的_xhash_node_get, 并做了一些参数校验.
void *xhash_getx(xht h, const char *key, int len) { xhn n; if(h == NULL || key == NULL || len <= 0 || (n = _xhash_node_get(h, key, len, _xhasher(key,len))) == NULL) { /* log_debug(ZONE,"failed lookup of %s",key); */ return NULL; } /* log_debug(ZONE,"found %s returning %X",key,n->val); */ return n->val; } void *xhash_get(xht h, const char *key) { if(h == NULL || key == NULL) return NULL; return xhash_getx(h,key,strlen(key)); }
删除一个指定的key: 后者调用前者, 主要是操纵双向链表, 并且需要照顾到迭代器是否指向了要删除的node.
如果要删除的node不是哈希桶的那个静态结点(不需要删除, key=NULL就可以表示删除了), 并且也不是当前迭代到的结点, 那么就移除并插到free_list头部.
对于哈希桶第一个静态Node与被迭代器指向的Node, 作者简单的令key=NULL表示删除, 仅此而已.
void xhash_zap_inner( xht h, xhn n, int index) { int i = index % h->prime; // if element:n is in bucket list and it's not the current iter if( &h->zen[i] != n && h->iter_node != n ) { if(n->prev) n->prev->next = n->next; if(n->next) n->next->prev = n->prev; // add it to the free_list head. n->prev = NULL; n->next = h->free_list; h->free_list = n; } //empty the value. n->key = NULL; n->val = NULL; /* dirty the xht and track the total */ h->dirty++; h->count--; #ifdef XHASH_DEBUG h->stat[i]--; #endif } void xhash_zapx(xht h, const char *key, int len) { xhn n; int index; if( !h || !key ) return; index = _xhasher(key,len); n = _xhash_node_get(h, key, len, index); if( !n ) return; /* log_debug(ZONE,"zapping %s",key); */ xhash_zap_inner(h ,n, index ); }
下面是一些比较杂的函数, 其中xhash_dirty返回的dirty值是在每次插入与删除node时+1的, 在这里还看不出它的具体用途.
/** return the dirty flag (and reset) */ int xhash_dirty(xht h) { int dirty; if(h == NULL) return 1; dirty = h->dirty; h->dirty = 0; return dirty; } /** return the total number of entries in this xht */ int xhash_count(xht h) { if(h == NULL) return 0; return h->count; } /** get our pool */ pool_t xhash_pool(xht h) { return h->p; }
xhash提供了一个遍历哈希表的接口, 允许用户指定回调函数与自定义数据, 原理很简单:
void xhash_walk(xht h, xhash_walker w, void *arg) { int i; xhn n; if(h == NULL || w == NULL) return; /* log_debug(ZONE,"walking %X",h); */ for(i = 0; i < h->prime; i++) for(n = &h->zen[i]; n != NULL; n = n->next) if(n->key != NULL && n->val != NULL) (*w)(n->key, n->keylen, n->val, arg); }
剩下的是迭代器: 迭代器一方面提供了传统的迭代访问元素的方式, 另一方面其内部也在迭代的过程中回收了那些Key=NULL 或者val=NULL的正常node, 这些node是因为上一次迭代过程中zap删除迭代器指向的node引起的, 在这次迭代过程中将被回收到free_list中.
初始化迭代器: 令iter_bucket和iter_node为初始化状态, 前者表示当前迭代哪个桶, 后者表示迭代哪个结点. 最后会调用xhash_iter_next将迭代器挪到第一个Node.
/** iteration */ int xhash_iter_first(xht h) { if(h == NULL) return 0; h->iter_bucket = -1; h->iter_node = NULL; return xhash_iter_next(h); }
令迭代器前进: 先让迭代node指向下一个node, 如果node为空, 那么说明当前的桶内没有node了, 必须迭代下一个哈希桶, 并在新的桶内找到一个key!=NULL&&val!=NULL的Node. 如果当前桶内还有剩余node, 那么令迭代node(iter_node)指向下一个node, 这里有一个while循环, 目的是因为可能迭代的node是之前被半删除的node, 这里会将它们回收到free_list中, 或者遇到一个key!=NULL&val!=NULL的Node则返回.
注:此处可以看出为什么初始化迭代器设置iter_node =NULL, iter_bucket= -1的原因.
int xhash_iter_next(xht h) { if(h == NULL) return 0; /* next in this bucket */ h->iter_node = h->iter_node ? h->iter_node->next : NULL; while(h->iter_node != NULL) { xhn n = h->iter_node; if(n->key != NULL && n->val != NULL) return 1; h->iter_node = n->next; if (n != &h->zen[h->iter_bucket]) { if(n->prev) n->prev->next = n->next; if(n->next) n->next->prev = n->prev; // add it to the free_list head. n->prev = NULL; n->next = h->free_list; h->free_list = n; } } /* next bucket */ for(h->iter_bucket++; h->iter_bucket < h->prime; h->iter_bucket++) { h->iter_node = &h->zen[h->iter_bucket]; while(h->iter_node != NULL) { if(h->iter_node->key != NULL && h->iter_node->val != NULL) return 1; h->iter_node = h->iter_node->next; } } /* there is no next */ h->iter_bucket = -1; h->iter_node = NULL; return 0; }
剩下的是删除迭代器指向的Node: 此处不会真正的删除该Node, 只会令key =NULL, 并在下一轮新的迭代过程中被发现并回收到free_list. 之所以不删除是因为会影响接下来的迭代, 作者这样实现迭代器的删除并不是不能实现的更直接, 而是一种对C++ map迭代器类似的原则, 将迭代器正确操作的责任交给使用者.
void xhash_iter_zap(xht h) { int index; if( !h || !h->iter_node ) return; index = _xhasher( h->iter_node->key, h->iter_node->keylen ); xhash_zap_inner( h ,h->iter_node, index); }
最后一个接口, 允许用户获取当前迭代器指向node的key和val, 传入的都是指针的地址: 这里严格判断, 一个空的容器的迭代器永远iter_node = NULL, 所以要判断仔细.
下面就是把用户需要的内容返回给用户.
int xhash_iter_get(xht h, const char **key, int *keylen, void **val) { if(h == NULL || (key == NULL && val == NULL) || (key != NULL && keylen == NULL)) return 0; if(h->iter_node == NULL) { if(key != NULL) *key = NULL; if(val != NULL) *val = NULL; return 0; } if(key != NULL) { *key = h->iter_node->key; *keylen = h->iter_node->keylen; } if(val != NULL) *val = h->iter_node->val; return 1; }
在xhash的插入操作中, 并没有看到预想的pstrdup(key)的操作, 作者将key的副本生成的责任交给了用户自己, 而xhash内部的pool只负责分配xht, xhn的内存.
