limen_core/
lib.rs

1// Copyright © 2025–present Arlo Louis Byrne (idky137)
2// SPDX-License-Identifier: Apache-2.0
3//
4// Licensed under the Apache License, Version 2.0.
5// See the LICENSE-APACHE file in the project root for license terms.
6
7#![cfg_attr(not(feature = "std"), no_std)]
8#![warn(missing_docs)]
9#![deny(unsafe_code)]
10//! # limen-core
11//!
12//! **Limen Core** defines the *stable contracts and primitives* for the Limen
13//! graph-driven, edge inference runtime targeting embedded and resource-constrained
14//! systems.
15//!
16//! ## Design principles
17//!
18//! - **`no_std` by default.** All code compiles without `std`. Heap use is gated
19//!   behind `#[cfg(feature = "alloc")]`; concurrent primitives behind `std`.
20//! - **No dynamic dispatch in hot paths.** Node, edge, memory manager, and
21//!   scheduler types are monomorphized via generics and const generics.
22//! - **Token-based message passing.** Edges carry [`types::MessageToken`] handles
23//!   rather than full messages. Message data (header + payload) lives in a
24//!   [`memory::manager::MemoryManager`], addressed by token. This enables
25//!   zero-copy routing and heterogeneous memory classes (host, pinned, device).
26//! - **Stable contracts.** The traits defined here are the versioned boundary
27//!   between application code and the runtime. Higher-level crates
28//!   (`limen-runtime`, `limen-codegen`, `limen-node`) depend on this crate and
29//!   can evolve independently without breaking the contract surface.
30//!
31//! ## Module overview
32//!
33//! | Module | What it provides |
34//! |--------|-----------------|
35//! | [`types`] | Newtypes for IDs, timing, QoS, `MessageToken`, `DataType`/`DType`, `F16`/`BF16` |
36//! | [`errors`] | Error families for queues, nodes, inference, graph, runtime |
37//! | [`memory`] | `MemoryClass`, `PlacementAcceptance`, `BufferDescriptor`; memory manager traits and impls |
38//! | [`message`] | `MessageHeader`, `MessageFlags`, `Message<P>`; `Payload` trait; `Tensor`; `Batch` |
39//! | [`policy`] | Batching, budget, deadline, admission, and per-edge/node policy types |
40//! | [`compute`] | `ComputeBackend` / `ComputeModel` traits for dyn-free inference backends |
41//! | [`edge`] | `Edge` SPSC trait; `EnqueueResult`, `EdgeOccupancy`; queue implementations |
42//! | [`node`] | `Node` trait; `StepContext`, `StepResult`, `ProcessResult`; source/sink/model sub-traits |
43//! | [`graph`] | `GraphApi`, `ScopedGraphApi`; compile-time node/edge access traits; descriptor validation |
44//! | [`scheduling`] | `Readiness`, `NodeSummary`, `DequeuePolicy`; `WorkerScheduler` for concurrent execution |
45//! | [`telemetry`] | `Telemetry` trait; `TelemetryEvent`; `NodeMetrics`, `EdgeMetrics`, `GraphMetrics` |
46//! | [`platform`] | `PlatformClock`, `Span`, `Timers`, `Affinity`; `NoopClock` |
47//! | [`runtime`] | `LimenRuntime` trait; `RuntimeStopHandle` |
48//! | [`prelude`] | Convenience re-exports for all of the above, feature-gated |
49//!
50//! ## Feature flags
51//!
52//! | Flag | Effect |
53//! |------|--------|
54//! | *(default)* | `no_std`, no heap; fixed-size SPSC queues (`SpscArrayQueue`) |
55//! | `alloc` | `HeapMemoryManager`, `SpscVecDeque`, owned `BatchView` |
56//! | `std` | implies `alloc`; `ConcurrentMemoryManager`, `ConcurrentEdge`, `ScopedEdge`, `ScopedGraphApi`, concurrent telemetry |
57//! | `spsc_raw` | unsafe lock-free ring buffer (`SpscRawQueue`); requires `std` |
58//! | `bench` | exposes test nodes, edges, graphs, and runtimes for integration tests |
59//! | `checked-memory-manager-refs` | adds per-slot borrow-state tracking to `StaticMemoryManager` and `HeapMemoryManager` |
60
61#[cfg(feature = "alloc")]
62extern crate alloc;
63
64pub mod errors;
65pub mod memory;
66pub mod types;
67
68pub mod message;
69pub mod platform;
70pub mod policy;
71
72pub mod compute;
73pub mod scheduling;
74pub mod telemetry;
75
76pub mod edge;
77pub mod graph;
78pub mod node;
79pub mod runtime;
80
81pub mod prelude;
limen_core/lib.rs

limen_core/
lib.rs
