redis之整数集合的实现源码分析

      整数集合（intset）是集合键的底层实现之一，当一个集合只包含整数值元素，并且这个集合的元素数量不多时，redis就会使用整数集合作为集合键的底层实现。整数集合（intset）是redis用于保存整数值的集合抽象数据结构，它可以保存类型为int16_t、int32_t、int64_t的整数值，并且保证集合中不会出现重复元素。

   我们首先来看redis对于intset.h的实现：

  intset.h：

#ifndef __INTSET_H
#define __INTSET_H
#include <stdint.h>
/*
 * 对于结构体的说明：
 *   虽然从intset结构将contents属性声明为int8_t类型的数组，但实际contents数组并不保存int8_t类型的值，
 *       contents数组的真正类型取决于encoding属性的值：
 *   （1）如果encoding属性值为INTSTE_ENC_INT16,那么contents就是一个int16_t类型的数组，数组里的每一项都是一个
 *        int16_t类型的整数值（最小值为-32768，最大值为32767）
 *   （2）如果encoding属性值为INTSTE_ENC_INT32,那么contents就是一个int32_t类型的数组，数组里的每一项都是一个
 *        int32_t类型的整数值（最小值为-2147483648，最大值为2147483647）
 *   （3）如果encoding属性值为INTSTE_ENC_INT64,那么contents就是一个int64_t类型的数组，数组里的每一项都是一个
 *        int64_t类型的整数值（最小值为-9223372036854775808，最大值为9223372036854775807）
 * */
typedef struct intset {
    //编码方式
    uint32_t encoding;
    //集合包含的元素数量
    uint32_t length;
    //保存元素的数组
    int8_t contents[];
} intset;
//创建一个新的整数集合
intset *intsetNew(void);
//将给定元素添加到整数集合里面
intset *intsetAdd(intset *is, int64_t value, uint8_t *success);
//从整数集合中移除给定元素
intset *intsetRemove(intset *is, int64_t value, int *success);
//检查给定值是否存在于集合(由于底层数组有序，查找可以通过二分查找法来进行)
uint8_t intsetFind(intset *is, int64_t value);
//从整数集合中随机返回一个元素
int64_t intsetRandom(intset *is);
//取出底层数据在给定索引上的元素
uint8_t intsetGet(intset *is, uint32_t pos, int64_t *value);
//返回整数集合包含的元素个数
uint32_t intsetLen(intset *is);
//返回整数集合占用的内存字节数
size_t intsetBlobLen(intset *is);

#endif // __INTSET_H

intset.h中定义了整数集合结构体和一些接口的声明。。。在文件里也对其进行了解析。

 下面我们具体来看redis是如何实现的：

 intset.c：

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "intset.h"
#include "zmalloc.h"
#include "endianconv.h"

/* Note that these encodings are ordered, so:
 * INTSET_ENC_INT16 < INTSET_ENC_INT32 < INTSET_ENC_INT64. */
#define INTSET_ENC_INT16 (sizeof(int16_t))
#define INTSET_ENC_INT32 (sizeof(int32_t))
#define INTSET_ENC_INT64 (sizeof(int64_t))

/* Return the required encoding for the provided value. */
/*
 * 返回适用于传入值的v的编码方式
 *
 *
 * */
static uint8_t _intsetValueEncoding(int64_t v) {
    
    if (v < INT32_MIN || v > INT32_MAX)
        return INTSET_ENC_INT64;
    else if (v < INT16_MIN || v > INT16_MAX)
        return INTSET_ENC_INT32;
    else
        return INTSET_ENC_INT16;
}

/* Return the value at pos, given an encoding. */
/*
 * 根据给定的编码方式enc，返回集合的底层数组在pos索引上的元素
 *
 *
 *
 * */
