Loading...
Searching...
No Matches
Introduction

MPack is a C implementation of an encoder and decoder for the MessagePack serialization format. It is:

- Simple and easy to use
- Secure against untrusted data
- Lightweight, suitable for embedded
- Extensively documented
- Extremely fast

The core of MPack contains a buffered reader and writer, and a tree-style parser that decodes into a tree of dynamically typed nodes. Helper functions can be enabled to read values of expected type, to work with files, to grow buffers or allocate strings automatically, to check UTF-8 encoding, and more.

The MPack code is small enough to be embedded directly into your codebase. Simply download the amalgamation package and add `mpack.h` and `mpack.c` to your project.

MPack supports all modern compilers, all desktop and smartphone OSes, WebAssembly, inside the Linux kernel, and even 8-bit microcontrollers such as Arduino. The MPack featureset can be customized at compile-time to set which features, components and debug checks are compiled, and what dependencies are available.

# The Node API

The Node API parses a chunk of MessagePack data into an immutable tree of dynamically-typed nodes. A series of helper functions can be used to extract data of specific types from each node.

// parse a file into a node tree
mpack_tree_t tree;
mpack_tree_init_filename(&tree, "homepage-example.mp", 0);
mpack_tree_parse(&tree);
mpack_node_t root = mpack_tree_root(&tree);
// extract the example data on the msgpack homepage
bool compact = mpack_node_bool(mpack_node_map_cstr(root, "compact"));
int schema = mpack_node_i32(mpack_node_map_cstr(root, "schema"));
// clean up and check for errors
if (mpack_tree_destroy(&tree) != mpack_ok) {
fprintf(stderr, "An error occurred decoding the data!\n");
return;
}
mpack_ok
@ mpack_ok
No error.
Definition: mpack-common.h:162
mpack_node_i32
int32_t mpack_node_i32(mpack_node_t node)
Returns the 32-bit signed value of the node.
mpack_tree_init_filename
void mpack_tree_init_filename(mpack_tree_t *tree, const char *filename, size_t max_bytes)
Initializes a tree to parse the given file.
mpack_node_t
struct mpack_node_t mpack_node_t
A handle to node data in a parsed MPack tree.
Definition: mpack-node.h:63
mpack_tree_root
mpack_node_t mpack_tree_root(mpack_tree_t *tree)
Returns the root node of the tree, if the tree is not in an error state.
mpack_node_map_cstr
mpack_node_t mpack_node_map_cstr(mpack_node_t node, const char *cstr)
Returns the value node in the given map for the given null-terminated string key.
mpack_tree_parse
void mpack_tree_parse(mpack_tree_t *tree)
Parses a MessagePack message into a tree of immutable nodes.
mpack_tree_t
struct mpack_tree_t mpack_tree_t
An MPack tree parser to parse a blob or stream of MessagePack.
Definition: mpack-node.h:82
mpack_tree_destroy
mpack_error_t mpack_tree_destroy(mpack_tree_t *tree)
Destroys the tree.
mpack_node_bool
bool mpack_node_bool(mpack_node_t node)
Returns the bool value of the node.

Note that no additional error handling is needed in the above code. If the file is missing or corrupt, if map keys are missing or if nodes are not in the expected types, special "nil" nodes and false/zero values are returned and the tree is placed in an error state. An error check is only needed before using the data.

The above example allocates nodes automatically. A fixed node pool can be provided to the parser instead in memory-constrained environments. For maximum performance and minimal memory usage, the Expect API can be used to parse data of a predefined schema.

# The Write API

The Write API encodes structured data to MessagePack.

