[redis source code day reading] compressed list (ziplist)

Compressed list

Like the author: redis source code, many comments and very detailed. Before looking at the source code of the compressed list, you can first look at the comments at the top of the ziplist.c file to basically understand the data structure design.

The compressed list ziplist is a two-way linked list designed to save memory. It stores both strings and integer values. The internal implementation of the list is mainly to manage a piece of continuous memory. The list supports the insertion or pop-up of nodes at the beginning and end of the list. Because write operations involve memory reallocation, the complexity depends on the current usage of memory. Generally, it is not recommended to store a large amount of data. According to the data length, the sorted set is saved with two data structures, ziplist and skiplist.

The ziplist is a specially encoded dually linked list that is designed to be very memory efficient. It stores both strings and integer values, where integers are encoded as actual integers instead of a series of characters. It allows push and pop operations on either side of the list in O(1) time. However, because every operation requires a reallocation of the memory used by the ziplist, the actual complexity is related to the amount of memory used by the ziplist.


Compression principle: for example, int a = 0 a is an integer variable, accounting for 4 bytes. But the number a = 0, 0 needs only one bit to save. If we use 4 bytes (32 bit) of memory to save it, it will be a waste. According to this idea, you can roughly understand how compression strategy works. For details, see the document and source code.

Compressed data management is a bit like data serialization, which is often used in the transmission of serialized data. You can understand the protobuf source code and see how the data is packaged. In addition to data serialization, the compressed list also needs to insert and delete data, and some additional structures need to be added for memory management.


List structure

Head + node + tail
<zlbytes> <zltail> <zllen> <entry> <entry> ... <entry> <zlend>

/* Size of the "end of ziplist" entry. Just one byte. */
#define ZIPLIST_HEADER_SIZE     (sizeof(uint32_t)*2+sizeof(uint16_t))

/* Size of the "end of ziplist" entry. Just one byte. */
#define ZIPLIST_END_SIZE        (sizeof(uint8_t))

/* Return total bytes a ziplist is composed of. */
#define ZIPLIST_BYTES(zl)       (*((uint32_t*)(zl)))

/* Return the offset of the last item inside the ziplist. */
#define ZIPLIST_TAIL_OFFSET(zl) (*((uint32_t*)((zl)+sizeof(uint32_t))))

/* Return the length of a ziplist, or UINT16_MAX if the length cannot be
 * determined without scanning the whole ziplist. */
#define ZIPLIST_LENGTH(zl)      (*((uint16_t*)((zl)+sizeof(uint32_t)*2)))

/* Special "end of ziplist" entry. */
#define ZIP_END 255


Node structure: < prevlen > < encoding > < entry data >, but sometimes the value is very small. Data can also be saved with < encoding >, which does not need < entry data >, that is, < prevlen > < encoding >.

The nodes of the compressed list are a little special. The list here is not a traditional list. Each node of the traditional list has a prev or next pointer to connect. The compressed list node locates the previous node in memory through prevlen because <encoding> The current node data type and data length are stored, so that the next node can be located backward.


condition length format
< 254 bytes 1 byte <prevlen from 0 to 253> <encoding> <entry-dagta>
>=254 bytes 5 byte 0xFE <4 bytes unsigned little endian prevlen> <encoding> <entry-data>

The length of the previous node is stored at the head of this node. There are two storage lengths, one byte or five byte space for storage. Please refer to the previous description for details.

/* Return the number of bytes used to encode the length of the previous
 * entry. The length is returned by setting the var 'prevlensize'. */
#define ZIP_DECODE_PREVLENSIZE(ptr, prevlensize) do {                          \
    if ((ptr)[0] < ZIP_BIG_PREVLEN) {                                          \
        (prevlensize) = 1;                                                     \
    } else {                                                                   \
        (prevlensize) = 5;                                                     \
    }                                                                          \
} while(0);

prevlen: the length of the previous node.
prevlensize: how much memory is used to save prevlen (1 / 5)

/* Return the length of the previous element, and the number of bytes that
 * are used in order to encode the previous element length.
 * 'ptr' must point to the prevlen prefix of an entry (that encodes the
 * length of the previous entry in order to navigate the elements backward).
 * The length of the previous entry is stored in 'prevlen', the number of
 * bytes needed to encode the previous entry length are stored in
 * 'prevlensize'. */
