Managing Contexts

Managing Contexts. More...

Functions
lite3_ctx *	lite3_ctx_create_with_size (size_t bufsz)
	Create context with custom size.
lite3_ctx *	lite3_ctx_create_from_buf (const unsigned char *buf, size_t buflen)
	Create context by copying from a buffer.
lite3_ctx *	lite3_ctx_create_take_ownership (unsigned char *buf, size_t buflen, size_t bufsz)
	Create context by taking ownership of a buffer.
static lite3_ctx *	lite3_ctx_create (void)
	Create context with minimum size.
int	lite3_ctx_import_from_buf (lite3_ctx *ctx, const unsigned char *buf, size_t buflen)
	Copy data into existing context.
void	lite3_ctx_destroy (lite3_ctx *ctx)
	Destroy context.

Detailed Description

Managing Contexts.

See Context API. This section contains various functions for creating and destroying contexts, as well as importing data.

Function Documentation

lite3_ctx_create()

static lite3_ctx * lite3_ctx_create ( void  )

inlinestatic

Create context with minimum size.

Creates a context with default size of LITE3_CONTEXT_BUF_SIZE_MIN.

Warning

Any context that is not reused for the lifetime of the program must be manually destroyed by lite3_ctx_destroy() to prevent memory leaks.

Definition at line 214 of file lite3_context_api.h.

lite3_ctx_create_from_buf()

lite3_ctx * lite3_ctx_create_from_buf	(	const unsigned char *	buf,
		size_t	buflen
	)

Create context by copying from a buffer.

This function will copy data into a newly allocated context. The original data is not affected.

Warning

Any context that is not reused for the lifetime of the program must be manually destroyed by lite3_ctx_destroy() to prevent memory leaks.

Parameters

[in]	buf	source buffer pointer
[in]	buflen	source buffer used length (length of message)

Definition at line 97 of file ctx_api.c.

lite3_ctx_create_take_ownership()

lite3_ctx * lite3_ctx_create_take_ownership	(	unsigned char *	buf,
		size_t	buflen,
		size_t	bufsz
	)

Create context by taking ownership of a buffer.

When you have an existing allocation containing a Lite³ message, you might want a context to to take ownership over it rather than copying all the data. The passed buffer will also be freed when you call lite3_ctx_destroy() on the context later.

Warning

1. Any context that is not reused for the lifetime of the program must be manually destroyed by lite3_ctx_destroy() to prevent memory leaks.
2. *buf must be N-byte aligned according to LITE3_NODE_ALIGNMENT. On 64-bit machines, buffers allocated by libc malloc() always work with the default Lite³ configuration. Alignment should only become an issue if you use custom alignment (see lite3_node_alignment).

Parameters

[in]	buf	buffer pointer (created by malloc())
[in]	buflen	buffer used length (length of message)
[in]	bufsz	buffer max size (total size of allocation)

Definition at line 126 of file ctx_api.c.

lite3_ctx_create_with_size()

lite3_ctx * lite3_ctx_create_with_size

(

size_t

bufsz

)

Create context with custom size.

If you know that you will be storing a large message, it is more efficient to allocate a large context up front. Otherwise, a small default context will copy and relocate data several times similar to std::vector in C++.

Parameters

[in]

bufsz

(size_t) context buffer size

Warning

1. Any context that is not reused for the lifetime of the program must be manually destroyed by lite3_ctx_destroy() to prevent memory leaks.
2. Any value for bufsz below LITE3_CONTEXT_BUF_SIZE_MIN will be automatically clamped to LITE3_CONTEXT_BUF_SIZE_MIN. Any size above LITE3_BUF_SIZE_MAX will trigger an error.

Definition at line 75 of file ctx_api.c.

lite3_ctx_destroy()

void lite3_ctx_destroy

(

lite3_ctx *

ctx

)

Destroy context.

Parameters

[in]

ctx

(lite3_ctx *) context pointer

Warning

Any context that is not reused for the lifetime of the program must be manually destroyed by lite3_ctx_destroy() to prevent memory leaks.

Definition at line 229 of file ctx_api.c.

lite3_ctx_import_from_buf()

int lite3_ctx_import_from_buf	(	lite3_ctx *	ctx,
		const unsigned char *	buf,
		size_t	buflen
	)

Copy data into existing context.

This function allows for efficient reuse of contexts. For example, a listening server may want to copy packet data into an existing context. If the new data fits into the existing context, then no new calls to malloc() are needed. This avoids repeated allocations from creating and destroying of contexts.

Returns

0 on success

< 0 on error

Parameters

[in]	ctx	context pointer
[in]	buf	source buffer pointer
[in]	buflen	source buffer used length (length of message)

Definition at line 193 of file ctx_api.c.