redis intset 整数集合源码分析

// 整数集合
typedef struct intset {
    // 编码方式
    uint32_t encoding;
    // 集合包含元素的数量,注意是元素的数量,不是contents保存元素的字节数
    uint32_t length;
    // 保存元素的数组
    int8_t contents[];
} intset;


#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) {
    // 判断是否超过了32位的范围,超过了返回64位的类型
    if (v < INT32_MIN || v > INT32_MAX)
        return INTSET_ENC_INT64;
    // 判断是否超过了16位的类型,超过了16位但是没有超过32位就返回32位
    else if (v < INT16_MIN || v > INT16_MAX)
        return INTSET_ENC_INT32;
    // 否则就返回16位
    else
        return INTSET_ENC_INT16;
}

/* Return the value at pos, given an encoding. */
// 根据给定的编码方式,返回对应pos处的元素
static int64_t _intsetGetEncoded(intset *is, int pos, uint8_t enc) {
    int64_t v64;
    int32_t v32;
    int16_t v16;

    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. */
// 从整数集合中选择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处赋值
static void _intsetSet(intset *is, int pos, int64_t value) {
    uint32_t encoding = intrev32ifbe(is->encoding);

    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));
    // 默认类型是int16_t
    is->encoding = intrev32ifbe(INTSET_ENC_INT16);
    // 长度0
    is->length = 0;
    return is;
}

/* Resize the intset */
// 重新调整整数集合的大小
// 注意这个函数虽然调整大小,但是不修改length,也就是length还是修改之前的
static intset *intsetResize(intset *is, uint32_t len) {
    // 获取新的数组的大小
    uint32_t size = len*intrev32ifbe(is->encoding);
    // 加上结构体本身的大小就是最终的大小
    is = zrealloc(is,sizeof(intset)+size);
    return is;
}

/* Search for the position of "value". Return 1 when the value was found and
 * sets "pos" to the position of the value within the intset. Return 0 when
 * the value is not present in the intset and sets "pos" to the position
 * where "value" can be inserted. */
// 获取将来value插入的位置保存到pos中
// 如果value原来不存在,返回0
// 如果value原来就有,返回1
static uint8_t intsetSearch(intset *is, int64_t value, uint32_t *pos) {
    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 */
    // 如果原来的整数集合是空的
    if (intrev32ifbe(is->length) == 0) {
        // 将来的index就是0
        if (pos) *pos = 0;
        return 0;
    } else {
        /* Check for the case where we know we cannot find the value,
         * but do know the insert position. */
        // 判断是否比最大的都大
        if (value > _intsetGet(is,intrev32ifbe(is->length)-1)) {
            // 说明将来的index是数组的长度
            if (pos) *pos = intrev32ifbe(is->length);
            return 0;
        } else if (value < _intsetGet(is,0)) {
            // 如果比最小的还小,说明要插入倒第一个位置
            if (pos) *pos = 0;
            return 0;
        }
    }
    // 二分查找
    while(max >= min) {
        mid = ((unsigned int)min + (unsigned int)max) >> 1;
        cur = _intsetGet(is,mid);
        if (value > cur) {
            min = mid+1;
        } else if (value < cur) {
            max = mid-1;
        } else {
            // 如果mid处的元素等于value
            break;
        }
    }

    if (value == cur) {
        if (pos) *pos = mid;
        return 1;
    } else {
        if (pos) *pos = min;
        return 0;
    }
}

/* Upgrades the intset to a larger encoding and inserts the given integer. */
static intset *intsetUpgradeAndAdd(intset *is, int64_t value) {
    uint8_t curenc = intrev32ifbe(is->encoding);    // 当前的编码方式
    uint8_t newenc = _intsetValueEncoding(value);   // 新的编码方式
    int length = intrev32ifbe(is->length);
    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. */
    // 倒着把数据放到合适的位置
    // 先按照原来的编码方式获取到元素,然后放到新空间对应的位置
    while(length--)
        _intsetSet(is,length+prepend,_intsetGetEncoded(is,length,curenc));

    /* Set the value at the beginning or the end. */
    if (prepend) // 如果是负数那么插入到第一个位置
        _intsetSet(is,0,value);
    else    // 如果是正数,插入倒最后一个位置
        _intsetSet(is,intrev32ifbe(is->length),value);
    // 更新长度
    is->length = intrev32ifbe(intrev32ifbe(is->length)+1);
    return is;
}

