Crate troupe

Troupe provides a high-level toolset for modelling crates with actors. Troupe actors are built on top of async process, like those created from tokio::spawn, and help you model and control the flow of information in and out of them. The main goals of troupe are to provide:

• An easy to conceptualize data flow
• Simple access to concurrently processing of futures within actors
• A model that can be adopted into an existing project all at once or over time
• An ergonomic API devoid of magic

At the core of every actor is an ActorState. These are the building blocks used to model your program with troupe. This state is fully isolated from the rest of your application and can only be reached by attaching a stream of messages. For many actors, a stream is provided by troupe in the form of an mpsc-style tokio channel. All attached streams are managed by a Scheduler. The state can attach new streams, queue futures that yield message, or hand off futures that yield nothing to the scheduler.

Communication to and from an actor is managed by a client. Each actor state defines how its clients should function via the ActorState’s ActorType. Conceptually, every actor is either something that consumes messages, i.e. a Sink, or something to broadcasts messages, i.e. a Stream, or both. An actor that largely receive messages from other parts of our program is a SinkActor, which use SinkClients. An actor that processes messages from a source (for example a Websocket) and then broadcast these messages is a StreamActor, which use StreamClients. If an actor does both of these, it is a JointActor and uses JointClients.

Troupe currently supports three async runtimes: tokio, async-std, and the runtime provided by the browser (via wasm-bindgen-futures). Do note that even if you are using the async-std runtime, client-actor communication is still done via tokio channels.

Modules

• compat
  The compatability layer between async runtimes as well as native vs WASM targets.
• joint
  Actors that both can be sent messages and broadcast messages.
• prelude
  Re-exports of commonly used items.
• sink
  Actors that are only sent messages (either fire-and-forget messages or request-response messages).
• stream
  Actors that broadcast messages.

Structs

• ActorBuilder
  Holds a type that implements ActorState, helps aggregate all data that the actor needs, and then launches the async actor process. When the actor process is launched, a client is returned to the caller. This client’s type depends on the actor’s type.
• OneshotReceiver
  Receives a value from the associated Sender.
• OneshotSender
  Sends a value to the associated Receiver.
• Permanent
  A marker type used in the ActorState. It communicates that the actor should never die. As such, the Scheduler will not provide the actor state a method to shutdown. Also, the Trackers for request-response style messages will implictly unwrap responses from their oneshot channels.
• Scheduler
  The primary bookkeeper for the actor. The state attach stream and queue manage futures that will be managed by the Scheduler. The scheduler also tracks if it is possible that no other message will be yielded for the actor to process. If it finds itself in a state where all streams are closed and there are no queued futures, it will close the actor; otherwise, the deadlocked actor will stay in memory doing nothing.
• Transient
  A marker type used in the ActorState. It communicates that the actor should exist for a non-infinite amount of time. The Scheduler will provide the actor state a method to shutdown. Also, the Trackers for request-response style messages will not implictly unwrap responses from their oneshot channels.

Traits

• ActorState
  The core abstraction of the actor model. An ActorState sits at the heart of every actor. It processes messages, queues futures, and attaches streams in the Scheduler, and it can forward messages. Actors serves two roles. They can act similarly to a Sink where other parts of your application (including other actors) since messages into the actor. They can also act as a Stream that generate messages to be sent throughout your application. This role is denoted by the actor’s ActorType, which informs the ActorBuilder what kind of actor it is working with. For sink-like actors, use the SinkActor type. For stream-like actors, use the StreamActor type. For actors that function as both, use the JointActor type.

Functions

• oneshot_channel
  Creates a new one-shot channel for sending single values across asynchronous tasks.

Attribute Macros

• async_trait