Module runtime 

Runtime state and scheduling.

This module contains the core runtime machinery:

• config: Runtime configuration types
• builder: Runtime builder and handles
• state: Global runtime state (Σ = {regions, tasks, obligations, now})
• scheduler: Three-lane priority scheduler
• stored_task: Type-erased future storage
• task_handle: TaskHandle for awaiting spawned task results
• waker: Waker implementation with deduplication
• timer: Timer heap for deadline management
• deadline_monitor: Deadline monitoring for approaching timeouts
• reactor: I/O reactor abstraction
• io_driver: Reactor driver that dispatches readiness to wakers
• region_heap: Region-owned heap allocator with quiescent reclamation
• cache: Content-addressed artifact cache and zero-copy handoff policy
• rch_health: Deterministic RCH worker health and cache-warm admission
• pool_sizing: Pure queueing-theoretic pool sizing recommendations

Runtime Builder

Asupersync configures the runtime with a fluent, move-based builder API. Each builder method consumes self and returns an updated builder, enabling ergonomic chaining without borrowing hazards.

Quick Start

A RuntimeBuilder constructs the Runtime. Code polled by Runtime::block_on can recover its runtime-wired context and use the returned TaskHandle to observe a region-owned child.

use asupersync::Cx;
use asupersync::runtime::RuntimeBuilder;

let runtime = RuntimeBuilder::current_thread()
    .build()
    .expect("build current-thread runtime");
let value = runtime.block_on(async {
    let cx = Cx::current().expect("block_on installs a runtime Cx");
    let mut task = cx
        .spawn(|child_cx| async move {
            child_cx.checkpoint().expect("child remains active");
            42_u8
        })
        .expect("runtime Cx has spawn authority");
    task.join(&cx).await.expect("task completes")
});
assert_eq!(value, 42);

Single-Threaded (Deterministic)

use asupersync::runtime::RuntimeBuilder;

let runtime = RuntimeBuilder::current_thread().build()?;
runtime.block_on(async { /* deterministic tests */ });

High-Throughput Server

use asupersync::runtime::RuntimeBuilder;

let runtime = RuntimeBuilder::high_throughput()
    .global_queue_limit(65_536)
    .blocking_threads(4, 64)
    .build()?;

Low-Latency Workloads

use asupersync::runtime::RuntimeBuilder;
use std::time::Duration;

let runtime = RuntimeBuilder::low_latency()
    .poll_budget(16)
    .deadline_monitoring(|m| {
        m.enabled(true)
            .check_interval(Duration::from_millis(5))
            .warning_threshold_fraction(0.2)
    })
    .build()?;

Config File + Environment Overrides

use asupersync::runtime::RuntimeBuilder;

// Requires the `config-file` feature.
let runtime = RuntimeBuilder::from_toml("config/runtime.toml")?
    .with_env_overrides()?
    .build()?;

Error Handling

use asupersync::runtime::RuntimeBuilder;

// Requires the `config-file` feature.
let result = RuntimeBuilder::from_toml_str("not valid {{{");
assert!(result.is_err());

Migration Guide (RuntimeConfig → RuntimeBuilder)

use asupersync::runtime::{Runtime, RuntimeBuilder, RuntimeConfig};

// Old style: build a config directly.
let mut config = RuntimeConfig::default();
config.worker_threads = 4;
let runtime = Runtime::with_config(config)?;

// New style: builder chain.
let runtime = RuntimeBuilder::new()
    .worker_threads(4)
    .build()?;

Configuration Reference (Defaults + Notes)

