Skip to main content

asupersync/
lib.rs

1//! Asupersync: Spec-first, cancel-correct, capability-secure async runtime for Rust.
2//!
3//! # Overview
4//!
5//! Asupersync is an async runtime built on the principle that correctness should be
6//! structural, not conventional. Every task is owned by a region that closes to
7//! quiescence. Cancellation is a first-class protocol, not a silent drop. Effects
8//! require explicit capabilities.
9//!
10//! # Core Guarantees
11//!
12//! - **No orphan tasks**: Every spawned task is owned by a region; region close waits for all children
13//! - **Cancel-correctness**: Cancellation is request → drain → finalize, never silent data loss
14//! - **Bounded cleanup**: Cleanup budgets are sufficient conditions, not hopes
15//! - **No silent drops**: Two-phase effects (reserve/commit) prevent data loss
16//! - **Deterministic testing**: Lab runtime with virtual time and deterministic scheduling
17//! - **Capability security**: All effects flow through explicit `Cx`; no ambient authority
18//!
19//! # Module Structure
20//!
21//! - [`types`]: Core types (identifiers, outcomes, budgets, policies)
22//! - [`record`]: Internal records for tasks, regions, obligations
23//! - [`trace`](mod@trace): Tracing infrastructure for deterministic replay
24//! - [`runtime`]: Scheduler and runtime state
25//! - [`cx`]: Capability context and scope API
26//! - [`combinator`]: Join, race, timeout combinators
27//! - [`lab`]: Deterministic lab runtime for testing
28//! - [`util`]: Internal utilities (deterministic RNG, arenas)
29//! - [`error`](mod@error): Error types
30//! - [`channel`]: Two-phase channel primitives (MPSC, etc.)
31//! - [`encoding`]: RaptorQ encoding pipeline
32//! - [`observability`]: Structured logging, metrics, and diagnostic context
33//! - [`security`]: Symbol authentication and security primitives
34//! - [`time`]: Sleep and timeout primitives for time-based operations
35//! - [`io`]: Async I/O traits and adapters
36//! - [`net`]: Async networking primitives (Phase 0: synchronous wrappers)
37//! - [`bytes`]: Zero-copy buffer types (Bytes, BytesMut, Buf, BufMut)
38//! - [`tracing_compat`]: Optional tracing integration (requires `tracing-integration` feature)
39//! - [`plan`]: Plan DAG IR for join/race/timeout rewrites
40//!
41//! # API Stability
42//!
43//! Asupersync is currently in the 0.x series. Unless explicitly noted in
44//! `docs/api_audit.md`, public items should be treated as **unstable** and
45//! subject to change. Core types like [`Cx`], [`Outcome`], and [`Budget`] are
46//! intended to stabilize first.
47
48// Default to deny for unsafe code - specific modules (like epoll reactor) can use #[allow(unsafe_code)]
49// when they need to interface with FFI or low-level system APIs
50#![deny(unsafe_code)]
51#![warn(missing_docs)]
52#![warn(clippy::pedantic)]
53#![warn(clippy::nursery)]
54// Phase 0: Allow dead code and documentation lints for stubs
55#![allow(dead_code)]
56#![allow(clippy::missing_panics_doc)]
57#![allow(clippy::missing_errors_doc)]
58#![allow(clippy::missing_const_for_fn)]
59#![allow(clippy::module_inception)]
60#![allow(clippy::doc_markdown)]
61#![allow(clippy::cast_possible_truncation)]
62#![cfg_attr(test, allow(clippy::large_stack_arrays))]
63// Test harness builds a large test table in one frame.
64#![cfg_attr(test, allow(clippy::large_stack_frames))]
65#![cfg_attr(feature = "simd-intrinsics", feature(portable_simd))]
66
67pub mod actor;
68pub mod app;
69pub mod audit;
70pub mod bytes;
71pub mod cancel;
72pub mod channel;
73pub mod cli;
74pub mod codec;
75pub mod combinator;
76pub mod config;
77pub mod conformance;
78pub mod console;
79pub mod cx;
80#[cfg(any(feature = "sqlite", feature = "postgres", feature = "mysql"))]
81pub mod database;
82pub mod decoding;
83pub mod distributed;
84pub mod encoding;
85pub mod epoch;
86pub mod error;
87pub mod evidence;
88pub mod evidence_sink;
89pub mod fs;
90pub mod gen_server;
91pub mod grpc;
92pub mod http;
93pub mod io;
94pub mod lab;
95pub mod link;
96pub mod messaging;
97pub mod migration;
98pub mod monitor;
99pub mod net;
100pub mod obligation;
101pub mod observability;
102pub mod plan;
103#[cfg(unix)]
104pub mod process;
105pub mod raptorq;
106pub mod record;
107pub mod remote;
108pub mod runtime;
109pub mod security;
110pub mod server;
111pub mod service;
112pub mod session;
113pub mod signal;
114pub mod spork;
115pub mod stream;
116pub mod supervision;
117pub mod sync;
118#[cfg(any(test, feature = "test-internals"))]
119pub mod test_logging;
120#[cfg(any(test, feature = "test-internals"))]
121pub mod test_ndjson;
122#[cfg(any(test, feature = "test-internals"))]
123pub mod test_utils;
124pub mod time;
125#[cfg(feature = "tls")]
126pub mod tls;
127pub mod trace;
128pub mod tracing_compat;
129pub mod transport;
130pub mod types;
131pub mod util;
132pub mod web;
133
134// Re-exports for convenient access to core types
135pub use config::{
136    AdaptiveConfig, BackoffConfig, ConfigError, ConfigLoader, EncodingConfig,
137    PathSelectionStrategy, RaptorQConfig, ResourceConfig, RuntimeProfile, SecurityConfig,
138    TimeoutConfig, TransportConfig,
139};
140pub use cx::{Cx, Scope};
141pub use decoding::{
142    DecodingConfig, DecodingError, DecodingPipeline, DecodingProgress, RejectReason,
143    SymbolAcceptResult,
144};
145pub use encoding::{EncodedSymbol, EncodingError, EncodingPipeline, EncodingStats};
146pub use epoch::{
147    BarrierResult, BarrierTrigger, Epoch, EpochBarrier, EpochBulkheadError,
148    EpochCircuitBreakerError, EpochClock, EpochConfig, EpochContext, EpochError, EpochId,
149    EpochJoin2, EpochPolicy, EpochRace2, EpochScoped, EpochSelect, EpochSource, EpochState,
150    EpochTransitionBehavior, SymbolValidityWindow, bulkhead_call_in_epoch,
151    bulkhead_call_weighted_in_epoch, circuit_breaker_call_in_epoch, epoch_join2, epoch_race2,
152    epoch_select,
153};
154pub use error::{
155    AcquireError, BackoffHint, Error, ErrorCategory, ErrorKind, Recoverability, RecoveryAction,
156    RecvError, Result, ResultExt, SendError,
157};
158pub use lab::{LabConfig, LabRuntime};
159pub use remote::{
160    CancelRequest, CompensationResult, ComputationName, DedupDecision, IdempotencyKey,
161    IdempotencyRecord, IdempotencyStore, Lease, LeaseError, LeaseRenewal, LeaseState, NodeId,
162    RemoteCap, RemoteError, RemoteHandle, RemoteMessage, RemoteOutcome, RemoteTaskId,
163    ResultDelivery, Saga, SagaState, SagaStepError, SpawnAck, SpawnAckStatus, SpawnRejectReason,
164    SpawnRequest, spawn_remote,
165};
166pub use types::{
167    Budget, CancelKind, CancelReason, ObligationId, Outcome, OutcomeError, PanicPayload, Policy,
168    RegionId, Severity, SystemPressure, TaskId, Time, join_outcomes,
169};
170
171// Re-export proc macros when the proc-macros feature is enabled
172// Note: join! and race! are not re-exported because they conflict with the
173// existing macro_rules! definitions in combinator/. The proc macro versions
174// will replace those in future tasks (asupersync-mwff, asupersync-hcpl).
175#[cfg(feature = "proc-macros")]
176pub use asupersync_macros::{join_all, scope, spawn};
177
178// Proc macro versions available with explicit path when needed
179#[cfg(feature = "proc-macros")]
180pub mod proc_macros {
181    //! Proc macro versions of structured concurrency macros.
182    //!
183    //! These are provided for explicit access when the macro_rules! versions
184    //! are also in scope.
185    pub use asupersync_macros::{join, join_all, race, scope, session_protocol, spawn};
186}