Akka Stopping Actors

Table of contents

Reading Time: 2 minutes

In Akka, you can stop Actors by invoking the stop() method of either ActorContext or ActorSystem class. ActorContext is used to stop child actor and ActorSystem is used to stop top level Actor.

The actual termination of the actor is performed asynchronously.

There are some other methods available in Akka, which are used to stop Actor. Some of which are PoisonPill, terminate() and gracefulStop() are used to stop Actor.

1. Using stop() Method

We can use the stop() method on the ActorSystem to an actor. This will stop the actor once it completes the processing of the current message. All the remaining messages in the mailbox will be sent to DeadLetters. Let’s give it a try:

val system = ActorSystem("system") 
system.stop(actor)

If the actor is stopped while processing the message Msg 1, it will suspend its mailbox and wait for the current processing to be completed. Once it is completed, the actor will be stopped, and the rest of the messages in the mailbox will be sent to DeadLetters. After the current actor is stopped, it will invoke its postStop() hook to clean up the resources.

Akka Stopping Top Level Actor Example

You can simply call stop() method to stop top level Actor. The following example describes the uses of stop() method.23.7M496HTML Tutorial

import akka.actor.{Actor,ActorSystem, Props};
class ActorExample extends Actor{
def receive = {
case message:String => println(“Message received: “+message);
case _ => println(“Unknown message”);
}
override def postStop(){
println(“Actor stoped”);
}
}
object ActorExample{
def main(args:Array[String]){
val actorSystem = ActorSystem(“ActorSystem”);
val actor = actorSystem.actorOf(Props[ActorExample], “RootActor”);
actor ! “Hello”
actorSystem.stop(actor);
}
}

Output:

Message received: Hello
Actor stoped

Akka Stopping Child Actor Example

import akka.actor.{Actor,ActorSystem, Props};
class ActorExample extends Actor{
def receive = {
case message:String => println(“Message received by “+self.path.name+”: “+message);
val childactor = context.actorOf(Props[ChildActor], “ChildActor”);
childactor ! “Hello child Actor”
context.stop(childactor);
case _ => println(“Unknown message”);
}
}
class ChildActor extends Actor{
def receive = {
case message:String => println(“Message received by “+self.path.name+”: “+message);
case _ => println(“Unknown message”);
}
override def postStop(){
println(“Child Actor stoped”);
}
}
object ActorExample{
def main(args:Array[String]){
val actorSystem = ActorSystem(“ActorSystem”);
val actor = actorSystem.actorOf(Props[ActorExample], “RootActor”);
actor ! “Hello”
}
}

Output:

Message received by RootActor: Hello
Message received by ChildActor: Hello child Actor
Child Actor stoped

2. Using terminate() Method

You can stop actor system by calling it’s terminate method. This method will stop the guardian actor, which in turn will recursively stop all its child actors.

Akka Stopping ActorSystem Example

import akka.actor.{Actor,ActorSystem, Props};
class ActorExample extends Actor{
def receive = {
case message:String => println(“Message received by “+self.path.name+”: “+message);
val childactor = context.actorOf(Props[ChildActor], “ChildActor”);
childactor ! “Hello child Actor”
case _ => println(“Unknown message”);
}
override def postStop(){
println(“Top Level Actor stoped”);
}
}
class ChildActor extends Actor{
def receive = {
case message:String => println(“Message received by “+self.path.name+”: “+message);
case _ => println(“Unknown message”);
}
override def postStop(){
println(“Child Actor stoped”);
}
}
object ActorExample{
def main(args:Array[String]){
val actorSystem = ActorSystem(“ActorSystem”);
val actor = actorSystem.actorOf(Props[ActorExample], “RootActor”);
actor ! “Hello”
actorSystem.terminate();
}
}

Output:

Message received by RootActor: Hello
Message received by ChildActor: Hello child Actor
Child Actor stoped
Top Level Actor stoped

3. Using PoisonPill Message

Another way to stop an actor is by sending a special type of message, called PoisonPill, to the actor. This message acts like any other message and will be queued up in the actor’s mailbox. When the actor finds this message, it will be itself. That means all the messages before the PoisonPill will be processed normally. The messages which came after the PoisonPill will be sent to DeadLetters.

Let’s send the PoisonPill to the actor:

actor ! PoisonPill

4. Using gracefulStop

Another way of stopping an actor is using the gracefulStop() method. This method will return a Future response. When the actor completes processing and terminates within the configured timeout, it will return with success. If it exceeds more time, the response will be a failed Future. This is especially useful when we want to stop the actors in an orderly fashion:

5. Using Kill

We can also stop an actor using the Kill message. As soon as an actor gets a Kill message, it will complete the current processing message and throws an ActorKilledException. Hence, the supervisor actor will get notified and handle the situation based on the configured supervision strategy.

We can send the kill message as: