Configuration Options

Description

Defines the MPack configuration options.

Copy mpack-config.h.sample to mpack-config.h somewhere in your project's include tree and, optionally, edit it to suit your setup. In almost all cases you can leave this file with the default config.

You can also override the default configuration by pre-defining options to 0 or 1.

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...

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

System 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...

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
#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_NODE_PAGE_SIZE   4096
	Size of an allocated node page in bytes. 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...

Macro Definition Documentation

#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.

#define MPACK_CUSTOM_ASSERT   0

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

This function must not return, and must have the following signature:

void mpack_assert_fail(const char* message)

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.

#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.

Note that MPACK_DEBUG cannot be defined differently for different source files because it affects layout of structs defined in header files. Your entire project must be compiled with the same value of MPACK_DEBUG. (This is why NDEBUG is not used.)

#define MPACK_EXPECT   1

Enables compilation of the static Expect API.

#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.

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

#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.

The default is malloc() if MPACK_STDLIB is enabled.

#define MPACK_NODE   1

Enables compilation of the dynamic Node API.

#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.

#define MPACK_NODE_MAX_DEPTH_WITHOUT_MALLOC   32

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

The parsing stack is placed on the call stack.

#define MPACK_NODE_PAGE_SIZE   4096

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.)

Nodes are 16 bytes on most common architectures (32-bit and 64-bit.)

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

#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.

#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.)

#define MPACK_READER   1

Enables compilation of the base Tag Reader.

#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.

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.

#define MPACK_STACK_SIZE   4096

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

#define MPACK_STDIO   1

Enables the use of C stdio.

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

#define MPACK_STDLIB   1

Enables the use of C stdlib.

This allows the library to use malloc for debugging and in allocation helpers.

#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.

This is on by default if it is not defined.

#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.

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

#define MPACK_WRITER   1

Enables compilation of the Writer.