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