#include <arrow_abi.h>

Data Fields
int(*	on_schema )(struct ArrowAsyncDeviceStreamHandler self, struct ArrowSchema stream_schema)

int(*	on_next_task )(struct ArrowAsyncDeviceStreamHandler self, struct ArrowAsyncTask task, const char *metadata)

void(*	on_error )(struct ArrowAsyncDeviceStreamHandler self, int code, const char message, const char *metadata)

void(*	release )(struct ArrowAsyncDeviceStreamHandler *self)

struct ArrowAsyncProducer *	producer

void *	private_data
	Opaque handler-specific data.

Detailed Description

EXPERIMENTAL: Similar to ArrowDeviceArrayStream, except designed for an asynchronous style of interaction. While ArrowDeviceArrayStream provides producer defined callbacks, this is intended to be created by the consumer instead. The consumer passes this handler to the producer, which in turn uses the callbacks to inform the consumer of events in the stream.

Field Documentation

void(* ArrowAsyncDeviceStreamHandler::on_error)(struct ArrowAsyncDeviceStreamHandler *self, int code, const char *message, const char *metadata)

Handler for encountering an error. The producer should call release after this returns to clean up any resources. The code passed in can be any error code that a producer wants, but should be errno-compatible for consistency.

If the message or metadata are non-null, they will only last as long as this function call. The consumer would need to perform a copy of the data if it is necessary for them to live past the lifetime of this call.

Error metadata should be encoded as with metadata in ArrowSchema, defined in the spec at https://arrow.apache.org/docs/format/CDataInterface.html#c.ArrowSchema.metadata

It is valid for this to be called by a producer with or without a preceding call to ArrowAsyncProducer.request.

This callback must not call any methods of an ArrowAsyncProducer object.

int(* ArrowAsyncDeviceStreamHandler::on_next_task)(struct ArrowAsyncDeviceStreamHandler *self, struct ArrowAsyncTask *task, const char *metadata)

Handler for receiving data. This is called when data is available providing an ArrowAsyncTask struct to signify it. The producer indicates the end of the stream by passing NULL as the value for the task rather than a valid pointer to a task. The task object is only valid for the lifetime of this function call, if a consumer wants to utilize it after this function returns, it must copy or move the contents of it to a new ArrowAsyncTask object.

The request callback of a provided ArrowAsyncProducer must be called in order to start receiving calls to this handler.

The metadata argument can be null or can be used by a producer to pass arbitrary extra information to the consumer (such as total number of rows, context info, or otherwise). The data should be passed using the same encoding as the metadata within the ArrowSchema struct itself (defined in the spec at https://arrow.apache.org/docs/format/CDataInterface.html#c.ArrowSchema.metadata)

If metadata is non-null then it only needs to exist for the lifetime of this call, a consumer who wants it to live after that must copy it to ensure lifetime.

A producer must not call this concurrently from multiple different threads.

A consumer must be prepared to receive one or more calls to this callback even after calling cancel on the corresponding ArrowAsyncProducer, as cancel does not guarantee it happens immediately.

Return value: 0 if successful, errno-compatible error otherwise.

If the consumer returns a non-zero return from this method, that indicates to the producer that it should stop propagating data as an error occurred. After receiving such a return, the only interaction with this object is for the producer to call the release callback.

int(* ArrowAsyncDeviceStreamHandler::on_schema)(struct ArrowAsyncDeviceStreamHandler *self, struct ArrowSchema *stream_schema)

Handler for receiving a schema. The passed in stream_schema must be released or moved by the handler (producer is giving ownership of the schema to the handler, but not ownership of the top level object itself).

With the exception of an error occurring (on_error), this must be the first callback function which is called by a producer and must only be called exactly once. As such, the producer should provide a valid ArrowAsyncProducer instance so the consumer can control the flow. See the documentation on ArrowAsyncProducer for how it works. The ArrowAsyncProducer is owned by the producer who calls this function and thus the producer is responsible for cleaning it up when calling the release callback of this handler.

If there is any additional metadata tied to this stream, it will be provided as a non-null value for the additional_metadata field of the ArrowAsyncProducer which will be valid at least until the release callback is called.

Return value: 0 if successful, errno-compatible error otherwise

A producer that receives a non-zero return here should stop producing and eventually call release instead.

struct ArrowAsyncProducer* ArrowAsyncDeviceStreamHandler::producer

MUST be populated by the producer BEFORE calling any callbacks other than release. This provides the connection between a handler and its producer, and must exist until the release callback is called.

void(* ArrowAsyncDeviceStreamHandler::release)(struct ArrowAsyncDeviceStreamHandler *self)

Release callback to release any resources for the handler. Should always be called by a producer when it is done utilizing a handler. No callbacks should be called after this is called.

It is valid for the release callback to be called by a producer with or without a preceding call to ArrowAsyncProducer.request.

The release callback must not call any methods of an ArrowAsyncProducer object.

The documentation for this struct was generated from the following file:

qdb/arrow_abi.h

Data Fields

Detailed Description

Field Documentation