Description

Defines the MPack configuration options.

Custom configuration of MPack is not usually necessary. In almost all cases you can ignore this and use the defaults.

If you do want to configure MPack, you can define the below options as part of your build system or project settings. This will override the below defaults.

If you'd like to use a file for configuration instead, define MPACK_HAS_CONFIG to 1 in your build system or project settings. This will cause MPack to include a file you create called mpack-config.h in which you can define your configuration. This is useful if you need to include specific headers (such as a custom allocator) in order to configure MPack to use it.

Warning: The value of all configuration options must be the same in all translation units of your project, as well as in the mpack source itself. These configuration options affect the layout of structs, among other things, which cannot be different in source files that are linked together.

Note: MPack does not contain defaults for building inside the Linux kernel. There is a configuration file for the Linux kernel that can be used instead.

Debug Functions
void	mpack_assert_fail (const char *message)
	Implement this and define MPACK_CUSTOM_ASSERT to use a custom assertion function. More...

File Configuration
#define	MPACK_HAS_CONFIG 0
	Causes MPack to include a file you create called `mpack-config.h` . More...

Features
#define	MPACK_READER 1
	Enables compilation of the base Tag Reader. More...

#define	MPACK_EXPECT 1
	Enables compilation of the static Expect API. More...

#define	MPACK_NODE 1
	Enables compilation of the dynamic Node API. More...

#define	MPACK_WRITER 1
	Enables compilation of the Writer. More...

#define	MPACK_BUILDER 1
	Enables compilation of the Builder. More...

#define	MPACK_COMPATIBILITY 0
	Enables compatibility features for reading and writing older versions of MessagePack. More...

#define	MPACK_EXTENSIONS 0
	Enables the use of extension types. More...

Dependencies
#define	MPACK_CONFORMING 1
	Enables the inclusion of basic C headers to define standard types and macros. More...

#define	MPACK_STDLIB 1
	Enables the use of the C stdlib. More...

#define	MPACK_STDIO 1
	Enables the use of C stdio. More...

#define	MPACK_FLOAT 1
	Whether the 'float' type and floating point operations are supported. More...

#define	MPACK_DOUBLE 1
	Whether the 'double' type is supported. More...

Allocation Functions
#define	MPACK_MALLOC malloc
	Defines the memory allocation function used by MPack. More...

#define	MPACK_FREE free
	Defines the memory free function used by MPack. More...

#define	MPACK_REALLOC realloc
	Defines the realloc function used by MPack. More...

System Functions
#define	MPACK_MEMCMP memcmp
	The function MPack will use to provide `memcmp()`. More...

#define	MPACK_MEMCPY memcpy
	The function MPack will use to provide `memcpy()`. More...

#define	MPACK_MEMMOVE memmove
	The function MPack will use to provide `memmove()`. More...

#define	MPACK_MEMSET memset
	The function MPack will use to provide `memset()`. More...

#define	MPACK_STRLEN strlen
	The function MPack will use to provide `strlen()`. More...

Debugging Options
#define	MPACK_DEBUG 1
	Enables debug features. More...

#define	MPACK_STRINGS 1
	Enables descriptive error and type strings. More...

#define	MPACK_CUSTOM_ASSERT 0
	Set this to 1 to implement a custom mpack_assert_fail() function. More...

#define	MPACK_READ_TRACKING 1
	Enables compound type size tracking for readers. More...

#define	MPACK_WRITE_TRACKING 1
	Enables compound type size tracking for writers. More...

Miscellaneous Options
#define	MPACK_OPTIMIZE_FOR_SIZE 0
	Whether to optimize for size or speed. More...

#define	MPACK_STACK_SIZE 4096
	Stack space in bytes to use when initializing a reader or writer with a stack-allocated buffer. More...

#define	MPACK_BUFFER_SIZE 4096
	Buffer size to use for allocated buffers (such as for a file writer.) More...

#define	MPACK_PAGE_SIZE 4096
	Minimum size for paged allocations in bytes. More...

#define	MPACK_NODE_PAGE_SIZE MPACK_PAGE_SIZE
	Minimum size of an allocated node page in bytes. More...

#define	MPACK_BUILDER_PAGE_SIZE MPACK_PAGE_SIZE
	Minimum size of an allocated builder page in bytes. More...

#define	MPACK_BUILDER_INTERNAL_STORAGE 0
	Enables a small amount of internal storage within the writer to avoid some allocations when using builders. More...

