[−][src]Module sealrs::actors

Actor based asynchronous runtime

Introduction

This runtime is realize the classical actor paradigm actively used in the actor based languages, such as Erlang and actors framework, such as Akka. To be frank, this module is heavily relies on the last and actively use principles and abstractions submitted in this framework.

At this moment, module presents next features:

Untyped actors with exchanged the messages derived from Any trait
Actor lifetime management
DeadLetters
TestKit
Timers
Watching
Various dispatchers realizations
FSM

Perspective features:

Under this features already exists architectural basis, and their implementation is a question of my free time.

Mailboxes with user defined functional
Supervising
Distributed actor systems

Architecture elements

Before we go to the concrete examples of usage, you mast understand the internal architecture of the actors runtime. Without this, you will do not understand many of errors which may cause at work with the library and it will be seems for you as bags, but it's doesn't.

Actor runtime contains three big elements:

Runtime - contains objects used of actor at execution
System - environment of actors representation . Controls actors lifetime (start, stop, and etc.). Contains default and other system elements.
Actor - objects providing actor execution in the runtime

Runtime consists two object:

Mailbox - queue protected from race condition. This is an interface, which presents set of some basic methods for work with the internal queue. In this queue drops all messages passed to the actor before his actual processing. In the library exists few standard realization of this interface:
- UnboundedMailbox - mailbox without any queue size restrictions. This mailbox is used by default at the time of actor creation, if other mailbox type, does not specified explicitly.
Dispatcher - entity which process the messages. Message processing may be planned in it, and after that, dispatcher decides himself, how and when run his processing. Message processing is the operation, when receive method of actor is called with processed message and prepared context. Dispatcher is an interface, and him concrete behavior base on it's implementation. In the library exists few standard realization of this interface:
- DefaultDispatcher - dispatcher based on on ThradPinnedDispatcher with thread pinning stratagy. This executor contants set of threads, which distributes between actors. He is used for main purpose and non blocking tasks, with medium loading for the system.
- PinnedDispatcher - dispatcher which contain only one thread and service work of only one actor. Stops at the same time with serviced actor. Used for situations when actor needs to perform some heavy synchronous tasks such as working with a files or using a network. Blocking of message processing in this dispatcher have nothing impact to other actors in the system.

Runtime consists five object:

Actor - user defined structure implemented with the Actor trait. This object contains application logic of program constructed in the actors style. Him has one mandatory function for realization (receive) and few optional (preStart, postStop an others).
ActorRef - representation of the actor link. This is an interface, through which users code may interact with underlayed actor. This interface is an encapsulate of interaction with the underlying ActorCell (described below). ActorRef may be cloned as many time as you want, safe shared between actors and other thread. This feature ensured by the fact, that all instances of the cloned ref, will link to the single protected ActorCell object.
ActorCell - system actor representation. Coordinates all interaction with actor from the outside. This object contains the current lifetime state of an actor. In him stored mailbox and link to the dispatcher, in which will be processed messages from the mailbox. Functional it performs, start, stop and suspend actor. Interacts with dispatcher for planning messages processing and etc. Need make a comment about the mailbox and dispatcher instances. ActorCell has always it's own instance if the mailbox, which will created with the other elements of the actor at the creation stage of him. Unique of the dispatcher depends on it's type. Some dispatchers has a shared nature. They may be user with few actors at the same time. Others is unique for each actor instance. Example of the first type dispatcher is DefaultDispatcher. Second is PinnedDispatcher (in developing stage, used in the strategy - os thread per actor).
ActorPath - representation of the actor path in the actors system. This object is used for comparing actor references, paths printing in the debug messages and other internal needs.
ActorContext - actor environment at processing message. This struct conatins message sender reference, self actor reference, link to the system on witch actor is executed and other useful values and methods.

System consists two object:

ActorSystem - object represents the actor system. It used for creating, stopping actors and some other service operations performing.
Dead Letter - special sort of the mailbox in which all enqueued messages is logged and after that destroyed. Never is planned. Used to dispose of undelivered messages for various reasons.

