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(associated_type_defaults)]
51#![feature(box_patterns)]
52#![feature(btree_cursors)]
53#![feature(error_reporter)]
54#![feature(exact_size_is_empty)]
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 addr;
66pub mod channel;
67pub mod client;
68pub mod config;
69pub mod context;
70pub mod endpoint;
71pub mod environment;
72/// Gateway management for proc connectivity.
73pub mod gateway;
74pub mod id;
75mod init;
76pub mod introspect;
77pub mod mailbox;
78pub mod message;
79pub mod metrics;
80pub mod monitor;
81pub mod ordering;
82pub mod panic_handler;
83mod parse;
84pub mod port;
85pub mod proc;
86pub mod ref_;
87pub mod remote;
88pub mod runtime_identity;
89pub(crate) mod sequenced;
90mod signal_handler;
91mod stdio_redirect;
92pub mod subject;
93pub mod supervision;
94pub mod sync;
95/// Test utilities.
96pub mod testing;
97pub mod time;
98pub mod value_mesh;
99
100#[cfg(fbcode_build)]
101pub mod meta;
102
103/// Re-exports of external crates used by hyperactor_macros codegen.
104/// This module is not part of the public API and should not be used directly.
105#[doc(hidden)]
106pub mod internal_macro_support {
107    pub use anyhow;
108    pub use async_trait;
109    pub use inventory;
110    pub use opentelemetry;
111    pub use paste::paste;
112    pub use serde_json;
113    pub use tracing;
114    pub use typeuri;
115}
116
117pub use actor::Actor;
118pub use actor::ActorGuard;
119pub use actor::ActorHandle;
120pub use actor::AnyActorGuard;
121pub use actor::AnyActorHandle;
122pub use actor::Handler;
123pub use actor::HandlerInfo;
124pub use actor::MessageStatusReporting;
125pub use actor::RemoteHandles;
126pub use actor::RemoteSpawn;
127pub use actor_local::ActorLocal;
128pub use addr::ActorAddr;
129pub use addr::Addr;
130pub use addr::AddrParseError;
131pub use addr::Location;
132pub use addr::PortAddr;
133pub use addr::ProcAddr;
134pub use client::Client;
135pub use endpoint::Endpoint;
136pub use endpoint::EndpointLocation;
137pub use endpoint::RemoteEndpoint;
138pub use environment::ActorEnvironment;
139pub use environment::ActorEnvironmentError;
140pub use gateway::Gateway;
141#[doc(inline)]
142pub use hyperactor_macros::HandleClient;
143#[doc(inline)]
144pub use hyperactor_macros::Handler;
145#[doc(inline)]
146pub use hyperactor_macros::RefClient;
147#[doc(inline)]
148pub use hyperactor_macros::behavior;
149#[doc(inline)]
150pub use hyperactor_macros::export;
151#[doc(inline)]
152pub use hyperactor_macros::handle;
153#[doc(inline)]
154pub use hyperactor_macros::instrument;
155#[doc(inline)]
156pub use hyperactor_macros::instrument_infallible;
157pub use hyperactor_macros::observe_async;
158pub use hyperactor_macros::observe_result;
159#[doc(inline)]
160pub use hyperactor_macros::spawnable;
161#[doc(inline)]
162pub use hyperactor_macros::uid;
163pub use hyperactor_telemetry::declare_static_counter;
164pub use hyperactor_telemetry::declare_static_gauge;
165pub use hyperactor_telemetry::declare_static_histogram;
166pub use hyperactor_telemetry::declare_static_timer;
167pub use hyperactor_telemetry::key_value;
168pub use hyperactor_telemetry::kv_pairs;
169pub use id::ActorId;
170pub use id::Id;
171pub use id::Label;
172pub use id::PortId;
173pub use id::ProcId;
174pub use id::Uid;
175#[doc(inline)]
176pub use init::initialize;
177#[doc(inline)]
178pub use init::initialize_with_current_runtime;
179#[doc(inline)]
180pub use init::initialize_with_log_prefix;
181pub use mailbox::Data;
182pub use mailbox::IdleFlushPortHandle;
183pub use mailbox::Mailbox;
184pub use mailbox::MailboxError;
185pub use mailbox::Message;
186pub use mailbox::OncePortHandle;
187pub use mailbox::PortHandle;
188pub use mailbox::PortReceiver;
189pub use mailbox::RemoteMessage;
190pub use monitor::ActorMonitor;
191pub use monitor::ActorSupervisor;
192pub use monitor::EndpointId;
193pub use monitor::MonitorFailure;
194pub use monitor::MonitorStatus;
195pub use monitor::MonitorableEndpoint;
196pub use monitor::SyntheticSupervision;
197pub use port::ControlPort;
198pub use port::Port;
199pub use proc::Context;
200pub use proc::Instance;
201pub use proc::InstanceCell;
202pub use proc::Proc;
203pub use proc::StatusMessage;
204pub use proc::WeakProc;
205pub use ref_::ActorRef;
206pub use ref_::IdleFlushPortRef;
207#[doc(hidden)]
208pub use ref_::IdleFlushPortRefRepr;
209pub use ref_::OncePortRef;
210#[doc(hidden)]
211pub use ref_::OncePortRefRepr;
212pub use ref_::PortRef;
213#[doc(hidden)]
214pub use ref_::PortRefRepr;
215pub use remote::Accepts;
216/// Rank or position index used by distributed mesh helpers.
217pub type Index = usize;
218#[doc(inline)]
219pub use signal_handler::SignalCleanupGuard;
220#[doc(inline)]
221pub use signal_handler::SignalDisposition;
222#[doc(inline)]
223pub use signal_handler::query_signal_disposition;
224#[doc(inline)]
225pub use signal_handler::register_signal_cleanup;
226#[doc(inline)]
227pub use signal_handler::register_signal_cleanup_scoped;
228#[doc(inline)]
229pub use signal_handler::sigpipe_disposition;
230#[doc(inline)]
231pub use signal_handler::unregister_signal_cleanup;
232
233/// Serve the current gateway on the provided channel address.
234pub fn serve(
235    addr: channel::ChannelAddr,
236) -> Result<gateway::GatewayServeHandle, channel::ChannelError> {
237    Gateway::current().serve(addr)
238}
239
240/// Spawn a root actor with a fresh uid labeled from the actor type on the current proc.
241pub fn spawn<A: Actor>(actor: A) -> ActorHandle<A> {
242    Proc::current().spawn(actor)
243}
244
245/// Spawn a root actor with a fresh uid carrying a display label on the current proc.
246pub fn spawn_with_label<A: Actor>(label: &str, actor: A) -> ActorHandle<A> {
247    Proc::current().spawn_with_label(label, actor)
248}
249
250/// Spawn a root actor using an explicit uid on the current proc.
251pub fn spawn_with_uid<A: Actor>(uid: Uid, actor: A) -> anyhow::Result<ActorHandle<A>> {
252    Proc::current().spawn_with_uid(uid, actor)
253}
254
255/// Create a client actor on the current proc.
256pub fn client(label: &str) -> Client {
257    Proc::current().client(label)
258}
259
260mod private {
261    /// Public trait in a private module for sealing traits within this crate:
262    /// [Sealed trait pattern](https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed).
263    pub trait Sealed {}
264
265    // These two implement context capabilities:
266    impl<A: crate::Actor> Sealed for crate::proc::Instance<A> {}
267    impl<A: crate::Actor> Sealed for &crate::proc::Instance<A> {}
268    impl<A: crate::Actor> Sealed for crate::proc::Context<'_, A> {}
269    impl<A: crate::Actor> Sealed for &crate::proc::Context<'_, A> {}
270    impl Sealed for crate::client::Client {}
271    impl Sealed for &crate::client::Client {}
272    impl Sealed for crate::mailbox::Mailbox {}
273    impl Sealed for &crate::mailbox::Mailbox {}
274    impl<A: crate::Actor> Sealed for &crate::actor::ActorHandle<A> {}
275    impl<M: crate::Message> Sealed for &crate::mailbox::PortHandle<M> {}
276    impl<M: crate::Message> Sealed for crate::mailbox::OncePortHandle<M> {}
277    impl<A: crate::actor::Referable> Sealed for &crate::ref_::ActorRef<A> {}
278    impl<M: crate::RemoteMessage> Sealed for &crate::ref_::IdleFlushPortRef<M> {}
279    impl<M: crate::RemoteMessage> Sealed for &crate::ref_::PortRef<M> {}
280    impl<M: crate::RemoteMessage> Sealed for crate::ref_::OncePortRef<M> {}
281}
hyperactor/lib.rs

hyperactor/
lib.rs