#define	MPACK_BUILDER_INTERNAL_STORAGE_SIZE 256
	Amount of space reserved inside mpack_writer_t for the Builders. More...

#define	MPACK_NODE_INITIAL_DEPTH 8
	The initial depth for the node parser. More...

#define	MPACK_NODE_MAX_DEPTH_WITHOUT_MALLOC 32
	The maximum depth for the node parser if MPACK_MALLOC is not available. More...

#define	MPACK_NO_BUILTINS 0
	Whether to disable compiler intrinsics and other built-in functions. More...

Macro Definition Documentation

◆ MPACK_BUFFER_SIZE

#define MPACK_BUFFER_SIZE 4096

Buffer size to use for allocated buffers (such as for a file writer.)

Starting with a single page and growing as needed seems to provide the best performance with minimal memory waste. Increasing this does not improve performance even when writing huge messages.

◆ MPACK_BUILDER

#define MPACK_BUILDER 1

Enables compilation of the Builder.

The Builder API provides additional functions to the Writer for automatically determining the element count of compound elements so you do not have to specify them up-front.

This requires a malloc(). It is enabled by default if MPACK_WRITER is enabled and MPACK_MALLOC is defined.

See also: mpack_build_map(); mpack_build_array(); mpack_complete_map(); mpack_complete_array()

◆ MPACK_BUILDER_INTERNAL_STORAGE

#define MPACK_BUILDER_INTERNAL_STORAGE 0

Enables a small amount of internal storage within the writer to avoid some allocations when using builders.

This is disabled by default. Enable it to potentially improve performance at the expense of a larger writer.

See also: MPACK_BUILDER_INTERNAL_STORAGE_SIZE to configure its size.

◆ MPACK_BUILDER_INTERNAL_STORAGE_SIZE

#define MPACK_BUILDER_INTERNAL_STORAGE_SIZE 256

Amount of space reserved inside mpack_writer_t for the Builders.

This can allow small messages to be built with the Builder API without incurring an allocation.

Builder metadata is placed in this space in addition to the literal MessagePack data. It needs to be big enough to be useful, but not so big as to overflow the stack. If more space is needed, pages are allocated.

This is only used if MPACK_BUILDER_INTERNAL_STORAGE is enabled.

See also: MPACK_BUILDER_PAGE_SIZE; MPACK_BUILDER_INTERNAL_STORAGE

Warning: Writers are typically placed on the stack so make sure you have sufficient stack space. Some libc use relatively small stacks even on desktop platforms, e.g. musl.

◆ MPACK_BUILDER_PAGE_SIZE

#define MPACK_BUILDER_PAGE_SIZE MPACK_PAGE_SIZE

Minimum size of an allocated builder page in bytes.

Builder writes are deferred to the allocated builder buffer which is composed of a list of buffer pages. This defines the size of those pages.

◆ MPACK_COMPATIBILITY

#define MPACK_COMPATIBILITY 0

Enables compatibility features for reading and writing older versions of MessagePack.

This is disabled by default. When disabled, the behaviour is equivalent to using the default version, mpack_version_current.

Enable this if you need to interoperate with applications or data that do not support the new (v5) MessagePack spec. See the section on v4 compatibility in Protocol Clarifications for more information.

◆ MPACK_CONFORMING

#define MPACK_CONFORMING 1

Enables the inclusion of basic C headers to define standard types and macros.

This causes MPack to include headers required for conforming implementations of C99 even in freestanding, in particular <stddef.h>, <stdint.h>, <stdbool.h> and <limits.h>. It also includes <inttypes.h>; this is technically not required for freestanding but MPack needs it to detect integer limits.

You can disable this if these headers are unavailable or if they do not define the standard types and macros (for example inside the Linux kernel.) If this is disabled, MPack will include no headers and will assume a 32-bit int. You will probably also want to define MPACK_HAS_CONFIG to 1 and include your own headers in the config file. You must provide definitions for standard types such as size_t, bool, int32_t and so on.

See also: cppreference.com documentation on Conformance

◆ MPACK_CUSTOM_ASSERT

#define MPACK_CUSTOM_ASSERT 0

Set this to 1 to implement a custom mpack_assert_fail() function.

See the documentation on mpack_assert_fail() for details.

