com.bigdata.relation.accesspath

Interface IBlockingBuffer<E>

Type Parameters:

E - The generic type of the elements in the chunks.

All Superinterfaces:

IBuffer<E>, IRunnableBuffer<E>

All Known Implementing Classes:

BlockingBuffer, BlockingBufferWithStats, DelegateBuffer, OutputStatsBuffer

public interface IBlockingBuffer<E>
extends IRunnableBuffer<E>

Interface provides an iterator to drain chunks from an IBuffer.

CONOPS

This interface is useful where one (or more) processes will write asynchronously on the IBuffer while another drains it via the iterator(). For better performance in a multi-threaded environment, each thread is given an UnsynchronizedArrayBuffer of some capacity. The threads populate their UnsynchronizedArrayBuffers in parallel using non-blocking operations. The UnsynchronizedArrayBuffers in turn are configured to flush chunks of elements onto an either an IBuffer whose generic type is E[]. Each element in the target IBuffer is therefore a chunk of elements from one of the source UnsynchronizedArrayBuffers.

There are two families of synchronized IBuffers

1. An IBuffer that targets a mutable IRelation;
and
2. An IBlockingBuffer that exposes an IAsynchronousIterator for reading chunks of elements.

This design means that blocking operations are restricted to chunk-at-a-time operations, primarily when an UnsynchronizedArrayBuffer<E> overflows onto an IBuffer<<E[]> and when the IBuffer<<E[]> either is flushed onto an IMutableRelation or drained by an IChunkedIterator.

Version:

$Id$

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
long	flush() This is a NOP since the iterator() is the only way to consume data written on the buffer.
IAsynchronousIterator<E>	iterator() Return an iterator reading from the buffer.
void	setFuture(Future future) Set the Future for the source processing writing on the IBlockingBuffer (the producer).

Methods inherited from interface com.bigdata.relation.accesspath.IRunnableBuffer

abort, add, close, getFuture, isOpen

Methods inherited from interface com.bigdata.relation.accesspath.IBuffer

isEmpty, reset, size

Method Detail

iterator

IAsynchronousIterator<E> iterator()

Return an iterator reading from the buffer. It is NOT safe for concurrent processes to consume the iterator. The iterator will visit elements in the order in which they were written on the buffer, but note that the elements may be written onto the IBlockingBuffer by concurrent processes in which case the order is not predictable without additional synchronization.

Returns:

The iterator.

flush

long flush()

This is a NOP since the iterator() is the only way to consume data written on the buffer.

Specified by:

flush in interface IBuffer<E>

Returns:

ZERO (0L)

setFuture

void setFuture(Future future)

Set the Future for the source processing writing on the IBlockingBuffer (the producer).

Note: You should always wrap the task as a FutureTask and set the Future on the IBlockingBuffer before you start the consumer. This ensures that the producer will be cancelled if the consumer is interrupted.

Parameters:

future - The Future.

Throws:

IllegalArgumentException - if the argument is null.

IllegalStateException - if the future has already been set.

See Also:

BlockingBuffer.close() does not unblock threads