hyperactor::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_id(&self) -> &ProcId;
    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, 'async_trait>(
        &'life0 self,
        timeout: Duration,
    ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, TerminateError<Self::TerminalStatus>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: '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_id(&self) -> &ProcId

The proc’s logical identity on this host.

Source

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

The proc’s address (the one callers bind into the host router).

Source

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

The agent actor reference hosted in the proc.

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, 'async_trait>( &'life0 self, timeout: Duration, ) -> Pin<Box<dyn Future<Output = Result<Self::TerminalStatus, TerminateError<Self::TerminalStatus>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: '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.

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", so this trait is not object safe.

Implementors§