static int64_t _intsetGetEncoded(intset *is, int pos, uint8_t enc) {
    int64_t v64;
    int32_t v32;
    int16_t v16;
    //((ENCODING *)is ->contents)首先将数组转换成编码的类型
    //然后((ENCODING *) is ->contents) + pos计算出元素在数组中的正确位置
    //之后member(&vENc,...,sizeof(vEnc))再从数组中拷贝出正确数量的字节
    //如果由需要的话，memrevEncifbe(&vEnc)会对拷贝出的字节进行大小端转换
    //最后将值返回
    if (enc == INTSET_ENC_INT64) {
        memcpy(&v64,((int64_t*)is->contents)+pos,sizeof(v64));
        memrev64ifbe(&v64);
        return v64;
    } else if (enc == INTSET_ENC_INT32) {
        memcpy(&v32,((int32_t*)is->contents)+pos,sizeof(v32));
        memrev32ifbe(&v32);
        return v32;
    } else {
        memcpy(&v16,((int16_t*)is->contents)+pos,sizeof(v16));
        memrev16ifbe(&v16);
        return v16;
    }
}

/* Return the value at pos, using the configured encoding. */
/*
 * 根据给定的编码方式enc，返回集合的底层数组在pos索引上的元素
 *
 *
 *
 * */
static int64_t _intsetGet(intset *is, int pos) {
    return _intsetGetEncoded(is,pos,intrev32ifbe(is->encoding));
}

/* Set the value at pos, using the configured encoding. */
/*
 * 根据集合编码的方式，将底层数组再pos位置上的值设为value
 *
 *
 * */
static void _intsetSet(intset *is, int pos, int64_t value) {
    //取出集合编码方式
    uint32_t encoding = intrev32ifbe(is->encoding);
    
    //根据编码((Enc_t *)is ->contents)将数组转换回正确的类型
    //然后将((Enc_t *)is ->contents)[pos]定位到数组索引上
    //接着将((Enc_t *)is ->contents)[pos] = value 将值赋给数组
    //最后，((Enc_t *)is ->contents) + pos 定位到刚刚设置的的新值上
    //如果有需要的话，memrevEncifbe将对值进行大小端转换
    if (encoding == INTSET_ENC_INT64) {
        ((int64_t*)is->contents)[pos] = value;
        //
        memrev64ifbe(((int64_t*)is->contents)+pos);
    } else if (encoding == INTSET_ENC_INT32) {
        ((int32_t*)is->contents)[pos] = value;
        memrev32ifbe(((int32_t*)is->contents)+pos);
    } else {
        ((int16_t*)is->contents)[pos] = value;
        memrev16ifbe(((int16_t*)is->contents)+pos);
    }
}

/* Create an empty intset. */
/*
 * 创建一个新的整数集合
 *
 * */
intset *intsetNew(void) {
    //定义整数集合，并申请内存
    intset *is = zmalloc(sizeof(intset));
    //初始化其编码方式,encoding属性为INTSET_ENC_INT16(int16_t 类型)
    is->encoding = intrev32ifbe(INTSET_ENC_INT16);
    //初始化整数集合包含的元素数量为0，即contents数组的长度
    is->length = 0;
    //返回整数集合
    return is;
}

/* Resize the intset */
/*
 * 调整整数集合的内存空间大小
 *
 * 如果调整后的大小要比集合原来的大小要大
 * 那么集合中原有元素的值不发生改变
 *
 * 返回值：调整大小后的整数集合
 * */
static intset *intsetResize(intset *is, uint32_t len) {
    //计算数组的空间大小
    uint32_t size = len*intrev32ifbe(is->encoding);
    //根据空间大小，重新分配空间
    //注意这里使用的是 zrealloc
    //所以如果新空间的大小要比原来的空间大小要大
    //那么数组原有的数据会被保留
    is = zrealloc(is,sizeof(intset)+size);
    return is;
}

/* Search for the position of "value".
 * 在集合is的底层数组中查找值value所在的索引
 * Return 1 when the value was found and
 * sets "pos" to the position of the value within the intset.
 *
 * 成功找到value时，返回1，并将*pos的值设为value所在的索引 
 *
 * Return 0 when the value is not present in the intset and 
 * sets "pos" to the position where "value" can be inserted. 
 *
 * 当在数组中没找到value时，返回0，
 * 并将*pos的值设为value可以插入到数组中的位置
 *
 * */
