Vert.x 4.5.13 · io.vertx.core.streams.impl.InboundBuffer

A buffer that transfers elements to an handler with back-pressure.

The buffer is softly bounded, i.e the producer can write any number of elements and shall cooperate with the buffer to not overload it.

Writing to the buffer

When the producer writes an element to the buffer, the boolean value returned by the write method indicates whether it can continue safely adding more elements or stop.

The producer can set a drainHandler to be signaled when it can resume writing again. When a write returns false, the drain handler will be called when the buffer becomes writable again. Note that subsequent call to write will not prevent the drain handler to be called.

Reading from the buffer

The consumer should set an handler to consume elements.

Buffer mode

The buffer is either in flowing or fetch mode.

Initially the buffer is in flowing mode.

When the buffer is in flowing mode, elements are delivered to the handler.
When the buffer is in fetch mode, only the number of requested elements will be delivered to the handler.

The mode can be changed with the pause(), resume() and fetch methods:

Calling resume() sets the flowing mode
Calling pause() sets the fetch mode and resets the demand to 0
Calling fetch(long) requests a specific amount of elements and adds it to the actual demand

Concurrency

To avoid data races, write methods must be called from the context thread associated with the buffer, when that's not the case, an IllegalStateException is thrown.

Other methods can be called from any thread.

The handlers will always be called from a context thread.

Warning

this class is mostly useful for implementing the io.vertx.core.streams.ReadStream and has little or no use within a regular application.

Field Summary

Modifier and Type	Field and Description
private final ContextInternal	context
private long	demand
private Handler<Void>	drainHandler
private boolean	emitting
private Handler<Void>	emptyHandler
public static final Object	END_SENTINEL A reusable sentinel for signaling the end of a stream.
private Handler<Throwable>	exceptionHandler
private Handler<E>	handler
private final long	highWaterMark
private boolean	overflow
private ArrayDeque<E>	pending

Constructor Summary

Access	Constructor and Description
public	InboundBuffer(Context context)
public	InboundBuffer(Context context, long highWaterMark)
private	InboundBuffer(Context context, long highWaterMark, long demand, Handler<Void> drainHandler, Handler<E> handler)

Method Summary

Modifier and Type	Method and Description
private void	asyncDrain()
private static void	checkPositiveAmount(long amount)
private void	checkThread()
private boolean	checkWritable()
public synchronized InboundBuffer<E>	Returns: a reference to this, so the API can be used fluently clear() Clear the buffer synchronously.
public static <E> InboundBuffer<E>	createAndFetch(Context context, long highWaterMark, long demand, Handler<Void> drainHandler, Handler<E> handler)
public static <E> InboundBuffer<E>	createPaused(Context context, long highWaterMark, Handler<Void> drainHandler, Handler<E> handler)
private void	drain() Drain the buffer.
public synchronized InboundBuffer<E>	Returns: a reference to this, so the API can be used fluently drainHandler(Handler<Void> the handler to be called handler) Set an `handler` to be called when the buffer is drained and the producer can resume writing to the buffer.
private boolean	emit(long amount)
private boolean	emitPending()
public synchronized InboundBuffer<E>	Returns: a reference to this, so the API can be used fluently emptyHandler(Handler<Void> the handler to be called handler) Set an `handler` to be called when the buffer becomes empty.
public synchronized InboundBuffer<E>	Returns: a reference to this, so the API can be used fluently exceptionHandler(Handler<Throwable> the handler handler) Set an `handler` to be called when an exception is thrown by an handler.
public boolean	Returns: `true` when the buffer will be drained fetch(long amount) Request a specific `amount` of elements to be fetched, the amount is added to the actual demand.
private <T> void	handleEvent(Handler<T> handler, T element)
private void	handleException(Throwable err)
public synchronized InboundBuffer<E>	Returns: a reference to this, so the API can be used fluently handler(Handler<E> the handler handler) Set an `handler` to be called with elements available from this buffer.
public synchronized boolean	Returns: whether the buffer is empty isEmpty()
public synchronized boolean	Returns: whether the buffer is paused, i.e it is in `fetch` mode and the demand is `0`. isPaused()
public synchronized boolean	Returns: whether the buffer is writable isWritable()
public synchronized InboundBuffer<E>	Returns: a reference to this, so the API can be used fluently pause() Pause the buffer, it sets the buffer in `fetch` mode and clears the actual demand.
public E	Returns: the most recent element or `null` if no element was in the buffer read() Read the most recent element synchronously.
public boolean	Returns: `true` when the buffer will be drained resume() Resume the buffer, and sets the buffer in `flowing` mode.
public synchronized int	Returns: the actual number of elements in the buffer size()
public boolean	Returns: `false` when the producer should stop writing write(E the element to add element) Write an `element` to the buffer.
public boolean	Returns: `false` when the producer should stop writing write(Iterable<E> the elements to add elements) Write an `iterable` of `elements`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

