grafos_std/
lib.rs

1//! grafos-std — The Rust SDK for programs targeting grafOS.
2//!
3//! This crate provides typed, safe access to fabric resources (memory,
4//! block storage, GPU, CPU) through host function bindings. Programs
5//! compile against `grafos-std` and run as WASM tasklets on the grafOS
6//! runtime, or natively for development and testing.
7//!
8//! # Resource modules
9//!
10//! | Module | Resource | Host API | Status |
11//! |--------|----------|----------|--------|
12//! | [`mem`] | Byte-addressable memory | FBMU | Implemented |
13//! | [`block`] | 512-byte block storage | FBBU | Implemented |
14//! | [`gpu`] | GPU kernel dispatch | GPU_SUBMIT (0x0600) | Implemented |
15//! | [`cpu`] | CPU tasklet dispatch | TASKLET_SUBMIT (0x0500) | Implemented |
16//!
17//! Each resource module exposes three types:
18//! - A **handle** (`FabricMem`, `FabricBlock`, etc.) for performing I/O.
19//! - A **lease** (`MemLease`, `BlockLease`, etc.) that wraps the handle with
20//!   RAII cleanup.
21//! - A **builder** (`MemBuilder`, `BlockBuilder`, etc.) for requesting a
22//!   resource with capacity constraints.
23//!
24//! The [`fabric`] module provides a top-level entry point for discovery and
25//! allocation across all resource types.
26//!
27//! # Dual-target design
28//!
29//! On `wasm32` targets, host functions link to real imports provided by the
30//! grafOS runtime. On native targets, the [`host`] module provides mock
31//! implementations backed by thread-local storage, so all resource modules
32//! work in unit tests without a WASM runtime.
33//!
34//! # Feature flags
35//!
36//! | Feature | Default | Effect |
37//! |---------|---------|--------|
38//! | `std` | Yes | Enables `std::error::Error` impl for [`FabricError`] |
39//! | `serde` | No | Enables `serde_support` module for typed struct I/O via postcard |
40//!
41//! # Quick start
42//!
43//! ```rust
44//! use grafos_std::prelude::*;
45//!
46//! fn main() -> grafos_std::Result<()> {
47//!     # grafos_std::host::reset_mock();
48//!     # grafos_std::host::mock_set_fbmu_arena_size(4096);
49//!     let mem = grafos_std::mem::FabricMem::hello()?;
50//!     mem.write(0, b"hello fabric")?;
51//!     let data = mem.read(0, 12)?;
52//!     assert_eq!(&data, b"hello fabric");
53//!     Ok(())
54//! }
55//! ```
56
57#![cfg_attr(not(feature = "std"), no_std)]
58
59extern crate alloc;
60
61pub mod error;
62pub mod host;
63pub mod lease;
64
65pub mod affinity;
66pub mod block;
67pub mod cpu;
68pub mod cpu_shared;
69pub mod fabric;
70pub mod gpu;
71pub mod grafos_worker_v0;
72pub mod mem;
73pub mod net;
74
75#[cfg(feature = "serde")]
76pub mod serde_support;
77
78#[cfg(feature = "observe")]
79pub(crate) mod observe_hooks;
80
81/// Convenience re-exports for `use grafos_std::prelude::*`.
82///
83/// Imports all public handle types, lease types, builder types, error types,
84/// and the [`Fabric`](crate::fabric::Fabric) entry point. This is the
85/// recommended way to import the SDK in application code.
86pub mod prelude {
87    pub use crate::block::{BlockBuilder, BlockLease, FabricBlock, BLOCK_SIZE};
88    pub use crate::cpu::{CpuBuilder, CpuLease, FabricCpu, TaskletResult};
89    pub use crate::error::{FabricError, Result};
90    pub use crate::fabric::{Fabric, NodeInfo};
91    pub use crate::gpu::{GpuBuilder, GpuLease};
92    pub use crate::lease::{LeaseInfo, LeaseStatus};
93    pub use crate::mem::{FabricMem, MemBuilder, MemLease};
94    pub use crate::net::{FabricNet, NetBuilder, NetLease};
95}
96
97pub use error::{FabricError, Result};
grafos_std/lib.rs

grafos_std/
lib.rs