• worker_threads: default = available parallelism (min 1). Higher throughput, more CPU use.
• thread_stack_size: default = 2 MiB. Larger stack increases memory per worker.
• thread_name_prefix: default = asupersync-worker. Improves diagnostics.
• global_queue_limit: default = 0 (unbounded). Lower values add backpressure.
• steal_batch_size: default = 16. Larger favors throughput; smaller favors latency.
• blocking_threads(min, max): default = 0..0. Max is clamped to be >= min.
• enable_parking: default = true. Disabling reduces wake latency at CPU cost.
• poll_budget: default = 128. Lower for fairness, higher for throughput.
• root_region_limits: default = None. Admission limits applied to root region.
• on_thread_start/stop: lifecycle hooks; keep work minimal to avoid jitter.
• metrics(...): default = NoOp. Custom providers add instrumentation overhead.
• deadline_monitoring(...): disabled by default; enables warning callbacks.

Re-exports

pub use crate::record::RegionLimits;

pub use crate::sync::ContendedMutex;

pub use crate::sync::LockMetricsSnapshot;

pub use blocking_pool::BlockingPool;

pub use blocking_pool::BlockingPoolHandle;

pub use blocking_pool::BlockingPoolOptions;

pub use blocking_pool::BlockingTaskHandle;

pub use builder::BrowserRuntime;

pub use builder::BrowserRuntimeBuildError;

pub use builder::BrowserRuntimeBuilder;

pub use builder::BrowserRuntimeSelectionResult;

pub use builder::BrowserServiceWorkerBrokerSupportDiagnostics;

pub use builder::BrowserServiceWorkerBrokerSupportReason;

pub use builder::BrowserSharedWorkerCoordinatorSupportDiagnostics;

pub use builder::BrowserSharedWorkerCoordinatorSupportReason;

pub use builder::BrowserWorkerFallbackTarget;

pub use builder::CheckedJoinHandle;

pub use builder::DeadlineMonitoringBuilder;

pub use builder::JoinHandle;

pub use builder::Runtime;

pub use builder::RuntimeBuilder;

pub use builder::RuntimeHandle;

pub use cache::ArtifactCache;

pub use cache::ArtifactCacheConfig;

pub use cache::ArtifactMemoryPressureSnapshot;

pub use cache::ArtifactMetadata;

pub use cache::CacheStatistics;

pub use cache::EvictionPolicy;

pub use changepoint::ChangeDirection;

pub use changepoint::ChangePointDetection;

pub use changepoint::ChangePointDetectorKind;

pub use changepoint::ChangePointMonitor;

pub use changepoint::ChangePointMonitorConfig;

pub use changepoint::ChangePointSeriesConfig;

pub use changepoint::ChangePointSnapshot;

pub use changepoint::CusumConfig;

pub use changepoint::CusumDetector;

pub use changepoint::MetricSample;

pub use changepoint::PageHinkleyConfig;

pub use changepoint::PageHinkleyDetector;

pub use changepoint::RuntimeMetricSeries;

pub use changepoint::SeriesDetector;

pub use config::BlockingPoolConfig;

pub use config::RuntimeConfig;

pub use config::TraceStorageBudget;

pub use config::TraceStorageProfile;

pub use deadline_monitor::AdaptiveDeadlineConfig;

pub use deadline_monitor::DeadlineMonitor;

pub use deadline_monitor::DeadlineWarning;

pub use deadline_monitor::MonitorConfig;

pub use deadline_monitor::WarningReason;

pub use epoch_tracker::EpochConsistencyConfig;

pub use epoch_tracker::EpochConsistencyTracker;

pub use epoch_tracker::EpochConsistencyViolation;

pub use epoch_tracker::ModuleId;

pub use io_driver::IoDriver;

pub use io_driver::IoDriverHandle;

pub use io_driver::IoRegistration;

pub use io_op::IoOp;

pub use memory_residency::MEMORY_RESIDENCY_ACCOUNTING_DEBUG_ENDPOINT;

pub use memory_residency::MEMORY_RESIDENCY_ACCOUNTING_SNAPSHOT_SCHEMA_VERSION;

pub use memory_residency::MEMORY_RESIDENCY_DECISION_SCHEMA_VERSION;

pub use memory_residency::MEMORY_RESIDENCY_POLICY_SCHEMA_VERSION;

