hyperactor/
lib.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! Hyperactor is an actor system intended for managing large scale compute.
10//!
11//! # Actor data model
12//!
13//! Hyperactor is designed to support large scale (millions of nodes)
14//! machine learning workloads where actor topologies communicate through
15//! high fanout multicast messaging.
16//!
17//! Supporting this scale requires us to impose additional structure
18//! at the level of the framework, so that we can efficiently refer to
19//! _meshes_ of actors that implement the same worker runtimes.
20//!
21//! Similarly, Hyperactor must co-schedule actors in order to support
22//! collective communicaton between actors.
23//!
24//! Hyperactor is organized into a hierarchy:
25//!
26//! * Each _proc_ represents a single actor runtime instance, and hosts
27//!   zero or more actors.
28//! * Actors are _spawned_ into procs, and assigned a global name.
29//!   Actors spawned in this way are assigned a local PID (pid) of 0.
30//!   Actors in turn can spawn local actors. These inherit the global pid
31//!   of their parent, but receive a unique pid.
32//!
33//! This scheme confers several benefits:
34//!
35//! * Routing of messages can be performed by prefix. For example, we
36//!   can identify the _proc_ of the actor and send the message to it,
37//!   which can then in turn be routed locally.
38//!
39//! * We can represent meshes of actors in a uniform and compact way.
40//!   This is the basis on which we implement efficient multicasting
41//!   within the system.
42//!
43//!
44//! | Entity    | Identifier                    |
45//! |-----------|-------------------------------|
46//! | Proc      | `addr,proc_name`              |
47//! | Actor     | `addr,proc_name,name[pid]`    |
48
49#![feature(anonymous_lifetime_in_impl_trait)]
50#![feature(assert_matches)]
51#![feature(associated_type_defaults)]
52#![feature(box_patterns)]
53#![feature(btree_cursors)]
54#![feature(error_reporter)]
55#![feature(impl_trait_in_assoc_type)]
56#![feature(never_type)]
57#![feature(panic_update_hook)]
58#![feature(type_alias_impl_trait)]
59#![feature(trait_alias)]
60#![deny(missing_docs)]
61
62pub mod accum;
63pub mod actor;
64pub mod actor_local;
65pub mod channel;
66pub mod checkpoint;
67pub mod config;
68pub mod context;
69pub mod host;
70pub mod id;
71mod init;
72pub mod introspect;
73pub mod mailbox;
74pub mod message;
75pub mod metrics;
76pub mod ordering;
77pub mod panic_handler;
78pub mod port;
79pub mod proc;
80pub mod ref_;
81pub mod reference;
82pub mod remote;
83mod signal_handler;
84mod stdio_redirect;
85pub mod supervision;
86pub mod sync;
87/// Test utilities.
88pub mod testing;
89pub mod time;
90
91#[cfg(fbcode_build)]
92mod meta;
93
94/// Re-exports of external crates used by hyperactor_macros codegen.
95/// This module is not part of the public API and should not be used directly.
96#[doc(hidden)]
97pub mod internal_macro_support {
98    pub use anyhow;
99    pub use async_trait;
100    pub use inventory;
101    pub use opentelemetry;
102    pub use paste::paste;
103    pub use serde_json;
104    pub use tracing;
105    pub use typeuri;
106}
107
108pub use actor::Actor;
109pub use actor::ActorHandle;
110pub use actor::Handler;
111pub use actor::HandlerInfo;
112pub use actor::RemoteHandles;
113pub use actor::RemoteSpawn;
114pub use actor_local::ActorLocal;
115#[doc(inline)]
116pub use hyperactor_macros::Bind;
117#[doc(inline)]
118pub use hyperactor_macros::HandleClient;
119#[doc(inline)]
120pub use hyperactor_macros::Handler;
121#[doc(inline)]
122pub use hyperactor_macros::RefClient;
123#[doc(inline)]
124pub use hyperactor_macros::Unbind;
125#[doc(inline)]
126pub use hyperactor_macros::behavior;
127#[doc(inline)]
128pub use hyperactor_macros::export;
129#[doc(inline)]
130pub use hyperactor_macros::handle;
131#[doc(inline)]
132pub use hyperactor_macros::instrument;
133#[doc(inline)]
134pub use hyperactor_macros::instrument_infallible;
135pub use hyperactor_macros::observe_async;
136pub use hyperactor_macros::observe_result;
137#[doc(inline)]
138pub use hyperactor_macros::uid;
139pub use hyperactor_telemetry::declare_static_counter;
140pub use hyperactor_telemetry::declare_static_gauge;
141pub use hyperactor_telemetry::declare_static_histogram;
142pub use hyperactor_telemetry::declare_static_timer;
143pub use hyperactor_telemetry::key_value;
144pub use hyperactor_telemetry::kv_pairs;
145pub use id::Label;
146pub use id::Uid;
147#[doc(inline)]
148pub use init::initialize;
149#[doc(inline)]
150pub use init::initialize_with_current_runtime;
151#[doc(inline)]
152pub use init::initialize_with_log_prefix;
153pub use mailbox::Data;
154pub use mailbox::Mailbox;
155pub use mailbox::Message;
156pub use mailbox::OncePortHandle;
157pub use mailbox::PortHandle;
158pub use mailbox::RemoteMessage;
159pub use proc::Context;
160pub use proc::Instance;
161pub use proc::InstanceCell;
162pub use proc::Proc;
163pub use proc::WeakProc;
164// Re-exported because `hyperactor_macros::RefClient` generates code referencing `hyperactor::ActorRef`.
165#[doc(hidden)]
166pub use reference::ActorRef;
167pub use remote::Accepts;
168#[doc(inline)]
169pub use signal_handler::SignalCleanupGuard;
170#[doc(inline)]
171pub use signal_handler::SignalDisposition;
172#[doc(inline)]
173pub use signal_handler::query_signal_disposition;
174#[doc(inline)]
175pub use signal_handler::register_signal_cleanup;
176#[doc(inline)]
177pub use signal_handler::register_signal_cleanup_scoped;
178#[doc(inline)]
179pub use signal_handler::sigpipe_disposition;
180#[doc(inline)]
181pub use signal_handler::unregister_signal_cleanup;
182
183mod private {
184    /// Public trait in a private module for sealing traits within this crate:
185    /// [Sealed trait pattern](https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed).
186    pub trait Sealed {}
187
188    // These two implement context capabilities:
189    impl<A: crate::Actor> Sealed for crate::proc::Instance<A> {}
190    impl<A: crate::Actor> Sealed for &crate::proc::Instance<A> {}
191    impl<A: crate::Actor> Sealed for crate::proc::Context<'_, A> {}
192    impl<A: crate::Actor> Sealed for &crate::proc::Context<'_, A> {}
193    impl Sealed for crate::mailbox::Mailbox {}
194    impl Sealed for &crate::mailbox::Mailbox {}
195}
hyperactor/lib.rs

hyperactor/
lib.rs