static uint8_t intsetSearch(intset *is, int64_t value, uint32_t *pos) {
    //min、max用来记录数组的下标，mid为二分点
    int min = 0, max = intrev32ifbe(is->length)-1, mid = -1;
    int64_t cur = -1;

    /* The value can never be found when the set is empty */
    //如果数组长度为0
    if (intrev32ifbe(is->length) == 0) {
        //如果pos为真，将*pos 置为0    
        if (pos) *pos = 0;
        //返回0，表示没有找到
        return 0;
    } else {
        //当数组长度不为0时
        /* Check for the case where we know we cannot find the value,
         * but do know the insert position. */
        /*
         * 函数_intsetGet功能：
         *     根据集合的编码方式，返回底层数组在pos索引上的值
         * */
        //因为底层数组是有序的，如果value比数组中最后一个值都要大
        //那么value不存在于集合中
        //并且应该将value添加到底层数组的最末端
        if (value > _intsetGet(is,intrev32ifbe(is->length)-1)) {
            //如果pos为真，将*pos置为is->length
            if (pos) *pos = intrev32ifbe(is->length);
            return 0;
        } else if (value < _intsetGet(is,0)) {
            //如果value小于数组下标为0的元素（即是数组中的最小值），
            //说明value小于最小值
            //如果pos为真，*pos记录下标
            if (pos) *pos = 0;
            return 0;
        }
    }
    //循环的条件： max >= min
    while(max >= min) {
        //mid记录min、max下标的中点
        mid = ((unsigned int)min + (unsigned int)max) >> 1;
        //根据编码方式，返回底层数组在pos索引上的值
        cur = _intsetGet(is,mid);
        if (value > cur) {
            //如果value > cur ,右二分
            min = mid+1;
        } else if (value < cur) {
            //如果value < cur, 左二分
            max = mid-1;
        } else {
            //如果value == cur ，跳出
            break;
        }
    }
    //从while循环出来之后，判断value 是否与 cur相等
    if (value == cur) {
        //如果相等，则说明找到了，
        //判断如果pos为真，*pos记录下标
        if (pos) *pos = mid;
        return 1;
    } else {
        //否则，没找到，同样也要记录下标，将value插入到数组中
        if (pos) *pos = min;
        return 0;
    }
}

/* Upgrades the intset to a larger encoding and inserts the given integer. */
/*
 * 根据值value所使用的编码方式，对整数集合的编码进行升级
 * 并将value的值添加到升级后的整数集合中
 *
 * 返回值:添加新元素之后的集合
 * */