pub use memory_residency::MemoryResidencyAccountingSnapshot;

pub use memory_residency::MemoryResidencyAccountingSource;

pub use memory_residency::MemoryResidencyAccountingStatus;

pub use memory_residency::MemoryResidencyAggregationKind;

pub use memory_residency::MemoryResidencyAggregationRow;

pub use memory_residency::MemoryResidencyCapacitySnapshot;

pub use memory_residency::MemoryResidencyDecision;

pub use memory_residency::MemoryResidencyLiveTaskAction;

pub use memory_residency::MemoryResidencyNoClaimBoundary;

pub use memory_residency::MemoryResidencyPolicy;

pub use memory_residency::MemoryResidencyPolicyInput;

pub use memory_residency::MemoryResidencyProfile;

pub use memory_residency::MemoryResidencyReasonCode;

pub use memory_residency::MemoryResidencyRecordPoolCounters;

pub use memory_residency::MemoryResidencyTier;

pub use memory_residency::MemoryResidencyTierAccountingRow;

pub use memory_residency::ProofPackWarmthTelemetry;

pub use obligation_table::ObligationAbortInfo;

pub use obligation_table::ObligationCommitInfo;

pub use obligation_table::ObligationLeakInfo;

pub use obligation_table::ObligationTable;

pub use panic_isolation::CleanupPhase;

pub use panic_isolation::FinalizerType;

pub use panic_isolation::MetricsProviderPanicExt;

pub use panic_isolation::PanicContext;

pub use panic_isolation::PanicIsolationConfig;

pub use panic_isolation::PanicIsolationResult;

pub use panic_isolation::PanicIsolator;

pub use panic_isolation::PanicLocation;

pub use pool_sizing::POOL_SIZING_SCALE;

pub use pool_sizing::PoolSizingAction;

pub use pool_sizing::PoolSizingBounds;

pub use pool_sizing::PoolSizingCandidateMetrics;

pub use pool_sizing::PoolSizingControllerState;

pub use pool_sizing::PoolSizingDecision;

pub use pool_sizing::PoolSizingEstimator;

pub use pool_sizing::PoolSizingMode;

pub use pool_sizing::PoolSizingObservation;

pub use pool_sizing::PoolSizingPolicy;

pub use pool_sizing::PoolSizingReason;

pub use pool_sizing::PoolSizingRecommendation;

pub use pool_sizing::PoolSizingTarget;

pub use pool_sizing::PoolWorkloadEstimate;

pub use pool_sizing::decide_pool_sizing;

pub use pool_sizing::pool_sizing_candidate_metrics;

pub use pool_sizing::recommend_pool_size;

pub use pool_sizing::square_root_staffing_size;

pub use reactor::BrowserReactor;

pub use reactor::BrowserReactorConfig;

pub use reactor::Event;

pub use reactor::Events;

pub use reactor::Interest;

pub use reactor::LabReactor;

pub use reactor::Reactor;

pub use reactor::Registration;

pub use reactor::Source;

pub use reactor::Token;

pub use region_heap::HeapIndex;

pub use region_heap::HeapRef;

pub use region_heap::HeapStats;

pub use region_heap::RegionHeap;

pub use region_heap::global_alloc_count;

pub use region_table::RegionCreateError;

pub use region_table::RegionTable;

pub use resource_cleanup_verifier::ResourceCleanupConfig;

pub use resource_cleanup_verifier::ResourceCleanupError;

pub use resource_cleanup_verifier::ResourceCleanupStats;

pub use resource_cleanup_verifier::ResourceCleanupVerifier;

pub use resource_cleanup_verifier::ResourceId;

pub use resource_cleanup_verifier::ResourceRecord;

pub use resource_cleanup_verifier::ResourceState;

pub use resource_cleanup_verifier::ResourceType;

pub use scheduler::Scheduler;

pub use sharded_state::ShardGuard;

pub use sharded_state::ShardedConfig;

pub use sharded_state::ShardedObservability;