context	back to summary
private final ContextInternal context

demand	back to summary
private long demand

drainHandler	back to summary
private Handler<Void> drainHandler

emitting	back to summary
private boolean emitting

emptyHandler	back to summary
private Handler<Void> emptyHandler

END_SENTINEL	back to summary
public static final Object END_SENTINEL A reusable sentinel for signaling the end of a stream.

exceptionHandler	back to summary
private Handler<Throwable> exceptionHandler

handler	back to summary
private Handler<E> handler

highWaterMark	back to summary
private final long highWaterMark

overflow	back to summary
private boolean overflow

pending	back to summary
private ArrayDeque<E> pending

Constructor Detail

InboundBuffer	back to summary
public InboundBuffer(Context context)

InboundBuffer	back to summary
public InboundBuffer(Context context, long highWaterMark)

InboundBuffer	back to summary
private InboundBuffer(Context context, long highWaterMark, long demand, Handler<Void> drainHandler, Handler<E> handler)

Method Detail

asyncDrain	back to summary
private void asyncDrain()

checkPositiveAmount	back to summary
private static void checkPositiveAmount(long amount)

checkThread	back to summary
private void checkThread()

checkWritable	back to summary
private boolean checkWritable()

clear	back to summary
public synchronized InboundBuffer<E> clear() Clear the buffer synchronously. No handler will be called. Returns:InboundBuffer<E> a reference to this, so the API can be used fluently

clear

back to summary

public synchronized InboundBuffer<E> clear()

Clear the buffer synchronously.

No handler will be called.

Returns:InboundBuffer<E>: a reference to this, so the API can be used fluently

createAndFetch	back to summary
public static <E> InboundBuffer<E> createAndFetch(Context context, long highWaterMark, long demand, Handler<Void> drainHandler, Handler<E> handler)

createPaused	back to summary
public static <E> InboundBuffer<E> createPaused(Context context, long highWaterMark, Handler<Void> drainHandler, Handler<E> handler)

drain back to summary

drain	back to summary
private void drain() Drain the buffer. Calling this assumes `(demand > 0L && !pending.isEmpty()) == true`

private void drain()

Drain the buffer.

Calling this assumes (demand > 0L && !pending.isEmpty()) == true

drainHandler back to summary

drainHandler	back to summary
public synchronized InboundBuffer<E> drainHandler(Handler<Void> handler) Set an `handler` to be called when the buffer is drained and the producer can resume writing to the buffer. Parameters handler:Handler<Void> the handler to be called Returns:InboundBuffer<E> a reference to this, so the API can be used fluently

public synchronized InboundBuffer<E> drainHandler(Handler<Void> handler)

Set an handler to be called when the buffer is drained and the producer can resume writing to the buffer.

Parameters

handler:Handler<Void>: the handler to be called

Returns:InboundBuffer<E>

a reference to this, so the API can be used fluently

emit	back to summary
private boolean emit(long amount)

emitPending	back to summary
private boolean emitPending()

emptyHandler back to summary

emptyHandler	back to summary
public synchronized InboundBuffer<E> emptyHandler(Handler<Void> handler) Set an `handler` to be called when the buffer becomes empty. Parameters handler:Handler<Void> the handler to be called Returns:InboundBuffer<E> a reference to this, so the API can be used fluently

public synchronized InboundBuffer<E> emptyHandler(Handler<Void> handler)

Set an handler to be called when the buffer becomes empty.

Parameters

handler:Handler<Void>: the handler to be called

Returns:InboundBuffer<E>

a reference to this, so the API can be used fluently

exceptionHandler back to summary

exceptionHandler	back to summary
public synchronized InboundBuffer<E> exceptionHandler(Handler<Throwable> handler) Set an `handler` to be called when an exception is thrown by an handler. Parameters handler:Handler<Throwable> the handler Returns:InboundBuffer<E> a reference to this, so the API can be used fluently