static intset *intsetUpgradeAndAdd(intset *is, int64_t value) {
    //当前的编码方式
    uint8_t curenc = intrev32ifbe(is->encoding);
    //返回适合value的编码方式
    uint8_t newenc = _intsetValueEncoding(value);
    //length记录集合元素的数量
    int length = intrev32ifbe(is->length);
    //根据value的值，决定是将它添加到底层数组的最前端还是最后端
    //注意：因为value的编码比集合原有的所有的其他元素的编码都要大
    //所以，value要么大于集合中的所有元素，要么小于集合中的所有元素
    //因此，value只能添加到底层数组的最前端或最后端
    int prepend = value < 0 ? 1 : 0;

    /* First set new encoding and resize */
    //更新集合编码方式
    is->encoding = intrev32ifbe(newenc);
    //调整整数集合的内存空间大小
    is = intsetResize(is,intrev32ifbe(is->length)+1);

    /* Upgrade back-to-front so we don't overwrite values.
     * Note that the "prepend" variable is used to make sure we have an empty
     * space at either the beginning or the end of the intset. */
    //根据集合原来的编码方式，从底层数组中取出集合元素
    //然后再将元素以新编码的方式添加到集合中
    //当完成了这个步骤之后，集合中所有的元素就完成了从旧编码到新编码的转换
    //因为新分配的空间都在数组的后端，所以程序先从后端向前端移动元素
    //举个例子，假设原有的curenc编码的三个元素，它们在数组中排列如下：
    //| x | y | z |
    //当程序对数组进行重分配之后，数组就被扩容了（符号？表示未使用的内容）：
    //| x | y | z | ？ |   ？   |   ？   |
    //这时程序从数组的后端开始，重新插入元素：
    //| x | y | z | ？ |   z    |   ?    |
    //| x | y |   y    |   z    |   ?    |
    //|   x   |   y    |   z    |   ?    |
    //最后，程序可以将新元素添加到最后？号标示的位置中
    //|   x   |   y    |   z    |  new   |
    //上面演示的是新元素比原来的所有元素都大时的情况，也即是prepend == 0
    //当新元素比原来的所有的元素都小时（prepend == 1），调整过程如下：
    //| x | y | z | ？ |   ？   |   ？   |
    //| x | y | z | ？ |   ?    |   z    |
    //| x | y | z | ?  |   y    |   z    |
    //| x | y |   x    |   y    |   z    |
    //当添加新值时，原本的| x | y |的数据将被新值代替
    //|  new  |   x    |   y    |   z    |
    //

    //length为集合中元素的个数
    while(length--)
        //调用函数_intsetGetEncoded,根据给定的编码curenc，返回集合的底层数组在length索引上的元素
        //再调用函数_intsetSet，将底层数组在length + prepend位置上的值设为length索引上的元素
        
       //例如：当前数组集合元素个数为3个：(prepend == 0的情况)
       //| x | y | z |
       //将编码方式更改了之后，调整内存空间的大小，申请的大小为：新的编码方式 * (length + 1)
       //| x | y | z | ？ |   ?    |   ?    |
       //
       //第1次进循环时，length = 2，按照原有的编码方式调用函数_intsetGetEncoded得到的值为'z'
       //调用函数_inetsetSet时，使用新的编码方式，执行结果如下：
       //| x | y | z | ？ |   z    |   ？    |
       //
       //第2次进循环时，length = 1，按照原有的编码方式调用函数_intsetGetEncoded得到的值为'y'
       //调用函数_inetsetSet时，使用新的编码方式，执行结果如下：
       //| x | y |   y    |   z    |   ？    |
       //
       //第3次进循环时，length = 0，按照原有的编码方式调用函数_intsetGetEncoded得到的值为'x'
       //调用函数_inetsetSet时，使用新的编码方式，执行结果如下：
       //|   x   |   y    |   z    |   ？    |
     
        _intsetSet(is,length+prepend,_intsetGetEncoded(is,length,curenc));

    /* Set the value at the beginning or the end. */
    //如果prepend == 1时，
    //将value插入到，数组的首位置
    if (prepend)
        _intsetSet(is,0,value);
    else
        //如果prepend == 0时，说明value的值大于数组的所有元素，将value插入到数组 末尾的位置
        _intsetSet(is,intrev32ifbe(is->length),value);
    //更新数组的长度
    is->length = intrev32ifbe(intrev32ifbe(is->length)+1);
    return is;
}
/*
 * 向前或向后移动指定索引范围内的数组元素
 *
 * 函数名中的MoveTail其实是一个有误导性的名字
 *
 * 这个函数可以向前或向后移动元素
 * 而不仅仅是向后
 *
 * （1）在添加新元素到数组时，就需要进行向后移动
 * 如果数组表示如下（？表示一个未设置新值的空间）
 * | x | y | z | ？ |
 *     |<----->|
 * 而新元素n的pos为1，那么数组将移动y和z两个元素
 * | x | y | y | z |
 *         |<----->|
 * 接着就可以将新元素n设置到pos上了
 * （2）当数组中删除元素时，就需要进行向前移动
 * 如果数组表示如下，并且b为要删除的目标
 * | a | b | c | d |
 *         |<----->|
 * 那么程序就会移动b之后的所有元素向前一个元素的位置，
 * 从而覆盖b的数据
 * | a | c | d | d |
 *     |<----->|
 * 最后，程序再从数组末尾删除一个元素的空间
 * | a | c | d | 
 * 这样就完成了删除操作
 * */
