Pure deficit weighted round robin scheduler: no process, no I/O, no hidden state.

Scheduler values are immutable. Successful operations return the new scheduler, possibly with a result ({:ok, result, scheduler}). On a tagged error no new scheduler is returned: keep using the input you passed, which is unchanged. Old snapshots remain valid, so one snapshot can be branched into separate pure histories. Branches do not share writes.

Tagged errors are :invalid_index, :negative_take, :zero_cost, :cost_too_large, :zero_quantum and :quantum_too_large. Arguments outside the documented domain, such as a non-integer index or count, a negative count, or a negative cost or quantum, raise ArgumentError instead of returning a tagged error. Domain validation precedes shared error ordering: enqueue checks the integer index and entire proper list of Item structs with nonnegative integer costs first; set_quantum checks the integer index and nonnegative integer quantum first. For domain-valid arguments, an invalid index wins, then enqueue reports the first zero or oversized cost, and set_quantum reports zero or oversized quantum.

Values are opaque: the scheduler stores and returns them without inspecting them. Costs and quanta are limited to 2^63-1, and each queue's credit stays within 2^64-3. These are shared scheduler limits, not BEAM limits. Fairness is by declared cost, not time: the scheduler does not measure work, and it makes no unrestricted fairness promise for dynamic backlogs.

Queues are FIFO and never overtake a blocked head. take/2 returns up to n items in service order. Enqueue joins the active visit; set_quantum/3 changes only the next grant and keeps credit. remove_queue/1 deletes only the last queue and its items, and add_queue/1 may reuse that index. remove_head/2 and drain_queue/2 withdraw items without debiting credit.

Requires Elixir >=1.18 and OTP >=27.

Examples

Each example is an independent history.

s = Dwrr.new(1)
{:ok, s} = Dwrr.enqueue(s, 0, [%Dwrr.Item{value: :job, cost: 2}])
{:ok, served, _s} = Dwrr.take(s, 1)
result = Enum.map(served, & &1.value)
# => [:job]
s = Dwrr.new(1)
{:ok, old} = Dwrr.enqueue(s, 0, [%Dwrr.Item{value: :original, cost: 1}])
{:ok, served, _after_take} = Dwrr.take(old, 1)
{:ok, drained, _after_drain} = Dwrr.drain_queue(old, 0)
result = {Enum.map(served, & &1.value), Enum.map(drained, & &1.value)}
# => {[:original], [:original]}
s = Dwrr.new(1)
result = Dwrr.enqueue(s, 0, [%Dwrr.Item{value: :job, cost: 0}])
# => {:error, :zero_cost}

Summary

Functions

Append an empty queue; return {index, scheduler}.

Withdraw all queue items FIFO; return {:ok, items, scheduler} or {:error, code}.

Append a proper list of Item structs atomically; return {:ok, scheduler} or {:error, code}.

Create count empty queues (nonnegative integer); return the scheduler.

Withdraw one head without debiting credit; return {:ok, Item or nil, scheduler} or {:error, code}.

Remove only the last queue, discarding items; return scheduler.

Set quantum for the next grant without changing credit; return {:ok, scheduler} or {:error, code}.

Retrieve up to n Scheduled structs, preserving paused visits; return {:ok, items, scheduler} or {:error, code}.

Types

error()

@type error() ::
  :invalid_index
  | :negative_take
  | :zero_cost
  | :cost_too_large
  | :zero_quantum
  | :quantum_too_large

t(value)

@opaque t(value)

Functions

add_queue(s)

@spec add_queue(t(value)) :: {non_neg_integer(), t(value)} when value: term()

Append an empty queue; return {index, scheduler}.

Examples

iex> {index, _s} = Dwrr.add_queue(Dwrr.new(1))
iex> index
1

drain_queue(s, queue)

@spec drain_queue(t(value), integer()) ::
  {:ok, [Dwrr.Item.t(value)], t(value)} | {:error, error()}
when value: term()

Withdraw all queue items FIFO; return {:ok, items, scheduler} or {:error, code}.

Examples

iex> {:ok, items, _s} = Dwrr.drain_queue(Dwrr.new(1), 0)
iex> items
[]

enqueue(s, queue, items)

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

Append a proper list of Item structs atomically; return {:ok, scheduler} or {:error, code}.

Examples

iex> {:ok, s} = Dwrr.enqueue(Dwrr.new(1), 0, [%Dwrr.Item{value: :job, cost: 2}])
iex> {:ok, items, _s} = Dwrr.take(s, 1)
iex> items
[%Dwrr.Scheduled{queue: 0, value: :job, cost: 2}]

new(count)

@spec new(non_neg_integer()) :: t(term())

Create count empty queues (nonnegative integer); return the scheduler.

Examples

iex> s = Dwrr.new(1)
iex> Dwrr.take(s, 0) |> elem(1)
[]

remove_head(s, queue)

@spec remove_head(t(value), integer()) ::
  {:ok, Dwrr.Item.t(value) | nil, t(value)} | {:error, error()}
when value: term()

Withdraw one head without debiting credit; return {:ok, Item or nil, scheduler} or {:error, code}.

Examples

iex> {:ok, item, _s} = Dwrr.remove_head(Dwrr.new(1), 0)
iex> item
nil

remove_queue(s)

@spec remove_queue(t(value)) :: t(value) when value: term()

Remove only the last queue, discarding items; return scheduler.

Examples

iex> s = Dwrr.new(1) |> Dwrr.remove_queue()
iex> Dwrr.enqueue(s, 0, [])
{:error, :invalid_index}

set_quantum(s, queue, quantum)

@spec set_quantum(t(value), integer(), non_neg_integer()) ::
  {:ok, t(value)} | {:error, error()}
when value: term()

Set quantum for the next grant without changing credit; return {:ok, scheduler} or {:error, code}.

Examples

iex> Dwrr.set_quantum(Dwrr.new(1), 0, 0)
{:error, :zero_quantum}

take(s, n)

@spec take(t(value), integer()) ::
  {:ok, [Dwrr.Scheduled.t(value)], t(value)} | {:error, error()}
when value: term()

Retrieve up to n Scheduled structs, preserving paused visits; return {:ok, items, scheduler} or {:error, code}.

Examples

iex> Dwrr.take(Dwrr.new(1), -1)
{:error, :negative_take}