Crate hyperactor_macros

Defines macros used by the [hyperactor] crate.

Macros

behavior

Create a [Referable] definition, handling a specific set of message types. Behaviors are used to create an [ActorRef] without having to depend on the actor’s implementation. If the message type need to be cast, add castable flag to those types. e.g. the following example creates a behavior with 5 message types, and 4 of which need to be cast.

Attribute Macros

export

Exports handlers for this actor. The set of exported handlers determine the messages that may be sent to remote references of the actor ([hyperaxtor::ActorRef]). Only messages that implement [hyperactor::RemoteMessage] may be exported.

forward

Forward messages of the provided type to this handler implementation.

instrument

Use this macro in place of tracing::instrument to prevent spamming our tracing table. We set a default level of INFO while always setting ERROR if the function returns Result::Err giving us consistent and high quality structured logs. Because this wraps around tracing::instrument, all parameters mentioned in https://fburl.com/9jlkb5q4 should be valid. For functions that don’t return a Result type, use instrument_infallible

instrument_infallible

Use this macro in place of tracing::instrument to prevent spamming our tracing table. Because this wraps around tracing::instrument, all parameters mentioned in https://fburl.com/9jlkb5q4 should be valid.

observe_async

A procedural macro that automatically injects telemetry code into async functions that do not return a Result type.

observe_result

A procedural macro that automatically injects telemetry code into async functions that return a Result type.

Derive Macros

Actor

Derives the Actor trait for a struct. By default, generates an implementation with no params (type Params = () and async fn new(_params: ()) -> Result<Self, anyhow::Error>). This requires that the Actor implements Default.

AttrValue

Derive the [hyperactor::attrs::AttrValue] trait for a struct or enum.

Bind

Derive a custom implementation of [hyperactor::message::Bind] trait for a struct or enum. This macro is normally used in tandem with [fn derive_unbind] to make the applied struct or enum castable.

HandleClient

Derives a client implementation on ActorHandle<Actor>. See Handler documentation for details.

Handler

Derive a custom handler trait for given an enum containing tuple structs. The handler trait defines a method corresponding to each of the enum’s variants, and a handle function that dispatches messages to the correct method. The macro supports two messaging patterns: “call” and “oneway”. A call is a request-response message; a [hyperactor::mailbox::OncePortRef] or [hyperactor::mailbox::OncePortHandle] in the last position is used to send the return value.

Named

Derive the [hyperactor::data::Named] trait for a struct with the provided type URI. The name of the type is its fully-qualified Rust path. The name may be overridden by providing a string value for the name attribute.

RefClient

Derives a client implementation on ActorRef<Actor>. See Handler documentation for details.

Unbind

Derive a custom implementation of [hyperactor::message::Unbind] trait for a struct or enum. This macro is normally used in tandem with [fn derive_bind] to make the applied struct or enum castable.