rasa/queue

This module provides a Queue built using a rasa.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 that provide ever-increasing integer values used as keys for the underlying rasa.Table. If using counter.atomic, each new integer value is 1 greater than the previous. Atomic counters are backed by erlang counters and are therefore guaranteed atomicity.

If using counter.monotonic, 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 </>

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(name: String) -> Builder

Creates a new Builder with the given name. Defaults to Protected access.

delete

</>

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

Removes the item at the given index from 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: Builder,
  counter: counter.Counter,
) -> Queue(a)

Creates a new Queue from a Builder. This function will update the builder to specify an OrderedSet as Queues must be backed by OrderedSets.

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.

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: rasa.Access,
) -> Builder

Sets the access level on the builder.