Basic operations

Now, after we will learn set of the basis framework elements, let's try to write some practical code. First, we need some implementation of an actor. Let's create actor to which we may send message with some text, and actor will print it. As side-effect, actor will be count of printed characters.

use crate::actors::prelude::*;
use std::any::Any;
use std::sync::{Mutex, Arc};
use match_downcast::*;

pub fn props() -> Props {
    Props::new(tsafe!(BasicActor::new()))
}

pub struct Print {
    pub text: String,
}

pub struct BasicActor {
    printed_chars: usize
}

impl BasicActor {
    pub fn new() -> BasicActor {
        BasicActor {
            printed_chars: 0
        }
    }
}

impl Actor for BasicActor {

    fn receive(self: &mut Self, msg: Message, _ctx: ActorContext) -> HandleResult {
        let msg = msg.get();
        match_downcast_ref!(msg, {
            m: Print => {
                self.printed_chars = self.printed_chars + m.text.len();
                println!("{}", m.text);
            },
            _ => return Ok(false)
        });

        Ok(true)
    }
}

Next we write the code which use this actor:

let mut system = LocalActorSystem::new();

let mut printer = system
    .actor_of(basic_actor::props(), Some("printer"));

let msg = msg!(basic_actor::Print { text: String::from("Hello world!") });
printer.tell(msg, None);

At first line, we create new actor system. Internally, this operation creates default dispatcher and DeadLetter synthetic actor. At next line, we create the early defined actor. actor_of functions is receive Pops object as first argument, and actor name as second. Actor name is optional, and it may be set to None. In this case, name will be generated automatically. Props object is indicates the system, which actor to create, and with which params. We will come across this structure more than once as the material is presented. For now, we simple creates new actor instance and put it's to the Props object. As a result of the actor_off call, we will receive actor link object - ActorRef. Internally this call, besides the ActorRef, will create next objects: ActorCell, Mailbox and Dispatcher if it was specified and has unique nature. After performs all internal operations, library code will call preStart function, which will be described later in this doc.

And at last stage, we may send the Print message to the actor.We create the new Print structure, uses for it the msg! macro and then send her to the actor through tell function. The 'msg!' macros is creates the special wrapper for messages, which may contain any data type and he may be safely shared between threads. Tell function receive message as first argument and sender actor reference as second. Last is optional, because if we send message outside of the actor system we do not someone whom may be represents as sender. If you perform this operation from the actor, you should be set ctx.self_ to this value. But about this we say later. When you call tell function, ActorCell get passed message to the mailbox and indicates dispatcher schedule this message for processing.

Ok, message in the mailbox, what happens with him further? Next, the dispatcher, when he will be ready for it, extract message from the mailbox and message processing stage is starts. First, the message is heading to the internal receive function. His task, determine service message (such as PoisonPill, witch stops the actor). If it is, it will be processed, some service actions will be performed and message will dropped. He will does not reach the receive function of the target actor. If this message is not a service message, actor.receive function will be called. This function must return a HandleResult value, which indicates fact, was handled message or not (or some error occurs). If the message was handled, message processing logic is end, else the message will be dropped to the DeadLetter.

Now consider the the function of messages receive of our actor. It have three args. First arg is the link to self object which state is fully mutable. Second args is the received message. Last arg is the message processing context. Message represents as boxed Any type and may be matched be any comfortable way for you. I use for this the crate 'match-downcast' which allows keep code clear at downcast operations. From the context, for now, only one object is interesting - sender. What does he point to? At DeadLetter, because at tell operation, we was specify None as sender reference.

Lifetime hooks

Actor has few lifetime hooks which may be used for various operations:

pre_start - called after full actor initialization and before allowing reception of messages. At this stage already exists actor context, which may be used for creating new actors or sending message for himself. Also is available actor's internal state for mutating.
post_stop - called after full stop of actor. This means, that all message passed to the actor was processed or dropped and it will not receive any new messages further. This is the last point of interaction with internal actor's state. At this stage actor context also exists and may be user to perform various operations.
pre_fail - Called before some supervising operation will be started. Read more about what it in the special chapter.
post_restart - Called after actor was restarted. This may occurs if some supervision action occurs. Read more about what it in the special chapter.

