WPILibC++ 2024.3.2
Configuration Options

Defines the MPack configuration options. 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   0
 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   0
 Enables compound type size tracking for readers. More...
 
#define MPACK_WRITE_TRACKING   0
 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...
 

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

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 docs/protocol.md 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   0

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 docs/protocol.md 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);
and restrictions which apply to each piece of software is included later in this file and or inside of the individual applicable source files The disclaimer of warranty in the WPILib license above applies to all code in and nothing in any of the other licenses gives permission to use the names of FIRST nor the names of the WPILib contributors to endorse or promote products derived from this software The following pieces of software have additional or alternate and or Google Inc All rights reserved Redistribution and use in source and binary with or without are permitted provided that the following conditions are this list of conditions and the following disclaimer *Redistributions in binary form must reproduce the above copyright this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution *Neither the name of Google Inc nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY EXPRESS OR IMPLIED BUT NOT LIMITED THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY OR CONSEQUENTIAL WHETHER IN STRICT OR EVEN IF ADVISED OF THE POSSIBILITY OF SUCH January AND DISTRIBUTION Definitions License shall mean the terms and conditions for and distribution as defined by Sections through of this document Licensor shall mean the copyright owner or entity authorized by the copyright owner that is granting the License Legal Entity shall mean the union of the acting entity and all other entities that control are controlled by or are under common control with that entity For the purposes of this definition control direct or to cause the direction or management of such whether by contract or including but not limited to software source documentation and configuration files Object form shall mean any form resulting from mechanical transformation or translation of a Source including but not limited to compiled object generated and conversions to other media types Work shall mean the work of whether in Source or Object made available under the as indicated by a copyright notice that is included in or attached to the whether in Source or Object that is based or other modifications as a an original work of authorship For the purposes of this Derivative Works shall not include works that remain separable or merely the Work and Derivative Works thereof Contribution shall mean any work of including the original version of the Work and any modifications or additions to that Work or Derivative Works that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner For the purposes of this submitted means any form of or written communication sent to the Licensor or its including but not limited to communication on electronic mailing source code control and issue tracking systems that are managed or on behalf the Licensor for the purpose of discussing and improving the but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as Not a Contribution Contributor shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work Grant of Copyright License Subject to the terms and conditions of this each Contributor hereby grants to You a non no royalty free
Definition: ThirdPartyNotices.txt:151

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);
constexpr auto count() -> size_t
Definition: core.h:1203

◆ 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);
static constexpr const velocity::meters_per_second_t c(299792458.0)
Speed of light in vacuum.

◆ 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   0

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   0

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.