Reference/Language bindings

Language bindings

CCatalyst

The C ABI for values, errors, runtimes, messengers, and servers.

C ABI mc/CCatalyst.h
#include <mc/CCatalyst.h>

This header is usable from C. Fallible calls return NULL on success or an owned CErrorHandle* on failure. No exceptions may cross the boundary, including callbacks.

Returned handles are owned unless stated otherwise; release them with the matching release function. Keep a live handle for each call. Strings and buffers use explicit byte lengths.

Reads produce snapshots. Callback values are editable snapshots whose changes are committed before the callback returns. Callback parameters are borrowed; retain a messenger to keep it.

Only cvar, CMessenger, CServer, and their support types are exposed to Python and Swift.

Jump to a declaration · 76
CAdmitCallback cCatalystABIVersion cCatalystDrain CCloseCallback CContextRelease cErrorCause cErrorCreate CErrorHandle cErrorMessage cErrorRelease cErrorType CMessageCallback cMessengerCall cMessengerCallbackError cMessengerCallbacks cMessengerClose cMessengerConnect cMessengerConnected cMessengerCreate CMessengerHandle cMessengerReceive cMessengerRelease cMessengerRetain cMessengerSend cMessengerSession cMessengerSetSession cRuntimeCreate CRuntimeHandle cRuntimeRelease cRuntimeRetain cServerCallback cServerCallbackError cServerClose cServerCreate CServerHandle cServerListen cServerRelease cServerRetain cVarAppend cVarAssign cVarBool cVarBytes cVarCopy cVarCopyBytes cVarCreate cVarCSON cVarElements cVarEraseRange cVarFloat cVarFunction cVarGetBool cVarGetBytes cVarGetFloat cVarGetIndex cVarGetInteger cVarGetKey cVarGetTag CVarHandle cVarHasKey cVarInteger cVarParse cVarRelease cVarRemoveKey cVarRestore cVarRetain cVarSetIndex cVarSetKey cVarSetTag cVarSize cVarStore CVarTag CVarTag::attrs CVarTag::flags CVarTag::kind CVarTag::type CVarType

Free functions & types

Types, constants & data

typedef struct CVarHandle CVarHandle;
typedef struct CErrorHandle CErrorHandle;
typedef struct CRuntimeHandle CRuntimeHandle;
typedef struct CServerHandle CServerHandle;
enum CVarType { CVarNone = 1, CVarNull = 2, CVarInteger = 5, CVarFloat = 6, CVarString = 7, CVarSymbol = 8, CVarVector = 9, CVarFunction = 10, CVarMap = 11, CVarBuffer = 12, CVarPacked = 13, CVarSet = 16, CVarBool = 4 };
typedef void (*CContextRelease)(void* context);
typedef CErrorHandle* (*CMessageCallback)(void* context, CMessengerHandle* messenger, CVarHandle* message, int* handled);
typedef CErrorHandle* (*CCloseCallback)(void* context, CMessengerHandle* messenger);
typedef CErrorHandle* (*CAdmitCallback)(void* context, CMessengerHandle* messenger, CVarHandle* auth, int* accepted);

Functions

cCatalystABIVersion

uint32_t cCatalystABIVersion(void);

Returns the C bridge’s ABI version, currently 1. Bindings can check it before using the handle and callback interfaces.

cErrorMessage

const char* cErrorMessage(const CErrorHandle* error);

Returns text borrowed from the error; keep the error handle alive.

cErrorRelease

void cErrorRelease(CErrorHandle* error);

Releases an owned error handle. Borrowed message and type text must no longer be used afterward.

cErrorCreate

CErrorHandle* cErrorCreate(const char* message, size_t size);

Creates an owned error containing a copy of the given message bytes, for example to report a callback failure. This call returns the error itself, rather than a success-or-error status.

cVarRetain

void cVarRetain(CVarHandle* value);

Adds an ownership reference to the same value handle. Use cVarCopy() when an independent value snapshot is needed.

cVarRelease

void cVarRelease(CVarHandle* value);

Releases one ownership reference; the value is destroyed after its final release.

cVarCreate

CErrorHandle* cVarCreate(uint8_t type, CVarHandle** out);

Creates an owned None, Null, Vector, Map, or Set handle. Other type codes require their corresponding typed constructors.

cVarBytes

CErrorHandle* cVarBytes(uint8_t type, const void* bytes, size_t size, CVarHandle** out);

Copies the supplied byte range into an owned String, Symbol, or Buffer value. size is a byte count and excludes any optional trailing terminator.

cVarFunction

CErrorHandle* cVarFunction(const char* name, size_t size, const CVarHandle* arguments, CVarHandle** out);

Creates a named function expression from the name bytes and a vector of arguments. Copies the arguments and computes its dispatch hash; this constructs data without invoking a function.

cVarCopy

CErrorHandle* cVarCopy(const CVarHandle* value, CVarHandle** out);

Returns an owned snapshot of the value in a new handle. Subsequent assignment to the original handle does not replace this snapshot.

