# `MingaEditor.EffectScheduler.Engine`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_editor/effect_scheduler/engine.ex#L1)

Lifecycle, admission-policy, and worker coordination for `EffectScheduler`.

# `admission`

```elixir
@type admission() ::
  {:ok, MingaEditor.Effect.Request.id(), :running | :queued}
  | {:error, admission_error()}
```

# `admission_error`

```elixir
@type admission_error() ::
  :already_admitted
  | :owner_unavailable
  | :policy_mismatch
  | :queue_full
  | :scheduler_full
```

# `claim`

```elixir
@type claim() :: :ok | {:error, :not_pending}
```

# `handoff`

```elixir
@type handoff() :: admission() | {:error, :not_found}
```

# `active?`

```elixir
@spec active?(MingaEditor.EffectScheduler.State.t(), module()) :: boolean()
```

Returns whether a handler has running, queued, or pending work.

# `active_activity?`

```elixir
@spec active_activity?(MingaEditor.EffectScheduler.State.t(), atom()) :: boolean()
```

Returns whether any active request advertises a semantic activity.

# `active_source?`

```elixir
@spec active_source?(
  MingaEditor.EffectScheduler.State.t(),
  Minga.Extension.ContributionCleanup.contribution_source()
) :: boolean()
```

Returns whether a source has running, queued, or pending work.

# `admitted?`

```elixir
@spec admitted?(
  MingaEditor.EffectScheduler.State.t(),
  MingaEditor.Effect.Request.id()
) :: boolean()
```

Returns whether an exact request still holds scheduler admission.

# `attach`

```elixir
@spec attach(MingaEditor.EffectScheduler.State.t(), pid()) ::
  {:ok | {:error, :already_attached}, MingaEditor.EffectScheduler.State.t()}
```

Attaches the scheduler's single owner.

# `cancel`

```elixir
@spec cancel(MingaEditor.EffectScheduler.State.t(), MingaEditor.Effect.Request.id()) ::
  {:ok | {:error, :not_found}, MingaEditor.EffectScheduler.State.t()}
```

Cancels an admitted request.

# `cancel_operation`

```elixir
@spec cancel_operation(
  MingaEditor.EffectScheduler.State.t(),
  MingaEditor.State.Operation.id()
) ::
  {:ok | {:error, :not_found}, MingaEditor.EffectScheduler.State.t()}
```

Cancels the admitted request correlated with a semantic operation.

# `cancel_resource`

```elixir
@spec cancel_resource(
  MingaEditor.EffectScheduler.State.t(),
  MingaEditor.Effect.Request.resource()
) ::
  {:ok, MingaEditor.EffectScheduler.State.t()}
```

Cancels and terminalizes all work for one semantic resource.

# `cancel_source`

```elixir
@spec cancel_source(
  MingaEditor.EffectScheduler.State.t(),
  Minga.Extension.ContributionCleanup.contribution_source()
) :: {:ok, MingaEditor.EffectScheduler.State.t()}
```

Cancels and terminalizes all work attributed to a contribution source.

# `claim`

```elixir
@spec claim(MingaEditor.EffectScheduler.State.t(), MingaEditor.Effect.Outcome.t()) ::
  {claim(), MingaEditor.EffectScheduler.State.t()}
```

Atomically claims a still-pending candidate without releasing its resource.

# `finalize`

```elixir
@spec finalize(MingaEditor.EffectScheduler.State.t(), MingaEditor.Effect.Outcome.t()) ::
  MingaEditor.EffectScheduler.State.t()
```

Finalizes a domain-applied candidate, if it is still pending.

# `finalize_and_schedule`

```elixir
@spec finalize_and_schedule(
  MingaEditor.EffectScheduler.State.t(),
  MingaEditor.Effect.Outcome.t(),
  MingaEditor.Effect.Request.t()
) :: {handoff(), MingaEditor.EffectScheduler.State.t()}
```

Finalizes a candidate and admits its follow-up as one scheduler transition.

# `process_down`

```elixir
@spec process_down(MingaEditor.EffectScheduler.State.t(), reference(), pid(), term()) ::
  MingaEditor.EffectScheduler.State.t()
```

Processes an owner or worker DOWN message.

# `schedule`

```elixir
@spec schedule(MingaEditor.EffectScheduler.State.t(), MingaEditor.Effect.Request.t()) ::
  {admission(), MingaEditor.EffectScheduler.State.t()}
```

Admits a request according to its resource policy.

# `shutdown`

```elixir
@spec shutdown(MingaEditor.EffectScheduler.State.t(), term()) ::
  MingaEditor.EffectScheduler.State.t()
```

Stops all work and terminalizes every admitted request.

# `stats`

```elixir
@spec stats(MingaEditor.EffectScheduler.State.t()) :: map()
```

Returns bounded scheduler statistics.

# `task_result`

```elixir
@spec task_result(MingaEditor.EffectScheduler.State.t(), reference(), term()) ::
  MingaEditor.EffectScheduler.State.t()
```

Processes a successful worker reply.

# `timeout`

```elixir
@spec timeout(MingaEditor.EffectScheduler.State.t(), MingaEditor.Effect.Request.id()) ::
  MingaEditor.EffectScheduler.State.t()
```

Processes a scheduler-owned request timeout.

---

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