For example let's add this hooks to our basic actor:

...

fn pre_start(self: &mut Self, ctx: ActorContext) {
    println!("BasicActor is started")
}

fn post_stop(self: &mut Self, ctx: ActorContext) {
    println!("BasicActor is stopped")
}

...

After you run this modified example, before printing the passed message, in the stdout you will see 'BasicActor is started'. postTop will triggered after actor will be stopped. This operation we will learn below.

Stopping actors

Actor can be stopped in two way:

Send PoisonPill - this is a special service message, located in the actor submodule. If you send this message to an actor, it will be enqueued as an any regular message. But when dispatcher will face with him, he will drop all messages in the mailbox after it, and starts actor stopping procedure.
```
bench.tell(msg!(actor::PoisonPill { }), None);
```
ActorSystem::stop(ActorRef) - this call immediately stops the specified actor. He lead to block mailbox of the actor, flush all it's messages and mark him as stopped. If this call happens from a message handler, current message will be processed, but all subsequent does not. Internally this call does the following. He suspends the actor, clean his mailbox and prepend to it ths single PoisonPill message. This will lead to that after processing the current message dispatcher will immediately come across a message PoisonPill and stops the actor. Similar situation will be happened and if this call occurs outside of actor system. In this case, if target actor is in process of some message, it will be processed and after that actor will be stopped.
```
system.stop(bench);
```

Actor communications

For consideration of this topic, we need some more complicated example. In the 'example' submodule located module named logger. This is more complex program then basic example, but this much more real world example of actors usage. Here contains three actors which realize logger, in which we may indicate logging target. Log target may be StdOut or File. Logger actor contains links to the writers, whom directly realize logging logic to him target. Task of the logger actor is receive Log message, determine target writer actor and send Write message to him. Writer actor receive this message, performs write and respond to the sender with Ok message. Logger actor receive this message, increment internal counter of write chars and print info text about this action to console. Below are given 'receive' functions of this actors. Surrounding code is redundant for this doc, and you may see him in in the source files.

// Logger
fn receive(self: &mut Self, msg: Message, ctx: ActorContext) -> HandleResult {
   let msg = msg.get();
   match_downcast_ref!(msg, {
           m: Log => {
               match m.target {
                   LogTarget::File => {
                       let msg = msg!(file_writer::Write { text: m.text.to_string() });
                       self.file_writer.tell(msg , Some(&ctx.self_))
                   },
                   LogTarget::StdOut => {
                       let msg = msg!(stdout_writer::Write { text: m.text.to_string() });
                       self.stdout_writer.tell(msg, Some(&ctx.self_))
                   }
               };
           },
           m: file_writer::Ok => {
               println!("File logger write '{}' chars", m.chars_count);
               self.chars_counter = self.chars_counter + m.chars_count;
           },
           m: stdout_writer::Ok => {
                println!("Stout logger write '{}' chars", m.chars_count);
               self.chars_counter = self.chars_counter + m.chars_count;
           },
           _ => return Ok(false)
       });

   Ok(true)
}


//StdoutWriter
fn receive(self: &mut Self, msg: Message, mut ctx: ActorContext) -> HandleResult {
   let msg = msg.get();
   match_downcast_ref!(msg, {
           m: Write => {
              println!("{}", m.text);
              let resp = msg!(Ok { chars_count: m.text.len() });
              ctx.sender.tell(resp, Some(&ctx.self_));
           },
           _ => return Ok(false)
       });

   Ok(true)
}


