Control.Concurrent.Chan.Unagi.Bounded

Read an element from the chan, blocking if the chan is empty.

Note re. exceptions: When an async exception is raised during a readChan the message that the read would have returned is likely to be lost, even when the read is known to be blocked on an empty queue. If you need to handle this scenario, you can use readChanOnException.

Like readChan but allows recovery of the queue element which would have been read, in the case that an async exception is raised during the read. To be precise exceptions are raised, and the handler run, only when readChanOnException is blocking.

The second argument is a handler that takes a blocking IO action returning the element, and performs some recovery action. When the handler is called, the passed IO a is the only way to access the element.

Returns immediately with:

• an Element a future, which returns one unique element when it becomes available via tryRead.

• a blocking IO action that returns the element when it becomes available.

Note: This is a destructive operation. See Element for more details.

Note re. exceptions: When an async exception is raised during a tryReadChan the message that the read would have returned is likely to be lost, just as it would be when raised directly after this function returns.

An IO action that returns a particular enqueued element when and if it becomes available.

Each Element corresponds to a particular enqueued element, i.e. a returned Element always offers the only means to access one particular enqueued item. The value returned by tryRead moves monotonically from Nothing to Just a when and if an element becomes available, and is idempotent at that point.

So for instance:

   (in, out) <- newChan
   (el, _) <- tryReadChan out  -- READ FROM EMPTY CHAN
   writeChan in "msg1"
   writeChan in "msg2"
   readChan out        -- RETURNS "msg2"
   tryRead el          -- RETURNS "msg1" (which would otherwise be lost)

Return a lazy infinite list representing the contents of the supplied OutChan, much like System.IO.hGetContents.

Return the estimated length of a bounded queue

The more concurrent writes and reads that are happening, the more inaccurate the estimate of the chan's size is likely to be.

Write a value to the channel. If the chan is full this will block.

To be precise this may block when the number of elements in the queue >= size, and will certainly block when >= size*2, where size is the argument passed to newChan, rounded up to the next highest power of two.

Note re. exceptions: In the case that an async exception is raised while blocking here, the write will nonetheless succeed. When not blocking, exceptions are masked. Thus writes always succeed once writeChan is entered.

Try to write a value to the channel, aborting if the write is likely to exceed the bounds, returning a Bool indicating whether the write was successful.

This function never blocks, but may occasionally write successfully to a queue that is already "full". Unlike writeChan this function treats the requested bounds (raised to nearest power of two) strictly, rather than using the n .. n*2 range. The more concurrent writes and reads that are happening, the more inaccurate the estimate of the chan's size is likely to be.

Write an entire list of items to a chan type. Writes here from multiple threads may be interleaved, and infinite lists are supported.

Duplicate a chan: the returned OutChan begins empty, but data written to the argument InChan from then on will be available from both the original OutChan and the one returned here, creating a kind of broadcast channel.

Writers will be blocked only when the fastest reader falls behind the bounds; slower readers of duplicated OutChan may fall arbitrarily behind.