# `Tinkex.Regularizer.Executor`
[🔗](https://github.com/North-Shore-AI/tinkex/blob/v0.4.0/lib/tinkex/regularizer/executor.ex#L1)

Manages regularizer execution with process-based parallelism.

This module handles both synchronous and async regularizers,
with optional parallel execution using Elixir Tasks.

## Execution Modes

### Sequential (`:parallel => false`)

Executes regularizers one at a time in the order specified.
Useful for debugging and deterministic behavior.

### Parallel (`:parallel => true`, default)

Executes regularizers concurrently using `Task.async_stream/3`.
Provides better throughput for CPU-bound regularizers.

## Async Regularizers

Regularizers with `async: true` in their spec should return a `Task.t()`
instead of the result directly. The executor will `Task.await/2` the result.

## Telemetry

Emits the following events:

- `[:tinkex, :regularizer, :compute, :start]` - Before each regularizer
- `[:tinkex, :regularizer, :compute, :stop]` - After each regularizer
- `[:tinkex, :regularizer, :compute, :exception]` - On failure

# `execute_all`

```elixir
@spec execute_all(
  [Tinkex.Types.RegularizerSpec.t()],
  [Tinkex.Types.Datum.t()],
  Nx.Tensor.t(),
  keyword()
) :: {:ok, [Tinkex.Types.RegularizerOutput.t()]} | {:error, term()}
```

Execute all regularizers and collect outputs.

## Options

- `:parallel` - Run in parallel (default: true)
- `:timeout` - Execution timeout in ms (default: 30_000)
- `:track_grad_norms` - Compute gradient norms (default: false)
- `:max_concurrency` - Max parallel tasks (default: schedulers_online)

## Returns

- `{:ok, list(RegularizerOutput.t())}` on success
- `{:error, term()}` on failure

## Examples

    {:ok, outputs} = Executor.execute_all(regularizers, data, logprobs,
      parallel: true,
      timeout: 60_000,
      track_grad_norms: true
    )

# `execute_one`

```elixir
@spec execute_one(
  Tinkex.Types.RegularizerSpec.t(),
  [Tinkex.Types.Datum.t()],
  Nx.Tensor.t(),
  keyword()
) :: {:ok, Tinkex.Types.RegularizerOutput.t()} | {:error, term()}
```

Execute a single regularizer and return output.

## Options

- `:timeout` - Timeout for async regularizers (default: 30_000)
- `:track_grad_norms` - Compute gradient norm (default: false)

## Returns

- `{:ok, RegularizerOutput.t()}` on success
- `{:error, {:regularizer_failed, name, exception}}` on failure
- `{:error, {:regularizer_exit, name, reason}}` on exit

---

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