|
Lite³
A JSON-Compatible Zero-Copy Serialization Format
|
Configuration options for the Lite³ library. More...
Macros | |
| #define | LITE3_ZERO_MEM_DELETED |
| Overwrite deleted values with NULL bytes (0x00). | |
| #define | LITE3_ZERO_MEM_EXTRA |
| Overwrite any unused bytes inside the Lite³ buffer with NULL bytes (0x00). | |
| #define | LITE3_PREFETCHING |
| Speeds up iterators, but may cause crashes on non-x86 platforms like ARM. | |
| #define | LITE3_ERROR_MESSAGES |
Print library-specific error messages to stdout. | |
| #define | LITE3_DEBUG |
Print library-specific debug information to stdout. | |
| #define | LITE3_BUF_SIZE_MAX |
| Maximum Lite³ buffer size. | |
| #define | LITE3_NODE_ALIGNMENT |
| B-tree node alignment. | |
| #define | LITE3_NODE_SIZE |
| B-tree node size setting. | |
| #define | LITE3_TREE_HEIGHT_MAX |
| Maximum B-tree height. | |
| #define | LITE3_NODE_SIZE_KC_OFFSET |
Offset of the size_kc field inside struct node. | |
| #define | LITE3_HASH_PROBE_MAX |
| Enable hash probing to tolerate 32-bit hash collisions. | |
| #define | LITE3_VERIFY_KEY_OK |
| #define | LITE3_VERIFY_KEY_HASH_COLLISION |
| #define | LITE3_KEY_HASH_COMPILE_TIME |
| Macro to calculate DJB2 key hashes at compile-time. | |
| #define | LITE3_JSON |
| Enable JSON-related functions for conversion between Lite³ and JSON. | |
| #define | LITE3_JSON_NESTING_DEPTH_MAX |
| Maximum nesting limit for JSON documents being encoded or decoded. | |
| #define | LITE3_CONTEXT_BUF_SIZE_MIN |
| The minimum buffer size for a Lite³ context. | |
Configuration options for the Lite³ library.
Configuration options can be toggled either by manually (un)commenting #define inside the header include/lite3.h, or by passing -D flags to your compiler.
For example, library error messages are disabled by default. However it is recommended to enable them to receive feedback during development. To do this, either:
// #define LITE3_ERROR_MESSAGES inside the header file: include/lite3.h-DLITE3_ERROR_MESSAGES | #define LITE3_BUF_SIZE_MAX |
| #define LITE3_CONTEXT_BUF_SIZE_MIN |
The minimum buffer size for a Lite³ context.
Must be greater than LITE3_NODE_ALIGNMENT_MASK
Definition at line 130 of file lite3_context_api.h.
| #define LITE3_DEBUG |
Print library-specific debug information to stdout.
Disabled by default.
The output mainly consists of print statements for every value that gets inserted. Enabling this also turns on LITE3_ZERO_MEM_DELETED and LITE3_ZERO_MEM_EXTRA features to make the binary structure more readable in memory.
Also enables the function lite3_print(const unsigned char *buf, size_t buflen) to view the internal structure of Lite³ buffers.
| #define LITE3_ERROR_MESSAGES |
| #define LITE3_HASH_PROBE_MAX |
| #define LITE3_JSON |
| #define LITE3_JSON_NESTING_DEPTH_MAX |
| #define LITE3_KEY_HASH_COMPILE_TIME |
Macro to calculate DJB2 key hashes at compile-time.
Lite³ compares hash digest of keys instead of direct string comparisons. The hashes are stored inside the nodes of the B-tree, and the algorithm will traverse them to find a given key.
Calculating such key hashes adds runtime cost and is inside the critical path for tree traversal. Fortunately, for string literals we can calculate them at compile time and eliminate the runtime cost completely. This technique makes the API somewhat macro-heavy, but the savings are significant enough to justify it.
One downside is that this can noticably increase compile times due to pressure on the preprocessor. Therefore this feature can be disabled to speed up build times during development.
| #define LITE3_NODE_ALIGNMENT |
B-tree node alignment.
This determines the address alignment at which nodes are placed inside a Lite³ buffer.
Always set to 4-byte alignment according to the node struct's largest member variable (uint32_t). This setting cannot be changed.
@important The start of a message (the *buf pointer) MUST ALWAYS start on an address that is (at least) 4-byte aligned. On 64-bit machines, libc malloc() guarantees 16-byte alignment for allocations >= 16 bytes.
| #define LITE3_NODE_SIZE |
B-tree node size setting.
Set to 96 bytes (1.5 cache lines) by default. For the vast majority of applications, this setting should never need changing.
struct node inside lite3.c for more info.@important Do not change this setting unless performance profiling shows real improvements and you know what you are doing.
| #define LITE3_NODE_SIZE_KC_OFFSET |
| #define LITE3_PREFETCHING |
| #define LITE3_TREE_HEIGHT_MAX |
| #define LITE3_ZERO_MEM_DELETED |
Overwrite deleted values with NULL bytes (0x00).
Enabled by default.
This is a safety feature since not doing so would leave 'deleted' entries intact inside the datastructure until they are overwritten by other values. Disable if you do not care about leaking deleted data.
LITE3_ZERO_MEM_DELETED and LITE3_ZERO_MEM_EXTRA are required. | #define LITE3_ZERO_MEM_EXTRA |
Overwrite any unused bytes inside the Lite³ buffer with NULL bytes (0x00).
Enabled by default.
This is a safety feature to prevent leaking uninitialized memory bytes into messages. It is also useful for debugging, as it makes the structure a lot more readable. If you plan to use compression, this option makes Lite³ structures achieve better compression ratios.
LITE3_ZERO_MEM_DELETED and LITE3_ZERO_MEM_EXTRA are required.