# Supervision

In GoAkt, the supervision mechanism enables you to specify the supervisor strategy to handle actor failures. That strategy is configured at the time of actor creation by using the `SpawnOption` method [`WithSupervisor`](https://github.com/Tochemey/goakt/blob/main/actor/spawn_option.go#L188). To define a custom supervisor strategy, call the [`NewSupervisor`](https://github.com/Tochemey/goakt/blob/main/actor/supervisor.go#L213) function and supply the desired options via [`SupervisorOption`](https://github.com/Tochemey/goakt/blob/main/actor/supervisor.go#L92-L127).

GoAkt also provides built-in error types to use with supervisor directives:

* **`PanicError`:** Wraps an error as an alternative to triggering the standard Go panic.
* **`InternalError`:** Serves as a wrapper for errors classified as internal.
* **`SpawnError`:** Recommended for situations where the creation of an actor fails

To cover any type of errors, one can use the option [**`WithAnyErrorDirective`**](https://github.com/Tochemey/goakt/blob/main/actor/supervisor.go#L173)

## Example

```go
supervisor := NewSupervisor(
	WithStrategy(OneForOneStrategy),
	WithDirective(PanicError{}, RestartDirective),
	WithDirective(&runtime.PanicNilError{}, RestartDirective),
	WithDirective(InternalError{}, ResumeDirective),
	WithDirective(SpawnError{}, ResumeDirective),
)
```

## Strategies

GoAkt supports the following supervisor strategies:

* **`OneForOneStrategy`**: if a child actor fails, only that specific child actor is affected by the supervisor's `Directive` . This is the default supervisor strategy.
* **`OneForAllStrategy`**: if a child actor fails, that specific child actor and its siblings are affected by the supervisor's `Directive` .This strategy is particularly appropriate when the child actors are tightly coupled or interdependent—where the malfunction of one actor can adversely affect the overall functionality of the ensemble.

## Directives

GoAkt supports the following supervisor directives:

* **`StopDirective`**: Instructs the supervisor to stop the failing actor along its siblings depending upon the strategy used.
* **`ResumeDirective`**: Instructs the supervisor to resume the failing actor without restarting it allowing it to continue processing messages (typically used for recoverable errors)
*   **`RestartDirective`**: Instructs the supervisor to restart the failing actor along its siblings depending upon the strategy used, reinitialising its state or their states.&#x20;

    With the **`RestartDirective`** directive, only the direct alive children of the given actor will be shutdown and respawned with their initial state. There are only two scenarios where an actor can supervise another actor:

    * It watches the given actor via the **`Watch`** method. With this method the parent actor can also listen to the **`Terminated`** message to decide what happens next to the child actor.
    * The actor to be supervised is a child of the given actor.
* **`EscalateDirective`** : Instructs the supervisor to escalate the handling of the failure to the parent actor. The parent actor needs to handle the system message called [**`Mayday`**](https://github.com/Tochemey/goakt/blob/main/protos/goakt/goakt.proto#L194) and decide how to handle the failure. The _sender_ of the `Mayday` message is the child actor. When the escalate directive is used the child actor is _**suspended**_.

### Note

GoAkt will suspend a faulty actor when there is no supervisor strategy set in place for the corresponding error type. Once can check the state of the actor using the **`IsSuspended`** method on the `PID`. A suspended actor can be _reinstated_ or _shutdown_, however it cannot handle any messages sent to it until reinstated. &#x20;
