Crate reflow_rt_capi

Expand description

C ABI bindings for the Reflow runtime.

§Design conventions

§Handles

All objects exposed to C are opaque pointers created by *_new / *_load functions and destroyed by the matching *_free function. Passing NULL to a *_free function is a no-op (idempotent).

§Return values

Functions that can fail return an rfl_status enum. Output values are written through out-parameters. On error, out-parameters are left untouched and the last error message is available via rfl_last_error_message (thread-local).

§Strings

C → Rust: null-terminated UTF-8 const char *.
Rust → C: char * allocated by this library; caller frees with rfl_string_free. Never pass a Rust-allocated string to free(3).

§Threading

Handles are Send + Sync and may be used from any thread once created. The runtime owns a single multi-thread tokio executor that is spun up on the first call that needs async work. rfl_runtime_shutdown tears it down (called implicitly by the library destructor).

Structs§

CapiActor
rfl_actor: Opaque handle to an actor template. Produced by rfl_actor_new (callback-driven actor), rfl_template_actor_new (bundled component), or rfl_subgraph_actor_new_from_json (embedded subgraph). Hand to rfl_network_register_actor to publish under a template id, or to rfl_actor_free to release without registering.
rfl_actor_ctx: Opaque per-call context handed to a callback actor.
rfl_events: Opaque handle to a subscriber on the network’s event stream. One subscriber per handle — create as many as you need.
rfl_graph: Opaque handle to a reflow_graph::Graph.
rfl_message: Opaque Reflow message handle.
rfl_network: Opaque handle to a reflow_network::Network, wrapped so the C side can share it across threads without touching its internal Arc<Mutex<_>>.
rfl_stream: Opaque producer handle to a stream. Create with rfl_stream_new, hand chunks in via rfl_stream_send_bytes, terminate with rfl_stream_end / rfl_stream_error. Free with rfl_stream_free.
rfl_stream_recv: Opaque receiver for a stream’s data channel.
rfl_subgraph_builder: Builder for a SubgraphActor with an explicit actor map.

Enums§

rfl_message_kind: Variant tag — matches the Message enum in reflow_actor.
rfl_status
rfl_stream_frame_kind: Variant tag returned by rfl_stream_recv_next.

Functions§

