Crate oxide_update_engine 

An engine for declaring and executing sequential update steps with serializable event streams.

The oxide-update-engine crate provides the execution engine for running update steps.

• For types-only consumers (e.g. API clients), see oxide-update-engine-types.
• For code to display update engine events as a human-readable stream, see oxide-update-engine-display.

Examples

A minimal engine that runs a single update step:

use oxide_update_engine::{
    StepSuccess, UpdateEngine, channel,
};
use oxide_update_engine::types::spec::EngineSpec;

// A EngineSpec defines the domain-specific types that flow
// through the engine. Use () for metadata you don't need.
enum MySpec {}
impl EngineSpec for MySpec {
    fn spec_name() -> String {
        "example".into()
    }
    type Component = String;
    type StepId = usize;
    type StepMetadata = ();
    type ProgressMetadata = ();
    type CompletionMetadata = ();
    type SkippedMetadata = ();
    type Error = anyhow::Error;
}

let log =
    slog::Logger::root(slog::Discard, slog::o!());
let (sender, _receiver) = channel::<MySpec>();
let engine = UpdateEngine::new(&log, sender);

// Steps run sequentially in registration order.
engine
    .new_step(
        "fw".to_owned(),
        1,
        "Write firmware image",
        |_cx| async {
            // ... perform update work here ...
            StepSuccess::new(()).into()
        },
    )
    .register();

engine.execute().await?;

For more complex engines, including engines that have nested local and remote steps, see the full example.

Re-exports

pub use oxide_update_engine_types as types;

Macros

define_update_engine

Defines type aliases for engine-crate types parameterized by a particular EngineSpec.

Structs

AbortHandle

An abort handle, used to forcibly cancel update engine executions.

AbortWaiter

A future which can be used to optionally block until an abort message is processed.

CompletionContext

Context returned by a successful UpdateEngine::execute.

ComponentRegistrar

Provides component context against which a step can be registered.

ExecutionHandle

A join handle for an UpdateEngine.

MetadataContext

Context for a step’s metadata-generation function.

NewStep

A new step that hasn’t been registered by an execution engine yet.

SharedStepHandle

A shared version of StepHandle.

StepContext

Context for a step’s execution function.

StepHandle

A way to obtain a step’s result.

StepHandleToken

A token to retrieve the value within a StepHandle.

StepResult

The result of a step.

StepSkipped

StepSuccess

A success result produced by a step.

StepWarning

UpdateEngine

Enums

ExecutionError

An error that occurs while the engine is being executed.

Functions

channel

Creates an MPSC channel suitable to be passed into the update engine.