//FileWriter
fn receive(self: &mut Self, msg: Message, mut ctx: ActorContext) -> HandleResult {
   let msg = msg.get();
   match_downcast_ref!(msg, {
           m: Write => {
              fs::write(&self.file, m.text.as_bytes());
              let resp = msg!(Ok { chars_count: m.text.len() });
              ctx.sender.tell(resp, Some(&ctx.self_));
           },
           _ => return Ok(false)
       });

   Ok(true)
}

And code which use this actors:

let mut system = LocalActorSystem::new();

let mut logger =  {
    let mut system = system;
    let file_writer = system.actor_of(file_writer::props("/tmp/log"), Some("file_writer"));
    let stdout_writer = system.actor_of(stdout_writer::props(), Some("stdout_writer"));
    system.actor_of(logger::props(file_writer, stdout_writer), Some("logger"))
};

logger.tell(msg!(logger::Log { text: String::from("To file log"), target: logger::LogTarget::File }), None);
logger.tell(msg!(logger::Log { text: String::from("To stdout log"), target: logger::LogTarget::StdOut }), None);

This code demonstrate two patterns and operation as part of this library:

Dependency Injection - at deploying stage of the system, we create two actors (writers) and inject it to the logger actor through him constructor (which is hidden by the props function).
Context using - demonstrated actor context usage for sending messages to another actor and respond to messages.

In the previous example we was moved created references to the logging writers to the constructor of logger actor. But what about if you want to use this references later in your code? For this, ActorRef's may by simply cloned.

let (mut logger, mut file_writer, mut stdout_writer) = {
    let mut system = system;
    let file_writer = system.actor_of(file_writer::props("/tmp/log"), Some("file_writer"));
    let stdout_writer = system.actor_of(stdout_writer::props(), Some("stdout_writer"));
    let logger = system.actor_of(logger::props(file_writer.clone(), stdout_writer.clone()), Some("logger"));
    (logger, file_writer, stdout_writer)
};

More about DeadLetters

In the previous text will be described what is the DeadLetters. Now will be described why it exists and how it use. Basic idea of the actors message passing, consists in that all message must be delivered to the target actor and consumed. If this is not happens, and message not consumed be the receiver, this is an semantic error in the your program. Main task of the DeadLetters, is quite aggressive indicates to you, that this error type was occurs in your program. For this, DeadLetter log each received by him message to the stdout.

DeadLetter receive some message ... from 'ActorRef (/stdout_writer)' to 'ActorRef (/logger)'

This feature is unable to disable be the ideological reasons. Because not processed messages is an error! In practical, this prints is very useful for actor system debug , when something goes wrong and work improperly. 90% of errors in actor-based programs linked to the problem of not delivered messages and DeadLetters allows to you fastly determine bags.

Also, you may encounter with situation, when you may want to interact with DeadLetters directly. This is may be performed by obtaining the DeadLetter actor reference. This reference stored in the ActorSystem and may by cloned from it by the special function:

let mut deadLetters = system.dead_letters();

This is a regular actor reference, but all messages passed through it, will be dropped directly to the DeadLetter.

More about dispatchers

Messages dispatch is more complex topic for describe him in one paragraph. Next text completes this omission.

Specifying the dispatcher via props

You may specify dispatcher for actor by presents her name to the Props object. By default, exists two dispatchers type - default and pinned. Default used alwasy as default if you don't set another type explicitly. You may specify other dispatcher by calling with_dispatcher function.

let some_actor = Props::new(tsafe!(SomeActor::new()))
    .with_dispatcher("pinned");

Adding new dispatchers

You can add external dispatchers to the actor system through add_ dispatcher method. This method receive name of created dispatcher and his object. Should notice that if dispatcher with the same name exists, it will be replaced. Old dispatcher will be immediately stoppd and dropped. After adding dispatcher, he may be used with Props object through with_dispatcher method. Replacing feature, permits you to replace default dispatcher of the actor system.


// Replace default dispatcher with custom count of threads
system.add_dispatcher("default", tsafe!(DefaultDispatcher::new(16)));

Implementing custom dispatcher

