allocate

A (possibly stateful) memory allocator: allocation and deallocation function pointers plus an opaque state pointer passed to both. Function pointers instead of an interface because interfaces cannot be stored in variables.

The ambient context: settings implicitly used by the standard library. Like in Odin and Jai, library code allocates through the allocator found here instead of calling malloc directly. Every cx function takes its caller's context as a hidden parameter; only context roots (the entry point, exported extern functions, C callbacks) start from the default.

Context& context()

Returns the caller's ambient context. This is a compiler intrinsic: direct calls read the hidden context parameter. The body only runs for indirect calls, which cannot provide a context and abort.

Allocator defaultAllocator()

Returns the default allocator, which allocates with malloc and frees with free.

void withAllocator(Allocator allocator, void() body)

Runs body with the given allocator installed in the ambient context. The override applies to body and everything it calls, and never leaks to the caller. This is a compiler intrinsic: direct calls push a context overriding the allocator. Indirect calls cannot do that and abort.

T[*] allocate<T>(int64 count)

Allocates uninitialized storage for count values and returns a pointer to it. The block can be freed by passing the returned pointer to deallocate.

The allocation goes through the ambient context's allocator.

If the allocation fails, the program aborts.

T[*]? tryAllocate<T>(int64 count)

Allocates uninitialized storage for count values and returns a pointer to it. The block can be freed by passing the returned pointer to deallocate.

If the allocation fails, null is returned.

T* allocateValue<T>(T value)

Moves the given value into newly allocated dynamic memory and returns a pointer to it. The block can be freed by passing the returned pointer to deallocate.

If the memory allocation fails, the program aborts.

T*? tryAllocateValue<T>(T value)

Moves the given value into newly allocated dynamic memory and returns a pointer to it. The block can be freed by passing the returned pointer to deallocate.

If the memory allocation fails, null is returned.

void deallocate<T>(T* allocation)

Deallocates a block of dynamic memory that was previously allocated by a call to allocate, tryAllocate, allocateValue, or tryAllocateValue. The ambient context's allocator must be the same one that allocated the block.

void deallocate<T>(T[*] allocation)