rasa/queue

This module provides a Queue built using a Table. Queues created by this module are built using ordered_set ETS tables. Ordered sets use a binary search tree so insert and lookups are performed in logarithmic time. These operations will take longer as the queue grows in size.

Queues require a Counter to generate integer keys for the underlying Table. You can use the counter module to define custom counters, or use one of the counters defined in that module.

If using counter.atomic, each new integer value is 1 greater than the previous. Atomic counters are backed by erlang atomics and are therefore guaranteed atomicity.

If using counter.monotonic, each new value is a strictly monotonically increasing unique integer backed by erlang’s unique_integer/1. Consecutive calls to queue.push are guaranteed to produce unique indices.

If using counter.monotonic_time, each new value comes from calling monotonic_time with the specified time unit. Since monotonic_time can produce the same result from consecutive calls, it is possible for calls to queue.push to return an error if that index key was previously inserted into the queue.

Types

Builder

opaque </>

A Queue builder. Defaults to Protected access and an atomic integer counter.

pub opaque type Builder

Queue

opaque </>

A FIFO queue backed by an ordered ETS table. Values are indexed by a Counter.

pub opaque type Queue(a)

Values

at

</>

pub fn at(queue: Queue(a), index: Int) -> Result(a, Nil)

Returns the value stored in the queue at a given index.

build

</>

pub fn build(builder: Builder) -> Queue(a)

Returns a new Queue configured according to the provided Builder. The underlying table is always an OrderedSet.

delete

</>

pub fn delete(queue: Queue(a), index: Int) -> Result(Nil, Nil)

Removes the item at the given index from the queue. Succeeds even if the index does not exist in the queue.

drop

</>

pub fn drop(queue: Queue(a)) -> Result(Nil, Nil)

Deletes the queue.

first

</>

pub fn first(queue: Queue(a)) -> Result(#(Int, a), Nil)

Returns the first item in the queue without removing it from the queue.

is_empty

</>

pub fn is_empty(queue: Queue(a)) -> Bool

Determines whether the queue is empty. Returns True if the underlying table does not exist.

last

</>

pub fn last(queue: Queue(a)) -> Result(#(Int, a), Nil)

Returns the last item in the queue without removing it from the queue.

new

</>

pub fn new() -> Builder

Returns a new Builder, defaulting to Protected access and an atomic integer counter.

pop

</>

pub fn pop(queue: Queue(a)) -> Result(a, Nil)

Removes and returns the queue’s first value. Returns Error(Nil) if the queue is empty.

For Public queues accessed from multiple processes, if another process removes the first entry between the lookup and the removal, the operation retries from the new first entry.

push

</>

pub fn push(queue: Queue(a), value: a) -> Result(Int, Nil)

Inserts a value into the queue. Returns the index assigned to the value. For queues using a counter that doesn’t guarantee new values on each next call, push can return an error if a previously used index key is reused.

size

</>

pub fn size(queue: Queue(a)) -> Result(Int, Nil)

Returns the number of items in the queue.

to_list

</>

pub fn to_list(queue: Queue(a)) -> Result(List(a), Nil)

Returns the queue’s values as a list in insertion order.

with_access

</>

pub fn with_access(
  builder: Builder,
  access: table.Access,
) -> Builder

Sets the access level on the Builder.

with_counter

</>

pub fn with_counter(
  builder: Builder,
  counter: counter.Counter,
) -> Builder

Sets the counter on the Builder.