// 从from处搬移元素到to处
static void intsetMoveTail(intset *is, uint32_t from, uint32_t to) {
    void *src, *dst;
    uint32_t bytes = intrev32ifbe(is->length)-from;// 获取要搬移多少个元素
    uint32_t encoding = intrev32ifbe(is->encoding);

    if (encoding == INTSET_ENC_INT64) {
        src = (int64_t*)is->contents+from;
        dst = (int64_t*)is->contents+to;
        bytes *= sizeof(int64_t);
    } else if (encoding == INTSET_ENC_INT32) {
        src = (int32_t*)is->contents+from;
        dst = (int32_t*)is->contents+to;
        bytes *= sizeof(int32_t);
    } else {
        src = (int16_t*)is->contents+from;      // 获取源地址
        dst = (int16_t*)is->contents+to;        // 搬移到的目的地址
        bytes *= sizeof(int16_t);
    }
    memmove(dst,src,bytes);     // 从src开始搬移bytes个字节到dst处
}

/* Insert an integer in the intset */
// 向整数集合中添加元素value,结果保存在success中,返回1表示成功, 0 失败
intset *intsetAdd(intset *is, int64_t value, uint8_t *success) {
    uint8_t valenc = _intsetValueEncoding(value);
    uint32_t pos;
    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. */
    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. */
        // 如果返回1,直接返回,因为该值原来就有,不需要插入
        if (intsetSearch(is,value,&pos)) {
            if (success) *success = 0;
            return is;
        }
        // 多空出来一个位置
        is = intsetResize(is,intrev32ifbe(is->length)+1);
        // 如果插入的位置不是最后一个的话,那么从插入位置开始都需要向后平移一个元素
        if (pos < intrev32ifbe(is->length)) intsetMoveTail(is,pos,pos+1);
    }

    _intsetSet(is,pos,value);
    // 更新整数集合的大小
    is->length = intrev32ifbe(intrev32ifbe(is->length)+1);
    return is;
}

/* Delete integer from intset */
// 
intset *intsetRemove(intset *is, int64_t value, int *success) {
    uint8_t valenc = _intsetValueEncoding(value);   // 获取类型
    uint32_t pos;
    if (success) *success = 0;
    // 第一个判断是为了配合数组升级的情况
    // 第二个判断是为了判断元素是否存在,存在返回1.pos中保存着所在的位置
    if (valenc <= intrev32ifbe(is->encoding) && intsetSearch(is,value,&pos)) {
        uint32_t len = intrev32ifbe(is->length);

        /* We know we can delete */
        if (success) *success = 1;

        /* Overwrite value with tail and update length */
        // 如果要删除的元素不是最后一个元素,那么需要把后面的元素向前移动一个位置
        // 如果是最后一个元素就不需要了,直接通过调整大小即可
        if (pos < (len-1)) intsetMoveTail(is,pos+1,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) {
    uint8_t valenc = _intsetValueEncoding(value);
    return valenc <= intrev32ifbe(is->encoding) && intsetSearch(is,value,NULL);
}

/* Return random member */
// 随机返回一个数组中的值
int64_t intsetRandom(intset *is) {
    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. */
// 从intset中获取pos位置的元素,如果存在返回1
// 不存在(下标越界)返回0
uint8_t intsetGet(intset *is, uint32_t pos, int64_t *value) {
    if (pos < intrev32ifbe(is->length)) {
        *value = _intsetGet(is,pos);
        return 1;
    }
    return 0;
}

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

/* Return intset blob size in bytes. */
// 返回整数集合所占的大小
size_t intsetBlobLen(intset *is) {
    return sizeof(intset)+intrev32ifbe(is->length)*intrev32ifbe(is->encoding);
}