org.apache.arrow.flight

Interface OutboundStreamListener

All Known Subinterfaces:

FlightClient.ClientStreamListener, FlightProducer.ServerStreamListener

public interface OutboundStreamListener

An interface for writing data to a peer, client or server.

Method Summary

Modifier and Type	Method and Description
void	completed() Indicate that transmission is finished.
void	error(Throwable ex) Indicate an error to the client.
boolean	isReady() A hint indicating whether the client is ready to receive data without excessive buffering.
void	putMetadata(ArrowBuf metadata) Send a pure metadata message without any associated data.
void	putNext() Send the current contents of the associated VectorSchemaRoot.
void	putNext(ArrowBuf metadata) Send the current contents of the associated VectorSchemaRoot alongside application-defined metadata.
default void	setOnReadyHandler(Runnable handler) Set a callback for when the listener is ready for new calls to putNext(), i.e.
default void	setUseZeroCopy(boolean enabled) Toggle whether to ues the zero-copy write optimization.
default void	start(VectorSchemaRoot root) Start sending data, using the schema of the given VectorSchemaRoot.
default void	start(VectorSchemaRoot root, DictionaryProvider dictionaries) Start sending data, using the schema of the given VectorSchemaRoot.
void	start(VectorSchemaRoot root, DictionaryProvider dictionaries, IpcOption option) Start sending data, using the schema of the given VectorSchemaRoot.

Method Detail

isReady

boolean isReady()

A hint indicating whether the client is ready to receive data without excessive buffering.

Writers should poll this flag before sending data to respect backpressure from the client and avoid sending data faster than the client can handle. Ignoring this flag may mean that the server will start consuming excessive amounts of memory, as it may buffer messages in memory.

setOnReadyHandler

default void setOnReadyHandler(Runnable handler)

Set a callback for when the listener is ready for new calls to putNext(), i.e. isReady() has become true.

Note that this callback may only be called some time after isReady() becomes true, and may never be called if all executor threads on the server are busy, or the RPC method body is implemented in a blocking fashion. Note that isReady() must still be checked after the callback is run as it may have been run spuriously.

start

default void start(VectorSchemaRoot root)

Start sending data, using the schema of the given VectorSchemaRoot.

This method must be called before all others, except putMetadata(ArrowBuf).

start

default void start(VectorSchemaRoot root,
                   DictionaryProvider dictionaries)

Start sending data, using the schema of the given VectorSchemaRoot.

This method must be called before all others, except putMetadata(ArrowBuf).

start

void start(VectorSchemaRoot root,
           DictionaryProvider dictionaries,
           IpcOption option)

Start sending data, using the schema of the given VectorSchemaRoot.

This method must be called before all others, except putMetadata(ArrowBuf).

putNext

void putNext()

Send the current contents of the associated VectorSchemaRoot.

This will not necessarily block until the message is actually sent; it may buffer messages in memory. Use isReady() to check if there is backpressure and avoid excessive buffering.

putNext

void putNext(ArrowBuf metadata)

Send the current contents of the associated VectorSchemaRoot alongside application-defined metadata.

Parameters:

metadata - The metadata to send. Ownership of the buffer is transferred to the Flight implementation.

putMetadata

void putMetadata(ArrowBuf metadata)

Send a pure metadata message without any associated data.

This may be called without starting the stream.

error

void error(Throwable ex)

Indicate an error to the client. Terminates the stream; do not call completed() afterwards.

completed

void completed()

Indicate that transmission is finished.

setUseZeroCopy

default void setUseZeroCopy(boolean enabled)

Toggle whether to ues the zero-copy write optimization.

By default or when disabled, Arrow may copy data into a buffer for the underlying implementation to send. When enabled, Arrow will instead try to directly enqueue the Arrow buffer for sending. Not all implementations support this optimization, so even if enabled, you may not see a difference.

In this mode, buffers must not be reused after they are written with putNext(). For example, you would have to call VectorSchemaRoot.allocateNew() after every call to putNext(). Hence, this is not enabled by default.

The default value can be toggled globally by setting the JVM property arrow.flight.enable_zero_copy_write or the environment variable ARROW_FLIGHT_ENABLE_ZERO_COPY_WRITE.