Loading...
Searching...
No Matches
Configuration Options

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

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

## MPACK_WRITER

#define MPACK_WRITER 1

Enables compilation of the Writer.

## Function Documentation

## mpack_assert_fail()

void mpack_assert_fail | ( | const char * | message | ) |

Implement this and define MPACK_CUSTOM_ASSERT to use a custom assertion function.

This function should not return. If it does, MPack will `abort()`.

If you use C++, make sure you include `mpack.h` where you define this to get the correct linkage (or define it `extern "C"`.)

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.