Document and fix how to implement custom stopping logic

The `BackgroundService` should not return early if there are no tasks
in `stop()`, as sub-classes could need to implement a custom stopping
logic. In this case it should be enough to override the `cancel()` and
`wait()` methods, and the `is_running` property.

We also add an example of how this could be done.

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

Author: llucax

RELEASE_NOTES.md

@@ -39,4 +39,4 @@
 
 ## Bug Fixes
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+- Fix a bug in `BackgroundService` where it won't try to `self.cancel()` and `await self.wait()` if there are no internal tasks. This prevented to properly implement custom stop logic without having to redefine the `stop()` method too.

src/frequenz/sdk/actor/_background_service.py

@@ -36,8 +36,9 @@ class BackgroundService(abc.ABC):
         information, please refer to the [Python `asyncio`
         documentation](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task).
 
-    Example:
+    Example: Simple background service example
         ```python
+        from typing_extensions import override
         import datetime
         import asyncio
 
@@ -46,6 +47,7 @@ def __init__(self, resolution_s: float, *, name: str | None = None) -> None:
                 super().__init__(name=name)
                 self._resolution_s = resolution_s
 
+            @override
             def start(self) -> None:
                 self._tasks.add(asyncio.create_task(self._tick()))
 
@@ -67,6 +69,45 @@ async def main() -> None:
 
         asyncio.run(main())
         ```
+
+    Example: Background service example using custom stopping logic
+        If you need to implement custom stopping logic, you can override the
+        [`cancel()`][frequenz.sdk.actor.BackgroundService.cancel] and
+        [`wait()`][frequenz.sdk.actor.BackgroundService.wait] methods, and the
+        [`is_running`][frequenz.sdk.actor.BackgroundService.is_running] property.
+
+        For example, if you are using an external library that uses tasks internally and
+        you don't have access to them.
+
+        ```python
+        from typing_extensions import override
+        import asyncio
+
+        class SomeService(BackgroundService):
+            def __init__(self, somelib, *, name: str | None = None) -> None:
+                self.somelib = somelib
+                super().__init__(name=name)
+
+            @override
+            def start(self) -> None:
+                self.somelib.start()
+
+            @property
+            @override
+            def is_running(self) -> bool:
+                return self.somelib.is_running()
+
+            @override
+            def cancel(self, msg: str | None = None) -> None:
+                self.somelib.cancel()
+
+            @override
+            async def wait(self) -> None:
+                try:
+                    await self.somelib.wait()
+                except BaseExceptionGroup as exc:
+                    raise BaseExceptionGroup("Error while stopping SomeService", [exc]) from exc
+        ```
     """
 
     def __init__(self, *, name: str | None = None) -> None:
@@ -144,8 +185,6 @@ async def stop(self, msg: str | None = None) -> None:  # noqa: DOC503
             BaseExceptionGroup: If any of the tasks spawned by this service raised an
                 exception.
         """
-        if not self._tasks:
-            return
         self.cancel(msg)
         try:
             await self.wait()