tricu.h (3812B)
1 #ifndef TRICU_H 2 #define TRICU_H 3 #include <stddef.h> 4 #include <stdint.h> 5 #ifdef __cplusplus 6 extern "C" { 7 #endif 8 9 /* Haskell embedding ABI 1. See ext/haskell/README.md for lifecycle, 10 * demand, concurrency and resource limits. Every output is unchanged on failure. 11 * All pointers must be valid; distinct output parameters must not overlap. 12 * Input buffers are borrowed for the call; NULL is allowed only at length zero. 13 * Every successful handle output owns one root; inputs are borrowed. */ 14 typedef uint64_t tricu_context; 15 typedef uint64_t tricu_handle; 16 typedef uint32_t tricu_status; 17 enum { 18 TRICU_OK = 0, TRICU_INVALID_CONTEXT = 1, TRICU_INVALID_HANDLE = 2, 19 TRICU_INVALID_DATA = 3, TRICU_TYPE_ERROR = 4, 20 TRICU_EXCEPTION = 5, TRICU_ID_EXHAUSTED = 6 21 }; 22 enum { TRICU_LEAF = 0, TRICU_STEM = 1, TRICU_FORK = 2 }; 23 24 /* Call once before other entrypoints; repeated calls are harmless. Owns RTS 25 * initialization: use in a process that has not already initialized GHC. 26 * Keep the library loaded until process exit. No shutdown entrypoint. */ 27 void tricu_init(void); 28 uint32_t tricu_abi_version(void); 29 tricu_status tricu_context_new(tricu_context *out); 30 tricu_status tricu_context_free(tricu_context ctx); 31 tricu_status tricu_retain(tricu_context ctx, tricu_handle value, tricu_handle *out); 32 tricu_status tricu_release(tricu_context ctx, tricu_handle value); 33 tricu_status tricu_leaf(tricu_context ctx, tricu_handle *out); 34 tricu_status tricu_stem(tricu_context ctx, tricu_handle child, tricu_handle *out); 35 tricu_status tricu_fork(tricu_context ctx, tricu_handle left, tricu_handle right, tricu_handle *out); 36 /* Application constructs a suspension; reduce demands only its outer constructor. 37 * Inspection and decoding also demand the portions they observe. */ 38 tricu_status tricu_apply(tricu_context ctx, tricu_handle fn, tricu_handle arg, tricu_handle *out); 39 tricu_status tricu_reduce(tricu_context ctx, tricu_handle value, tricu_handle *out); 40 tricu_status tricu_kind(tricu_context ctx, tricu_handle value, uint32_t *out); 41 tricu_status tricu_child(tricu_context ctx, tricu_handle value, uint32_t index, tricu_handle *out); 42 tricu_status tricu_from_u64(tricu_context ctx, uint64_t value, tricu_handle *out); 43 tricu_status tricu_to_bool(tricu_context ctx, tricu_handle value, uint32_t *out); 44 tricu_status tricu_to_u64(tricu_context ctx, tricu_handle value, uint64_t *out); 45 tricu_status tricu_from_bytes(tricu_context ctx, const uint8_t *bytes, size_t len, tricu_handle *out); 46 tricu_status tricu_from_utf8(tricu_context ctx, const uint8_t *bytes, size_t len, tricu_handle *out); 47 tricu_status tricu_to_bytes(tricu_context ctx, tricu_handle value, uint8_t **out, size_t *len); 48 tricu_status tricu_to_utf8(tricu_context ctx, tricu_handle value, uint8_t **out, size_t *len); 49 /* Last boundary error, retained across successes. UTF-8, length-delimited. 50 * Empty initially. Returned buffers are independent of contexts and must be freed 51 * exactly once with tricu_buffer_free, including empty buffers. */ 52 tricu_status tricu_last_error(tricu_context ctx, uint8_t **out, size_t *len); 53 void tricu_buffer_free(uint8_t *buffer); 54 55 enum { TRICU_COMPLETED = 0, TRICU_FAILED = 1, TRICU_CANCELLED = 2 }; 56 57 /* Load a verified Arboricx bundle with an explicit UTF-8 export name. */ 58 tricu_status tricu_load_bundle(tricu_context ctx, const uint8_t *bytes, size_t len, 59 const uint8_t *name, size_t name_len, tricu_handle *out); 60 /* Runs a canonical tricuIO v2 envelope with OS process authority. Task outcome 61 * is data: value is completion value or opaque failure/cancellation reason; 62 * cleanup is a list of IO-v2 problems. All three outputs publish atomically. */ 63 tricu_status tricu_run_io(tricu_context ctx, tricu_handle program, 64 uint32_t *outcome, tricu_handle *value, tricu_handle *cleanup); 65 #ifdef __cplusplus 66 } 67 #endif 68 #endif