# `Raxol.Core.Runtime.Directive`
[🔗](https://github.com/DROOdotFOO/raxol/blob/v2.8.0/lib/raxol/core/runtime/directive.ex#L1)

Runtime-essential effect directives that any TEA application can return
from `update/2`.

These directives need no agent context: they run purely against the
caller's runtime (`Process.send_after`, `Task.start`, runtime pid signal).
Agent-specific directives (shell access, inter-agent messaging,
multi-message async streams) live in `Raxol.Agent.Directive` and depend
on raxol_agent.

## Built-in directives

| Directive | Effect |
| --- | --- |
| `Stop` | Signal the runtime to stop |
| `Schedule` | Send a message after a delay (`Process.send_after`) |
| `Spawn` | Run a 0-arg function in a Task; its return value is sent back once |

## Examples

    import Raxol.Core.Runtime.Directive, only: [stop: 0, schedule: 2, spawn_task: 1]

    stop()
    schedule(1_000, :tick)
    spawn_task(fn -> {:result, expensive_op()} end)

## Dispatch

Each struct implements `Raxol.Core.Runtime.Directive.Executor`. The
runtime invokes the protocol's `execute/2` with a context map containing
at minimum `:pid` and `:runtime_pid`. Result messages arrive at
`context.pid` as `{:command_result, payload}` (the message name is
historical; both the old `Command` system and the directive system use
it).

External packages register additional directives by defining a struct
and implementing `Raxol.Core.Runtime.Directive.Executor` for it.

# `t`

```elixir
@type t() ::
  Raxol.Core.Runtime.Directive.Stop.t()
  | Raxol.Core.Runtime.Directive.Schedule.t()
  | Raxol.Core.Runtime.Directive.Spawn.t()
  | struct()
```

# `schedule`

```elixir
@spec schedule(non_neg_integer(), term()) :: Raxol.Core.Runtime.Directive.Schedule.t()
```

Construct a `Schedule` directive. `interval_ms` must be non-negative.

# `spawn_task`

```elixir
@spec spawn_task((-> any())) :: Raxol.Core.Runtime.Directive.Spawn.t()
```

Construct a `Spawn` directive with a no-arg function.

# `stop`

```elixir
@spec stop(term()) :: Raxol.Core.Runtime.Directive.Stop.t()
```

Construct a `Stop` directive.

---

*Consult [api-reference.md](api-reference.md) for complete listing*