Getting started
Copy Markdowndwrr is an immutable deficit weighted round robin scheduler for Elixir.
Use it to select work from FIFO queues with different declared-cost shares.
It does not execute jobs, measure elapsed time, or start an application process.
This guide and API reference describe dwrr 0.1.0, published from
88c8dc7.
The documentation was prepared separately from the package. Source links point
to files at that release commit, not to the later documentation edits.
Install
Requires Elixir 1.18 or later on OTP 27 or later. Add to mix.exs:
{:dwrr, "~> 0.1.0"}Run mix deps.get. There are no runtime dependencies or application children.
Schedule work
Queue indexes start at zero. Each queue initially has quantum 1. Choose cost units that match your workload (for example bytes, not an opaque priority score). Quantum is the credit granted on a visit; it is not a limit on item size.
s = Dwrr.new(2)
{:ok, s} = Dwrr.set_quantum(s, 0, 2)
{:ok, s} = Dwrr.enqueue(s, 0, [%Dwrr.Item{value: :upload, cost: 2}])
{:ok, s} = Dwrr.enqueue(s, 1, [%Dwrr.Item{value: :ping, cost: 1}])
{:ok, items, next} = Dwrr.take(s, 2)
Enum.map(items, &{&1.queue, &1.value, &1.cost})
# => [{0, :upload, 2}, {1, :ping, 1}]Keep next for subsequent operations. s remains a valid independent snapshot.
Dwrr.take/2 returns Dwrr.Scheduled structs; withdrawals return Dwrr.Item
structs instead. Values are opaque and can be any Elixir term.
Handle errors without losing state
s = Dwrr.new(1)
Dwrr.enqueue(s, 0, [%Dwrr.Item{value: :bad, cost: 0}])
# => {:error, :zero_cost}
Dwrr.take(s, 1) |> elem(1)
# => []Tagged errors return no replacement scheduler: retain the input. Enqueue is
atomic. Invalid argument domains raise ArgumentError; see Dwrr for validation
ordering and limits. Costs and quanta must be positive and at most 2^63-1.
Own the process, if you need one
The pure API needs no server. For serialized shared access, supervise
{Dwrr.Server, count} or start it explicitly:
{:ok, pid} = Dwrr.Server.start_link(1, name: :work_scheduler)
{:ok, _snapshot} = Dwrr.Server.enqueue(pid, 0, [%Dwrr.Item{value: :job, cost: 1}])
{:ok, items, _snapshot} = Dwrr.Server.take(pid, 1)
Enum.map(items, & &1.value)
# => [:job]
GenServer.stop(pid)
# => :okNaming is optional. Calls use the default 5-second GenServer.call/2 timeout.
A timeout does not imply rollback. Invalid arguments terminate the server; a
restart loses queued work and starts fresh. There is no persistence, retry,
backpressure or worker pool. Returned snapshots do not mutate the server.
Scheduling boundaries
- FIFO heads never overtake each other.
take/2preserves paused visits. - Enqueue joins an active visit; changing quantum affects the next grant and retains existing credit.
remove_head/2anddrain_queue/2withdraw without debiting credit.remove_queue/1removes only the last queue, including its backlog;add_queue/1can reuse its index.- Fairness is by declared cost under stable backlog, not wall-clock duration or an unrestricted guarantee for changing backlogs.
Continue with Dwrr for pure operations and Dwrr.Server for process ownership.