time_queue v0.2.0 TimeQueue

This is the single module of the TimeQueue library.

Link to this section Summary

Functions

Deletes an entry from the queue and returns the new queue.

Adds a new entry to the queue with a TTL and the current system time as now.

Adds a new entry to the queue with a TTL relative to the given timestamp in milliseconds.

Adds a new entry to the queue with an absolute timestamp.

Creates an empty time queue.

Returns the next event of the queue with the current system time as now.

Returns the next event of the queue according to the given current time in milliseconds.

Extracts the next event of the queue with the current system time as now.

Extracts the next event of the queue according to the given current time in milliseconds.

Returns the value of an queue entry.

Link to this section Types

Link to this opaque

entry()

(opaque)
entry()
Link to this opaque

t()

(opaque)
t()
Link to this type

timespec()

timespec() :: {pos_integer(), timespec_unit()}
Link to this type

timespec_unit()

timespec_unit() ::
  :ms
  | :second
  | :seconds
  | :minute
  | :minutes
  | :hour
  | :hours
  | :day
  | :days
  | :week
  | :weeks
Link to this opaque

tref()

(opaque)
tref()
Link to this type

ttl()

ttl() :: timespec() | integer()

Link to this section Functions

Link to this function

delete(tq, arg)

delete(t(), entry()) :: t()

Deletes an entry from the queue and returns the new queue.

The function does not fail if the entry was not found and simply returns the queue as-is.

Link to this function

enqueue(tq, ttl, val)

enqueue(t(), ttl(), any()) :: {:ok, tref(), t()}

Adds a new entry to the queue with a TTL and the current system time as now.

See enqueue/4.

Link to this function

enqueue(tq, ttl, val, now_ms)

enqueue(t(), ttl(), any(), now :: integer()) :: {:ok, tref(), t()}

Adds a new entry to the queue with a TTL relative to the given timestamp in milliseconds.

Returns {:ok, tref, new_queue} where tref is a timer reference (not used yed).

Link to this function

enqueue_abs(tq, ts, val)

enqueue_abs(t(), end_time :: integer(), value :: any()) :: {:ok, tref(), t()}

Adds a new entry to the queue with an absolute timestamp.

Returns {:ok, tref, new_queue} where tref is a timer reference (not used yed).

Link to this function

new()

new() :: t()

Creates an empty time queue.

iex> tq = TimeQueue.new()
iex> TimeQueue.peek(tq)
:empty
Link to this function

peek(tq)

peek(t()) :: :empty | {:delay, non_neg_integer()} | {:ok, entry()}

Returns the next event of the queue with the current system time as now.

See peek/2.

Link to this function

peek(tq, now)

peek(t(), now_ms :: pos_integer()) ::
  :empty | {:delay, non_neg_integer()} | {:ok, entry()}

Returns the next event of the queue according to the given current time in milliseconds.

Possible return values are:

  • :empty
  • {:ok, entry} if the timestamp of the first entry is <= to the given current time.
  • {:delay, ms} if the timestamp of the first entry is > to the given current time. The remaining amount of milliseconds is returned.

Example

iex> {:ok, _tref, tq} = TimeQueue.new() |> TimeQueue.enqueue(100, :hello, _now = 0)
iex> TimeQueue.peek(tq, _now = 20)
{:delay, 80}
iex> {:ok, _} = TimeQueue.peek(tq, _now = 100)
Link to this function

pop(tq)

pop(t()) :: :empty | {:delay, non_neg_integer()} | {:ok, entry()}

Extracts the next event of the queue with the current system time as now.

See pop/2.

Link to this function

pop(tq, now)

pop(t(), now_ms :: pos_integer()) ::
  :empty | {:delay, non_neg_integer()} | {:ok, entry()}

Extracts the next event of the queue according to the given current time in milliseconds.

Possible return values are:

  • :empty
  • {:ok, entry, new_queue} if the timestamp of the first entry is <= to the given current time. The entry is deleted from new_queue.
  • {:delay, ms} if the timestamp of the first entry is > to the given current time. The remaining amount of milliseconds is returned.

Example

iex> {:ok, _tref, tq} = TimeQueue.new() |> TimeQueue.enqueue(100, :hello, _now = 0)
iex> TimeQueue.pop(tq, _now = 20)
{:delay, 80}
iex> {:ok, _, _} = TimeQueue.pop(tq, _now = 100)
Link to this function

value(arg)

value(entry()) :: any()

Returns the value of an queue entry.

iex> tq = TimeQueue.new()
iex> {:ok, _, tq} = TimeQueue.enqueue(tq, 10, :my_value)
iex> Process.sleep(10)
iex> {:ok, entry} = TimeQueue.peek(tq)
iex> TimeQueue.value(entry)
:my_value