arboricx.h (4996B)
1 #ifndef ARBORICX_H 2 #define ARBORICX_H 3 4 #include <stddef.h> 5 #include <stdint.h> 6 7 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 typedef struct arb_ctx arb_ctx_t; 12 typedef uint64_t arb_handle_t; 13 typedef enum { 14 ARB_OK = 0, ARB_INVALID_HANDLE = 1, ARB_OUT_OF_MEMORY = 2, 15 ARB_FUEL_EXHAUSTED = 3, ARB_TYPE_MISMATCH = 4, ARB_INVALID_DATA = 5, 16 ARB_IO_ERROR = 6, ARB_HANDLE_EXHAUSTED = 7 17 } arb_status_t; 18 19 /* ABI v2: each successful handle output is independently owned. Inputs are 20 * borrowed. arb_retain creates another owned handle; arb_release invalidates 21 * only that handle. Handles are opaque, context-bound and never serialize. 22 * Reduction is lazy and in place: aliases observe shared evaluation progress, 23 * including partial progress on failure. Failure leaves output parameters 24 * unchanged. Distinct outputs must not alias. All pointers must be valid; 25 * buffers/arrays may be empty but must have a non-null pointer. Contexts are 26 * single-threaded and non-reentrant. Context destruction releases all handles. 27 * Inspection does not force; returned children are owned handles too. 28 * Collection reclaims unreachable nodes, not necessarily resident OS pages. 29 */ 30 uint32_t arb_abi_version(void); 31 arb_status_t arb_retain(arb_ctx_t* ctx, arb_handle_t handle, arb_handle_t* out); 32 arb_status_t arb_release(arb_ctx_t* ctx, arb_handle_t handle); 33 arb_status_t arb_collect(arb_ctx_t* ctx); 34 /* Set allocation headroom: max(minimum, last_live_nodes * multiplier). 35 * Both arguments must be positive; invalid input leaves the policy unchanged. 36 * No collection/allocation occurs here. The next reducer safepoint checks the 37 * new threshold against allocations since the last collection. Default: 1048576, 38 * 1. This is NOT a memory limit; construction does not automatically collect. */ 39 arb_status_t arb_set_gc_policy(arb_ctx_t* ctx, uint32_t minimum, uint32_t multiplier); 40 41 /* Context lifecycle */ 42 arb_ctx_t* arboricx_init(void); 43 void arboricx_free(arb_ctx_t* ctx); 44 void arboricx_free_buf(arb_ctx_t* ctx, uint8_t* ptr, size_t len); 45 46 /* Tree construction */ 47 arb_status_t arb_leaf(arb_ctx_t* ctx, arb_handle_t* out); 48 arb_status_t arb_stem(arb_ctx_t* ctx, arb_handle_t child, arb_handle_t* out); 49 arb_status_t arb_fork(arb_ctx_t* ctx, arb_handle_t left, arb_handle_t right, arb_handle_t* out); 50 arb_status_t arb_app(arb_ctx_t* ctx, arb_handle_t func, arb_handle_t arg, arb_handle_t* out); 51 52 /* Reduction */ 53 arb_status_t arb_reduce(arb_ctx_t* ctx, arb_handle_t root, uint64_t fuel, arb_handle_t* out); 54 55 /* Codec constructors */ 56 arb_status_t arb_of_number(arb_ctx_t* ctx, uint64_t n, arb_handle_t* out); 57 arb_status_t arb_of_string(arb_ctx_t* ctx, const char* s, arb_handle_t* out); 58 arb_status_t arb_of_bytes(arb_ctx_t* ctx, const uint8_t* bytes, size_t len, arb_handle_t* out); 59 arb_status_t arb_of_list(arb_ctx_t* ctx, const arb_handle_t* items, size_t len, arb_handle_t* out); 60 61 /* Codec destructors (return ARB_OK on success) */ 62 arb_status_t arb_to_number(arb_ctx_t* ctx, arb_handle_t root, uint64_t* out); 63 arb_status_t arb_to_string(arb_ctx_t* ctx, arb_handle_t root, uint8_t** out_ptr, size_t* out_len); 64 arb_status_t arb_to_bytes(arb_ctx_t* ctx, arb_handle_t root, uint8_t** out_ptr, size_t* out_len); 65 arb_status_t arb_to_bool(arb_ctx_t* ctx, arb_handle_t root, int* out); 66 67 /* Result unwrapping (return ARB_OK on success) */ 68 arb_status_t arb_unwrap_result(arb_ctx_t* ctx, arb_handle_t root, int* out_ok, arb_handle_t* out_value, arb_handle_t* out_rest); 69 arb_status_t arb_unwrap_host_value(arb_ctx_t* ctx, arb_handle_t root, uint64_t* out_tag, arb_handle_t* out_payload); 70 71 /* Tree inspection (Layer 1 — for custom IO drivers and non-POSIX hosts) */ 72 arb_status_t arb_is_leaf(arb_ctx_t* ctx, arb_handle_t root, int* out); 73 arb_status_t arb_is_stem(arb_ctx_t* ctx, arb_handle_t root, int* out); 74 arb_status_t arb_is_fork(arb_ctx_t* ctx, arb_handle_t root, int* out); 75 arb_status_t arb_is_app(arb_ctx_t* ctx, arb_handle_t root, int* out); 76 arb_status_t arb_get_stem_child(arb_ctx_t* ctx, arb_handle_t root, arb_handle_t* out); 77 arb_status_t arb_get_fork_children(arb_ctx_t* ctx, arb_handle_t root, 78 arb_handle_t* out_left, arb_handle_t* out_right); 79 arb_status_t arb_get_app_func_arg(arb_ctx_t* ctx, arb_handle_t root, 80 arb_handle_t* out_func, arb_handle_t* out_arg); 81 82 /* IO driver (Layer 2 — POSIX interaction-tree runtime) */ 83 typedef struct { 84 int allow_read_all; 85 int allow_write_all; 86 } arb_io_perms_t; 87 88 arb_status_t arb_run_io(arb_ctx_t* ctx, arb_handle_t program, const arb_io_perms_t* perms, arb_handle_t* out); 89 90 /* Kernel entrypoints */ 91 arb_status_t arb_kernel_root(arb_ctx_t* ctx, arb_handle_t* out); 92 93 /* Native bundle loading (fast path — bypasses the Tricu kernel) */ 94 arb_status_t arb_load_bundle(arb_ctx_t* ctx, const uint8_t* bytes, size_t len, const char* name, arb_handle_t* out); 95 arb_status_t arb_load_bundle_default(arb_ctx_t* ctx, const uint8_t* bytes, size_t len, arb_handle_t* out); 96 97 #ifdef __cplusplus 98 } 99 #endif 100 101 #endif /* ARBORICX_H */