Context API

Context API. More...

Modules
	Iterators
	Create and use iterators for objects/arrays.
	Managing Contexts
	Managing Contexts.
	Object / Array Initialization
	Object / array initialization.
	Object Set
	Set key-value pair in object.
	Array Append
	Append value to array.
	Array Set
	Set (or overwrite) value in array.
	Utility Functions
	Utility functions.
	Object Get
	Get value from object by key.
	Array Get
	Get value from array by index.
	Iterators
	Create and use iterators for objects/arrays.
	JSON Conversion
	Conversion between Lite³ and JSON.

Detailed Description

Context API.

Lite³ provides an alternative API called the 'Context API'. Compared to the Buffer API, this API represents a more accessible alternative where memory allocations are hidden from the user, providing all the same functionality without requiring manual buffer management.

Contexts are containers for Lite³ buffers, containing a single buffer for a single message. Instead of buffers being passed directly, functions take a *ctx variable as argument. The context will automatically resize when needed, similar to std::vector in C++.

If you want to access the buffer inside of a context, you can like so:

ctx->buf        // (uint8_t *) buffer pointer
ctx->buflen     // (size_t) message length in bytes

There is also a ctx->bufsz member that stores the total capacity inside the allocation. Contexts start out with a size of LITE3_CONTEXT_BUF_SIZE_MIN (default: 1024) and will reallocate 4X the current capacity if they run out of space. This happens automatically, though you might occasionally see error messages in your terminal when this happens:

NO BUFFER SPACE FOR ENTRY INSERTION
NO BUFFER SPACE FOR NODE SPLIT

This is nothing to worry about, as the context will use these errors to grow its size.

Note

Contexts will preserve LITE3_NODE_ALIGNMENT alignment during (re)allocation (see lite3_node_alignment).

Warning

Automatic memory management requires some overhead and internal allocations might happen unexpectedly. Therefore, it is not recommended to use the Context API for realtime or latency-sensitive applications. If you must, then create an oversized context up front and keep reusing it indefinitely to avoid reallocations.

Error handling

Unless otherwise specified, Lite³ uses the POSIX error handling convention. This means functions will return a value of -1 and set errno to one of several values:

Err	Hex	Var	Description
2	0x02	ENOENT	No such file or directory
5	0x05	EIO	Input/output error
14	0x0e	EFAULT	Bad address
22	0x16	EINVAL	Invalid argument
74	0x4a	EBADMSG	Bad message
75	0x4b	EOVERFLOW	Value too large for defined data type
90	0x5a	EMSGSIZE	Message too long
105	0x69	ENOBUFS	No buffer space available

Used feature breaking ANSI-C / C89 compatibility:

C99:

• inline functions
• compound literals
• flexible array member (no specified size)
• single-line comments //
• variadic macros (VA_ARGS)
• restrict pointers
  
• initializing a structure by field names: struct Point p = { .x = 1, .y = 2 };

C11:

• static_assert