orust-runtime

orust-runtime is the Rust runtime library used by programs generated from ORust. ORust is an object-oriented front end for Rust: the compiler emits ordinary Rust, while this crate supplies shared helpers for async execution, tasks, channels, diagnostics, collections, I/O, environment access, and math.

The runtime does not replace Rust's ownership, borrowing, type, privacy, Send, or 'static checks. It is a thin, versioned bridge over Tokio, futures, and async-trait.

Installation

Most ORust users install the orust CLI and do not install this crate manually. Running orust new project-name creates a Cargo project whose manifest already includes orust-runtime; orust run builds it through Cargo.

For a handwritten Rust project that uses runtime APIs directly, add:

[dependencies]
orust-runtime = "0.1.2"

Example:

use orust_runtime::{seconds, sleep};

#[tokio::main]
async fn main() {
    sleep(seconds(1)).await;
}

The crate currently enables Tokio's macros, rt-multi-thread, time, and sync features, and depends on futures and async-trait.

Generated Rust mapping

See the runtime architecture guide, async guide, and modules guide.

Tasks and async execution

spawn starts a Tokio task and returns Task<T>. Awaiting the task exposes a join failure as Error:

use orust_runtime::{spawn, Error, Task};

async fn compute() -> i64 { 40 + 2 }

async fn run() -> Result<i64, Error> {
    let task: Task<i64> = spawn(compute());
    task.await_task().await
}

Spawning requires the future and captured values to satisfy Send + 'static. The runtime deliberately preserves this Tokio requirement. Calling an async function creates a lazy future; execution starts only when it is awaited or spawned. See the async semantics documentation.

Time helpers are available to generated and handwritten Rust:

use orust_runtime::{millis, seconds};

let short = millis(250);
let long = seconds(2);

Channels

channel(capacity) creates a bounded Tokio multi-producer channel. Cloning a Channel<T> clones its sender and shares the receiver behind an async mutex:

use orust_runtime::{channel, spawn, Error};

async fn example() -> Result<i64, Error> {
    let queue = channel::<i64>(8);
    let producer = queue.clone();
    let task = spawn(async move { producer.send(42).await });

    let value = queue.recv().await.unwrap_or_default();
    task.await_task().await??;
    Ok(value)
}

send returns Error when the receiver is dropped. recv returns None when the channel is closed and empty.

Errors and panic diagnostics

Error stores a user-facing message and converts from errors implementing std::error::Error + Send + Sync + 'static:

use orust_runtime::Error;

fn adapt(error: std::io::Error) -> Error { error.into() }

Generated ORust entry points install the panic hook automatically. Rust applications can install it explicitly:

fn main() {
    orust_runtime::install_panic_hook();
}

Known failures map to stable ORust codes:

• OR0008 — arithmetic overflow
• OR0010 — list index out of range
• OR0011 — conflicting borrow
• OR0012 — invalid string character boundary
• OR0013 — division by zero
• OR0014 — missing optional value was unwrapped
• OR0099 — unknown runtime panic

Set ORUST_BACKTRACE=1 to include the Rust panic location. See the diagnostics guide and error-code registry.

Safe indexing and options

Generated collection access uses checked_index:

let index = orust_runtime::checked_index(2, values.len());
let value = &values[index];

Negative indexes and indexes outside the collection produce an ORust runtime diagnostic. display_option renders Some(value) through Display and renders None as null:

assert_eq!(orust_runtime::display_option(&Some(7)), "7");
assert_eq!(orust_runtime::display_option::<i32>(&None), "null");

Standard helper modules

std_math

Provides pi, e, and common f64 operations: sqrt, pow, sin, cos, tan, log, exp, min, max, abs, floor, and ceil.

std_env

Provides args, get, set, and cwd. These follow Rust's process-wide environment semantics.

std_io

std_io::File provides string-oriented existence, read, write, and append helpers. std_io::Path provides portable join, parent, and file-name helpers. I/O failures become Error values:

use orust_runtime::std_io::File;

fn read(path: String) -> Result<String, orust_runtime::Error> {
    File::read_string(path)
}

Use std::fs directly in a Rust block for advanced filesystem operations.

Rust interoperability

The runtime is ordinary Rust and can be used beside ORust-generated code:

rust use orust_runtime::{seconds, sleep};

async void main() {
  rust { sleep(seconds(1)).await; }
}

External crates such as serde_json belong in the project's Cargo.toml or orust.toml; Cargo resolves those dependencies. Use explicit Rust imports, @rustImport, @rustType, or passthrough blocks at the boundary. See the Rust/ORust interoperability guide.

Versioning and packaging

The runtime version follows the ORust release line. Generated code should use the same major/minor runtime line as the CLI that emitted it. Patch releases should preserve generated-code compatibility; breaking runtime API changes require a coordinated compiler release.

Generated projects use the crate name orust_runtime in emitted Rust. Cargo handles downloading and compiling the matching runtime version automatically.

Documentation map

• Runtime architecture
• Async and Tokio semantics
• Ownership and cleanup
• Modules and Cargo dependencies
• Rust/ORust interoperability
• Diagnostics and error codes