Add Lifecycle, Communication and Implementing an Actor sections

These new sections explain in more detail how actors work, and what's
needed to both use them and implement them properly.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/sdk/actor/__init__.py

@@ -43,9 +43,157 @@
   [`asyncio`][]. You can create and manage tasks within the actor, and the `Actor`
   class handles task cancellation and cleanup.
 
-- **Simplified lifecycle management:** Actors are [async context
-  managers](https://docs.python.org/3/reference/datamodel.html#async-context-managers)
-  and also a [`run()`][frequenz.sdk.actor.run] function is provided.
+- **Simplified lifecycle management:** Actors are [async context managers] and also
+  a [`run()`][frequenz.sdk.actor.run] function is provided.
+
+## Lifecycle
+
+Actors are not started when they are created. There are 3 main ways to start an actor
+(from most to least recommended):
+
+1. By using the [`run()`][frequenz.sdk.actor.run] function.
+2. By using the actor as an [async context manager].
+3. By using the [`start()`][frequenz.sdk.actor.Actor.start] method.
+
+!!! warning
+
+    1. If an actor raises an unhandled exception, it will be restarted automatically.
+
+    2. Actors manage [`asyncio.Task`][] objects, so a reference to the actor object must
+       be held for as long as the actor is expected to be running, otherwise its tasks
+       will be cancelled and the actor will stop. For more information, please refer to
+       the [Python `asyncio`
+       documentation](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task).
+
+
+### The `run()` Function
+
+The [`run()`][frequenz.sdk.actor.run] function can start many actors at once and waits
+for them to finish. If any of the actors are stopped with errors, the errors will be
+logged.
+
+???+ example
+
+    ```python
+    from frequenz.sdk.actor import Actor, run
+
+    class MyActor(Actor):
+        async def _run(self) -> None:
+            print("Hello World!")
+
+    await run(MyActor()) # (1)!
+    ```
+
+    1. Will block until the actor is stopped.
+
+### Async Context Manager
+
+When an actor is used as an [async context manager], it is started when the
+`async with` block is entered and stopped automatically when the block is exited
+(even if an exception is raised).
+
+???+ example
+
+    ```python
+    from frequenz.sdk.actor import Actor
+
+    class MyActor(Actor):
+        async def _run(self) -> None:
+            print("Hello World!")
+
+    async with MyActor() as actor: # (1)!
+        print("The actor is running")
+    # (2)!
+    ```
+
+    1. [`start()`][frequenz.sdk.actor.Actor.start] is called automatically when entering
+        the `async with` block.
+    2. [`stop()`][frequenz.sdk.actor.Actor.stop] is called automatically when exiting
+        the `async with` block.
+
+### The `start()` Method
+
+When using the [`start()`][frequenz.sdk.actor.Actor.start] method, the actor is
+started in the background and the method returns immediately. The actor will
+continue to run until it is **manually** stopped.
+
+???+ example
+
+    ```python
+    from frequenz.sdk.actor import Actor
+
+    class MyActor(Actor):
+        async def _run(self) -> None:
+            print("Hello World!")
+
+    actor = MyActor() # (1)!
+    actor.start() # (2)!
+    print("The actor is running") # (3)!
+    await actor.stop() # (4)!
+    ```
+
+    1. The actor is created but not started yet.
+    2. The actor is started manually, it keeps running in the background.
+    3. !!! danger
+
+        If this function would raise an exception, the actor will never be stopped!
+
+    4. Until the actor is stopped manually.
+
+!!! warning
+
+    This method is not recommended because it is easy to forget to stop the actor
+    manually, specially in error conditions.
+
+## Communication
+
+The [`Actor`][frequenz.sdk.actor.Actor] class doesn't impose any specific way to
+communicate between actors. However, [Frequenz
+Channels](https://github.com/frequenz-floss/frequenz-channels-python/) are always used
+as the communication mechanism between actors in the SDK.
+
+## Implementing an Actor
+
+To implement an actor, you must inherit from the [`Actor`][frequenz.sdk.actor.Actor]
+class and implement the abstract `_run()` method.
+
+### The `_run()` Method
+
+The abstract `_run()` method is called automatically by the base class when the actor is
+[started][frequenz.sdk.actor.Actor.start].
+
+Normally an actor should run forever (or until it is
+[stopped][frequenz.sdk.actor.Actor.stop]), so it is very common to have an infinite loop
+in the `_run()` method, typically receiving messages from one or more channels
+([receivers][frequenz.channels.Receiver]), processing them and sending the results to
+other channels ([senders][frequenz.channels.Sender]).
+
+### Stopping
+
+By default, the [`stop()`][frequenz.sdk.actor.Actor.stop] method will call the
+[`cancel()`][frequenz.sdk.actor.Actor.cancel] method (which will cancel all the tasks
+created by the actor) and will wait for them to finish.
+
+This means that when an actor is stopped, the `_run()` method will receive
+a [`CancelledError`][asyncio.CancelledError] exception. You should have this in mind
+when implementing your actor and make sure to handle this exception properly if you need
+to do any cleanup.
+
+The actor will handle the [`CancelledError`][asyncio.CancelledError] exception
+automatically if it is not handled in the `_run()` method, so if there is no need for
+extra cleanup, you don't need to worry about it.
+
+If an unhandled exception is raised in the `_run()` method, the actor will re-run the
+`_run()` method automatically. This ensures robustness in the face of errors, but you
+should also have this in mind if you need to do any cleanup to make sure the re-run
+doesn't cause any problems.
+
+???+ tip
+
+    You could implement your own [`stop()`][frequenz.sdk.actor.Actor.stop] method to,
+    for example, send a message to a channel to notify that the actor should stop, or
+    any other more graceful way to stop the actor if you need to make sure it can't be
+    interrupted at any `await` point.
 
 ## Example
 
@@ -157,6 +305,8 @@ async def main() -> None:  # (2)!
 
 11. The actors are stopped and cleaned up automatically when the `async with`
     block ends.
+
+[async context manager]: https://docs.python.org/3/reference/datamodel.html#async-context-managers
 """
 
 from ..timeseries._resampling import ResamplerConfig