public synchronized InboundBuffer<E> exceptionHandler(Handler<Throwable> handler)

Set an handler to be called when an exception is thrown by an handler.

Parameters

handler:Handler<Throwable>: the handler

Returns:InboundBuffer<E>

a reference to this, so the API can be used fluently

fetch back to summary

fetch	back to summary
public boolean fetch(long amount) Request a specific `amount` of elements to be fetched, the amount is added to the actual demand. Pending elements in the buffer will be delivered asynchronously on the context to the handler. This method can be called from any thread. Returns:boolean `true` when the buffer will be drained

public boolean fetch(long amount)

Request a specific amount of elements to be fetched, the amount is added to the actual demand.

Pending elements in the buffer will be delivered asynchronously on the context to the handler.

This method can be called from any thread.

Returns:boolean: true when the buffer will be drained

handleEvent	back to summary
private <T> void handleEvent(Handler<T> handler, T element)

handleException	back to summary
private void handleException(Throwable err)

handler back to summary

handler	back to summary
public synchronized InboundBuffer<E> handler(Handler<E> handler) Set an `handler` to be called with elements available from this buffer. Parameters handler:Handler<E> the handler Returns:InboundBuffer<E> a reference to this, so the API can be used fluently

public synchronized InboundBuffer<E> handler(Handler<E> handler)

Set an handler to be called with elements available from this buffer.

Parameters

handler:Handler<E>: the handler

Returns:InboundBuffer<E>

a reference to this, so the API can be used fluently

isEmpty	back to summary
public synchronized boolean isEmpty() Returns:boolean whether the buffer is empty

isPaused	back to summary
public synchronized boolean isPaused() Returns:boolean whether the buffer is paused, i.e it is in `fetch` mode and the demand is `0`.

isWritable	back to summary
public synchronized boolean isWritable() Returns:boolean whether the buffer is writable

pause back to summary

pause	back to summary
public synchronized InboundBuffer<E> pause() Pause the buffer, it sets the buffer in `fetch` mode and clears the actual demand. Returns:InboundBuffer<E> a reference to this, so the API can be used fluently

public synchronized InboundBuffer<E> pause()

Pause the buffer, it sets the buffer in fetch mode and clears the actual demand.

Returns:InboundBuffer<E>: a reference to this, so the API can be used fluently

read back to summary

read	back to summary
public E read() Read the most recent element synchronously. No handler will be called. Returns:E the most recent element or `null` if no element was in the buffer

public E read()

Read the most recent element synchronously.

No handler will be called.

Returns:E: the most recent element or null if no element was in the buffer

resume back to summary

resume	back to summary
public boolean resume() Resume the buffer, and sets the buffer in `flowing` mode. Pending elements in the buffer will be delivered asynchronously on the context to the handler. This method can be called from any thread. Returns:boolean `true` when the buffer will be drained

public boolean resume()

Resume the buffer, and sets the buffer in flowing mode.

Pending elements in the buffer will be delivered asynchronously on the context to the handler.

This method can be called from any thread.

Returns:boolean: true when the buffer will be drained

size	back to summary
public synchronized int size() Returns:int the actual number of elements in the buffer

write back to summary

write	back to summary
public boolean write(E element) Write an `element` to the buffer. The element will be delivered synchronously to the handler when it is possible, otherwise it will be queued for later delivery. Parameters element:E the element to add Returns:boolean `false` when the producer should stop writing

public boolean write(E element)

Write an element to the buffer. The element will be delivered synchronously to the handler when it is possible, otherwise it will be queued for later delivery.

Parameters

element:E: the element to add

Returns:boolean

false when the producer should stop writing

write back to summary

write	back to summary
public boolean write(Iterable<E> elements) Write an `iterable` of `elements`. Parameters elements:Iterable<E> the elements to add Returns:boolean `false` when the producer should stop writing See Also `write(E)`

public boolean write(Iterable<E> elements)

Write an iterable of elements.

Parameters

elements:Iterable<E>: the elements to add

Returns:boolean

false when the producer should stop writing

See Also

write(E)

public Class InboundBuffer<E>

Writing to the buffer

Reading from the buffer

Buffer mode

Concurrency

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail