Context API

The context module provides a flexible context management system for state management and error handling in C applications.

Context Management

The context system allows state to be tracked and propagated throughout a program execution, with support for error handling and extension data.

Types

type myrtx_context_t

Context structure holding arenas, scratch pool, extensions and error state.

typedef struct myrtx_context {
    myrtx_arena_t* global_arena;      /* Global arena for long-lived allocations */
    myrtx_arena_t* temp_arena;        /* Temporary arena for short-lived allocations */
    myrtx_scratch_pool_t scratch_pool;/* Pool of scratch arenas for reuse */
    bool owns_global_arena;           /* Whether context frees global_arena */
    void* extension_data[MYRTX_MAX_EXTENSION_TYPES];
    unsigned int flags;
    char error_buffer[256];
    int error_code;
} myrtx_context_t;

type myrtx_extension_info_t

Structure for describing context extensions.

typedef struct myrtx_extension_info {
    const char* name;        // Extension name
    size_t data_size;        // Size of extension data
    void (*init_func)(void*);    // Initialization function
    void (*free_func)(void*);    // Cleanup function
} myrtx_extension_info_t;

Creation and Destruction

myrtx_context_t *myrtx_context_create(myrtx_arena_t *global_arena)

Creates a new context.

If global_arena is NULL, a new arena is created and owned by the context. If a non-NULL arena is provided, the context references it and does not take ownership (it will not be freed by the context).

Parameters:

global_arena – Optional external arena to use (NULL to create one)

Returns:

Pointer to a new context or NULL on error

myrtx_context_t *myrtx_context_create_child(myrtx_context_t *parent)

Creates a new child context from a parent context.

Parameters:

parent – Pointer to the parent context

Returns:

Pointer to the new child context or NULL on error

void myrtx_context_destroy(myrtx_context_t *context)

Frees a context and all associated resources.

Frees the temporary arena and extension data. The global arena is freed only if the context owns it (i.e., it was created internally).

Parameters:

context – Pointer to the context to free

Ownership Semantics

External arena passed to myrtx_context_create() → context sets owns_global_arena = false and will not free the arena in myrtx_context_destroy().
No arena passed (NULL) → context creates the arena, sets owns_global_arena = true, and will free it on destroy.

Error Handling

bool myrtx_context_has_error(const myrtx_context_t *ctx)

Checks if a context has an error.

Parameters:

ctx – Pointer to the context

Returns:

true if the context has an error, false otherwise

const char *myrtx_context_get_error(const myrtx_context_t *ctx)

Gets the error message from a context.

Parameters:

ctx – Pointer to the context

Returns:

Pointer to the error message or NULL if there is no error

void myrtx_context_set_error(myrtx_context_t *ctx, const char *format, ...)

Sets an error message on a context.

Parameters:

ctx – Pointer to the context
format – Format string for the error message (printf-style)
... – Additional arguments for the format string

void myrtx_context_clear_error(myrtx_context_t *ctx)

Clears the error state of a context.

Parameters:

ctx – Pointer to the context

Extension Management

bool myrtx_context_register_extension(const myrtx_extension_info_t *info, int *id_out)

Registers a new extension type with the context system.

Parameters:

info – Pointer to the extension information
id_out – Pointer to store the extension ID

Returns:

true on success, false on error

void *myrtx_context_get_extension(myrtx_context_t *ctx, int extension_id)

Gets the extension data for a specified extension ID.

Parameters:

ctx – Pointer to the context
extension_id – ID of the extension

Returns:

Pointer to the extension data or NULL if not found

State Management

bool myrtx_context_set_value(myrtx_context_t *ctx, const char *key, void *value)

Associates a value with a key in the context.

Parameters:

ctx – Pointer to the context
key – Key to associate with the value
value – Pointer to the value

Returns:

true on success, false on error

void *myrtx_context_get_value(const myrtx_context_t *ctx, const char *key)

Retrieves a value associated with a key from the context.

Parameters:

ctx – Pointer to the context
key – Key to look up

Returns:

Pointer to the value or NULL if not found

bool myrtx_context_remove_value(myrtx_context_t *ctx, const char *key)

Removes a key-value pair from the context.

Parameters:

ctx – Pointer to the context
key – Key to remove

Returns:

true if the key was found and removed, false otherwise

Inheritance and Propagation

myrtx_context_t *myrtx_context_get_parent(const myrtx_context_t *ctx)

Gets the parent context of a context.

Parameters:

ctx – Pointer to the context

Returns:

Pointer to the parent context or NULL if there is no parent

bool myrtx_context_propagate_error(myrtx_context_t *ctx)

Propagates an error up the context hierarchy.

Parameters:

ctx – Pointer to the context

Returns:

true if an error was propagated, false otherwise