Actors

Actors

Actors encapsulate a single task or process into an atomic operation in relation to the whole service. Each actor holds its own distinct state. Communication between the actors is done via message passing through mailboxes.

It is necessary to write an special actor, when developing a service (Further reading on Service development), Hydra will do that for you. All you need to do, is write your ServiceActivator and bundle it with an archive.xml file.

Be aware that Hydras actors are strictly non distributed. They are bound to the actor system they were created in, distribution is managed by Hydra itself.

Working with actors:

Actors implement the base class Actor.

public class TestActor extends Actor {
...
}

To start an actor you need an running actor system and invoke its spawnActor method:

ActorSystem as = ActorSystem.create();
ActorRef ref = as.spawnActor(TestActor.class, "test");

To send a message to the actor you can use the tell or ask methods of the returned actor ref. Tell will send an asynchronous "fire-and-forget" message to the actor. Ask will send a message and return a future object that can be used to wait for an response. Be aware that the waiting will prevent any other message from being processed by the actor until the get method returns.

ref.tell("hello", null);

Future<?> f = ref.ask("are there dragons?");
f.get(10, TimeUnit.SECONDS);

Every actor has an unique actor path that marks its place in the actor hierarchy. You can us this path to look up existing actors:

ActorRef ref = as.getActor("/app/test");

Actor system

Hydras actors live in an internal actor system, that is responsible for actor supervision, error handling and message passing. The actors are ordered hierarchically under several Guardians:

• RootGuardian: The root guardian is the top level guardian and will catch all errors that are escalated through other supervisiors.
• SysGuardian: The system guardian is responsible for system services on the actor level. These include the standard input and output actors as well as the log actor.
• AppGuardian: The application guardian is the supervisor for all user defined actors. Hydras actors are child actors to this guardian.

Shutdown order

In order to guarantee an orderly shutdown, the guardians form a chain:

RootGuardian -> SysGuardian -> AppGuardian

On shutdown this chain is traversed in reversed order.

Supervision

Every actor has a parent (except the RootGuardian). If an error occures and is not catched by the actor, it will be escalated to the parent actor and the source actor and all its children are paused. The parent actor can then decide based on his SuperVisorStrategy how to handle the error:

• Ignore: Ignore the error and resume the actor that was the source of the error.
• Restart: Restarts the actor in response to the error. The hierarchical structure is not affected. Only the source actor will restart, leaving its children untouched.
• Stop: Stops the actor and all its child actors.
• Escalate: Escalates the error to the next parent actor. This will pause the current actor and all children recursively.