[][src]Crate bastion

Bastion: Fault-tolerant Runtime for Rust applications

Bastion is a highly-available, fault-tolerant runtime system with dynamic dispatch oriented lightweight process model. It supplies actor model like concurrency with primitives called lightproc and utilize all the system resources efficiently with at-most-once message delivery guarantee.

To have a quick start please head to: Bastion System Documentation.

Features

  • Message-based communication makes this project a lean mesh of actor system.
    • Without web servers, weird shenanigans, forced trait implementations, and static dispatch.
  • Runtime fault-tolerance makes it a good candidate for distributed systems.
    • If you want the smell of Erlang and the powerful aspects of Rust. That's it!
  • Completely asynchronous runtime with NUMA-aware and cache-affine SMP executor.
    • Exploiting hardware locality wherever it is possible. It is designed for servers.
  • Supervision system makes it easy to manage lifecycles.
    • Kill your application in certain condition or restart you subprocesses whenever a certain condition is met.
  • Automatic member discovery, cluster formation and custom message passing between cluster members.
    • Using zeroconf or not, launch your bastion cluster from everywhere, with a single actor block.
  • Proactive IO system which doesn't depend on anything other than futures.
    • Bastion's proactive IO has scatter/gather operations, io_uring support and much more...

Guarantees

  • At most once delivery for all the messages.
  • Completely asynchronous system design.
  • Asynchronous program boundaries with fort.
  • Dynamic supervision of supervisors (adding a subtree later during the execution)
  • Lifecycle management both at futures and lightproc layers.
  • Faster middleware development.
  • Above all "fault-tolerance".

Why Bastion?

If one of the questions below is answered with yes, then Bastion is just for you:

  • Do I want proactive IO?
  • Do I need fault-tolerance in my project?
  • Do I need to write resilient middleware/s?
  • I shouldn't need a webserver to run an actor system, right?
  • Do I want to make my existing code unbreakable?
  • Do I need an executor which is using system resources efficiently?
  • Do I have some trust issues with orchestration systems?
  • Do I want to implement my own application lifecycle?

Modules

child_ref

Allows users to communicate with Child through the mailboxes.

children

Children are a group of child supervised under a supervisor

children_ref

Allows users to communicate with children through the mailboxes.

context

A context allows a child's future to access its received messages, parent and supervisor.

dispatcher

Special module that allows users to interact and communicate with a group of actors through the dispatchers that holds information about actors grouped together.

distributeddistributed

Cluster formation and distributed actor instantiation

envelope

A envelope wraps messages and signs them to help user identify message senders and instruct Bastion how to send messages back to them

errors

Describes the error types that may happen within bastion. Given Bastion has a let it crash strategy, most error aren't noticeable. A ReceiveError may however be raised when calling try_recv() or try_recv_timeout() More errors may happen in the future.

executor

A module that exposes the functions used under the hoods from bastions macros: spawn!, run! and blocking!.

io

IO subsystem for Bastion

message

Dynamic dispatch oriented messaging system

path

A path represents a message sender's semantics and later will be used to route messages to them

prelude

Prelude of Bastion

resizer

Special kind of structs for resizable actor groups in runtime.

supervisor

Supervisors enable users to supervise a subtree of children or other supervisor trees under themselves.

Macros

answer

Answers to a given message, with the given answer.

blocking

Spawns a blocking task, which will run on the blocking thread pool, and returns the handle.

children

This macro creates a new children group with the given amount of worker callbacks, and a closure that will be executed when a message is received.

msg

Matches a Msg (as returned by BastionContext::recv or BastionContext::try_recv) with different types.

run

This macro blocks the current thread until passed future is resolved with an output (including the panic).

spawn

Spawn a given future onto the executor from the global level.

supervisor

This macro creates a new supervisor with the given strategy and the given callbacks. Children can be specified by using the children / child macro. You can provide as many children groups as you want. Supervised supervisors are currently not yet supported.

Structs

Bastion

A struct allowing to access the system's API to initialize it, start, stop and kill it and to create new supervisors and top-level children groups.

Callbacks

A set of methods that will get called at different states of a Supervisor or Children life.

Config

The configuration that should be used to initialize the system using Bastion::init_with.