start

Module: start

Contents

Structs

• ComponentHandle - Observational identity, process ID, and ready endpoint for one component.
• RunningStack - An in-process stack whose component child handles are owned by the caller.
• StackHandle - Informational handle returned once the stack is ready.

Functions

• spawn_stack_from_plan - Spawn the stack and wait for readiness without blocking on supervision.
• start_detached - Launch a generation-bound supervisor that becomes the component owner.
• start_foreground_from_plan - Start a caller-described stack in the foreground.

---

firma_process_orchestrator::start::ComponentHandle

Struct

Observational identity, process ID, and ready endpoint for one component.

This value grants no authority to signal or collect the process.

Methods:

• fn name(self: &Self) -> &str - Return the component’s topology identity.
• fn leader_pid(self: &Self) -> UserProcessId - Return the leader process ID observed at startup.
• fn endpoint(self: &Self) -> &ComponentEndpoint - Return the endpoint that passed readiness and canonical publication.

Traits: Eq

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &ComponentHandle) -> bool
• Clone
  • fn clone(self: &Self) -> ComponentHandle

firma_process_orchestrator::start::RunningStack

Struct

An in-process stack whose component child handles are owned by the caller.

Call [RunningStack::shutdown] for an orderly teardown. Successful shutdown consumes the [OwnedStack], so repeated calls are no-ops. Call [RunningStack::detach] to leave processes running under a background child collector. Dropping an owned stack fails closed by hard-terminating its process scopes and retaining runtime state for a later cleanup attempt. See the crate-level lifecycle model for the capabilities transferred by each transition.

Methods:

• fn handle(self: &Self) -> &StackHandle - Borrow the informational handle, including ready endpoints.
• fn shutdown(self: & mut Self, timeout: Duration) -> Result<StopOutcome, ShutdownError> - Stop the stack and collect its child processes.
• fn detach(self: & mut Self) -> Result<(), OrchestratorError> - Leave the stack running while transferring direct-child collection.

Trait Implementations:

• Drop
  • fn drop(self: & mut Self)

firma_process_orchestrator::start::StackHandle

Struct

Informational handle returned once the stack is ready.

The handle does not own the children’s lifecycle. [RunningStack] holds in-process ownership; persisted runtime state supports external observation through [crate::status::status_components()] and retryable teardown through [crate::stop::stop_components()]. See the crate-level lifecycle model for its place in foreground and detached operation.

Methods:

• fn components(self: &Self) -> impl Trait - Iterate over ready components in topology and startup order.
• fn component(self: &Self, name: &str) -> Option<&ComponentHandle> - Look up a ready component by its topology identity.

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> StackHandle

firma_process_orchestrator::start::spawn_stack_from_plan

Function

Spawn the stack and wait for readiness without blocking on supervision.

Returns ownership of the component child handles once every component is listening. topology defines startup order and runtime-state identity; build_component receives an aligned [ComponentPlanContext] immediately before each component’s spawn, in topology order. Its prior endpoints have already passed publication validation, probing, and canonical publication. Planning begins after the lock is claimed and the generation startup-report directory is created, so an already-running stack is reported before the caller’s (possibly failing) resolution runs. Commands are spawned unchanged except for the documented lifecycle process settings on [ComponentSpec]. The caller chooses an ownership transition on the returned stack: [RunningStack::shutdown] tears it down, [RunningStack::detach] explicitly leaves it running under the persistent collector, and [Drop] is a fail-closed emergency termination path. See the crate-level lifecycle model.

Used by wrappers that need in-process ownership after readiness.

Errors

Returns state-directory, lock, plan-resolution, spawn, or readiness errors. On failure after children have been spawned, this function tears them down. Runtime state is retained when target disappearance cannot be confirmed so callers can retry cleanup.

fn spawn_stack_from_plan<E, impl FnMut(ComponentPlanContext<'_>) -> Result<ComponentSpec, E>>(topology: &crate::StackTopology, build_component: impl Trait, state_dir: &std::path::Path, timeouts: crate::LifecycleTimeouts) -> Result<RunningStack, crate::error::StartError<E>>

firma_process_orchestrator::start::start_detached

Function

Launch a generation-bound supervisor that becomes the component owner.

The handoff protocol is defined by [LauncherAttachmentState]. The launcher retains the supervisor child handle through both phases and uses [rollback_detached_start] on any failure before collection transfer. The caller constructs the complete supervisor command from the allocated generation. The orchestrator adds detached-process settings and log redirection, but assigns no command-line protocol to the child. timeouts applies to the handoff and failed-handoff rollback; callers must separately pass the same policy to the supervisor process they construct.

Errors

Returns state-directory, supervisor spawn, attachment, handle reconstruction, collection-transfer, or rollback errors.

fn start_detached<impl FnOnce(StackGeneration) -> Command>(topology: &crate::StackTopology, state_dir: &std::path::Path, timeouts: crate::LifecycleTimeouts, build_supervisor: impl Trait) -> Result<StackHandle, crate::error::OrchestratorError>

firma_process_orchestrator::start::start_foreground_from_plan

Function

Start a caller-described stack in the foreground.

The plan is resolved only after the topology’s runtime-state lock is claimed. timeouts bounds component readiness and graceful shutdown.

Errors

Returns state directory, plan-resolution, spawn, readiness, or detach errors. On failure after children have been spawned, this function tears them down. Runtime state is retained when hard termination fails so callers can retry cleanup.

fn start_foreground_from_plan<E, impl FnMut(ComponentPlanContext<'_>) -> Result<ComponentSpec, E>>(topology: &crate::StackTopology, build_component: impl Trait, state_dir: &std::path::Path, timeouts: crate::LifecycleTimeouts) -> Result<StackHandle, crate::error::StartError<E>>