Alambic.BlockingQueue

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.

Summary

Functions

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, loosing all its current messages

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

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

Types

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

Functions

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
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
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
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
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}
destroy(blocking_queue)

Specs

destroy(t) :: :ok

Destroy a BlockingQueue, loosing all its current messages.

Example

iex> queue = Alambic.BlockingQueue.create
iex> Alambic.BlockingQueue.destroy(queue)
:ok
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 item has been consumed.

Example

iex> q = Alambic.BlockingQueue.create()
iex> Alambic.BlockingQueue.enqueue(q, :some_data)
:ok
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}
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