How to Stop an Actor

Calling actorSystem.stop(actor) and context.stop(actor) are the most common ways to stop an actor.

PoisonPill

A major difference between calling the stop method on an actor and sending it a PoisonPill message is in how the actor is stopped. 

• The stop method lets the actor finish processing the current message in its mailbox (if any), and then stops it. 
• The PoisonPill message lets the actors process all messages that are in the mailbox ahead of it before stopping it.

GracefulStop

You can use the gracefulStop approach if you want to wait for a period of time for the termination process to complete gracefully.
gracefulStop(actorRef, timeout) “Returns a Future that will be completed with success when existing messages of the target actor has [sic] been processed and the actor has been terminated.” If the actor isn’t terminated within the timeout, the Future results in an ActorTimeoutException.
If the order in which actors are terminated is important, using gracefulStop can be a good way to attempt to terminate them in a desired order. 

Below is some notes of actor termination:

• Termination of an actor is performed asynchronously; the stop method may return before the actor is actually stopped.
• The actor will continue to process its current message, but no additional messages will be processed.
• An actor terminates in two steps. First, it suspends its mailbox and sends a stop message to all of its children. Then it processes termination messages from its children until they’re all gone, at which point it terminates itself. If one of the actors doesn’t respond (because it’s blocking, for instance), the process has to wait for that actor and may get stuck.
• When additional messages aren’t processed, they’re sent to the deadLetters actor of the ActorSystem (though this can vary depending on the mailbox implementation). You can access these with the deadLetters method on an ActorSystem.