Skip to content
Snippets Groups Projects
README.md 2.95 KiB
Newer Older
  • Learn to ignore specific revisions
  • clwi's avatar
    clwi committed
    # CWPack
    
    clwi's avatar
    clwi committed
    
    
    clwi's avatar
    clwi committed
    CWPack is a lightweight and yet complete implementation of the 
    
    clwi's avatar
    clwi committed
    [MessagePack](http://msgpack.org) serialization format 
    [version 5](https://github.com/msgpack/msgpack/blob/master/spec.md).
    
    
    clwi's avatar
    clwi committed
    ## Excellent Performance
    
    clwi's avatar
    clwi committed
    
    
    clwi's avatar
    clwi committed
    Together with [MPack](https://github.com/ludocode/mpack), CWPack is the fastest open-source messagepack implementation. Both totally outperform
    [CMP](https://github.com/camgunz/cmp) and [msgpack-c](https://github.com/msgpack/msgpack-c)
    
    clwi's avatar
    clwi committed
    
    
    clwi's avatar
    clwi committed
    ## Design
    
    CWPack does no memory allocations and no file handling. All that is done 
    outside of CWPack.
    
    CWPack is working against memory buffers. User defined handlers are called when buffers are 
    filled up (packing) or needs refill (unpack). 
    
    Containers (arrays, maps) are read/written in parts, first the item containing the size and 
    then the contained items one by one. Exception to this is the `cw_skip_items` function which 
    skip whole containers.
    
    ## Example
    
    Pack and unpack example from the MessagePack home page:
    
    
    clwi's avatar
    clwi committed
    ```c
    
    clwi's avatar
    clwi committed
    void example (void)
    {
        cw_pack_context pc;
        char buffer[20];
        cw_pack_context_init (&pc, buffer, 20, 0, 0);
    
    
    clwi's avatar
    clwi committed
        cw_pack_map_size (&pc, 2);
        cw_pack_str (&pc, "compact", 7);
        cw_pack_boolean (&pc, true);
        cw_pack_str (&pc, "schema", 6);
        cw_pack_unsigned (&pc, 0);
    
    clwi's avatar
    clwi committed
    
        int length = pc.current - pc.start;
    
    clwi's avatar
    clwi committed
        if (length > 18) ERROR;
    
    clwi's avatar
    clwi committed
    
        cw_unpack_context uc;
        cw_unpack_context_init (&uc, pc.start, length, 0, 0);
    
    
    clwi's avatar
    clwi committed
        cw_unpack_next(&uc);
    
    clwi's avatar
    clwi committed
        if (uc.item.type != CWP_ITEM_MAP || uc.item.as.map.size != 2) ERROR;
    
    
    clwi's avatar
    clwi committed
        cw_unpack_next(&uc);
    
    clwi's avatar
    clwi committed
        if (uc.item.type != CWP_ITEM_STR || uc.item.as.str.length != 7)) ERROR;
        if (strncmp("compact", uc.item.as.str.start, 7)) ERROR;
    
    
    clwi's avatar
    clwi committed
        cw_unpack_next(&uc);
    
    clwi's avatar
    clwi committed
        if (uc.item.type != CWP_ITEM_BOOLEAN || uc.item.as.boolean != true) ERROR;
    
    
    clwi's avatar
    clwi committed
        cw_unpack_next(&uc);
    
    clwi's avatar
    clwi committed
        if (uc.item.type != CWP_ITEM_STR || uc.item.as.str.length != 6)) ERROR;
        if (strncmp("schema", uc.item.as.str.start, 6)) ERROR;
    
    
    clwi's avatar
    clwi committed
        cw_unpack_next(&uc);
    
    clwi's avatar
    clwi committed
        if (uc.item.type != CWP_ITEM_POSITIVE_INTEGER || uc.item.as.u64 != 0) ERROR;
    
    
    clwi's avatar
    clwi committed
        cw_unpack_next(&uc);
        if (uc.return_code != CWP_RC_END_OF_INPUT)  ERROR;
    
    clwi's avatar
    clwi committed
    }
    
    clwi's avatar
    clwi committed
    ```
    
    clwi's avatar
    clwi committed
    
    
    clwi's avatar
    clwi committed
    In the examples folder there are more examples.
    
    ## Backward compatibility
    
    
    clwi's avatar
    clwi committed
    CWPack may be run in compatibility mode. It affects only packing; EXT is considered illegal, BIN are transformed to STR and generation of STR8 is supressed.
    
    clwi's avatar
    clwi committed
    
    
    clwi's avatar
    clwi committed
    ## Error handling
    
    
    clwi's avatar
    clwi committed
    When an error is detected in a context, the context is stopped and all future calls to that context are immediatly returned without any actions.
    
    clwi's avatar
    clwi committed
    
    
    clwi's avatar
    clwi committed
    CWPack does not check for illegal values (e.g. in STR for illegal unicode characters).
    
    clwi's avatar
    clwi committed
    
    ## Build
    
    
    clwi's avatar
    clwi committed
    CWPack consists of a single src file and two header files. It is written 
    
    clwi's avatar
    clwi committed
    in strict ansi C and the files are together ~ 1.2K lines. No separate build is neccesary, just include the 
    
    clwi's avatar
    clwi committed
    files in your own build.
    
    CWPack has no dependencies to other libraries.
    
    
    clwi's avatar
    clwi committed
    ## Test
    
    clwi's avatar
    clwi committed
    
    
    clwi's avatar
    clwi committed
    Included in the test folder are a module test and a performance test and shell scripts to run them.