Asserts are only used when MPACK_DEBUG is enabled, and can be triggered by bugs in MPack or bugs due to incorrect usage of MPack.

◆ MPACK_DEBUG

#define MPACK_DEBUG 1

Enables debug features.

You may want to wrap this around your own debug preprocs. By default, this is enabled if DEBUG or _DEBUG are defined. (NDEBUG is not used since it is allowed to have different values in different translation units.)

◆ MPACK_DOUBLE

#define MPACK_DOUBLE 1

Whether the 'double' type is supported.

This requires support for 'float'.

If MPACK_DOUBLE is disabled, doubles are read and written as uint32_t instead. This way messages with doubles do not result in errors and you can still perform manual doubles parsing yourself.

If MPACK_FLOAT is enabled but MPACK_DOUBLE is not, doubles can be read as floats using the shortening conversion functions, e.g. mpack_expect_float() or mpack_node_float().

◆ MPACK_EXPECT

#define MPACK_EXPECT 1

Enables compilation of the static Expect API.

◆ MPACK_EXTENSIONS

#define MPACK_EXTENSIONS 0

Enables the use of extension types.

This is disabled by default. Define it to 1 to enable it. If disabled, functions to read and write extensions will not exist, and any occurrence of extension types in parsed messages will flag mpack_error_invalid.

MPack discourages the use of extension types. See the section on extension types in Protocol Clarifications for more information.

◆ MPACK_FLOAT

#define MPACK_FLOAT 1

Whether the 'float' type and floating point operations are supported.

If MPACK_FLOAT is disabled, floats are read and written as uint32_t instead. This way messages with floats do not result in errors and you can still perform manual float parsing yourself.

◆ MPACK_FREE

#define MPACK_FREE free

Defines the memory free function used by MPack.

This is used by helpers for automatically allocating data the correct size. If this macro is undefined, the allocation helpers will not be compiled.

Set this to use a custom free() function. Your function must have the signature:

void free(void* p);

The default is free() if MPACK_MALLOC has not been customized and MPACK_STDLIB is enabled.

◆ MPACK_HAS_CONFIG

#define MPACK_HAS_CONFIG 0

Causes MPack to include a file you create called mpack-config.h .

The file is included before MPack sets any defaults for undefined configuration options. You can use it to configure MPack.

This is off by default.

◆ MPACK_MALLOC

#define MPACK_MALLOC malloc

Defines the memory allocation function used by MPack.

This is used by helpers for automatically allocating data the correct size, and for debugging functions. If this macro is undefined, the allocation helpers will not be compiled.

Set this to use a custom malloc() function. Your function must have the signature:

void* malloc(size_t size);

The default is malloc() if MPACK_STDLIB is enabled.

◆ MPACK_MEMCMP

#define MPACK_MEMCMP memcmp

The function MPack will use to provide memcmp().

Set this to use a custom memcmp() function. Your function must have the signature:

int memcmp(const void* left, const void* right, size_t count);

◆ MPACK_MEMCPY

#define MPACK_MEMCPY memcpy

The function MPack will use to provide memcpy().

Set this to use a custom memcpy() function. Your function must have the signature:

void* memcpy(void* restrict dest, const void* restrict src, size_t count);

◆ MPACK_MEMMOVE

#define MPACK_MEMMOVE memmove

The function MPack will use to provide memmove().

Set this to use a custom memmove() function. Your function must have the signature:

void* memmove(void* dest, const void* src, size_t count);

◆ MPACK_MEMSET

#define MPACK_MEMSET memset

The function MPack will use to provide memset().

Set this to use a custom memset() function. Your function must have the signature:

void* memset(void* p, int c, size_t count);

◆ MPACK_NO_BUILTINS

#define MPACK_NO_BUILTINS 0

Whether to disable compiler intrinsics and other built-in functions.

If this is enabled, MPack won't use __attribute__, __declspec, any function starting with __builtin, or pretty much anything else that isn't standard C.

◆ MPACK_NODE

#define MPACK_NODE 1

Enables compilation of the dynamic Node API.

◆ MPACK_NODE_INITIAL_DEPTH

#define MPACK_NODE_INITIAL_DEPTH 8

The initial depth for the node parser.

When MPACK_MALLOC is available, the node parser has no practical depth limit, and it is not recursive so there is no risk of overflowing the call stack.

◆ MPACK_NODE_MAX_DEPTH_WITHOUT_MALLOC

