# `Dwrr.Server`
[🔗](https://github.com/version2beta/dwrr-elixir/blob/88c8dc71f673c35281de00d602c5ae2a4a951f7e/lib/dwrr/server.ex)

Caller-owned, serialized wrapper around `Dwrr` for one process.

Start it under your own supervisor or with `start_link/2`. It is unnamed by default; the `:name` option is forwarded to
`GenServer.start_link/3`. It starts no children. Each function makes one `GenServer.call/2` with the default
5000 ms timeout and returns the exact `Dwrr` result, including the new scheduler.
Tagged errors are returned unchanged and leave the stored state unchanged. Calls
are applied in mailbox arrival order; the order of calls from different senders is
not guaranteed.

A timeout does not prove that the operation was rolled back. An argument outside
the `Dwrr` domain raises `ArgumentError` inside the server, which then terminates;
the caller sees an exit, not a tagged error. Invalid initialization fails
`start_link/2`. A restarted server starts fresh from its original count, so queued
items, quantum changes and added queues are lost. There are no retries, no
backpressure and no persistence. Returned snapshots are immutable values for pure
branching, not shared writes.

# `add_queue`

```elixir
@spec add_queue(GenServer.server()) :: {non_neg_integer(), Dwrr.t(term())}
```

Append queue; return {index, scheduler}.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `drain_queue`

```elixir
@spec drain_queue(GenServer.server(), integer()) ::
  {:ok, [Dwrr.Item.t(term())], Dwrr.t(term())} | {:error, Dwrr.error()}
```

Withdraw FIFO contents; return the exact core result.

# `enqueue`

```elixir
@spec enqueue(GenServer.server(), integer(), [
  %Dwrr.Item{cost: non_neg_integer(), value: term()}
]) ::
  {:ok, Dwrr.t(term())} | {:error, Dwrr.error()}
```

Append items; return the exact core result, including its scheduler.

# `remove_head`

```elixir
@spec remove_head(GenServer.server(), integer()) ::
  {:ok, Dwrr.Item.t(term()) | nil, Dwrr.t(term())} | {:error, Dwrr.error()}
```

Withdraw head; return the exact core result.

# `remove_queue`

```elixir
@spec remove_queue(GenServer.server()) :: Dwrr.t(term())
```

Remove last queue; return scheduler.

# `set_quantum`

```elixir
@spec set_quantum(GenServer.server(), integer(), non_neg_integer()) ::
  {:ok, Dwrr.t(term())} | {:error, Dwrr.error()}
```

Change quantum; return the exact core result.

# `start_link`

```elixir
@spec start_link(non_neg_integer(), GenServer.options()) :: GenServer.on_start()
```

Start from count; forward standard GenServer options, including `:name`.
Restart starts fresh.

## Examples

    iex> {:ok, pid} = Dwrr.Server.start_link(1)
    iex> {:ok, _snapshot} = Dwrr.Server.enqueue(pid, 0, [%Dwrr.Item{value: :job, cost: 1}])
    iex> {:ok, items, _snapshot} = Dwrr.Server.take(pid, 1)
    iex> items
    [%Dwrr.Scheduled{queue: 0, value: :job, cost: 1}]
    iex> GenServer.stop(pid)
    :ok

# `take`

```elixir
@spec take(GenServer.server(), integer()) ::
  {:ok, [Dwrr.Scheduled.t(term())], Dwrr.t(term())} | {:error, Dwrr.error()}
```

Retrieve items; return the exact core result.

---

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