#define ZIP_DECODE_PREVLEN(ptr, prevlensize, prevlen) do {                     \
    ZIP_DECODE_PREVLENSIZE(ptr, prevlensize);                                  \
    if ((prevlensize) == 1) {                                                  \
        (prevlen) = (ptr)[0];                                                  \
    } else if ((prevlensize) == 5) {                                           \
        assert(sizeof((prevlen)) == 4);                                    \
        memcpy(&(prevlen), ((char*)(ptr)) + 1, 4);                             \
        memrev32ifbe(&prevlen);                                                \
    }                                                                          \
} while(0);


There are two types of encoding: string / integer

The encoding field of the entry depends on the content of the entry. When the entry is a string, the first 2 bits of the encoding first byte will hold the type of encoding used to store the length of the string, followed by the actual length of the string. When the entry is an integer the first 2 bits are both set to 1. The following 2 bits are used to specify what kind of integer will be stored after this header. An overview of the different types and encodings is as follows. The first byte is always enough to determine the kind of entry.

Character string

If the content of a node is a string, the first two bits of < encoding > are mainly used to store the encoding type, and the remaining bits are used to store the string length of the current string. Three information can be obtained from < encoding >

  1. Encoding type.
  2. Length of node data content.
  3. The whole < encoding > length.
Identification encoding length String length describe Be careful
|00pppppp| 1 byte < = 63 bytes (6 bits) encoding is saved in one byte. The first two bits are 0, and the last six bits store the string length
|01pppppp|qqqqqqqq| 2 bytes < = 16383 bytes (14 bits) The first two bits of encoding are 0, followed by the next six bits to save the string length. 14 bit value is saved in large end mode
|10000000|qqqqqqqq|rrrrrrrr|ssssssss|tttttttt| 5 bytes >=16384 bytes The first byte of encoding is the identification, and the last four bytes hold the string length. The length value is saved in large end mode

Determine whether the first two bit s of a byte are 1, if not a string. ZIP_STR_MASK = “1100 0000”

/* Extract the encoding from the byte pointed by 'ptr' and set it into
 * 'encoding' field of the zlentry structure. */
#define ZIP_ENTRY_ENCODING(ptr, encoding) do {  \
    (encoding) = (ptr[0]); \
    if ((encoding) < ZIP_STR_MASK) (encoding) &= ZIP_STR_MASK; \
} while(0)

numerical value

When the node content is a value, the first two bits of < encoding > are set to 1, and the next two bits are used to save the value type. Three information can be obtained from < encoding >

  1. Encoding type.
  2. Value type.
  3. Numerical value.
First byte identification encoding length Numerical length describe
|11000000| 3 bytes 2 bytes int16_t
|11010000| 5 bytes 4 bytes int32_t
|11100000| 9 bytes 8 bytes int64_t
|11110000| 4 bytes 3 bytes Integer encoded as 24 bit signed (3 bytes).
|11111110| 2 bytes 1 byte Integer encoded as 8 bit signed (1 byte).
|1111xxxx| 1 byte 4 bits 4 bit integer can store 0 - 12, because 000011111111 can't be used, only 1 - 13 can be stored, so the saved number needs to be + 1 for operation, and - 1 is required after parsing
|11111111| 1 byte 0 bit List Terminator

Codec implementation

#define ZIP_STR_MASK 0xc0
#define ZIP_INT_MASK 0x30
#define ZIP_STR_06B (0 << 6)
#define ZIP_STR_14B (1 << 6)
#define ZIP_STR_32B (2 << 6)
#define ZIP_INT_16B (0xc0 | 0<<4)
#define ZIP_INT_32B (0xc0 | 1<<4)
#define ZIP_INT_64B (0xc0 | 2<<4)
#define ZIP_INT_24B (0xc0 | 3<<4)
#define ZIP_INT_8B 0xfe

/* Macro to determine if the entry is a string. String entries never start
 * with "11" as most significant bits of the first byte. */
#define ZIP_IS_STR(enc) (((enc) & ZIP_STR_MASK) < ZIP_STR_MASK)

