Update actor documentation

[daniel-zullo-frequenz]

What happened?

Initially, the actor was designed to run continuously unless there was an error or it was intentionally stopped. Later, the actor was updated to support a new use-case where the actor exits the running loop upon a normal termination.

The current actor documentation and examples primarily focus on stopping the actor manually, with only a brief mention that the actor also naturally terminates upon completing execution without errors. Some examples are either outdated or not entirely accurate.

For example, here it documents how it is expected to be used, as continuously running actors: https://github.com/frequenz-floss/frequenz-sdk-python/blob/v1.x.x/src/frequenz/sdk/actor/__init__.py#L214-L218
In this part, it states that actors will be restarted only when it exits with errors: https://github.com/frequenz-floss/frequenz-sdk-python/blob/v1.x.x/src/frequenz/sdk/actor/__init__.py#L38-L40
And here actors are awaited to finish execution https://github.com/frequenz-floss/frequenz-sdk-python/blob/v1.x.x/src/frequenz/sdk/actor/__init__.py#L46-L48 but the examples only point out that actors needs to be manually stopped

For this example, the actor will block either until execution termination or until it gets stopped
https://github.com/frequenz-floss/frequenz-sdk-python/blob/v1.x.x/src/frequenz/sdk/actor/__init__.py#L70-L88

Also internal documentation needs to be updated to reflect what the code actually does.
For instance, the actor will also exit if it finishes execution successfully without any error but this is not reflected in the function documentation
https://github.com/frequenz-floss/frequenz-sdk-python/blob/v1.x.x/src/frequenz/sdk/actor/_actor.py#L75-L111

What did you expect instead?

Update or extend documentation and examples in actor class and module to reflect what the actor code does, including the scenario where the actor terminates execution normally.

Affected version(s)

No response

Affected part(s)

Actors or actors utilities (decorator, etc.) (part:actor), Documentation (part:docs)

Extra information

Related to #632

[shsms]

It is also becoming more relevant now, as we are considering use cases where actor instances get spun up, run for a specific amount of time like a few hours, then exit. Such uses should already be possible, but we can incorporate any insights gained from that experience into our actor documentation as well.

[llucax]

frequenz-sdk-python/src/frequenz/sdk/actor/__init__.py

Lines 214 to 218 in 471adc6

	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]).

This doesn't look incorrect IMHO, it explicitly says one can stop the actor manually. Do you mean we should just not mentioning that actors "normally should run forever", or that they could also stop on their own?

[llucax]

frequenz-sdk-python/src/frequenz/sdk/actor/__init__.py

Lines 38 to 40 in 471adc6

	- **Automatic Restart:** If an unhandled exception occurs in an actor's logic
	([`_run()`][_run] method), the actor will be automatically restarted. This ensures
	robustness in the face of errors.

This also doesn't say unhanded errors are the only way an actor can be restarted, it says it is automatically restarted on errors.

[llucax]

frequenz-sdk-python/src/frequenz/sdk/actor/__init__.py

Lines 46 to 48 in 471adc6

	- **Simplified lifecycle management:** Actors are [async context managers] and also
	a [`run()`][frequenz.sdk.actor.run] function is provided to easily run a group of
	actors and wait for them to finish.

Same here, this is only describing one feature, actors are async context managers and can be used like that, but you don't have to.

[llucax]

frequenz-sdk-python/src/frequenz/sdk/actor/_actor.py

Lines 75 to 83 in 471adc6

	async def _run_loop(self) -> None:
	"""Run this actor's task in a loop until `_restart_limit` is reached.
	Raises:
	asyncio.CancelledError: If this actor's `_run()` gets cancelled.
	Exception: If this actor's `_run()` raises any other `Exception` and reached
	the maximum number of restarts.
	BaseException: If this actor's `_run()` raises any other `BaseException`.
	"""

Yeah, this one should be definitely updated/fixed.