Struct maxim::system::ActorSystem

pub struct ActorSystem { /* fields omitted */ }

An actor system that contains and manages the actors spawned inside it.

Methods

impl ActorSystem

pub fn create(config: ActorSystemConfig) -> ActorSystem

Creates an actor system with the given config. The user should benchmark how many slots are needed in the work channel, the number of threads they need in the system and and so on in order to satisfy the requirements of the software they are creating.

pub fn start(&self)

Starts an unstarted ActorSystem. The function will do nothing if the ActorSystem has already been started.

pub fn config(&self) -> &ActorSystemConfig

Returns a reference to the config for this actor system.

pub fn connect(
    &self,
    sender: &SeccSender<WireMessage>,
    receiver: &SeccReceiver<WireMessage>
) -> Uuid

Adds a connection to a remote actor system. When the connection is established the actor system will announce itself to the remote system with a WireMessage::Hello.

pub fn disconnect(&self, system_uuid: Uuid) -> Result<(), AidError>

Disconnects this actor system from the remote actor system with the given UUID.

pub fn connect_with_channels(system1: &ActorSystem, system2: &ActorSystem)

Connects two actor systems using two channels directly. This can be used as a utility in testing or to link two actor systems directly within the same process.

pub fn init_current(&self)

Initializes this actor system to use for the current thread which is necessary if the user wishes to serialize and deserialize Aids.

Contract

You must run this exactly once per thread where needed.

pub fn current() -> ActorSystem

Fetches a clone of a reference to the actor system for the current thread.

pub fn uuid(&self) -> Uuid

Returns the unique UUID for this actor system.

pub fn trigger_shutdown(&self)

Triggers a shutdown but doesn't wait for the Reactors to stop.

pub fn await_shutdown(
    &self,
    timeout: impl Into<Option<Duration>>
) -> ShutdownResult

Awaits the Executor shutting down all Reactors. This is backed by a barrier that Reactors will wait on after ActorSystem::trigger_shutdown is called, blocking until all Reactors have stopped.

pub fn trigger_and_await_shutdown(
    &self,
    timeout: impl Into<Option<Duration>>
) -> ShutdownResult

Triggers a shutdown of the system and returns only when all Reactors have shutdown.

pub fn spawn(&self) -> ActorBuilder

Creates a single use builder for this actor system that allows a user to build actors using a chained syntax while optionally providing configuration parameters if desired.

Examples

use maxim::prelude::*;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

async fn handler(mut count: usize, _: Context, _: Message) -> ActorResult<usize> {
    count += 1;
    Ok(Status::done(count))
}

let state = 0 as usize;

let aid1 = system.spawn().with(state, handler).unwrap();
let aid2 = system.spawn().name("Foo").with(state, handler).unwrap();
let aid3 = system.spawn().channel_size(10).with(state, handler).unwrap();

pub fn spawn_pool(&self, count: usize) -> ActorPoolBuilder

Create a one use actor pool builder that can be used to create a pool of actors.

The state and the handler function will be cloned and the count of actors will be spawned and their Aids added to an AidPool. With the AidPool you can send messages to the pool to have one of the actors in the pool handle each message. The method that is used to select an actor to handle the message depends on the AidPool implmentation. The most common actor pool implementation is RandomAidPool.

Examples

use maxim::prelude::*;

let system = ActorSystem::create(ActorSystemConfig::default().thread_pool_size(2));

async fn handler(mut count: usize, _: Context, _: Message) -> ActorResult<usize> {
    // Do something
    Ok(Status::done(count))
}

let state = 0 as usize;

let mut aid_pool: RandomAidPool = system.spawn_pool(10).with(state, handler).unwrap();
// Send a message to one of the actors in the pool
aid_pool.send_new(()).unwrap();

pub fn stop_actor(&self, aid: &Aid)

Stops an actor by shutting down its channels and removing it from the actors list and telling the Aid to not allow messages to be sent to the actor since the receiving side of the actor is gone.

This is something that should rarely be called from the outside as it is much better to send the actor a SystemMsg::Stop message and allow it to stop gracefully.

pub fn is_actor_alive(&self, aid: &Aid) -> bool

Checks to see if the actor with the given Aid is alive within this actor system.

pub fn find_aid_by_uuid(&self, uuid: &Uuid) -> Option<Aid>

Look up an Aid by the unique UUID of the actor and either returns the located Aid in a Option::Some or Option::None if not found.

pub fn find_aid_by_name(&self, name: &str) -> Option<Aid>

Look up an Aid by the user assigned name of the actor and either returns the located Aid in a Option::Some or Option::None if not found.

pub fn system_actor_aid(&self) -> Aid

Returns the Aid to the "System" actor for this actor system.

pub fn monitor(&self, monitoring: &Aid, monitored: &Aid)

Adds a monitor so that monitoring will be informed if monitored stops.

pub fn send_to_system_actors(&self, message: Message)

Asynchronously send a message to the system actors on all connected actor systems.

Trait Implementations

impl Clone for ActorSystem

fn clone(&self) -> ActorSystem

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ActorSystem

fn fmt(&self, formatter: &mut Formatter) -> Result

Formats the value using the given formatter.