context

    
bare_procedure :: () {
    print("The context is: %\n", context);
}
    

Context Base

The context begins with the fields defined in Context_Base, which is declared in the Runtime_Support module. These fields provide the default facilities available to every Jai program:

Reading and Writing the Context

The context behaves like any other struct instance. You can read its fields with dot notation and assign to them directly. When you modify the context inside a procedure, the change is visible to that procedure's callees and persists after they return. Because the context is shared mutable state, changes also remain visible to the caller after the procedure returns:

    
proc_a :: () {
    print("before: %\n", context.silly_number);  // 33
    proc_b();
    print("after:  %\n", context.silly_number);  // 34, the change leaked back.
}

proc_b :: () {
    context.silly_number += 1;
}
    

This upward flow is sometimes intentional (for example, passing error state up through many layers without requiring exception handling), but often it is not desirable. To prevent changes from leaking, use push_context.

To use push_context, copy the current context into a local variable, modify whatever fields you need, and then enter the block:

    
wrapper :: () {
    print("before: %\n", context.silly_number);  // 33

    new_context := context;
    new_context.silly_number += 1;

    push_context new_context {
        print("inside: %\n", context.silly_number);  // 34
        some_procedure();  // Also sees 34, and any further changes stay inside.
    }

    print("after: %\n", context.silly_number);   // 33, restored.
}
    

You can also write push_context with no argument to push a default initialized context. This is especially useful inside #c_call procedures that need to call back into normal Jai code:

    
push_context {
    // A default context is active here.
    print("Hello from inside a default context.\n");
}
    

Memory Allocation

The standard allocation procedure alloc obtains memory by calling context.allocator. Because the allocator lives in the context, you can replace it for any subtree of your call graph without modifying the source code of the procedures in that subtree.

An allocator is a single procedure that handles allocation, reallocation, and freeing, selected by the mode parameter of type Allocator_Mode. Packaging all operations into one procedure means you swap them all at once, which prevents mismatches between the allocator used to obtain memory and the one used to free it.

    
my_allocator_proc :: (mode: Allocator_Mode, size: s64, old_size: s64, old_memory_pointer: *void, proc_data: *void) -> *void {
    if mode == .ALLOCATE && size == 42 {
        print("Hello, Sailor! 42 byte allocation requested!\n");
    }
    return context.default_allocator.proc(mode, size, old_size, old_memory_pointer, proc_data);
}

install_example :: () {
    new_context := context;
    new_context.allocator.proc = my_allocator_proc;
    new_context.allocator.data = null;

    push_context new_context {
        // Everything called here uses my_allocator_proc.
        mem := alloc(42);  // Prints the greeting.
        free(mem);
    }

    // Outside the block, the original allocator is active again.
    mem := alloc(42);  // No greeting.
    free(mem);
}
    

Long lived data structures such as resizable arrays and hash tables store the allocator that was active when they were first used. They call that saved allocator consistently afterward, rather than using whatever context.allocator happens to be at the moment. This ensures that memory is always freed with the same allocator that allocated it.

    
{
    push_allocator(temp);
    // Allocations in this scope use temporary storage.
    s := copy_string("ephemeral");
}
// Previous allocator is restored here.
    

Logging

The log procedure from the Basic module formats a message and sends it to context.logger. Its signature is:

    
log :: (format_string: string, args: .. Any, loc := #caller_location, flags := Log_Flags.NONE, user_flags: u32 = 0);
    

To redirect log output, replace context.logger and optionally context.logger_data in a push_context block, exactly as you would replace the allocator. This makes it straightforward to, for example, send logging from one subsystem to a file and logging from another subsystem to the console, or to silence logging entirely in a release build unless a special flag is set.

    
my_logger :: (message: string, data: *void, info: Log_Info) {
    // Write to a file, filter by level, etc.
}

new_context := context;
new_context.logger = my_logger;
new_context.logger_data = null;

push_context new_context {
    log("This message is routed to my_logger.\n");
}
    

    
print("temporary storage: %\n", context.temporary_storage.*);
// Shows fields: data, size, occupied, high_water_mark, overflow_allocator, etc.
    

You can walk the stack trace at any time by following the next pointers:

    
node := context.stack_trace;
while node {
    if node.info {
        print("[%] at %:%\n", node.info.name, node.info.location.fully_pathed_filename, node.line_number);
    }
    node = node.next;
}
    

The Basic module provides print_stack_trace for convenience. To save a stack trace for later inspection, use pack_stack_trace, which copies the trace into a standalone data structure. The address of the current procedure is available through context.stack_trace.info.procedure_address.

Stack traces are useful for writing instrumentation code such as profilers and memory debuggers. When the build option is enabled, every procedure call emits code to push a Stack_Trace_Node onto the linked list and pop it on return.

    
#add_context silly_number: int = 33;

example :: () {
    print("%\n", context.silly_number);  // 33
    context.silly_number = 99;
    print("%\n", context.silly_number);  // 99
}
    

You are not limited to simple types; any data type can be added. However, there is potential for naming conflicts: if two modules or a module and the main program add a field with the same name, the program will not compile.

    
NUMBERS :: u32.[1, 69105, 1491625];

new_context := context;
push_context new_context {
    format_int := *context.print_style.default_format_int;

    for NUMBERS  print("% ", it);   // 1 69105 1491625
    print("\n");

    format_int.base = 16;
    for NUMBERS  print("% ", it);   // 1 10df1 16c2a9
    print("\n");

    format_int.base = 2;
    for NUMBERS  print("% ", it);   // 1 10000110111110001 101101100001010101001
    print("\n");
}

// Outside the block, the default base 10 formatting is restored.
for NUMBERS  print("% ", it);       // 1 69105 1491625
    

    
callback :: (x: int) -> int #c_call {
    // print("...", x);  // Error: no context available.

    push_context {
        print("callback received %\n", x);  // Works: default context is active.
    }

    return x * x;
}
    

Summary of Replaceable Facilities

The context provides a uniform mechanism for controlling operations that, in other languages, each require their own library specific API. The following table summarizes the main replaceable fields: