Akka Kill vs. Stop vs. Poison Pill?

Newbie question of Akka - I'm reading over Akka Essentials, could someone please explain the difference between Akka Stop/Poison Pill vs. Kill ? The book offers just a small explaination "Kill is synchronous vs. Poison pill is asynchronous." But in what way? Does the calling actor thread lock during this time? Are the children actors notified during kill, post-stop envoked, etc? Example uses of one concept vs. the other?

Many thanks!

Both stop and PoisonPill will terminate the actor and stop the message queue. They will cause the actor to cease processing messages, send a stop call to all its children, wait for them to terminate, then call its postStop hook. All further messages are sent to the dead letters mailbox.

The difference is in which messages get processed before this sequence starts. In the case of the stop call, the message currently being processed is completed first, with all others discarded. When sending a PoisonPill, this is simply another message in the queue, so the sequence will start when the PoisonPill is received. All messages that are ahead of it in the queue will be processed first.

By contrast, the Kill message causes the actor to throw an ActorKilledException which gets handled using the normal supervisor mechanism. So the behaviour here depends on what you've defined in your supervisor strategy. The default is to stop the actor. But the mailbox persists, so when the actor restarts it will still have the old messages except for the one that caused the failure.

Also see the 'Stopping an Actor', 'Killing an Actor' section in the docs:

http://doc.akka.io/docs/akka/snapshot/scala/actors.html

And more on supervision strategies:

http://doc.akka.io/docs/akka/snapshot/scala/fault-tolerance.html

Use PoisonPill whenever you can. It is put on the mailbox and is consumed like any other message. You can also use "context.stop(self)" from within an actor.

PoisonPill asynchronously stops the actor after it’s done with all messages that were received into mailbox, prior to PoisonPill.

You can use both actor stop and poison pill to stop processing of actors, and kill to terminate the actor in its entirety. x.stop is a call you make in akka receive method, will only replace actor state with new actor after calling postStop. x ! PoisonPill is a method that you pass to actor to stop processing when the actor is running(Recommended). will also replace actor state after calling postStop. x.kill will terminate the actor and will remove the actor in the actor Path and replace the entire actor with a new actor.