// encode to memory buffer
char* data;
size_t size;
mpack_writer_t writer;
mpack_writer_init_growable(&writer, &data, &size);
// write the example on the msgpack homepage
mpack_build_map(&writer);
mpack_write_cstr(&writer, "compact");
mpack_write_bool(&writer, true);
mpack_write_cstr(&writer, "schema");
mpack_write_uint(&writer, 0);
mpack_complete_map(&writer);
// finish writing
if (mpack_writer_destroy(&writer) != mpack_ok) {
fprintf(stderr, "An error occurred encoding the data!\n");
return;
}
// use the data
do_something_with_data(data, size);
free(data);
mpack_writer_init_growable
void mpack_writer_init_growable(mpack_writer_t *writer, char **data, size_t *size)
Initializes an MPack writer using a growable buffer.
mpack_complete_map
void mpack_complete_map(struct mpack_writer_t *writer)
Completes a map being built.
mpack_writer_destroy
mpack_error_t mpack_writer_destroy(mpack_writer_t *writer)
Cleans up the MPack writer, flushing and closing the underlying stream, if any.
mpack_write_cstr
void mpack_write_cstr(mpack_writer_t *writer, const char *cstr)
Writes a null-terminated string.
mpack_build_map
void mpack_build_map(struct mpack_writer_t *writer)
Starts building a map.
mpack_write_bool
void mpack_write_bool(mpack_writer_t *writer, bool value)
Writes a boolean.
mpack_write_uint
void mpack_write_uint(mpack_writer_t *writer, uint64_t value)
Writes an unsigned integer in the most efficient packing available.
Definition: mpack-writer.h:589
mpack_writer_t
struct mpack_writer_t mpack_writer_t
A buffered MessagePack encoder.
Definition: mpack-writer.h:66

In the above example, we encode to a growable memory buffer. The writer can instead write to a pre-allocated or stack-allocated buffer (with up-front sizes for compound types), avoiding the need for memory allocation. The writer can also be provided with a flush function (such as a file or socket write function) to call when the buffer is full or when writing is done.

If any error occurs, the writer is placed in an error state. The writer will flag an error if too much data is written, if the wrong number of elements are written, if an allocation failure occurs, if the data could not be flushed, etc. No additional error handling is needed in the above code; any subsequent writes are ignored when the writer is in an error state, so you don't need to check every write for errors.

The above example uses `mpack_build_map()` to automatically determine the number of key-value pairs contained. If you know up-front the number of elements needed, you can pass it to `mpack_start_map()` instead. In that case the corresponding `mpack_finish_map()` will assert in debug mode that the expected number of elements were actually written, which is something that other MessagePack C/C++ libraries may not do.

# Comparison With Other Parsers

MPack is rich in features while maintaining very high performance and a small code footprint. Here's a short feature table comparing it to other C parsers:

| MPack (v1.1) | msgpack-c (v3.3.0) | CMP (v19) | CWPack (v1.3.1)
--- | --- | --- | --- | ---
No libc requirement | ✓ |  | ✓ | ✓
Growable memory writer | ✓ | ✓ |  | ✓*
File I/O helpers | ✓ | ✓ |  | ✓*
Stateful error handling | ✓ |  | ✓ |
Incremental parser | ✓ |  | ✓ | ✓
Tree stream parser | ✓ | ✓ |  |
Compound size tracking | ✓ |  |  |
Automatic compound size | ✓ |  |  |

A larger feature comparison table is available here which includes descriptions of the various entries in the table.

This benchmarking suite compares the performance of MPack to other implementations of schemaless serialization formats. MPack outperforms all JSON and MessagePack libraries (except CWPack), and in some tests MPack is several times faster than RapidJSON for equivalent data.

# Why Not Just Use JSON?

Conceptually, MessagePack stores data similarly to JSON: they are both composed of simple values such as numbers and strings, stored hierarchically in maps and arrays. So why not just use JSON instead? The main reason is that JSON is designed to be human-readable, so it is not as efficient as a binary serialization format:

- Compound types such as strings, maps and arrays are delimited, so appropriate storage cannot be allocated upfront. The whole object must be parsed to determine its size.
- Strings are not stored in their native encoding. Special characters such as quotes and backslashes must be escaped when written and converted back when read.
- Numbers are particularly inefficient (especially when parsing back floats), making JSON inappropriate as a base format for structured data that contains lots of numbers.
- Binary data is not supported by JSON at all. Small binary blobs such as icons and thumbnails need to be Base64 encoded or passed out-of-band.

The above issues greatly increase the complexity of the decoder. Full-featured JSON decoders are quite large, and minimal decoders tend to leave out such features as string unescaping and float parsing, instead leaving these up to the user or platform. This can lead to hard-to-find platform-specific and locale-specific bugs, as well as a greater potential for security vulnerabilites. This also significantly decreases performance, making JSON unattractive for use in applications such as mobile games.

While the space inefficiencies of JSON can be partially mitigated through minification and compression, the performance inefficiencies cannot. More importantly, if you are minifying and compressing the data, then why use a human-readable format in the first place?

# Testing MPack

The MPack build process does not build MPack into a library; it is used to build and run the unit tests. You do not need to build MPack or the unit testing suite to use MPack.

See test/README.md for information on how to test MPack.