rfl_actor_free^⚠: Free an actor handle that was never registered. NULL-safe.
rfl_actor_new^⚠: Create a callback-driven actor.
rfl_compose_graphs^⚠: Compose N graph exports into a single GraphExport JSON document.
rfl_ctx_config_json^⚠: Return the current config as a JSON object string. Caller frees via rfl_string_free. Returns NULL on error.
rfl_ctx_emit^⚠: Emit a packet on port. message_json must parse as a Reflow Message (e.g. {"type":"Flow"}, {"type":"Integer","data":1}). Prefer rfl_ctx_emit_message for hot-path emits — this variant serializes JSON per call.
rfl_ctx_emit_message^⚠: Emit a typed message on port. Transfers ownership of the message — do not call rfl_message_free afterwards. Prefer this over the JSON variant for hot-path emits.
rfl_ctx_has_input^⚠: 1 if a packet is available on port, 0 otherwise. Does not consume.
rfl_ctx_input_json^⚠: Return the input packet on port as a JSON-encoded Message, or NULL if no packet is available. Caller frees via rfl_string_free.
rfl_ctx_state_get^⚠: Fetch a state entry as JSON. Returns NULL if absent. Caller frees via rfl_string_free.
rfl_ctx_state_set^⚠: Set a state entry. value_json is a JSON value (any shape).
rfl_ctx_take_input_message^⚠: Take the input packet on port as a typed message handle, removing it from the context. Returns NULL if no packet is available. Caller frees via rfl_message_free (or transfers ownership via rfl_ctx_emit_message).
rfl_events_free^⚠: Free an events handle. Safe on NULL.
rfl_events_recv^⚠: Poll for the next event, blocking up to timeout_ms milliseconds.
rfl_graph_add_connection^⚠
rfl_graph_add_graph_initial^⚠: Push a packet into one of the graph’s exposed inports.
rfl_graph_add_graph_initial_index^⚠: Indexed variant of rfl_graph_add_graph_initial.
rfl_graph_add_group^⚠: Create a group containing the given node ids. nodes_json must be a JSON array of strings, e.g. ["a","b"].
rfl_graph_add_initial^⚠: Add an initial packet. data_json is the JSON representation of the value (not a Message) — matches Graph::add_initial.
rfl_graph_add_initial_index^⚠: add_initial with an explicit slot index for arrays/streams. Mirrors Graph::add_initial_index.
rfl_graph_add_inport^⚠: Expose an inport on the graph (used when this graph is embedded as a subgraph). port_type_json is optional; pass NULL for PortType::Any or "\"All\"" / "\"Flow\"" etc.
rfl_graph_add_node^⚠: Add a node. metadata_json may be NULL or a JSON object string ({"key": ...}).
rfl_graph_add_outport^⚠
rfl_graph_add_to_group^⚠
rfl_graph_free^⚠: Free a graph handle. Safe on NULL.
rfl_graph_get_connection_json^⚠: Look up a connection by both endpoints. NULL if no such edge.
rfl_graph_get_node_json^⚠: Look up a node by id. Returns the JSON of the GraphNode, or NULL if the id is unknown (last error explains).
rfl_graph_get_properties_json^⚠
rfl_graph_import^⚠: Merge a GraphExport JSON document into the existing graph (additive — does not clear).
rfl_graph_list_connections_json^⚠
rfl_graph_list_groups_json^⚠
rfl_graph_list_initializers_json^⚠
rfl_graph_list_inports_json^⚠
rfl_graph_list_nodes_json^⚠: JSON array of every node in the graph.
rfl_graph_list_outports_json^⚠
rfl_graph_load_json^⚠: Load a graph from a GraphExport JSON document.
rfl_graph_new^⚠: Create a new empty graph.
rfl_graph_remove_connection^⚠
rfl_graph_remove_from_group^⚠
rfl_graph_remove_graph_initial^⚠: Remove an initial packet attached to a graph-level inport.
rfl_graph_remove_group^⚠
rfl_graph_remove_initial^⚠
rfl_graph_remove_inport^⚠
rfl_graph_remove_node^⚠
rfl_graph_remove_outport^⚠
rfl_graph_rename_inport^⚠: Rename an exposed inport (subgraph boundary).
rfl_graph_rename_node^⚠: Rename a node. Updates every connection that referenced the old id.
rfl_graph_rename_outport^⚠: Rename an exposed outport (subgraph boundary).
rfl_graph_set_connection_metadata^⚠: Replace the metadata on a connection. NULL metadata_json clears it.
rfl_graph_set_group_metadata^⚠
rfl_graph_set_inport_metadata^⚠
rfl_graph_set_node_metadata^⚠: Replace the metadata for an existing node.
rfl_graph_set_outport_metadata^⚠
rfl_graph_set_properties^⚠: Replace the graph’s properties dict. NULL clears it.
rfl_graph_to_json^⚠: Serialize a graph back to its GraphExport JSON form. Caller frees via rfl_string_free.
rfl_last_error_message: Returns the last thread-local error message as a newly allocated C string. Caller frees with rfl_string_free. Returns NULL if there is no error.
rfl_message_array_from_json^⚠: Array from a JSON array string.
rfl_message_as_boolean^⚠: If the message is a Boolean, writes its value into *out and returns 1. Returns 0 otherwise.
rfl_message_as_float^⚠
rfl_message_as_integer^⚠
rfl_message_as_json^⚠: Full message serialized as JSON. Always succeeds for representable variants. Caller frees via rfl_string_free.
rfl_message_as_string^⚠: String access — returns a newly allocated C string on String/Error variants, else NULL. Caller frees via rfl_string_free.
rfl_message_boolean
rfl_message_bytes^⚠: Binary payload; the buffer is copied into a refcounted allocation.
rfl_message_bytes_borrow^⚠: Zero-copy borrow of a Bytes payload. Writes a pointer into the Arc’d buffer and its length. The pointer is valid until the message handle is freed (or ownership transferred). Returns 1 on success, 0 if the message is not a Bytes variant.
rfl_message_error^⚠
rfl_message_float
rfl_message_flow
rfl_message_free^⚠: Free a message handle. Safe on NULL.
rfl_message_from_json^⚠: Fallback: parse a fully-tagged Message JSON (i.e. the same shape the legacy rfl_ctx_emit-by-JSON path consumes). Useful for tests / debugging — prefer the typed constructors in production.
rfl_message_get_kind^⚠
rfl_message_integer
rfl_message_object_from_json^⚠: Object from JSON. The JSON must parse as any valid serde value.
rfl_message_stream_take^⚠: Take the receiver for a StreamHandle message. Transfers ownership — only one call succeeds per stream. Returns NULL if the message is not a StreamHandle or the receiver has already been taken.
rfl_message_string^⚠: UTF-8 string; copied.
rfl_network_add_connection^⚠
rfl_network_add_initial^⚠: Seed an initial packet. message_json must parse as a Message (e.g. "\"Flow\"", {"Integer": 3}, {"String": "hi"}).
rfl_network_add_node^⚠: Add a node to a running or pending network. The template_id’s actor must have been registered first (via the component catalog or a custom rfl_actor_register once available).
rfl_network_events^⚠: Subscribe to the network’s event stream. Call before rfl_network_start for full coverage.
rfl_network_free^⚠: Free a network handle. Safe on NULL. Implies shutdown.
rfl_network_from_graph^⚠: Create a network from an already-loaded graph. The graph is consumed.
rfl_network_new: Create a new network with NetworkConfig::default().
rfl_network_new_with_config^⚠: Create a new network from a serialized NetworkConfig JSON. Returns NULL on parse error. Unknown fields are rejected.
rfl_network_register_actor^⚠: Register a callback actor as a template on the network. The network takes ownership; the caller must not continue to use the handle afterwards (treat it as freed).
rfl_network_shutdown^⚠: Signal the network to shut down. Non-blocking.
rfl_network_start^⚠: Start the network. Non-blocking; returns immediately after scheduling the actors.
rfl_pack_abi_version: The pack ABI version this host was compiled with. Pack authors can stamp the same number into their .rflpack manifests via reflow-pack build (which reads the REFLOW_PACK_ABI_VERSION env var or [abi] section).
rfl_pack_inspect_json^⚠: Read a .rflpack manifest without loading the pack. Fails for raw dylibs (they have no manifest). Caller frees the returned JSON via rfl_string_free.
rfl_pack_list_json: Return a JSON array describing every loaded pack: [{ "name": ..., "version": ..., "source_path": ..., "templates": [...] }]. Caller frees via rfl_string_free.
rfl_pack_load^⚠: Load an actor pack from path. path can point at either:
rfl_runtime_shutdown: Explicitly tear down the shared tokio runtime.
rfl_stream_end^⚠: Terminate the stream with success.
rfl_stream_error^⚠: Terminate the stream with an error.
rfl_stream_free^⚠: Free a producer handle without emitting it as a message. If the stream has live consumers, they will see an End frame when the sender is dropped.
rfl_stream_into_message^⚠: Convert this stream producer into a Message::StreamHandle that can be emitted on an output port. The producer is consumed — free is not necessary after this call.
rfl_stream_new^⚠: Allocate a new stream. buffer_size == 0 creates an unbounded channel; any positive value sets a bounded buffer (backpressure).
rfl_stream_recv_free^⚠: Free a stream receiver. Safe on NULL.
rfl_stream_recv_next^⚠: Block up to timeout_ms for the next frame.
rfl_stream_send_begin^⚠: Send a Begin frame (stream metadata). Optional — use before the first send_bytes if you want consumers to see content_type / size_hint / metadata_json before any data.
rfl_stream_send_bytes^⚠: Send a Data frame. The buffer is copied into a refcounted allocation.
rfl_string_free^⚠: Free a string returned by this library. Passing NULL is a no-op.
rfl_subgraph_actor_new_from_json^⚠: Build a SubgraphActor from a GraphExport JSON document. Each component referenced inside the export is resolved against the pack registry first, then the bundled reflow_components catalog. Returns NULL on parse error or on unknown component references.
rfl_subgraph_builder_build^⚠: Build the subgraph into an actor handle. Consumes the builder.
rfl_subgraph_builder_fill_from_catalog^⚠: Resolve any still-unregistered components: packs first, then the bundled catalog (if the components feature is on). Components still missing after both lookups cause the call to fail.
rfl_subgraph_builder_free^⚠: Abandon a builder without building. Safe on NULL.
rfl_subgraph_builder_new^⚠: Start a subgraph builder over a GraphExport JSON document. Returns NULL on parse error.
rfl_subgraph_builder_register_actor^⚠: Register an actor under component_name. The builder takes ownership of the actor handle — do not free it afterwards. Replacing an existing registration silently overwrites it.
rfl_template_actor_new^⚠: Instantiate an actor from a template id.
rfl_template_list_json: Return a JSON array of every template id reachable through this runtime — loaded packs plus (when compiled) the bundled catalog. Caller frees via rfl_string_free.
rfl_version: Runtime version string (newly allocated; free with rfl_string_free).

Type Aliases§

rfl_actor_drop_fn: Function pointer: released when the runtime drops the last reference to the actor. Use it to decrement a Node/Python/JVM GC root.
rfl_actor_fn: Function pointer: the body of a callback actor.