/* Write the encoidng header of the entry in 'p'. If p is NULL it just returns
 * the amount of bytes required to encode such a length. Arguments:
 * 'encoding' is the encoding we are using for the entry. It could be
 * ZIP_INT_* or ZIP_STR_* or between ZIP_INT_IMM_MIN and ZIP_INT_IMM_MAX
 * for single-byte small immediate integers.
 * 'rawlen' is only used for ZIP_STR_* encodings and is the length of the
 * srting that this entry represents.
 * The function returns the number of bytes used by the encoding/length
 * header stored in 'p'. */
unsigned int zipStoreEntryEncoding(unsigned char *p, unsigned char encoding, unsigned int rawlen) {
    unsigned char len = 1, buf[5];

    if (ZIP_IS_STR(encoding)) {
        /* Although encoding is given it may not be set for strings,
         * so we determine it here using the raw length. */
        if (rawlen <= 0x3f) {
            if (!p) return len;
            buf[0] = ZIP_STR_06B | rawlen;
        } else if (rawlen <= 0x3fff) {
            len += 1;
            if (!p) return len;
            buf[0] = ZIP_STR_14B | ((rawlen >> 8) & 0x3f);
            buf[1] = rawlen & 0xff;
        } else {
            len += 4;
            if (!p) return len;
            buf[0] = ZIP_STR_32B;
            buf[1] = (rawlen >> 24) & 0xff;
            buf[2] = (rawlen >> 16) & 0xff;
            buf[3] = (rawlen >> 8) & 0xff;
            buf[4] = rawlen & 0xff;
    } else {
        /* Implies integer encoding, so length is always 1. */
        if (!p) return len;
        buf[0] = encoding;

    /* Store this length at p. */
    return len;

/* 'encoding' field of the zlentry structure. */
#define ZIP_ENTRY_ENCODING(ptr, encoding) do {  \
    (encoding) = (ptr[0]); \
    // If it is a string type, take the first two bits and the other bits are 0
    if ((encoding) < ZIP_STR_MASK) (encoding) &= ZIP_STR_MASK; \
} while(0)

#define ZIP_INT_IMM_MIN 0xf1    /* 11110001 */
#define ZIP_INT_IMM_MAX 0xfd    /* 11111101 */

/* Return bytes needed to store integer encoded by 'encoding'. */
unsigned int zipIntSize(unsigned char encoding) {
    switch(encoding) {
    case ZIP_INT_8B:  return 1;
    case ZIP_INT_16B: return 2;
    case ZIP_INT_24B: return 3;
    case ZIP_INT_32B: return 4;
    case ZIP_INT_64B: return 8;
    if (encoding >= ZIP_INT_IMM_MIN && encoding <= ZIP_INT_IMM_MAX)
        return 0; /* 4 bit immediate */
    panic("Invalid integer encoding 0x%02X", encoding);
    return 0;

/* Store integer 'value' at 'p', encoded as 'encoding' */
void zipSaveInteger(unsigned char *p, int64_t value, unsigned char encoding) {
    int16_t i16;
    int32_t i32;
    int64_t i64;
    if (encoding == ZIP_INT_8B) {
        ((int8_t *)p)[0] = (int8_t)value;
    } else if (encoding == ZIP_INT_16B) {
        i16 = value;
        memcpy(p, &i16, sizeof(i16));
    } else if (encoding == ZIP_INT_24B) {
        i32 = value << 8;
        memcpy(p, ((uint8_t *)&i32) + 1, sizeof(i32) - sizeof(uint8_t));
    } else if (encoding == ZIP_INT_32B) {
        i32 = value;
        memcpy(p, &i32, sizeof(i32));
    } else if (encoding == ZIP_INT_64B) {
        i64 = value;
        memcpy(p, &i64, sizeof(i64));
    } else if (encoding >= ZIP_INT_IMM_MIN && encoding <= ZIP_INT_IMM_MAX) {
        /* Nothing to do, the value is stored in the encoding itself. */
    } else {

/* Decode the entry encoding type and data length (string length for strings,
 * number of bytes used for the integer for integer entries) encoded in 'ptr'.
 * The 'encoding' variable will hold the entry encoding, the 'lensize'
 * variable will hold the number of bytes required to encode the entry
 * length, and the 'len' variable will hold the entry length. */
#define ZIP_DECODE_LENGTH(ptr, encoding, lensize, len) do {                    \
    ZIP_ENTRY_ENCODING((ptr), (encoding));                                     \
    if ((encoding) < ZIP_STR_MASK) {                                           \
        if ((encoding) == ZIP_STR_06B) {                                       \
            (lensize) = 1;                                                     \
            (len) = (ptr)[0] & 0x3f;                                           \
        } else if ((encoding) == ZIP_STR_14B) {                                \
            (lensize) = 2;                                                     \
            (len) = (((ptr)[0] & 0x3f) << 8) | (ptr)[1];                       \
        } else if ((encoding) == ZIP_STR_32B) {                                \
            (lensize) = 5;                                                     \
            (len) = ((ptr)[1] << 24) |                                         \
                    ((ptr)[2] << 16) |                                         \
                    ((ptr)[3] <<  8) |                                         \
                    ((ptr)[4]);                                                \
        } else {                                                               \
            panic("Invalid string encoding 0x%02X", (encoding));               \
        }                                                                      \
    } else {                                                                   \
        (lensize) = 1;                                                         \
        (len) = zipIntSize(encoding);                                          \
    }                                                                          \
} while(0);


We can go through the program logic through debugging, observe the memory management of the data structure, and understand the workflow of ziplistNew, ziplistPush and other interfaces.

Debugging in order to compile through the appropriate increase or decrease part of the code.

gcc -g ziplist.c sds.c zmalloc.c util.c sha1.c -o ziplist  -I../deps/lua/src
sudo gdb ziplist


Create list

Initialize the information header and footer. You can check it. List structure

/* Create a new empty ziplist. */
unsigned char *ziplistNew(void) {
    unsigned int bytes = ZIPLIST_HEADER_SIZE+ZIPLIST_END_SIZE;
    unsigned char *zl = zmalloc(bytes);
    ZIPLIST_BYTES(zl) = intrev32ifbe(bytes);
    ZIPLIST_LENGTH(zl) = 0;
    // A byte at the end of the data structure is identified by '255' (OXFF).
    zl[bytes-1] = ZIP_END;
    return zl;

Add node

Insert elements at the beginning or end of a list

unsigned char *ziplistPush(unsigned char *zl, unsigned char *s, unsigned int slen, int where) {
    unsigned char *p;
    // #define ZIPLIST_HEADER_SIZE     (sizeof(uint32_t)*2+sizeof(uint16_t))
    // #define ZIPLIST_BYTES(zl)       (*((uint32_t*)(zl)))
    // #define ZIPLIST_ENTRY_END(zl)   ((zl)+intrev32ifbe(ZIPLIST_BYTES(zl))-1)
    return __ziplistInsert(zl,p,s,slen);

Insert Knot

Inserts data according to the location specified by p.

/* Insert item at "p". */
unsigned char *__ziplistInsert(unsigned char *zl, unsigned char *p, unsigned char *s, unsigned int slen) {
    // Get the current total memory length
    size_t curlen = intrev32ifbe(ZIPLIST_BYTES(zl)), reqlen;
    unsigned int prevlensize, prevlen = 0;
    size_t offset;
    int nextdiff = 0;
    unsigned char encoding = 0;
    long long value = 123456789; /* initialized to avoid warning. Using a value
                                    that is easy to see if for some reason
                                    we use it uninitialized. */
    zlentry tail;

    // If it is not the end node, the length of the previous node is obtained from the current node. If it is an end node, the length of the end node is taken (the end node is not an end node).
    /* Find out prevlen for the entry that is inserted. */
    if (p[0] != ZIP_END) {
        ZIP_DECODE_PREVLEN(p, prevlensize, prevlen);
    } else {
        // Terminal node
        unsigned char *ptail = ZIPLIST_ENTRY_TAIL(zl);
        if (ptail[0] != ZIP_END) {
            prevlen = zipRawEntryLength(ptail);

    // Get the content length. The string will try to convert to integer first.
    /* See if the entry can be encoded */
    if (zipTryEncoding(s,slen,&value,&encoding)) {
        /* 'encoding' is set to the appropriate integer encoding */
        reqlen = zipIntSize(encoding);
    } else {
        /* 'encoding' is untouched, however zipStoreEntryEncoding will use the
         * string length to figure out how to encode it. */
        reqlen = slen;
    /* We need space for both the length of the previous entry and
     * the length of the payload. */
    reqlen += zipStorePrevEntryLength(NULL,prevlen);
    reqlen += zipStoreEntryEncoding(NULL,encoding,slen);

    // When the < prevlen > of the node after the insertion position changes, nextdiff calculates the lensize difference of < prevlen >.
    /* When the insert position is not equal to the tail, we need to
     * make sure that the next entry can hold this entry's length in
     * its prevlen field. */
    int forcelarge = 0;
    nextdiff = (p[0] != ZIP_END) ? zipPrevLenByteDiff(p,reqlen) : 0;

    // Reduce the < prevlen > lensize chain reaction of subsequent nodes in the insertion location, and frequently call ziplistResize to lose performance. Force a forcetarget write.
    // For details, please refer to: https://segmentfault.com/a/11900018878466? Utm_source = Tag New est
    if (nextdiff == -4 && reqlen < 4) {
        nextdiff = 0;
        forcelarge = 1;

    /* Store offset because a realloc may change the address of zl. */
    offset = p-zl;
    zl = ziplistResize(zl,curlen+reqlen+nextdiff);
    p = zl+offset;

    /* Apply memory move when necessary and update tail offset. */
    if (p[0] != ZIP_END) {
        /* Subtract one because of the ZIP_END bytes */

        /* Encode this entry's raw length in the next entry. */
        if (forcelarge)

        /* Update offset for tail */

        /* When the tail contains more than one entry, we need to take
         * "nextdiff" in account as well. Otherwise, a change in the
         * size of prevlen doesn't have an effect on the *tail* offset. */
        zipEntry(p+reqlen, &tail);
        if (p[reqlen+tail.headersize+tail.len] != ZIP_END) {
            ZIPLIST_TAIL_OFFSET(zl) =
    } else {
        /* This element will be the new tail. */
        ZIPLIST_TAIL_OFFSET(zl) = intrev32ifbe(p-zl);

    // < ENTER > saves < prevlen >, the front node changes, resulting in the length changes, and the chain reaction of the back nodes also needs to be modified
    /* When nextdiff != 0, the raw length of the next entry has changed, so
     * we need to cascade the update throughout the ziplist */
    if (nextdiff != 0) {
        offset = p-zl;
        zl = __ziplistCascadeUpdate(zl,p+reqlen);
        p = zl+offset;

    /* Write the entry */
    p += zipStorePrevEntryLength(p,prevlen);
    p += zipStoreEntryEncoding(p,encoding,slen);
    if (ZIP_IS_STR(encoding)) {
    } else {
    return zl;


  • Reallocate memory
    ziplist needs to reallocate memory to write data.

  • Coupling problem
    ziplist compresses data for continuous memory management, saving memory overhead and memory fragmentation. However, prevlen, as a part of data node pair, is seriously coupled with other nodes. As long as a node is inserted or deleted in the middle of the linked list, it may be necessary to traverse all subsequent nodes in the update insertion or deletion position < prevlen >.

The implementation of sorted set is limited to write data.


zset-max-ziplist-entries 128
zset-max-ziplist-value 64


void zaddGenericCommand(client *c, int flags) {
    zobj = lookupKeyWrite(c->db,key);
    if (zobj == NULL) {
        if (xx) goto reply_to_client; /* No key + XX option: nothing to do. */
        if (server.zset_max_ziplist_entries == 0 ||
            server.zset_max_ziplist_value < sdslen(c->argv[scoreidx+1]->ptr))
            zobj = createZsetObject();
        } else {
            zobj = createZsetZiplistObject();
    } else {
        if (zobj->type != OBJ_ZSET) {
            goto cleanup;
  • Complexity
    The offset of the pointer tests the technical ability. The ziplist implementation is a bit more complex (for me). If it is much simpler to use the traditional two-way linked list, the purpose of compression can still be achieved, and the coupling between nodes is relatively small.

Reference resources

A historical bug of Redis and its subsequent improvement
Ziplist: insertion bug under particular conditions fixed.

55 original articles published, 10 praised, 90000 visitors+
Private letter follow

Tags: encoding Redis codec SHA1

Posted on Thu, 30 Jan 2020 00:22:05 -0500 by markmax33