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