You can implement your own dispatcher type with some specific functionality. This is not magic action, because actor system dispatcher is a simple struct which implements the two traits - Dispatcher and Executor. You may implement this struct and pass it with add_dispatcher method to the actor system. This action is contain too many code for describe him in this doc. You may see to the example of custom dispatcher implementing in the 'example/actors/custom_dispatcher'.

Using dispatchers with futures

Fact that dispatcher implements Executor trait, allows to you use him as execution context of AsyncPromise. You can do this in such way:

Timers

Timers is the separate module which is uses for scheduling automatic message sending with a specified time-params. Main his purpose is sending messages from an actor to himself for determine timeout of various asynchronous operations. Next example demonstrates contrived actor, uses this features. Realization details was dropped for more clear understanding of the concept ( you may found full code in the examples module ).

impl Actor for Ticker {

   fn pre_start(self: &mut Self, ctx: ActorContext) {
       let mut timers = RealTimers::new(ctx.system.clone());

       timers.start_single(
          0,
          &ctx.self_,
          &ctx.self_,
          Duration::from_secs(1),
          msg!(SingleTick {}));

       timers.start_periodic(
           1,
           &ctx.self_,
           &ctx.self_,
           Duration::from_secs(2),
           Box::new(|| msg!(PeriodicTick {})));

       self.timers = Some(tsafe!(timers));
   }

   fn post_stop(&mut self, _ctx: ActorContext) {
       self.timers.cancel_all();
   }


   fn receive(self: &mut Self, msg: Message, ctx: ActorContext) -> HandleResult {
       let msg = msg.get();
       match_downcast_ref!(msg, {
           m: SingleTick => {
              println!("SingleTick");
           },
           m: PeriodicTick => {
              if (self.ticks == 3) {
                  self.timers.cancel(1);
                  println!("PeriodicTick cancelled");
              } else {
                  println!("PeriodicTick");
                  self.ticks = self.ticks + 1;
             }
          },
           _ => return Ok(false)
       });

       Ok(true)
   }
}

Here in the pre_start hook, creates two timers. All timers has practically identical set of arguments. You must specify key, on which timer may be cancelled, sender and receiver refs, time parameter and message for sending. First timer is the single timer, it is send message only once with one second delay. Message are sent from self to self. As message specified SingleTick structure. Second timer is the periodic timer. He will send message to the actor each two second, until he will be explicitly cancelled. Message argument contains some trick. It's accept not struct itself, but closure which produce this struct. It is due to than for each timer iteration, schedulers needs the new message. If you send to this arg a structure, it will be fully consumed at first iteration, and timer will does not have what to send. Closure used here as factory of a single message.

After all timers was configured, timer object stored in the actor state. Through one second after start, the actor will receive the SingleTick message. After two, the actor will start receive the periodic message - PeriodicTick. After receive three such messages, it will cancel this timer specify the timer key in the cancel method.

In post_stop hook, all timers must be canceled. If this is don't do, you risk encounter with situation, when timer will send message to dead actor and it will be dropped to DeadLetters. This situation may be more dangerous, if intervals timers exists. If don't cancel it after actor was stopped, memory leaks occurs, because actor doesn't may be dropped because of him.

Stash

If an actor have several lines of behavior, exists one serious problem. What to do with messages not from current behavior? For this situation, exists special pattern named stashing. He expressed as simple struct which works as user side mailbox. You can put messages into it and when need you may initiate resend of stored messages. Normally stash created in pre_start hook:

self.stash = RealStash::new(&ctx);

And after that you can use it:

self.stash.stash(&msg, &ctx);

// In other message handler ...

self.stash.unstash_all();

Watching

Each actor have special set of internal events. When event from this set occurs, it's passed to the internal event bus. Watching allows one actor to subscribe to another actor's events. Most significant usege of this technique is tracking of terminating of watched actors. You may subscribe actor for events of another actor in the following way:

ctx.system().watch(&ctx.self_, &self.target);

First argument of the watch function is the reference to actor which will be subscribed for events of the actor specified in the second argument. After that subscriber, will be receive special messages always when some events occurs with the target actor. For now exists next event types:

