Alambic.BlockingCollection protocol

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.

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

Types

t :: term

Functions

add(bc, item)

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.

complete(bc)

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.

count(bc)

Specs

count(t) :: integer

Return the number of items in the collection.

take(bc)

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
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.

try_take(bc)

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