Browse documentation

Explanation

Concurrency, actors and async Rust

How Septa organizes concurrent work, how it differs from async Rust, and where the two fit together.

Septa provides a model for concurrent programming in its supported Rust profile. Durable actors own state, workflows save progress, and typed effects describe operations the runtime can manage and record.

Async Rust lets computations pause while waiting. Actors organize state and messages. You can build actors with async Rust; Septa adds checked effects, scoped permissions and recovery to the actor model.

Concurrency, parallelism and actors

Concurrency means several operations can make progress over the same period. While one order waits for a payment response, another can check stock. Parallelism means work executes simultaneously, for example on different CPU cores. Concurrent work does not require one thread per operation.

An actor owns state and receives messages. An async task is a computation managed by an executor. A task can implement an actor, but not every task needs an identity, mailbox or long-lived state. Tokio’s spawning guide explains how tasks are scheduled.

For example, Inventory can own reservations while a Checkout workflow coordinates an order. They can live in the same application. Actor boundaries do not require microservices or distributed deployment.

In v1, actors run on a single node. Septa does not automatically distribute them across machines.

What async Rust provides

Calling an async fn creates a future. Its body starts when that future is polled, usually by an executor. If an awaited operation is still pending, the task yields so other work can run. If the result is already ready, .await can continue without yielding. See Rust’s Future reference and Tokio’s explanation of async.

Async syntax alone does not make independent operations concurrent. Assuming these helpers are async functions, this fragment waits for stock before starting the price lookup:

let stock = fetch_stock(sku).await;
let price = fetch_price(sku).await;

Use tokio::join! to run independent lookups concurrently:

let (stock, price) = tokio::join!(
    fetch_stock(sku),
    fetch_price(sku)
);

join! polls both branches within the same task. They can overlap while waiting, but the macro does not put them on separate threads. Separate tasks can be spawned when work needs to be scheduled independently. See Tokio’s join documentation.

These examples use native async Rust, which is outside Septa’s profile. A future can pause and resume within a process. Recovering it after a process restart requires additional persistence and recovery code.

What changes in Septa

Septa code uses ordinary function and method calls. A typed effect call can pause the computation without an .await at the call site. Septa compiles supported source into a form that the runtime can save and resume.

The profile does not accept async fn, .await, Future values, threads or synchronization primitives. Concurrent work uses actors, managed runs and operations that combine effects. Running the same source through Cargo does not provide Septa’s scheduling or durability guarantees.

Both models can represent a computation as a state machine. Septa’s continuation format supports persistence and recovery. An ordinary Rust future may contain borrowed data, sockets or other resources tied to the current process; Septa does not automatically serialize it.

Read effects and handlers for what the compiler tracks and why the runtime owns the continuation.

Actor state while work is waiting

By default, a Septa actor finishes its current message handler before starting the next. This is called non-reentrant handling. Waiting for an external effect keeps that handler active; the answer resumes it. A handler can explicitly receive a matching message while it is open, but other messages stay queued.

Other actors and runs can continue working while this actor waits.

Requests queue behind a slow handler. If Inventory waits for payment before returning, it can delay unrelated reservations. Inventory could instead return a reservation and let a separate workflow coordinate payment, confirmation or release.

That design still needs expiry, failure and compensation rules. Serial handling does not make a multi-actor business operation atomic or eliminate logical races and deadlocks.

Tokio’s channels tutorial shows an actor built from a task that owns a resource and receives typed commands. Septa adds managed state, effect checking and recovery to this programming model.

Running independent effects together

Within a Septa run, ordinary effect calls run one after another. The profile defines composites that combine a bounded group of effects:

Composite Meaning
effect::all Collect every arm’s result, in declaration order.
effect::race Select a winning outcome and record what happens to the other arms.
effect::timeout Race an operation against an explicit clock deadline.

Each branch, called an arm, must be a literal closure containing one effect operation or a supported nested composite. It cannot contain an arbitrary async program. When the number of operations is only known at runtime, use bounded batch operations.

The composite’s outcome is recorded for replay. Whether external operations actually overlap depends on the execution path and supported handlers.

Scheduling and blocking work

Septa’s scheduling contract specifies serial execution within each run. Each ready run gets a slice of work measured in fuel. When that slice is used up, execution yields at the next point where the runtime charges fuel. This describes the scheduling model; it does not establish measured throughput or a hard real-time guarantee.

Native async executors also need work to yield. A long CPU calculation or blocking system call inside a future can delay other tasks. Moving it into an async function does not make it nonblocking. Tokio offers spawn_blocking for blocking work. CPU-heavy workloads still need bounded concurrency or an executor designed for CPU work. Once a blocking task starts, aborting its handle will not stop it.

Code outside Septa’s profile runs in native components, which manage their own scheduling, resource limits and failures. Both models still need bounded queues and rules for handling overload.

Cancellation, failure and recovery

In native async Rust, dropping a future you own stops polling it. Work it started elsewhere may continue. For example, dropping a Tokio JoinHandle detaches the spawned task, leaving it running. See Tokio’s JoinHandle documentation.

Septa records progress and effect outcomes at supported boundaries so work can resume after interruption. Races and timeouts follow the operation’s cancellation and delivery contracts. Some losing work can be asked to stop; other work may finish with its late result discarded.

Neither dropping a future nor timing out a durable operation undoes a payment already accepted by a provider. Retries still need idempotency rules, and uncertain outcomes need reconciliation. Septa accepts only one next revision from each saved revision of a run. That does not guarantee exactly-once external execution. See external effects and durable execution.

Choosing the model

Consideration Native async Rust Septa’s managed model
Language and libraries General Rust and compatible async crates. A constrained profile; crates outside it need native integration.
State ownership Choose shared state, channels, actors or another design. Durable actors provide a standard place for state and message handling.
Interactions Application code and libraries define their access patterns. Compiler-visible effects with runtime authority and delivery contracts.
Recovery Add persistence and recovery through application design or libraries. Supported state, continuations and effect outcomes are part of the runtime model.
Control Direct control over tasks, synchronization and executor choices. More runtime policy, fewer arbitrary control-flow and scheduling choices.
Costs You assemble the operational rules your application needs. Checking, recording and persistence add work; the profile imposes limits.

Use native async Rust when you need its libraries or direct control over tasks. Consider Septa when durable domain operations and workflows are central to the application. Compare complete designs, including persistence and recovery; neither model is always faster or safer.

Using both in one system

A native Rust host can use async libraries for HTTP, connections and SDKs while Septa manages domain state and workflows. The existing Services host handles transport framing and authenticates incoming requests in ordinary Rust. It calls managed operations through the public runtime CLI and ops/v1 JSON.

The host exchanges requests and results with the runtime. It cannot directly .await a Septa function, store arbitrary futures in durable state or import arbitrary async crates into the managed profile. This host integration does not provide a general SDK for writing effect handlers.

Define the request and result types, identify the caller, and decide how the host handles timeouts and uncertain outcomes. Native Rust integration describes the supported approach. The durable actor tutorial shows how to manage state in Septa.

Search concepts, guides and reference.