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//! _gangs_ of actors that implement the same worker runtimes.
20//!
21//! Similarly, Hyperactor must gang-schedule actors in order to support
22//! collective communicaton between actors.
23//!
24//! Hyperactor is organized into a hierarchy, wherein parents manage
25//! the lifecycle of their children:
26//!
27//! * Each _world_ represents a fixed number of _procs_, scheduled as
28//!   a gang.
29//! * Each _proc_ represents a single actor runtime instance, and hosts
30//!   zero or more actors.
31//! * Actors are _spawned_ into worlds, and assigned a global name.
32//!   Actors spawned in this way are assigned a local PID (pid) of 0.
33//!   Actors in turn can spawn local actors. These inherit the global pid
34//!   of their parent, but receive a unique pid.
35//!
36//! Actors that share a name within a world are called a _gang_.
37//!
38//! This scheme confers several benefits:
39//!
40//! * Routing of messages can be performed by prefix. For example, we
41//!   can route a message to an actor based on the world the actor belongs
42//!   to; from there, we can identify the _proc_ of the actor and send
43//!   the message to it, which can then in turn be routed locally.
44//!
45//! * We can represent gangs of actors in a uniform and compact way.
46//!   This is the basis on which we implement efficient multicasting
47//!   within the system.
48//!
49//!
50//! | Entity    | Identifier                |
51//! |-----------|---------------------------|
52//! | World     | `worldid`                 |
53//! | Proc      | `worldid[rank]`           |
54//! | Actor     | `worldid[rank].name[pid]` |
55//! | Gang      | `worldid.name`            |
56
57#![feature(anonymous_lifetime_in_impl_trait)]
58#![feature(assert_matches)]
59#![feature(associated_type_defaults)]
60#![feature(box_patterns)]
61#![feature(btree_cursors)]
62#![feature(const_type_id)]
63#![feature(error_reporter)]
64#![feature(impl_trait_in_assoc_type)]
65#![feature(never_type)]
66#![feature(panic_update_hook)]
67#![feature(type_alias_impl_trait)]
68#![feature(trait_alias)]
69#![feature(panic_payload_as_str)]
70#![deny(missing_docs)]
71
72pub mod accum;
73pub mod actor;
74pub mod attrs;
75pub mod channel;
76pub mod checkpoint;
77pub mod clock;
78pub mod config;
79pub mod context;
80pub mod data;
81pub mod host;
82mod init;
83pub mod mailbox;
84pub mod message;
85pub mod metrics;
86mod ordering;
87pub mod panic_handler;
88pub mod proc;
89pub mod reference;
90mod signal_handler;
91pub mod simnet;
92mod stdio_redirect;
93pub mod supervision;
94pub mod sync;
95/// Test utilities
96pub mod test_utils;
97pub mod time;
98
99pub use actor::Actor;
100pub use actor::ActorHandle;
101pub use actor::Handler;
102pub use actor::RemoteHandles;
103// Re-export public dependencies of hyperactor_macros codegen.
104#[doc(hidden)]
105pub use anyhow;
106#[doc(hidden)]
107pub use async_trait;
108pub use attrs::AttrValue;
109// Re-exported to use in Named derive macro.
110#[doc(hidden)]
111pub use cityhasher;
112#[doc(hidden)]
113pub use dashmap; // For intern_typename!
114pub use data::Named;
115#[doc(hidden)]
116pub use hyperactor_macros::Actor;
117#[doc(inline)]
118pub use hyperactor_macros::AttrValue;
119#[doc(inline)]
120pub use hyperactor_macros::Bind;
121#[doc(inline)]
122pub use hyperactor_macros::HandleClient;
123#[doc(inline)]
124pub use hyperactor_macros::Handler;
125#[doc(inline)]
126pub use hyperactor_macros::Named;
127#[doc(inline)]
128pub use hyperactor_macros::RefClient;
129#[doc(inline)]
130pub use hyperactor_macros::Unbind;
131#[doc(inline)]
132pub use hyperactor_macros::behavior;
133#[doc(inline)]
134pub use hyperactor_macros::export;
135#[doc(inline)]
136pub use hyperactor_macros::forward;
137#[doc(inline)]
138pub use hyperactor_macros::instrument;
139#[doc(inline)]
140pub use hyperactor_macros::instrument_infallible;
141pub use hyperactor_macros::observe_async;
142pub use hyperactor_macros::observe_result;
143pub use hyperactor_telemetry::declare_static_counter;
144pub use hyperactor_telemetry::declare_static_gauge;
145pub use hyperactor_telemetry::declare_static_histogram;
146pub use hyperactor_telemetry::declare_static_timer;
147pub use hyperactor_telemetry::key_value;
148pub use hyperactor_telemetry::kv_pairs;
149#[doc(inline)]
150pub use init::initialize;
151#[doc(inline)]
152pub use init::initialize_with_current_runtime;
153#[doc(inline)]
154pub use init::initialize_with_log_prefix;
155// Re-exported to make this available to callers of the `register!` macro.
156#[doc(hidden)]
157pub use inventory::submit;
158pub use mailbox::Data;
159pub use mailbox::Mailbox;
160pub use mailbox::Message;
161pub use mailbox::OncePortHandle;
162pub use mailbox::PortHandle;
163pub use mailbox::RemoteMessage;
164// Re-exported to support opentelemetry in hyperactor_macros codegen.
165#[doc(hidden)]
166pub use opentelemetry;
167#[doc(hidden)]
168pub use paste::paste;
169pub use proc::Context;
170pub use proc::Instance;
171pub use proc::Proc;
172pub use reference::ActorId;
173pub use reference::ActorRef;
174pub use reference::GangId;
175pub use reference::GangRef;
176pub use reference::OncePortRef;
177pub use reference::PortId;
178pub use reference::PortRef;
179pub use reference::ProcId;
180pub use reference::WorldId;
181// Re-exported to support tracing in hyperactor_macros codegen.
182#[doc(hidden)]
183pub use serde_json;
184#[doc(inline)]
185pub use signal_handler::SignalCleanupGuard;
186#[doc(inline)]
187pub use signal_handler::SignalDisposition;
188#[doc(inline)]
189pub use signal_handler::query_signal_disposition;
190#[doc(inline)]
191pub use signal_handler::register_signal_cleanup;
192#[doc(inline)]
193pub use signal_handler::register_signal_cleanup_scoped;
194#[doc(inline)]
195pub use signal_handler::sigpipe_disposition;
196#[doc(inline)]
197pub use signal_handler::unregister_signal_cleanup;
198// Re-exported to support tracing in hyperactor_macros codegen.
199#[doc(hidden)]
200pub use tracing;
201
202mod private {
203    /// Public trait in a private module for sealing traits within this crate:
204    /// [Sealed trait pattern](https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed).
205    pub trait Sealed {}
206
207    // These two implement context capabilities:
208    impl<A: crate::Actor> Sealed for crate::proc::Instance<A> {}
209    impl<A: crate::Actor> Sealed for &crate::proc::Instance<A> {}
210    impl<A: crate::Actor> Sealed for crate::proc::Context<'_, A> {}
211    impl<A: crate::Actor> Sealed for &crate::proc::Context<'_, A> {}
212    impl Sealed for crate::mailbox::Mailbox {}
213    impl Sealed for &crate::mailbox::Mailbox {}
214}
hyperactor/lib.rs

hyperactor/
lib.rs
