# Actor
Actix is a rust library providing a framework for developing concurrent applications.
Actix is built on the [Actor Model](https://en.wikipedia.org/wiki/Actor_model) which
allows applications to be written as a group of independently executing but cooperating
"Actors" which communicate via messages. Actors are objects which encapsulate
state and behavior and run within the *Actor System* provided by the actix library.
Actors run within specific execution context [*Context<A>*](../actix/struct.Context.html).
Context object is available only during execution. Each actor has separate
execution context. Also execution context controls lifecycle of an actor.
Actors communicate exclusively by exchanging messages. Sender actor can
wait for response. Actors are not referenced directly, but by different
types of addresses. Non thread safe [*Addr<Unsync, A>*](../actix/struct.Addr.html) or
thread safe address [*Addr<Syn, A>*](../actix/struct.Syn.html)
Any rust type can be an actor, it needs to implement [*Actor*](../actix/trait.Actor.html) trait.
To be able to handle specific message actor has to provide
[*Handler<M>*](../actix/trait.Handler.html) implementation for this message. All messages
are statically typed. Message could be handled in asynchronous fashion.
Actor can spawn other actors or add futures or streams to execution context.
Actor trait provides several methods that allow to control actor lifecycle.
## Actor lifecycle
### Started
Actor is always starts in `Started` state, during this state actor's `started()`
method get called. `Actor` trait provides default implementation for this method.
Actor context is available during this state, actor can start more actors or register
async streams or do any other required configuration.
### Running
After Actor's method `started()` get called, actor transitions to `Running` state.
Actor can stay in `running` state indefinitely long.
### Stopping
Actor execution state changes to `stopping` state in following situations,
* `Context::stop` get called by actor itself
* all addresses to the actor get dropped. i.e. no other actor reference it.
* no evented objects are registered in context.
Actor could restore from `stopping` state to `running` state by creating new
address or adding evented object, and by returning `Running::Continue` value.
If actor changed state to a `stopping` state because of `Context::stop()` get called
then context immediately stops processing incoming messages and calls
`Actor::stopping()` method. If actor does not restore back to a `running` state, all
unprocessed messages get dropped.
By default this method returns `Running::Stop` which confirms stop operation.
### Stopped
If actor does not modify execution context during stopping state, actor state changes
to `Stopped`. This state is considered final and at this point actor get dropped.
## Message
An Actor communicates with another Actors by sending messages. In actix all
messages are typed. Message could be any rust type which implements
[Message](../actix/trait.Message.html) trait. *Message::Result* defines return type.
Let's define a simple `Ping` message, an actor which will accept this message needs to return
`io::Result<bool>`.
```rust
# extern crate actix;
use std::io;
use actix::prelude::*;
struct Ping;
impl Message for Ping {
type Result = Result<bool, io::Error>;
}
# fn main() {}
```
## Spawning an actor
How to start an actor depends on it's context.Spawning a new async actor
is achieved via the `start` and `create` methods of
the [Actor](../actix/trait.Actor.html) trait. It provides several different ways of
creating actors, for details check the docs.
## Complete example
```rust
# extern crate actix;
# extern crate futures;
use std::io;
use actix::prelude::*;
use futures::Future;
/// Define message
struct Ping;
impl Message for Ping {
type Result = Result<bool, io::Error>;
}
// Define actor
struct MyActor;
// Provide Actor implementation for our actor
impl Actor for MyActor {
type Context = Context<Self>;
fn started(&mut self, ctx: &mut Context<Self>) {
println!("Actor is alive");
}
fn stopped(&mut self, ctx: &mut Context<Self>) {
println!("Actor is stopped");
}
}
/// Define handler for `Ping` message
impl Handler<Ping> for MyActor {
type Result = Result<bool, io::Error>;
fn handle(&mut self, msg: Ping, ctx: &mut Context<Self>) -> Self::Result {
println!("Ping received");
Ok(true)
}
}
fn main() {
let sys = System::new("example");
// Start MyActor in current thread
let addr: Addr<Unsync, _> = MyActor.start();
// Send Ping message.
// send() message returns Future object, that resolves to message result
let result = addr.send(Ping);
// spawn future to reactor
Arbiter::handle().spawn(
result.map(|res| {
match res {
Ok(result) => println!("Got result: {}", result),
Err(err) => println!("Got error: {}", err),
}
# Arbiter::system().do_send(actix::msgs::SystemExit(0));
})
.map_err(|e| {
println!("Actor is probably died: {}", e);
}));
sys.run();
}
```