sleela_munction.h
impl/core/sleela_munction.h · 104 line(s) · c
/* ==========================================================================
* sleela_munction.h -- Munction: the reach-composition engine (C core).
*
* The C/C++ re-authoring of Munction for the direct Sleela engine build. A
* Munction is one sane sentence of reach: start an addressed reach, connect
* over a system-method channel (pipe | file | tcp | sdps | crypto), coherently
* send a datum, thatch interim stages, consume what returns, latch the reached
* state, and close with a receipt.
*
* The structure of Reach is protected: transport may bump, but a reach is
* receivable (always yields a receipt) and every send is coherent (offered vs.
* acknowledged bytes accounted). The sentence is bounded to 4..16 verbs.
*
* A reach is a Sleela-owned bounded resource (a handle into a fixed table), the
* same discipline used for sockets/files.
* ========================================================================== */
#ifndef SLEELA_MUNCTION_H
#define SLEELA_MUNCTION_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Sentence sanity bound (verbs per Munction). */
#define SL_MUNCTION_MIN_VERBS 4
#define SL_MUNCTION_MAX_VERBS 16
/* Max concurrent reaches owned by one VM. */
#define SL_MUNCTION_MAX 64
/* Bounded buffer a channel can hold in flight (frames). */
#define SL_MUNCTION_QUEUE 64
/* System-method channels a reach can connect over. */
typedef enum {
SL_MUN_NONE = 0,
SL_MUN_PIPE, /* pipe: OS pipe / FIFO (framed, in-process) */
SL_MUN_FILE, /* file: file I/O (send appends, consume reads) */
SL_MUN_NET, /* tcp: internet TCP */
SL_MUN_SDPS, /* sdps: private packets (magic+len+MAC framing) */
SL_MUN_CRYPTO /* crypto: authenticated seal/open envelope */
} SLMunChannel;
/* Reach outcome, recorded in the receipt. */
typedef enum {
SL_MUN_REACHED = 0, /* completed / latched or closed cleanly */
SL_MUN_CONTAINED, /* a bump stopped at the boundary; partial real */
SL_MUN_ABORTED /* retired early; residual recorded */
} SLMunOutcome;
typedef struct SLMunction SLMunction;
/* start(name): open a named reach. Returns a reach or NULL on error. */
SLMunction* slmunction_start(const char* name);
/* connect(uri): bind the reach to a channel resolved from the URI scheme.
* Returns 0 on success, -1 on a boundary stop (unknown scheme / bad shape). */
int slmunction_connect(SLMunction* m, const char* uri);
/* enable(policy): permit an optional capability, e.g. "crypto:<keyref>" to key
* the crypto envelope, or "retry". Returns 0, or -1 on a boundary stop. */
int slmunction_enable(SLMunction* m, const char* policy);
/* send(datum,len): coherently push a datum. Returns acknowledged byte count
* (== len when coherent), or -1 on a boundary stop. */
int64_t slmunction_send(SLMunction* m, const char* datum, size_t len);
/* thatch(spec): weave interim stage names (comma/space list) over the path.
* The stages are recorded in the receipt; interim transforms are identity in
* the core (framing/telemetry live at higher layers). Returns 0 or -1. */
int slmunction_thatch(SLMunction* m, const char* spec);
/* consume(): pull one unit of what the channel returns into the reach's last
* reception. Returns the received byte count (>=0) or -1 when absent/boundary. */
int64_t slmunction_consume(SLMunction* m);
/* Copy the most recent reception bytes into out (NUL-terminated); returns the
* length (may be 0). */
int slmunction_last_reception(const SLMunction* m, char* out, size_t cap);
/* observe(): return a short channel-state string into out; returns length. */
int slmunction_observe(SLMunction* m, char* out, size_t cap);
/* latch(): hold/commit the reached state (at most once). Returns 0 or -1. */
int slmunction_latch(SLMunction* m);
/* closeWithReceipt(): orderly teardown. Fills the receipt string into out
* (NUL-terminated) and returns the outcome. abort() is the negative closer. */
SLMunOutcome slmunction_close(SLMunction* m, char* receipt_out, size_t cap);
SLMunOutcome slmunction_abort(SLMunction* m, char* receipt_out, size_t cap);
/* Introspection for tests / the language surface. */
int slmunction_verb_count(const SLMunction* m);
int64_t slmunction_sent_bytes(const SLMunction* m);
int64_t slmunction_received_units(const SLMunction* m);
int slmunction_coherent(const SLMunction* m); /* 1 if all sends coherent + no bumps */
#ifdef __cplusplus
}
#endif
#endif /* SLEELA_MUNCTION_H */