Add documentation for AK1002

[Arkatufus]

---

uid: AK1002
title: Akka.Analyzers Rule AK1002 - "Must not await Self.GracefulStop() inside ReceiveAsync or ReceiveAnyAsync"

AK1002 - Error

You should never await Self.GracefulStop() inside ReceiveActor ReceiveAsync<T>() or ReceiveAnyAsync()

Cause

Awaiting Self.GracefulStop() inside ReceiveAsync<T>() or ReceiveAnyAsync() will cause a deadlock because the ReceiveActor will block and wait inside the message handler for itself to terminate while its PoisonPill signal is stuck inside its MailBox, waiting to be processed.

An example:

using Akka.Actor;
using System.Threading.Tasks;
using System;

public sealed class MyActor : ReceiveActor
{
   public MyActor()
   {
      ReceiveAsync<string>(async str => {
         await Context.Self.GracefulStop(); // THIS WILL DEADLOCK
      }):
   }
}

Resolution

If you absolutely need to invoke Self.GracefulStop() inside ReceiveAsync<T>() or ReceiveAnyAsync(), make sure that you're using a detached Task instead of awaiting for it to complete.

Here's an example below:

using Akka.Actor;
using System.Threading.Tasks;
using System;

public sealed class MyActor : ReceiveActor
{
   public MyActor()
   {
      ReceiveAsync<string>(async str => {
         _ = Context.Self.GracefulStop();
      }):
   }
}

[Aaronontheweb]

@Arkatufus might also be worth mentioning that this can affect an UntypedActor.RunTask with the same type of await on a GracefulStop but that's even more of an edge case I suspect.