Crate byteflow 

Byteflow — embeddable register-based flow runtime.

Overview

Assemble programs with ChunkBuilder in host Rust (no separate source language). Spawn lightweight flows on an M:N scheduler; they communicate through FIFO mailboxes via Atomic Hops (Value::Message only on Send / Ask) and can be supervised on failure.

The crates.io package is byteflow-actors; this library crate is named byteflow, so dependents write use byteflow::....

Security (authenticated hops + FlowCap)

Structural typing (Send requires Value::Message) is not authentication or authorization. Bytecode may forge Message.sender via make_msg; the scheduler overwrites that field and mints a SEND-only reply_cap before delivery. Send / Ask targets must be Value::Cap — raw Value::Pid is identity only.

Full threat model, invariants S1–S7, and the capability roadmap: docs/security.md in the crate sources (also shipped on docs.rs when docs/ is included in the package).

Quick example

use byteflow::{ChunkBuilder, Opcode, FlowOutcome, Runtime, Value};

let mut b = ChunkBuilder::new("demo");
b.begin_function("main", 0, 2);
b.emit_load_imm(0, 41);
b.emit_load_imm(1, 1);
b.emit_binop(Opcode::Add, 0, 0, 1);
b.emit_return(0);

let rt = Runtime::new(b.finish())?;
let outcome = rt.spawn(0, &[])?.join();
rt.shutdown();
assert!(matches!(outcome, FlowOutcome::Completed(Value::Int(42))));

Host owns I/O. Byteflow owns cheap concurrency.

Re-exports

pub use bytecode::asm_macros;

pub use bytecode::decode;

pub use bytecode::disassemble;

pub use bytecode::encode;

pub use bytecode::verify;

pub use bytecode::Chunk;

pub use bytecode::ChunkBuilder;

pub use bytecode::FormatError;

pub use bytecode::FunctionDef;

pub use bytecode::Instruction;

pub use bytecode::Label;

pub use bytecode::Message;

pub use bytecode::Opcode;

pub use bytecode::Value;

pub use bytecode::VerifyError;

pub use bytecode::ABI_VERSION;

pub use bytecode::MAGIC;

pub use natives::std_native_map;

pub use natives::std_native_table;

pub use natives::std_natives;

pub use scheduler::fault_count;

pub use scheduler::next_flow_id;

pub use scheduler::flow_id_from_u64;

pub use scheduler::report_fault;

pub use scheduler::CapId;

pub use scheduler::CapRights;

pub use scheduler::ChildSpec;

pub use scheduler::Delivery;

pub use scheduler::Mailbox;

pub use scheduler::Flow;

pub use scheduler::FlowHandle;

pub use scheduler::FlowId;

pub use scheduler::FlowMetrics;

pub use scheduler::FlowOutcome;

pub use scheduler::FlowState;

pub use scheduler::RestartPolicy;

pub use scheduler::Runtime;

pub use scheduler::RuntimeConfig;

pub use scheduler::RuntimeError;

pub use scheduler::RuntimeMetrics;

pub use scheduler::RuntimeMetricsSnapshot;

pub use scheduler::RuntimeSpawner;

pub use scheduler::SendError;

pub use scheduler::SpawnError;

pub use scheduler::Supervisor;

pub use scheduler::SupervisorConfig;

pub use scheduler::DEFAULT_QUANTUM;

pub use vm::expect_arg;

pub use vm::expect_bool;

pub use vm::expect_int;

pub use vm::expect_message;

pub use vm::expect_u64;

pub use vm::Fault;

pub use vm::NativeFn;

pub use vm::NativeResult;

pub use vm::NativeTable;

pub use vm::NativeTableBuilder;

pub use vm::Vm;

pub use vm::VmResult;

pub use vm::MAX_CALL_DEPTH;

Modules

bytecode

Instruction set, .bf (BFV0) format, assembler (ChunkBuilder) and verifier. Pure data — no I/O, no threads.

log

Host-side scheduler diagnostics on stderr, gated by BYTEFLOW_LOG.

natives

Standard native (FFI) table shipped with the facade.

samples

Built-in demo chunks assembled with crate::ChunkBuilder.

scheduler

M:N flows, mailboxes, timer, supervisor and Runtime.

vm

Register-based interpreter for one virtual Flow. Scheduler effects return as VmResult.

Macros

emit_native1_from

emit_native1_from!(builder, dest, src, native) — sugar for crate::ChunkBuilder::emit_native1_from.

emit_native_n

emit_native_n!(builder, base, native, argc) — sugar for crate::ChunkBuilder::emit_native_n.