Alambic.BlockingQueue (alambic v1.1.0)

A queue hosted in a process so that other processes can access it concurrently. It implements the BlockingCollection protocol. Enumerating a BlockingQueue will consumes it content. Enumeration only complete when the BlockingQueue is empty and BlockingQueue.complete/1 has been called on the BlockingQueue.

It is implemented as a GenServer.

If you need to start a named BlockingQueue as part of a supervision tree, you can directly use the GenServer.start/start_link functions.

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Signal the collection will no longer accept items.

Return the number of items in the queue.

Create a BlockingQueue with a given limit on the numbers of items it can contain.

Create a BlockingQueue linked to the current process.

Dequeue one item from the queue. If no item is available, will wait until some data is available.

Destroy a BlockingQueue, losing all its current messages.

Enqueue some value. If the queue currently contains the maximum number of elements allowed, it will block until at least one item has been consumed.

Callback implementation for GenServer.init/1.

Try to dequeue some data from the queue. If one item is available {true, item} is returned, false otherwise.

Try to add an item to the queue. Will never block.

Link to this section Types

Specs

t() :: %Alambic.BlockingQueue{id: nil | pid()}

Link to this section Functions

Link to this function

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

complete(blocking_queue)

Specs

complete(t()) :: :ok

Signal the collection will no longer accept items.

Example

iex> q = Alambic.BlockingQueue.create()
iex> :ok = Alambic.BlockingQueue.complete(q)
iex> :completed = Alambic.BlockingQueue.dequeue(q)
iex> {false, :completed} = Alambic.BlockingQueue.try_dequeue(q)
iex> Alambic.BlockingQueue.enqueue(q, :item)
:error
Link to this function

count(blocking_queue)

Return the number of items in the queue.

Example

iex> q = Alambic.BlockingQueue.create()
iex> 0 = Alambic.BlockingQueue.count(q)
iex> :ok = Alambic.BlockingQueue.enqueue(q, :data)
iex> :ok = Alambic.BlockingQueue.enqueue(q, :data)
iex> :ok = Alambic.BlockingQueue.enqueue(q, :data)
iex> Alambic.BlockingQueue.count(q)
3
Link to this function

create(max \\ :unlimited)

Specs

create(integer() | :unlimited) :: t()

Create a BlockingQueue with a given limit on the numbers of items it can contain.

Example

iex> %Alambic.BlockingQueue{id: pid} = Alambic.BlockingQueue.create()
iex> is_pid(pid)
true
Link to this function

create_link(max \\ :unlimited)

Specs

create_link(integer() | :unlimited) :: t()

Create a BlockingQueue linked to the current process.

Example

iex> %Alambic.BlockingQueue{id: pid} = Alambic.BlockingQueue.create_link()
iex> is_pid(pid)
true
Link to this function

dequeue(blocking_queue)

Specs

dequeue(t()) :: {:ok, term()} | :error | :completed

Dequeue one item from the queue. If no item is available, will wait until some data is available.

Example

iex> q = Alambic.BlockingQueue.create()
iex> :ok = Alambic.BlockingQueue.enqueue(q, :data1)
iex> :ok = Alambic.BlockingQueue.enqueue(q, :data2)
iex> Alambic.BlockingQueue.dequeue(q)
{:ok, :data1}
Link to this function

destroy(blocking_queue)

Specs

destroy(t()) :: :ok

Destroy a BlockingQueue, losing all its current messages.

Example

iex> queue = Alambic.BlockingQueue.create
iex> Alambic.BlockingQueue.destroy(queue)
:ok
Link to this function

enqueue(blocking_queue, item)

Specs

enqueue(t(), term()) :: :ok | :error

Enqueue some value. If the queue currently contains the maximum number of elements allowed, it will block until at least one item has been consumed.

Example

iex> q = Alambic.BlockingQueue.create()
iex> Alambic.BlockingQueue.enqueue(q, :some_data)
:ok

Callback implementation for GenServer.init/1.

Link to this function

try_dequeue(blocking_queue)

Specs

try_dequeue(t()) :: {true, term()} | {false, :empty | :error | :completed}

Try to dequeue some data from the queue. If one item is available {true, item} is returned, false otherwise.

Example

iex> q = Alambic.BlockingQueue.create()
iex> {false, :empty} = Alambic.BlockingQueue.try_dequeue(q)
iex> :ok = Alambic.BlockingQueue.enqueue(q, :data)
iex> Alambic.BlockingQueue.try_dequeue(q)
{true, :data}
Link to this function

try_enqueue(blocking_queue, item)

Specs

try_enqueue(t(), term()) :: true | false

Try to add an item to the queue. Will never block.

Example

iex> q = Alambic.BlockingQueue.create(1)
iex> :ok = Alambic.BlockingQueue.enqueue(q, :item)
iex> Alambic.BlockingQueue.try_enqueue(q, :item)
false