1 unstable release

0.1.1 Apr 23, 2021

#1936 in Asynchronous


Used in scylla-rs

Custom license

410KB
928 lines


A framework for building data-driven distributed systems

Developer documentation portal

Discord StackExchange Apache 2.0 license

AboutPrerequisitesGetting startedSupporting the projectJoining the discussionFuture workLICENSE


About

Backstage is an actor-model framework which seeks to make distributed and fair processing simple. Actors can be defined as individual modules and be combined to form fully-fledged applications. For examples, see scylla.rs and chronicle.rs, which are built using Backstage.

NOTE: Backstage is currently under heavy development to improve its usability. It is not yet recommended to use in production environments as breaking changes will be frequent in the near future.

Prerequisites

Actors are best used across multiple parallel processing units, thus it is recommended that applications built with Backstage are run on machines with multiple cores.

Getting started

Actors are defined by four Subtraits: Name, Init, EventLoop, Terminating. With the exception of Name, these act like lifetime hooks. Each can fail and return a Need, which indicate how the actor's supervisor should handle the failure.

An actor's supervisor is simply another actor which has been defined to manage it. This can include spawning, aborting, and interop. Communication occurs via the supervisor handle provided in each of the lifetime trait functions. This handle can be anything, but safe communication across threads is usually performed via message channels.

In order to define an application comprised of various actors, Backstage provides a launcher! macro:

launcher!(builder: AppsBuilder {[] -> HelloWorld: HelloWorldBuilder, [] -> Howdy: HowdyBuilder}, state: Apps {});

This macro consumes a builder and state (a data struct used by the builder to construct the launcher) and defines a struct which holds that data. By implementing Builder for this struct you can define how the launcher actor builds each of its dependencies. Then, to start the launcher, invoke the builder:

// Create the launcher `Apps` by invoking `AppsBuilder::build()`
let apps = AppsBuilder::new().build();
// Start the launcher
apps.HelloWorld().await.Howdy().await.start(None).await;

Supporting the project

If you want to contribute to Backstage, consider posting a bug report, feature request or a pull request.

Please read the following before contributing:

Joining the discussion

If you want to get involved in the community, need help with getting set up, have any issues related to Backstage, or just want to discuss IOTA, Distributed Registry Technology (DRT) and IoT with other people, feel free to join our Discord.

Future work

  • Simplify actor creation using proc macros
  • Unify Actor traits into one
  • Remove launcher! macro and replace it with something more simple and reliable
  • Add more examples and documentation
  • Add unit tests

LICENSE

(c) 2021 - IOTA Stiftung

IOTA Backstage is distributed under the Apache License (Version 2.0).

Dependencies

~3–9MB
~83K SLoC