cVarAssign

CErrorHandle* cVarAssign(CVarHandle* value, const CVarHandle* other);

Replaces the destination handle’s value with a snapshot of other. Other owners retaining the destination handle observe the replacement.

cVarGetInteger

CErrorHandle* cVarGetInteger(const CVarHandle* value, int64_t* out);

Reads an Integer value into the output. Other types return an error instead of applying numeric coercion.

cVarGetFloat

CErrorHandle* cVarGetFloat(const CVarHandle* value, double* out);

Reads a Float value into the output. An Integer does not implicitly convert through this call.

cVarGetBool

CErrorHandle* cVarGetBool(const CVarHandle* value, int* out);

Reads a Bool value as zero or one. Other types return an error instead of applying truth-value conversion.

cVarGetBytes

CErrorHandle* cVarGetBytes(const CVarHandle* value, CVarHandle** out);

Returns an owned Buffer snapshot of a string, symbol name, function name, or buffer. Use cVarSize() and cVarCopyBytes() on that snapshot to access its bytes.

cVarSize

CErrorHandle* cVarSize(const CVarHandle* value, size_t* out);

Returns the byte count for String or Buffer, element count for Vector, Set, or Map, or argument count for Function. Unsupported scalar types return an error.

cVarCopyBytes

CErrorHandle* cVarCopyBytes(const CVarHandle* value, void* out, size_t size);

Copies a Buffer’s bytes into caller-owned memory, requiring room for the entire buffer. Adds no terminator and leaves any unused trailing destination bytes untouched; first use cVarGetBytes() for text.

cVarSetIndex

CErrorHandle* cVarSetIndex(CVarHandle* value, size_t index, const CVarHandle* item);

Copies an item into an existing vector position or function argument. It does not extend the sequence or change a function’s name or arity.

cVarAppend

CErrorHandle* cVarAppend(CVarHandle* value, const CVarHandle* item);

Copies an item into a Vector, Set, or Function, appending where order exists. Set insertion preserves uniqueness; function edits update the dispatch hash.

cVarHasKey

CErrorHandle* cVarHasKey(const CVarHandle* value, const char* key, size_t size, int* out);

Writes one if the map contains the key, otherwise zero. A non-map receiver returns an error.

cVarRemoveKey

CErrorHandle* cVarRemoveKey(CVarHandle* value, const char* key, size_t size);

Removes a key from a map, doing nothing if it is absent. Existing snapshots remain valid.

cVarEraseRange

CErrorHandle* cVarEraseRange(CVarHandle* value, size_t position, size_t count);

Erases bytes from a string or elements from a vector/function. Counts are clamped at the end; earlier snapshots are unchanged.

cVarParse

CErrorHandle* cVarParse(const char* code, size_t size, CVarHandle** out);

Parses the supplied CSON text into an owned value. The result must belong to the C bridge’s supported value-interchange surface; parsing does not evaluate expressions.

cVarRestore

CErrorHandle* cVarRestore(const void* bytes, size_t size, CVarHandle** out);

Restores one supported value from serialized bytes and returns an owned handle. Copies the input and rejects trailing bytes after the value.

cRuntimeRetain

void cRuntimeRetain(CRuntimeHandle* runtime);

Keeps the runtime alive for another owner. Messenger and server handles also retain their runtime automatically.

cRuntimeRelease

void cRuntimeRelease(CRuntimeHandle* runtime);

Releases one runtime ownership reference. Final cleanup is deferred so worker threads can shut down safely; cCatalystDrain() can wait for that cleanup.

cCatalystDrain

CErrorHandle* cCatalystDrain(void);

Waits for deferred final releases. Does not close live resources. Never call from a callback; release language locks before waiting.

cMessengerRetain

void cMessengerRetain(CMessengerHandle* messenger);

Adds an ownership reference to the messenger. Retain a borrowed callback handle before keeping it beyond that callback.

cMessengerRelease

void cMessengerRelease(CMessengerHandle* messenger);

Releases one ownership reference. Final messenger teardown is deferred; release every retained reference when finished.

cMessengerConnect

CErrorHandle* cMessengerConnect(CMessengerHandle* messenger, const char* host, size_t size, int port, int* connected);

Attempts to connect to the supplied host and port and writes the connection result to connected. The host uses an explicit byte length; an error handle reports a failure of the operation itself.

cServerRelease

void cServerRelease(CServerHandle* server);

Releases one ownership reference. Final teardown is deferred; cCatalystDrain() can wait for pending releases.

cServerListen

CErrorHandle* cServerListen(CServerHandle* server, int port);

Starts listening on the requested port using the runtime’s worker pool. Incoming connections are handled by the registered admission callback.

cServerClose

CErrorHandle* cServerClose(CServerHandle* server);

Stops listening and closes connections still awaiting admission. Separately retained, admitted messengers remain responsible for their own connection lifetime.

CVarTag

struct CVarTag

Types, constants & data

uint8_t type;
uint8_t flags;
uint16_t kind;
uint32_t attrs;