Terminated - occurs when watched actor is fully stopped (event occurs right after post_stop hook was called).

Actor may unsubscribes from actor events in similar way, using function unwatch:

ctx.system().unwatch(&ctx.self_, &self.target);

Caution about unwatching. You must always explicitly call unwatch method, before actor (which is watch to another actors) will be stopped. This is non critical, but if you don't do it, this cause to full walk of event bus tree for search and remove stopped actor from subscribers of events. It may be extremely expensive operation if on the event bus exists many observed actors.

You may see full example usage of watching in the 'examples/actors/watch' submodule.

Ask

Ask call doing the same thing that tell call, but expects, that target actor respond back with some message. This expectation represents as Future, which will be completed with received message or with AskTimeoutError if target actor does not respond with some timeout. This operation may be used in three way:

Interact with actor system from synchronous world. The essence of this patterns consists in that you Ask target, and block your thread on the Future, which returned be the function. This operation will permits to you interact with actors as if they would be a some synchronous function. This operation must be never used from the actor system, because it will cause to block of the dispatcher, that will very fast leads to dead lock of the entire system.

let req = actor.ask(&mut (system), msg!(SomeRequest {}));
let result = req.result(Duration::from_secs(5));

// Do some actions with received message or handle error

Connection of actor's world with future's world. This situation is very often occurs in the web development. Most count of modern server libraries, more or less supports future paradigm. This features consists in than when server receives a request, you do not process him in the handler but pass this work to the future. With Ask pattern you may represents interaction with actor system through such future. Basic example of this interactions may be expressed in this way:

actor.ask(&mut (system), msg!(SomeRequest {}))
    .map(|v| {
        // Do some with received message
    })
    .recover(|e| {
        // Do some with timeout error
    });

Intercommunication layer between actors without mutation of state . Imagine the next station. You have three actors A, B and C. A requests B for some data. But B for respond to A, need firstly request C and based on him response, he may create response for A. Without futures this may be realized only as state machine. After receives request from A, B sends request to C and change it's behavior for handle responses from C. When response from C will be received, B create response to A, send him, and switch her behavior to the normal. Details about what do with messages addressed to B when it's not in the normal state is omitted. If in this situation state of actor B does not mutates, state machine may be converted to actor with linear behavior, which uses for this operation futures. Such code Ask actor C and does not wait anything, all logic now live in the future combinators, which will be processed fully separate from the actor B. Situation of this sort, often have a place to be in DDD paradigm in parts of CQRS interactions logic. For example you ask to root aggregate for get some view object of some entity, he will calls read side of entity, read side in turn asks repository. Repository return raw view object to the read side. Read side transforms this object to the natural view object, and root aggregate removes some system fields from it and returns it to the requester. All stages in this chain is immutable for state of the participants. And all this operation may be performed with futures. On practice it may work follows:

fn receive(&mut self, msg: Message, mut ctx: ActorContext) -> HandlerResult {
    let msg = msg.get();
    match_downcast_ref!(msg, {
        m: commands::RequestFromA => {
            let inter_data = m.data + 100;

            let mut sender = ctx.sender.clone();
            let mut self_ = ctx.self_.clone();

            self.c_actor.ask(&mut (*ctx.system()), msg!(RequestFromB { data: inter_data }) )
                .on_complete(move |v| {
                    if v.is_ok() {
                        let resp = v.as_ref().ok().unwrap();
                        let resp = resp.get();
                        if let Some(m) = resp.downcast_ref::<ResponseFromC>() {
                            let inter = m.data;
                            sender.tell(msg!(ResponseFromB {data: inter }), Some(&self_));
                        }
                    } else {
                        println!("Oops! C does not respond!")
                    }
                });
            },
            _ => return Ok(false)
        });

   Ok(true)
}

You may see full example of Ask usage in the 'examples/actors/ask' submodule.

FSM

FSM is transcripted as Finite State Machine. This conceptions is very powerful used with actors, because permits you to create fully asynchronous state machines with full control around them behavior.