pub use sharded_state::ShardedState;

pub use slo_policy::FourthWaveRuntimeBridgeDecision;

pub use slo_policy::SloRuntimePolicyBridge;

pub use slo_policy::SloRuntimePolicyBridgeDecision;

pub use slo_policy::SloRuntimePolicyBridgeRequest;

pub use slo_policy::SloRuntimeWorkKind;

pub use spawn_blocking::spawn_blocking;

pub use spawn_blocking::spawn_blocking_io;

pub use state::ManualFinalizerReceipt;

pub use state::ManualFinalizerReceiptError;

pub use state::RuntimeSnapshot;

pub use state::RuntimeState;

pub use state::SpawnError;

pub use state_verifier::ObligationStateTransitions;

pub use state_verifier::RegionStateTransitions;

pub use state_verifier::StateEntityType;

pub use state_verifier::StateTransitionVerifier;

pub use state_verifier::StateVerifierConfig;

pub use state_verifier::StateVerifierStatsSnapshot;

pub use state_verifier::StateViolation;

pub use stored_task::StoredTask;

pub use task_handle::JoinError;

pub use task_handle::TaskHandle;

pub use task_table::TaskTable;

pub use yield_now::yield_now;

Modules

blocking_pool

Blocking pool for executing synchronous operations.

builder

Runtime builder, handles, and configuration.

cache

Artifact cache and memory pressure tracking for the lab runtime.

changepoint

Deterministic online change-point detectors for runtime metric series.

config

Runtime configuration types.

deadline_monitor

Deadline monitoring and warning callbacks.

effects

Two-phase effect system for cancel-safe network operations.

env_config

Environment variable and config file support for RuntimeBuilder.

epoch_gc

Epoch-based garbage collection for structured concurrency cleanup.

epoch_gc_integration

Integration of epoch-based garbage collection with runtime cleanup paths.

epoch_tracker

Runtime Epoch Consistency Tracker

epoch_tracking

Epoch Tracking Data Structures

io_driver

I/O driver that bridges reactor events to task wakers.

io_op

I/O operation obligation handle.

kernel

Proof-carrying decision-plane kernel for runtime controllers. Proof-carrying decision-plane kernel for runtime controllers.

local

Thread-local storage for non-Send local tasks.

memory_residency

Pure opt-in memory-residency recommendation engine. Pure opt-in memory-residency recommendation policy.

metrics

Feature-gated runtime instrumentation counters (timer/sched_yield/park). Lightweight, feature-gated runtime instrumentation counters.

obligation_table

Obligation table for tracked resource obligations.

panic_isolation

Panic isolation framework for structured concurrency runtime.

pool_sizing

Deterministic queueing-theoretic pool sizing substrate.

rch_health

Deterministic RCH worker health and cache-warm admission.

reactor

Reactor abstraction for I/O event multiplexing.

region_heap

Region heap allocator with quiescent reclamation.

region_table

Region table for structured-concurrency ownership data.

resource_cleanup_verifier

Runtime Resource Cleanup Verification Engine

resource_monitor

Resource monitoring and degradation trigger system.

scheduler

Work-stealing scheduler with 3-lane priority support.

sharded_state

Sharded runtime state for reduced contention.

slo_policy

Explicit runtime bridge for SLO policy admission decisions.

spawn_blocking

Async wrapper for blocking pool operations. Async wrapper for blocking pool operations.

spawn_mailbox

Lock-free spawn-request intake decoupled from RuntimeState. Spawn mailbox: lock-free spawn-request intake decoupled from RuntimeState.

state

Global runtime state.

state_verifier

Runtime State Machine Transition Verifier

stored_task

Stored task type for runtime future storage.

task_handle

TaskHandle for awaiting spawned task results.

task_table

Task table for hot-path task operations.

timer

Timer heap for deadline management.

waker

Waker implementation with deduplication.

yield_now

Yield points for cooperative multitasking. Cooperative yielding primitive for the asupersync runtime.