Expand description
§Orcher Rust SDK
Build durable workflows and tasks for the Orcher workflow engine.
Workflows are async functions whose progress the engine records, so they
survive crashes and restarts and resume where they left off. Tasks are the
steps that touch the outside world, and are retried under a policy when they
fail. A Worker polls the engine and runs both; a Client starts
workflows and reads their results.
§Quick start
use orcher_sdk::prelude::*;
// A worker is I/O-bound, so a single-threaded runtime is enough.
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
let worker = Worker::builder()
.server_url("http://localhost:50051")
.task_queue("my-queue")
.build()
.await?;
worker.run().await
}§Tokio runtime
A worker spends its time waiting on gRPC long-polls, so the single-threaded
runtime (#[tokio::main(flavor = "current_thread")]) is recommended: its
event loop sleeps while it waits, whereas the multi-threaded work-stealing
scheduler keeps its threads busy even when the worker is idle.
Run CPU-heavy work with tokio::task::spawn_blocking(), which uses a
separate thread pool and does not hold up the event loop:
use orcher_sdk::prelude::*;
#[task]
async fn checksum(_ctx: TaskContext, data: Vec<u8>) -> Result<u64> {
let sum = tokio::task::spawn_blocking(move || {
// CPU-intensive work here.
data.iter().map(|&b| u64::from(b)).sum::<u64>()
})
.await
.map_err(|e| Error::Other(e.to_string()))?;
Ok(sum)
}§Modules
workflow: the workflow context and the durable operations it offerstask: the task context, retry policies and task optionsactor: keyed actors with durable stateworker: building and running a workerclient: starting, querying and sending events to workflowserror: the SDK’s error typesprelude: the imports most programs need
Re-exports§
pub use actor::ActorContext;pub use actor::ActorKey;pub use client::Client;pub use error::Error;pub use error::ErrorCode;pub use error::Result;pub use error::Severity;pub use error::TaskFailureCode;pub use payload::PayloadCodec;pub use task::Task;pub use task::TaskContext;pub use worker::HealthReport;pub use worker::HealthStatus;pub use worker::RuntimeStats;pub use worker::Worker;pub use worker::WorkerBuilder;pub use workflow::Workflow;pub use workflow::WorkflowContext;
Modules§
- actor
- Worker-side actor runtime.
- client
- Client for starting and controlling workflows on the ORCHER orchestrator.
- debugging
- Tools for inspecting workflow execution while debugging and testing.
- error
- Error types for the Orcher Rust SDK.
- interceptor
- Interceptor framework for cross-cutting concerns.
- payload
- Converting values to and from
Payloads. - prelude
- The imports most programs need.
- task
- Tasks: the units of work a workflow schedules.
- testing
- Testing utilities for Orcher workflows.
- worker
- Workers: processes that poll the orchestrator and run workflows and tasks.
- workflow
- Workflow APIs for defining and executing durable workflows.
Macros§
- initialize_
handlers - Calls the crate’s generated
__orcher_force_registration()function.
Structs§
- List
Workflows Options - Filter, sort, and pagination options for listing workflows.
- Method
Stats - A worker’s wire measurements; see
Worker::wire_metrics. What one RPC method has done, asWireMetrics::snapshotreports it. - Namespace
- A namespace, as the namespace calls on
Clientreturn it. A namespace, as the engine reports it. - Payload
- Serialized data together with metadata describing its encoding.
- Search
Workflows Options - Pagination options for searching workflows.
- Wire
Metrics Snapshot - A worker’s wire measurements; see
Worker::wire_metrics. A copy of a worker’s wire measurements at one moment. - Work
Stats - A worker’s wire measurements; see
Worker::wire_metrics. The work a worker has handed to its language and reported back, asWireMetrics::snapshotreports it. - Workflow
Execution Description - Detailed description of a workflow execution.
- Workflow
Execution Info - Summary of a workflow execution, as returned in list and search results.
- Workflow
List Page - One page of workflow execution summaries.
Enums§
- List
Workflows Sort Order - Sort order for listing workflows.
- Workflow
Status - Status of a workflow execution.
Constants§
Attribute Macros§
- actor
- Marks a struct as a stateful actor type.
- event
- Declares an event: an asynchronous message sent to a running workflow to trigger an action or a state change. The sender does not wait for a result.
- operations
- Defines the operations of an actor on its impl block.
- query
- Declares a query: a read of a running workflow’s state that does not affect its execution.
- task
- Turns an
async fninto a task that workers can run. - tasks
- Defines a group of tasks as methods on an impl block.
- update
- Turns an
async fninto an update handler for a running workflow. - workflow
- Turns an
async fninto a workflow definition.
Derive Macros§
- Payload
- Derives JSON payload conversion methods for a type.