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: IBlockingBuffer.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Method Summary

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.

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.

Parameters:

future - The Future.

Throws:

IllegalArgumentException - if the argument is null.

IllegalStateException - if the future has already been set.

TODO:

There should be a generic type for this.