Actor may be presented as FSM if it her logic satisfies few things:

He uses few lines of behavior with various data
Some behaviours needs a timeouts
Lifetime of an actor is finite (this is partial demand, because may exist fsm with lifetime equals to lifetime of entire program).

All this aspects may be realized with conditional operators and timers, but in this case, your code will be is very dirty. For eliminate this difficulties, in the library exists special module, which contains abstraction layer for creating of FSM.

State and Data

State is the main executable unit of any FSM. Each state accompanied by a some Data. In any piece of time, FSM always be in one of some State and have one of some Data. States and Data on the language level describes as enum. Separate State handlers describes as function with the next signature:

pub fn state0(&mut self, msg: &Message, ctx: &ActorContext, data: &Data) -> StateResult<Self, State, Data> {
    //Make a some actions with a message based on a presented Data
}

You may perceive this handler as special variant of the standard receive function of actor. There you may do similar actions as in the receive functions, buf instead HandleResult, you must return StateResult. Last type is the alias for the very complex type, so for prevent you from creating a trash code, library presents few functions for produce this result. This result indicates to the upper library code, what to do next - switch state or data, stop actor or some other things.

Fsm::goto(state) - indicates to change current state to some other.
Fsm::goto_using(state, data) - indicates to change current state and data to some others
Fsm::stay() - indicates to stay in current state and with current data
Fsm::stay_using(data) - indicates to stay in current state but with some other data
Fsm::stop() - indicates that work of FSM is completed (stops the actor)
Fsm::unhandled() - indicates that current message was doest not be handled (unknown type of message or some other reasons)

Each state handlers must be explicitly registered in the fsm object:

fsm.register_handler(State::StateA, Self::state_a, Duration::from_secs(5));

In this call you must specify the state on which attached handler, handler function and state timeout.

States timeouts

Each separate state have it's own idle timeout. If fsm will does not receive any messages in this timeout, library automatically send special message SendTimeout, which will be indicates to the user code, that state timeout was reached. What to do next in this situation is youre decision.

Unhandled messages

You may register special handler of unhandled messages. This function will be called always, when some state completes with Fsm::unhandled(). Handler is useful when you need detect unhandled message in state independent manner. Handler presented as next function:

fn unhandled(&mut self, msg: &Message, ctx: &ActorContext, state: &State, data: &Data) -> HandleResult

Signature is analogous for default receive function of an actor, but contains additional information about state and data, under which fsm was missed a message. Handler may be registered through this method:

fsm.register_unhandled(Self::unhandled);

State transitions

You may execute some code in the moment when fsm will be change status. Handler of this situation have the next view:

fn transition(&mut self, from: &State, to: &State)

He contains in arguments link to the state from which fsm passes and a link to the state to which fsm goes. This handler may be registered with the next call:

fsm.register_transition(Self::transition);

Full example

You can see the full example of how to use fsm in 'examples/actor/fsm'

When you need to use FSM and when Futures?

When you start a real world work with fsm, you may encounter with the strange question - why I need to use the fsm, if i may instead I use combined futures? I suffered from this issue many cont of times, but in the end, I was create some conception of when user fsm and when use futures. Here she is.

Future - used when operation contains only lenear logic, less than three stage and it does not need information about states. Example - you need checks user permissions and based on this check, to request data from repository or not. All simple, two stage, no data between them and no branching.

Fsm - used when operation shares data between states or she contains more than three stages or operation logic is non linear. Example. At first stage you request of authorisation data from the local caсhe. If he contains data about user, you go to stage three. If not, you start stage two - checking user permissions on a remote server. At stage thee you have user permissions check result. If it is privileged user, you requests to repository for getting version of data for privileged user. If not, you requests to repository for getting version of data for non-privileged user. At stage four, based on this data from the repository, you respond to the originator with some final result. Four stages, shared data between them and several scenarios.

Supervision

All actors in the system grouped to tree, in which each actor have one parent and zero or more children's. Supervision in the actor system relies on the two simple ideas. First idea consists is that lifetime of all child actors directly depends on lifetime of his parents. Second idea is that actor may be failed when process some message, and after that, system will take some actions for restore broken actor from this situation.

Hierarchy

As was said before, each actor have one parent and may have childs. At the top of all hierarchy placed Root Guardian - synthetic actor whose only task is to be parents for all actors which will be created through system.actor_of method. You may create an actor through another way:

ctx.actor_of(some_actor::props(), Some("name"));

In this code as ActorRef provider ActorContext is used. Actor from called this action, becomes as parent for created actor and his lifetime is fully depended on lifetime of his parent. How it work on practice. For example you have the next actors hierarchy - /root/A/B/C. If you will stop the A actor, it will cause to recursive stopping of actors B and C. What about root? Yes, he also may be stopped. This action occurs when you call system.terminate method. Before the handler will stops the dispatchers, he will stop the Root Guardian, what cause to stops of all actors in the hierarchy.

actor_select

Hierarchy of actors gives us some useful feature. You may obtain ActorRef's of actors placed in some leaf of the tree if you know them path.

let selection = system.actor_select("/root/a/b");
let b_ref = &mut selection[0];

Call of acotor_select return the vector with found ActorRef's. This is the regular refs which will may be used as refs created through actor_of call.

Need make a note, that actor_of is the some cost operation, because with searching of actor, code goes through all hierarchy of cells, what cause to locks. Based on that, what then deeper the target actor, than more expensive the search.

Error recovery

Message handler may completes with some error:

fn receive(self: &mut Self, msg: Message, _ctx: ActorContext) -> HandleResult {
    let msg = msg.get();
    match_downcast_ref!(msg, {
            m: HelloToC => {
                println!("Hello to some from the outside world!")
            },
            m: FailMe => {
                println!("CActor receive FailMe");
                return Err(err!("some err"))
            },
            _ => return Ok(false)
        });

    Ok(true)
}

This situation treated be system as signal that processed actor was faced with an insoluble error, and system must take some actions. This actions is called supervision operation and determined with supervision strategy. Exist four strategies:

Resume - do nothing, ignore occurred error
Stop - stop the actor
Restart - restart the actor (stop and start)
Escalate - lift this error to the parent of the actor

All created actors has Restart strategy by default. Root Guardian and DeadLetters has Resume strategy. Strategy of a separate actor may be set up through Props object:

let props = Props::new(tsafe!(SomeActor::new()))
       .with_supervision_strategy(SupervisionStrategy::Escalate)

Before starts of the supervision operation, pre_fail hook of the failed actor will be called. This hook contains the actor context, occurred error and current supervision strategy.

Modules

abstract_actor_ref
abstract_actor_system
actor	Actor trait
actor_cell	Core of the actor
actor_context	Message processing context
actor_path	Actor path representation
actor_ref_factory
ask_actor
dead_letters	Crematorium for undelivered messages
default_dispatcher	Actor dispatcher with strategy - thread pool and single actor / single thread in pool
dispatcher
envelope	Internal representation of a message
error	Error wrapper
fsm
local_actor_ref	Reference to instance of some actor. It is an interface for interacting with the internal logic of the actor cell.
local_actor_system	Actor system is a container for actors runtime. She is used for actor creation, stop and other operations
mailbox	Mailbox interface
message	Message wrapper
pinned_dispatcher	Actor dispatcher with strategy - dedicated thread per actor
prelude	Prelude for work with actors
props	Constructor of user defined actor
scheduler	Scheduler for needs of actor system. Based on the Timers crate and as fact, is an wrapper above him.
stash	User side mailbox for actors with non-linear behaviors
supervision	Structs used for supervision
synthetic_actor	Empty actor stub for service needs
timers	Timers object for planning messages sending.
unbound_mailbox	Predefined mailbox without queue size restrictions
watcher	Event bus of watching
wrapped_dispatcher	Wrapper for dispatcher which permits to him mimic to an executor