static void intsetMoveTail(intset *is, uint32_t from, uint32_t to) {
    void *src, *dst;
    //用bytes记录要移动的元素个数
    uint32_t bytes = intrev32ifbe(is->length)-from;
    //encoding记录编码方式
    uint32_t encoding = intrev32ifbe(is->encoding);
    
    if (encoding == INTSET_ENC_INT64) {
        //判断如果编码方式为int64_t,
        //使用src指向要移动元素的首位置
        src = (int64_t*)is->contents+from;
        //使用dst指向要移动元素的末位置
        dst = (int64_t*)is->contents+to;
        //bytes记录一共要移动的字节数
        bytes *= sizeof(int64_t);
    } else if (encoding == INTSET_ENC_INT32) {
        //同理，判断编码方式为int32_t
        src = (int32_t*)is->contents+from;
        dst = (int32_t*)is->contents+to;
        bytes *= sizeof(int32_t);
    } else {
        //判断编码方式为int16_t
        src = (int16_t*)is->contents+from;
        dst = (int16_t*)is->contents+to;
        bytes *= sizeof(int16_t);
    }
    //调用库函数memmove
    //函数原型： void *memmove(void *dest,const void * src,size_t count)
    //功能：由src所指内存区域复制count个字节到dest所指的内存区域
    //与memcpy的区别：如果目标区域与源区域有重叠时，memmove能够保证串在被覆盖之前将重叠区域的字节拷贝到目标区域中，
    //但拷贝后src的内容会被更改，但当目标区域的与源区域没有重叠则和memcpy函数功能相同
    //
    memmove(dst,src,bytes);
}

/* Insert an integer in the intset */
/*
 * 尝试将元素value添加到整数集合中
 *
 * *success的值指示添加是否成功：
 *   如果添加成功，那么将*success的值设为1
 *   因为元素已经存在而造成添加失败时，将*success的值设为0
 * */
intset *intsetAdd(intset *is, int64_t value, uint8_t *success) {
    //返回适用value的编码方式
    uint8_t valenc = _intsetValueEncoding(value);
    uint32_t pos;
    //如果success为真，默认设置为插入成功
    if (success) *success = 1;

    /* Upgrade encoding if necessary. If we need to upgrade, we know that
     * this value should be either appended (if > 0) or prepended (if < 0),
     * because it lies outside the range of existing values. */
    //如果value的编码比整数集合现在的编码还要大时，
    //那么表示value必然可以添加到整数集合中，
    //并且整数集合需要对自身进行升级，才能满足value所需的编码
    if (valenc > intrev32ifbe(is->encoding)) {
        /* This always succeeds, so we don't need to curry *success. */
        return intsetUpgradeAndAdd(is,value);
    } else {
        /* Abort if the value is already present in the set.
         * This call will populate "pos" with the right position to insert
         * the value when it cannot be found. */
        //函数intsetSearch的功能：
        //    在集合is中的底层数组中查找值value所在的索引
        //    如果成功找到value，函数返回1，并将*pos的值设为value所在的索引
        //    当在数组中没找到value时，返回0，并将*pos的值设为value可以插入到数组中的位置
        if (intsetSearch(is,value,&pos)) {
            //如果函数返回1，说明在底层数组中找到value，插入失败，*success = 0
            if (success) *success = 0;
            return is;
        }
        //程序执行到这时，说明value在底层数组中没有出现，程序需要将value插入到底层数组中
        //对数组进行扩展
        is = intsetResize(is,intrev32ifbe(is->length)+1);
        //如果新的元素不是被添加到底层数组的末尾
        //那么需要对数组上的元素进行移动，空出pos的位置，用于设置新值
        //例如：
        //如果数组为：
        //| x | y | z | ? |
        //    |<----->|
        // 而新的元素n的pos值为1，那么数组将移动y和z两个元素
        //| x | y | y | z |
        //        |<----->|
        // 这样就可以将元素设置到pos上了

        //如果value在数组的索引值小于数组的长度，调用移动函数，将pos下标之后的元素依次后移，则
        //可以空出pos的位置，就可以将value插入到数组内
        if (pos < intrev32ifbe(is->length)) intsetMoveTail(is,pos,pos+1);
    }
    //调用函数，该函数的功是将底层数组在pos的索引设为value
    _intsetSet(is,pos,value);
    //更新底层数组的长度
    is->length = intrev32ifbe(intrev32ifbe(is->length)+1);
    //返回添加新元素的整数集合
    return is;
}

/* Delete integer from intset */
/*
 * 从整数集合中删除值value
 *
 * *success的值指示删除是否成功：
 *     因值不存在时造成删除失败，返回0
 *     删除成功返回1
 * */
