Skip to main content

ProcHandle

hyperactor_mesh::host

Trait ProcHandle 

Source 
pub trait ProcHandle:
    Clone
    + Send
    + Sync
    + 'static {
    type Agent: Actor + Referable;
    type TerminalStatus: Debug + Clone + Send + Sync + 'static;

    // Required methods
    fn proc_addr(&self) -> &ProcAddr;
    fn addr(&self) -> Option<ChannelAddr>;
    fn agent_ref(&self) -> Option<ActorRef<Self::Agent>>;
    fn ready<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<(), ReadyError<Self::TerminalStatus>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn wait<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, WaitError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn terminate<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        cx: &'life1 (impl 'async_trait + Actor),
        timeout: Duration,
        reason: &'life2 str,
    ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, TerminateError<Self::TerminalStatus>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait;
    fn kill<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, TerminateError<Self::TerminalStatus>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
}
Expand description

Minimal uniform surface for a spawned-proc handle returned by a ProcManager. Each manager can return its own concrete handle, as long as it exposes these. A proc is the Hyperactor runtime

  • its actors (lifecycle controlled via Proc APIs such as destroy_and_wait). A proc may be hosted inside an OS process, but it is conceptually distinct:
  • LocalProcManager: runs the proc in this OS process; there is no child process to signal. Lifecycle is entirely proc-level.
  • ProcessProcManager (test-only here): launches an external OS process which hosts the proc, but this toy manager does not wire a control plane for shutdown, nor an exit monitor.

This trait is therefore written in terms of the proc lifecycle:

  • ready() resolves when the proc is Ready (mailbox bound; agent available).
  • wait() resolves with the proc’s terminal status (Stopped/Killed/Failed).
  • terminate() requests a graceful shutdown of the proc and waits up to the deadline; managers that also own a child OS process may escalate to SIGKILL if the proc does not exit in time.
  • kill() requests an immediate, forced termination. For in-process procs, this may be implemented as an immediate drain/abort of actor tasks. For external procs, this is typically a SIGKILL.

The shape of the terminal value is Self::TerminalStatus. Managers that track rich info (exit code, signal, address, agent) can expose it; trivial managers may use ().

Managers that do not support signaling must return Unsupported.

Required Associated Types§

Source

type Agent: Actor + Referable

The agent actor type installed in the proc by the manager. Must implement both:

  • Actor, because the agent actually runs inside the proc, and
  • Referable, so callers can hold ActorRef<Self::Agent>.
Source

type TerminalStatus: Debug + Clone + Send + Sync + 'static

The type of terminal status produced when the proc exits.

For example, an external proc manager may use a rich status enum (e.g. ProcStatus), while an in-process manager may use a trivial unit type. This is the value returned by ProcHandle::wait and carried by ReadyError::Terminal.

Required Methods§

Source

fn proc_addr(&self) -> &ProcAddr

The proc’s logical address on this host.

Source

fn addr(&self) -> Option<ChannelAddr>

The proc’s address (the one callers bind into the host router). May return None before ready() completes. Guaranteed to return Some after ready() succeeds.

Prefer [ready_proc()] for type-safe access that guarantees availability at compile time.

Source

fn agent_ref(&self) -> Option<ActorRef<Self::Agent>>

The agent actor reference hosted in the proc. May return None before ready() completes. Guaranteed to return Some after ready() succeeds.

Prefer [ready_proc()] for type-safe access that guarantees availability at compile time.

Source

fn ready<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), ReadyError<Self::TerminalStatus>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Resolves when the proc becomes Ready. Multi-waiter, non-consuming.

Source

fn wait<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, WaitError>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Resolves with the terminal status (Stopped/Killed/Failed/etc). Multi-waiter, non-consuming.

Source

fn terminate<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, cx: &'life1 (impl 'async_trait + Actor), timeout: Duration, reason: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, TerminateError<Self::TerminalStatus>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Politely stop the proc before the deadline; managers that own a child OS process may escalate to a forced kill at the deadline. Idempotent and race-safe: concurrent callers coalesce; the first terminal outcome wins and all callers observe it via wait().

Returns the single terminal status the proc reached (the same value wait() will return). Never fabricates terminal states: this is only returned after the exit monitor observes termination.

§Parameters
  • cx: The actor context for sending messages.
  • timeout: Grace period before escalation.
  • reason: Human-readable reason for termination.
Source

fn kill<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, TerminateError<Self::TerminalStatus>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Force the proc down immediately. For in-process managers this may abort actor tasks; for external managers this typically sends SIGKILL. Also idempotent/race-safe; the terminal outcome is the one observed by wait().

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§