fidius-guest::stream_ffi
Rust
cdylib server-streaming FFI handle (FIDIUS-I-0026 Phase 3 / CS.1, T-0138).
A -> fidius::Stream<T> method on the cdylib backend can’t be a single
unary call. Instead its vtable slot holds an init shim (with the ordinary
(in_ptr, in_len, *mut *mut u8, *mut u32) -> i32 signature, so the vtable
layout is unchanged) that returns — via the standard out_ptr slot — a
pointer to a FidiusStreamHandle. The host then pulls the stream with an
arena-style next (FIDIUS-T-0138): the host passes a reusable buffer it
owns, and the guest writes the bincode-encoded item into it — no per-item
heap alloc, and no free_buffer FFI crossing.
status = (handle.next)(handle, buf_ptr, buf_cap, &mut out_len); STATUS_OK → one item: buf[..out_len] is the bincode-encoded item. STATUS_STREAM_END → clean end of stream (no item). STATUS_BUFFER_TOO_SMALL → out_len = required size; host grows + retries once. (The guest holds the serialized item across the retry, so no item is lost.) STATUS_PLUGIN_ERROR → buf[..out_len] is a bincode `PluginError`. STATUS_SERIALIZATION_ERROR / STATUS_PANIC → as usual.(handle.drop_fn)(handle); // run once: drops the producer + frees the handleItems cross as concrete bincode of the item type — byte-identical to the
unary cdylib wire (FIDIUS-T-0137). The host decodes each item with a
caller-supplied bincode::<O> decoder (the typed Client knows O).
Structs
Section titled “Structs”struct FidiusStreamHandle
Section titled “struct FidiusStreamHandle”pub
Per-stream handle returned by a cdylib streaming method’s init shim. See the module docs for the pull protocol. #[repr(C)] so the guest (which builds it) and the host (which drives it) agree on the layout across the FFI boundary.
Fields
Section titled “Fields”| Name | Type | Description |
|---|---|---|
next |
unsafe extern "C" fn(*mut FidiusStreamHandle, *mut u8, u32, *mut u32) -> i32 |
Advance one item into a host-provided buffer. (handle, buf_ptr, buf_cap, &mut out_len) -> status. |
drop_fn |
unsafe extern "C" fn(*mut FidiusStreamHandle) |
Finish/cancel: drops the producer and frees the handle box. Call exactly once. |
state |
*mut c_void |
Opaque pointer to the boxed [StreamState<T>], owned by the guest; freed by drop_fn. |
struct StreamState<T>
Section titled “struct StreamState<T>”pub
Guest-side driver for an arena-style cdylib stream (FIDIUS-T-0138). Wraps the producer Stream<T> and holds the current item value (not its bytes), so a BUFFER_TOO_SMALL retry re-serializes the same item rather than advancing the iterator (which would drop it) — and so the happy path serializes directly into the host buffer with no Vec allocation.
Methods
Section titled “Methods”pub
fn new(stream: crate::stream_marker::Stream<T>) -> SelfWrap a producer stream.
Source
pub fn new(stream: crate::stream_marker::Stream<T>) -> Self { Self { stream, pending: None, } }next_into
Section titled “next_into”pub
fn next_into(&mut self, buf: &mut [u8]) -> NextStatusPull the next item (if needed) and serialize it directly into buf — no intermediate allocation. On TooSmall the item value is retained and re-serialized on the next (larger-buffer) call, so nothing is lost.
Source
pub fn next_into(&mut self, buf: &mut [u8]) -> NextStatus { if self.pending.is_none() { match self.stream.next_item() { Some(item) => self.pending = Some(item), None => return NextStatus::End, } } // SAFETY of unwrap: pending is Some by the block above. let item = self.pending.as_ref().unwrap(); let size = match crate::wire::serialized_size(item) { Ok(s) => s as usize, Err(_) => return NextStatus::SerErr, }; if size > buf.len() { return NextStatus::TooSmall(size); } if crate::wire::serialize_into(&mut buf[..size], item).is_err() { return NextStatus::SerErr; } self.pending = None; NextStatus::Item(size) }struct HostStream<T>
Section titled “struct HostStream<T>”pub
Guest-side consumer of a host-produced stream — the client-streaming counterpart of StreamState (FIDIUS-I-0030 / ADR-0007). For a method that takes a Stream<T> argument, the host fills a FidiusStreamHandle from its producer and the guest pulls items by calling next and bincode-deserializing each into T. Yields items via Iterator; dropping it runs the host producer’s drop_fn (cancel).
Methods
Section titled “Methods”from_handle
Section titled “from_handle”pub unsafe
unsafe fn from_handle(handle: *mut FidiusStreamHandle) -> SelfWrap a host-provided handle. The handle is owned by this consumer and freed (via drop_fn) on drop.
Safety
handle must be a valid, exclusively-owned FidiusStreamHandle supplied by
the host for the duration of this consumer.
Source
pub unsafe fn from_handle(handle: *mut FidiusStreamHandle) -> Self { Self { handle, cap: 256, _marker: PhantomData, } }enum NextStatus
Section titled “enum NextStatus”pub
Outcome of StreamState::next_into — mapped to FFI status codes by the macro-generated next shim.
Variants
Section titled “Variants”Item- An item was written; payload isbuf[..n].End- No more items.TooSmall- The buffer was too small;usizeis the size required. The item is retained for the next call (no item lost on grow-and-retry).SerErr- Serializing the item failed.