Alambic.BlockingCollection protocol (alambic v1.1.0)

Interface to a blocking collection.

A blocking collection is a collection of items where:

  • multiple processes can push data into the collecion
  • multiple processes can consume items from the collection
  • a blocking collection may be "completed" meaning it will not accept any more items.
  • getting data blocks until some data is availbale or the collection is "omplete" (will not receive any more data)
  • putting data may block until some room is available in the collection for more data (blocking collections can either accept unlimited amount of items or limit the number of items they can hold)

BlockingCollection also implements the Enumerable protocol and using functions from the Enum and Stream module is the preferred way of consuming a blocking collection. Enumerating a blocking collection will consume its items, so if multiple processes are enumerating a blocking collection at the same time, they will only see a subset of the items added to the collection.

Link to this section Summary

Functions

Add an item to the collection. May block until some room is available in the collection.

Put the collection in the completed state, where it will not accept any more items but will serve those currently inside the collection.

Return the number of items in the collection.

Get an item from the collection. If no item is available, will block until an item is available or the collection has been completed.

Try to add an item in the collection. Will return true if the item was added, false if the collection cannot accept items at the moment.

Try to get an item from the collection. Do not block.

Link to this section Types

Specs

t() :: term()

Link to this section Functions

Specs

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

Add an item to the collection. May block until some room is available in the collection.

Return :ok if adding was successful, :error if some internal error occured or the collection does not accept items any more.

Specs

complete(t()) :: :ok | :error

Put the collection in the completed state, where it will not accept any more items but will serve those currently inside the collection.

Specs

count(t()) :: integer()

Return the number of items in the collection.

Specs

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

Get an item from the collection. If no item is available, will block until an item is available or the collection has been completed.

Return:

  • {:ok, item} when an item is available
  • :completed when the collection has been completed
  • :error if some error occurred
Link to this function

try_add(bc, item)

Specs

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

Try to add an item in the collection. Will return true if the item was added, false if the collection cannot accept items at the moment.

Specs

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

Try to get an item from the collection. Do not block.

Return:

  • {true, item} if some item was found
  • {false, reason} if not item could be returned. reason maybe:
    • :completed if the collection is completed
    • :error if an error occurred
    • :empty if the collection is currenlty empty