Skip to content
DocumentationManage resources and execution
On this page

Page resources

Open Markdownllms.txtView source

Last updated

Manage resources and concurrent work

This recipe processes a bounded upload with structured concurrency, backpressure, cancellation, and deterministic cleanup.

The .one and Rust APIs below are illustrative end-product syntax.

1. Declare resource and execution bounds

One
semantic parcelhub.imports
    domain one.components@1
    operation ImportOrders@1
        accepts OrderArchive
        returns ImportReport
        effect irreversible

        resource temporary_storage max 2GiB
        resource memory max 256MiB
        execution children max 8
        execution queue max 64
        deadline 10m
        cancellation cooperative

Acquisition requirements do not grant filesystem access or select a storage provider.

2. Borrow resources through the operation context

Rust
pub async fn import(ctx: ImportOrders, archive: OrderArchive) -> Result<ImportReport> {
    let scratch = ctx.resources().temporary_storage().acquire().await?;
    let mut scope = ctx.execution().scope();

    for batch in archive.bounded_batches(500)? {
        scope.spawn_bounded(async {
            validate_and_write(batch).await
        }).await?;
    }

    let results = scope.join_all().await?;
    scratch.release().await?;
    ImportReport::from_results(results)
}

Children cannot outlive the scope. Queue saturation applies backpressure instead of creating unbounded tasks.

3. Handle cancellation explicitly

Rust
match scope.join_all().await {
    Ok(results) => commit(results).await,
    Err(ExecutionFault::Cancelled) => {
        scope.cancel_children().await;
        rollback_uncommitted_batches().await
    }
    Err(fault) => reconcile_completed_batches(fault).await,
}

Dropping a handle is not proof that an external effect stopped. Completed writes retain receipts and uncertain writes are reconciled.

4. Test finite capacity

Console
one test --root OrderImport --scenario queue-saturation
one test --root OrderImport --scenario deadline-during-write
one test --root OrderImport --scenario resource-release-after-cancel

Executable evidence

The Execution and Resources atoms own the current checks behind this recipe; the composed .one and Rust above are illustrative end-product syntax. Run the atoms that bound cancellation, deadlines, channels, and cleanup:

Console
cargo test -p one-runtime-cancel -p one-runtime-deadline -p one-runtime-channel
cargo test -p one-lifecycle -p one-resource-tree

The governing contracts are execution and resources and lifecycle, and root-scoped tests and fixtures are where a composed scenario like ImportOrders would be proven.

See execution and resources and lifecycle.