com.stepsoncats.gublists
Class FlexPipe

java.lang.Object
  |
  +--com.stepsoncats.gublists.FlexPipe

Direct Known Subclasses:

ByteArrayPipe, InetReqPipe

public class FlexPipe

extends java.lang.Object

A FlexPipe is a FIFO linked list with one reader and one or more writers that behaves like a pipe. A thread registers itself as a FlexPipe's reader either explicitly or else implicitly on its initial attempt to read from the pipe. The reader of a FlexPipe remains its registered reader until it explicitly detaches itself from the pipe; any attempt to read from a pipe by any thread other than the registered reader (if any) throws an IllegalStateException. Reading an item from a FlexPipe removes the oldest item in the list. The readItem method always blocks the reader until the list contains at least one item. A non-blocking pollForItem method is also provided. Writing an item to a FlexPipe appends the item to the pipe's linked list and unblocks the reader. Writing an item to a FlexPipe never blocks the writer, as is possible when writing to PipedOutput; a slow reader merely causes the list length to increase. This means that a FlexPipe can easily handle arbitrarily spiky traffic, so long as the reader always eventually catches up. (For flow-controlled inter-thread communication, use PipedOutput and PipedInput.) Any item that's written to a FlexPipe which currently has no registered reader is simply discarded. This relieves the pipe's writer(s) of responsibility for ensuring that an unconstrained pipe doesn't grow endlessly and consume all memory.

Constructor Summary

protected

FlexPipe() Construct an empty FlexPipe with no registered reader.

Method Summary

void	attach() Register the calling thread as the pipe's sole reader.
void	detach() Unregister the pipe's currently registered reader, if any.
protected java.lang.Object	pollForItem() Extract from the pipe the object that has been in the pipe the longest, if any.
protected java.lang.Object	readItem() Extract from the pipe the object that has been in the pipe the longest.
protected void	writeItem(java.lang.Object item) Append a new object to the pipe.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FlexPipe

protected FlexPipe()

Construct an empty FlexPipe with no registered reader.

Method Detail

attach

public void attach()

Register the calling thread as the pipe's sole reader. The method throws an IllegalStateException if some other thread is already registered as the pipe's reader.

detach

public void detach()

Unregister the pipe's currently registered reader, if any.

writeItem

protected void writeItem(java.lang.Object item)

Append a new object to the pipe. Any thread can write to any FlexPipe at any time. Note, though, that nothing is actually appended to a pipe while that pipe has no registered reader.

Parameters:

item - The object to write to the pipe.

readItem

protected java.lang.Object readItem()
                             throws java.lang.InterruptedException

Extract from the pipe the object that has been in the pipe the longest. The method blocks until there is at least one object in the pipe. Automatically attaches the calling thread as the pipe's reader.

Returns:

The oldest object in the pipe.

pollForItem

protected java.lang.Object pollForItem()
                                throws java.lang.InterruptedException

Extract from the pipe the object that has been in the pipe the longest, if any. If the pipe is empty, the method immediately returns null. Automatically attaches the calling thread as the pipe's reader in any case.

Returns:

The oldest object in the pipe, or null if the pipe is empty.