intset *intsetRemove(intset *is, int64_t value, int *success) {
    //返回适用value的编码方式
    uint8_t valenc = _intsetValueEncoding(value);
    uint32_t pos;
    //如果success指针为真，*success设为0，表示默认删除失败
    if (success) *success = 0;
    //valuec的编码方式小于或等于当前的编码方式，并且将要删除的value在数组内存在
    if (valenc <= intrev32ifbe(is->encoding) && intsetSearch(is,value,&pos)) {
        //使用len记录当前的元素个数
        uint32_t len = intrev32ifbe(is->length);

        /* We know we can delete */
        //设置标示值为成功
        if (success) *success = 1;

        /* Overwrite value with tail and update length */
        //如果value在数组的索引（pos）不是数组的末尾，调用移动函数，将pos之后的所有元素都统一前移
        if (pos < (len-1)) intsetMoveTail(is,pos+1,pos);
        //程序能执行到这，说明索引（pos）就是数组的末尾
        //那么只用调用函数将数组缩短
        is = intsetResize(is,len-1);
        //更新集合元素数量
        is->length = intrev32ifbe(len-1);
    }
    //返回删除之后的整数集合
    return is;
}

/* Determine whether a value belongs to this set */
/*
 * 检查给定值value是否为集合中的元素
 *
 * 是返回1，不是返回0
 * */
uint8_t intsetFind(intset *is, int64_t value) {
    //调用函数确定value的编码方式
    uint8_t valenc = _intsetValueEncoding(value);
    //运算符 <= 的优先级高于 &&
    //当valenc编码 小于等于 当前整数集合的编码，并且 value在数组中存在时，则返回1 ，表明
    //value在是集合中的元素，否则返回0
    return valenc <= intrev32ifbe(is->encoding) && intsetSearch(is,value,NULL);
}

/* Return random member */
/*
 * 从整数集合中随机返回一个元素
 *
 * 只能在集合非空时使用
 *
 * */
int64_t intsetRandom(intset *is) {
    //intrev32ifbe(is ->length)用于获得数组的长度
    //rand()%intrev32ifbe(is ->length)获取一个随机的索引
    //调用函数_inysetGet,根据集合的编码方式，返回底层数组在pos索引上的值
    return _intsetGet(is,rand()%intrev32ifbe(is->length));
}

/* Sets the value to the value at the given position. When this position is
 * out of range the function returns 0, when in range it returns 1. */
/*
 * 取出集合底层数组指定位置中的值，并将它保存到value指针中。
 *
 * 如果pos没超出数组的索引范围，则返回1，如果超出索引则返回0
 * */
uint8_t intsetGet(intset *is, uint32_t pos, int64_t *value) {
    //判断如果pos（索引）小于 数组的长度
    if (pos < intrev32ifbe(is->length)) {
        //调用函数_intsetGet,根据编码方式，返回底层数组在pos索引上的值
        *value = _intsetGet(is,pos);
        //返回 1 ，表示保存成功
        return 1;
    }
    //否则，返回失败
    return 0;
}

/* Return intset length */
/* 
 * 返回整数集合的现有元素的个数
 *
 * */
uint32_t intsetLen(intset *is) {
    return intrev32ifbe(is->length);
}

/* Return intset blob size in bytes. */
/*
 * 返回集合现在占用的字节总数量
 *
 *  这个数量包括整数集合的结构大小，以及整数集合所有元素的总大小
 * */
size_t intsetBlobLen(intset *is) {
    //sizeof(intset) 用于计算结构体的大小
    //intrev32ifbe(is->length)*intrev32ifbe(is->encoding) 用于计算数组占用的大小
    return sizeof(intset)+intrev32ifbe(is->length)*intrev32ifbe(is->encoding);
}

     对与具体的实现，我也做了比较详细的说明，欢迎大家找茬！！！

     redis对于整数集合实现个人觉得其优点在于：在其结构体内封装了一个成员为编码方式，使得数组可以动态的进行升级，提升了整数集合灵活性，同样我们可以看到整数集合的底层是一个数组，我们知道数组在插入和删除时，效率是比较低的，所以在本文的开篇也提到了整数集合适用于集合的元素数量不多时使用比较方便，当数据规模变大时，这种方式变不适用，数据的删除和插入变得很慢！！！！

   之后还会继续更新有关redis的实现。。。。