Struct bastion::Bastion [−][src]
pub struct Bastion { /* fields omitted */ }
Expand description
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.
Example
use bastion::prelude::*;
fn run() {
/// Creating the system's configuration...
let config = Config::new().hide_backtraces();
// ...and initializing the system with it (this is required)...
Bastion::init_with(config);
// Note that `Bastion::init();` would work too and initialize
// the system with the default config.
// Starting the system...
Bastion::start();
// Creating a new supervisor...
let supervisor = Bastion::supervisor(|sp| {
sp
// ...with a specific supervision strategy...
.with_strategy(SupervisionStrategy::OneForAll)
// ...and some supervised children groups...
.children(|children| {
// ...
})
.children(|children| {
// ...
})
// ...or even supervised supervisors...
.supervisor(|sp| {
// ...
})
}).expect("Couldn't create the supervisor.");
// ...which can start supervising new children groups
// later on...
supervisor.children(|children| {
// ...
}).expect("Couldn't create the supervised children group.");
// ...or broadcast messages to all its supervised children
// and supervisors...
supervisor.broadcast("A message containing data.").expect("Couldn't broadcast the message.");
// ...and then can even be stopped or killed...
supervisor.stop().expect("Couldn't stop the supervisor");
// supervisor.kill().expect("Couldn't kill the supervisor");
// Creating a new top-level children group...
let children = Bastion::children(|children| {
children
// ...containing a defined number of elements...
.with_redundancy(4)
// ...all executing a similar future...
.with_exec(|ctx: BastionContext| {
async move {
// ...receiving and matching messages...
msg! { ctx.recv().await?,
ref msg: &'static str => {
// ...
};
msg: &'static str => {
// ...
};
msg: &'static str =!> {
// ...
};
// ...
_: _ => ();
}
// ...
Ok(())
}
})
}).expect("Couldn't create the children group.");
// ...which can broadcast messages to all its elements...
children.broadcast("A message containing data.").expect("Couldn't broadcast the message.");
// ...and then can even be stopped or killed...
children.stop().expect("Couldn't stop the children group.");
// children.kill().expect("Couldn't kill the children group.");
// Create a new top-level children group and getting a list
// of reference to its elements...
let children = Bastion::children(|children| {
// ...
}).expect("Couldn't create the children group.");
let elems: &[ChildRef] = children.elems();
// ...to then get one of its elements' reference...
let child = &elems[0];
// ...to then "tell" it messages...
child.tell_anonymously("A message containing data.").expect("Couldn't send the message.");
// ...or "ask" it messages...
let answer: Answer = child.ask_anonymously("A message containing data.").expect("Couldn't send the message.");
// ...until the child eventually answers back...
let answer: Result<SignedMessage, ()> = run!(answer);
// ...and then even stop or kill it...
child.stop().expect("Couldn't stop the child.");
// child.kill().expect("Couldn't kill the child.");
// Broadcasting a message to all the system's children...
Bastion::broadcast("A message containing data.").expect("Couldn't send the message.");
// Stopping or killing the system...
Bastion::stop();
// Bastion::kill();
// Blocking until the system has stopped (or got killed)...
Bastion::block_until_stopped();
}
Implementations
Initializes the system if it hasn’t already been done, using
the default Config
.
It is required that you call Bastion::init
or
Bastion::init_with
at least once before using any of
bastion’s features.
Example
use bastion::prelude::*;
Bastion::init();
// You can now use bastion...
Initializes the system if it hasn’t already been done, using
the specified Config
.
It is required that you call Bastion::init
or
Bastion::init_with
at least once before using any of
bastion’s features.
Arguments
config
- The configuration used to initialize the system.
Example
use bastion::prelude::*;
let config = Config::new()
.show_backtraces();
Bastion::init_with(config);
// You can now use bastion...
pub fn supervisor<S>(init: S) -> Result<SupervisorRef, ()> where
S: FnOnce(Supervisor) -> Supervisor,
pub fn supervisor<S>(init: S) -> Result<SupervisorRef, ()> where
S: FnOnce(Supervisor) -> Supervisor,
Creates a new Supervisor
, passes it through the specified
init
closure and then sends it to the system for it to
start supervising children.
This method returns a SupervisorRef
referencing the newly
created supervisor if it succeeded, or Err(())
otherwise.
Arguments
init
- The closure taking the newSupervisor
as an argument and returning it once configured.
Example
let sp_ref: SupervisorRef = Bastion::supervisor(|sp| {
// Configure the supervisor...
sp.with_strategy(SupervisionStrategy::OneForOne)
// ...and return it.
}).expect("Couldn't create the supervisor.");
Creates a new Children
, passes it through the specified
init
closure and then sends it to the system’s default
supervisor for it to start supervising it.
This methods returns a ChildrenRef
referencing the newly
created children group it it succeeded, or Err(())
otherwise.
Note that the “system supervisor” is a supervisor created by the system at startup.
Arguments
init
- The closure taking the newChildren
as an argument and returning it once configured.
Example
let children_ref: ChildrenRef = Bastion::children(|children| {
// Configure the children group...
children.with_exec(|ctx: BastionContext| {
async move {
// Send and receive messages...
let opt_msg: Option<SignedMessage> = ctx.try_recv().await;
// ...and return `Ok(())` or `Err(())` when you are done...
Ok(())
// Note that if `Err(())` was returned, the supervisor would
// restart the children group.
}
})
// ...and return it.
}).expect("Couldn't create the children group.");
Creates a new Children
which will have the given closure
as action and then sends it to the system’s default supervisor.
This method returns a ChildrenRef
referencing the newly created children
if the creation was successful, otherwise returns an Err(())
.
Internally this method uses the Bastion::children
and Children::with_exec
methods
to create a new children.
Arguments
action
- The closure which gets executed by the child.
Example
let children_ref: ChildrenRef = Bastion::spawn(|ctx: BastionContext| {
async move {
// ...
Ok(())
}
}).expect("Couldn't create the children group.");
pub fn distributed<I, F>(
cluster_config: &'static ArtilleryAPClusterConfig,
action: I
) -> Result<ChildrenRef, ()> where
I: Fn(Arc<DistributedContext>) -> F + Send + Sync + 'static,
F: Future<Output = Result<(), ()>> + Send + 'static,
distributed
only.Sends a message to the system which will then send it to all the root-level supervisors and their supervised children and supervisors, etc.
This method returns ()
if it succeeded, or Err(msg)
otherwise.
Arguments
msg
- The message to send.
Example
let msg = "A message containing data.";
Bastion::broadcast(msg).expect("Couldn't send the message.");
// And then in every children groups's elements' future...
msg! { ctx.recv().await?,
ref msg: &'static str => {
assert_eq!(msg, &"A message containing data.");
};
// We are only broadcasting a `&'static str` in this
// example, so we know that this won't happen...
_: _ => ();
}
Sends a message to the system to tell it to start handling messages and running children.
Example
use bastion::prelude::*;
Bastion::init();
// Use bastion, spawn children and supervisors...
Bastion::start();
// The system will soon start, messages will
// now be handled...
Sends a message to the system to tell it to stop every running children groups and supervisors.
Example
use bastion::prelude::*;
Bastion::init();
// Use bastion, spawn children and supervisors...
Bastion::start();
// Send messages to children and/or do some
// work until you decide to stop the system...
Bastion::stop();
Sends a message to the system to tell it to kill every running children groups and supervisors
Example
use bastion::prelude::*;
Bastion::init();
// Use bastion, spawn children and supervisors...
Bastion::start();
// Send messages to children and/or do some
// work until you decide to kill the system...
Bastion::kill();
Blocks the current thread until the system is stopped
(either by calling Bastion::stop
or
Bastion::kill
).
Example
use bastion::prelude::*;
Bastion::init();
// Use bastion, spawn children and supervisors...
Bastion::start();
// Send messages to children and/or do some
// work...
Bastion::block_until_stopped();
// The system is now stopped. A child might have
// stopped or killed it...
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Bastion
impl UnwindSafe for Bastion
Blanket Implementations
Mutably borrows from an owned value. Read more
pub fn vzip(self) -> V
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more