#define MPACK_NODE_MAX_DEPTH_WITHOUT_MALLOC 32

The maximum depth for the node parser if MPACK_MALLOC is not available.

◆ MPACK_NODE_PAGE_SIZE

#define MPACK_NODE_PAGE_SIZE MPACK_PAGE_SIZE

Minimum size of an allocated node page in bytes.

The children for a given compound element must be contiguous, so larger pages than this may be allocated as needed. (Safety checks exist to prevent malicious data from causing too large allocations.)

See mpack_node_data_t for the size of nodes.

Using as many nodes fit in one memory page seems to provide the best performance, and has very little waste when parsing small messages.

◆ MPACK_OPTIMIZE_FOR_SIZE

#define MPACK_OPTIMIZE_FOR_SIZE 0

Whether to optimize for size or speed.

Optimizing for size simplifies some parsing and encoding algorithms at the expense of speed and saves a few kilobytes of space in the resulting executable.

This automatically detects -Os with GCC/Clang. Unfortunately there doesn't seem to be a macro defined for /Os under MSVC.

◆ MPACK_PAGE_SIZE

#define MPACK_PAGE_SIZE 4096

Minimum size for paged allocations in bytes.

This is the value used by default for MPACK_NODE_PAGE_SIZE and MPACK_BUILDER_PAGE_SIZE.

◆ MPACK_READ_TRACKING

#define MPACK_READ_TRACKING 1

Enables compound type size tracking for readers.

This ensures that the correct number of elements or bytes are read from a compound type.

This is enabled by default in debug builds (provided a malloc() is available.)

◆ MPACK_READER

#define MPACK_READER 1

Enables compilation of the base Tag Reader.

◆ MPACK_REALLOC

#define MPACK_REALLOC realloc

Defines the realloc function used by MPack.

It is used by growable buffers to resize more efficiently.

The default is realloc() if MPACK_MALLOC has not been customized and MPACK_STDLIB is enabled.

Set this to use a custom realloc() function. Your function must have the signature:

void* realloc(void* p, size_t new_size);

This is optional, even when MPACK_MALLOC is used. If MPACK_MALLOC is set and MPACK_REALLOC is not, MPACK_MALLOC is used with a simple copy to grow buffers.

◆ MPACK_STACK_SIZE

#define MPACK_STACK_SIZE 4096

Stack space in bytes to use when initializing a reader or writer with a stack-allocated buffer.

Warning: Make sure you have sufficient stack space. Some libc use relatively small stacks even on desktop platforms, e.g. musl.

◆ MPACK_STDIO

#define MPACK_STDIO 1

Enables the use of C stdio.

This adds helpers for easily reading/writing C files and makes debugging easier.

◆ MPACK_STDLIB

#define MPACK_STDLIB 1

Enables the use of the C stdlib.

This allows the library to use basic functions like memcmp() and strlen(), as well as malloc() for debugging and in allocation helpers.

If this is disabled, allocation helper functions will not be defined, and MPack will attempt to detect compiler intrinsics for functions like memcmp() (assuming MPACK_NO_BUILTINS is not set.) It will fallback to its own (slow) implementations if it cannot use builtins. You may want to define MPACK_MEMCMP and friends if you disable this.

See also: MPACK_MEMCMP; MPACK_MEMCPY; MPACK_MEMMOVE; MPACK_MEMSET; MPACK_STRLEN; MPACK_MALLOC; MPACK_REALLOC; MPACK_FREE

◆ MPACK_STRINGS

#define MPACK_STRINGS 1

Enables descriptive error and type strings.

This can be turned off (by defining it to 0) to maximize space savings on embedded devices. If this is disabled, string functions such as mpack_error_to_string() and mpack_type_to_string() return an empty string.

◆ MPACK_STRLEN

#define MPACK_STRLEN strlen

The function MPack will use to provide strlen().

Set this to use a custom strlen() function. Your function must have the signature:

size_t strlen(const char* str);

◆ MPACK_WRITE_TRACKING

#define MPACK_WRITE_TRACKING 1

Enables compound type size tracking for writers.

This ensures that the correct number of elements or bytes are written in a compound type.

Note that without write tracking enabled, it is possible for buggy code to emit invalid MessagePack without flagging an error by writing the wrong number of elements or bytes in a compound type. With tracking enabled, MPack will catch such errors and break on the offending line of code.