sparrow::arrow_array_stream_proxy Class Reference

C++ proxy class for managing ArrowArrayStream objects. More...

#include <arrow_array_stream_proxy.hpp>

Public Member Functions
SPARROW_API	arrow_array_stream_proxy ()
	Constructs a new ArrowArrayStream producer.
SPARROW_API	arrow_array_stream_proxy (ArrowArrayStream &&stream)
	Constructs from an existing ArrowArrayStream by taking ownership.
SPARROW_API	arrow_array_stream_proxy (ArrowArrayStream *stream)
	Constructs from an existing ArrowArrayStream pointer by referencing it.
	arrow_array_stream_proxy (const arrow_array_stream_proxy &)=delete
arrow_array_stream_proxy &	operator= (const arrow_array_stream_proxy &)=delete
	arrow_array_stream_proxy (arrow_array_stream_proxy &&other) noexcept
arrow_array_stream_proxy &	operator= (arrow_array_stream_proxy &&other) noexcept
SPARROW_API	~arrow_array_stream_proxy ()
	Destructor that releases all resources.
SPARROW_API ArrowArrayStream *	export_stream ()
	Export the stream pointer.
template<std::ranges::input_range R> requires layout<std::ranges::range_value_t<R>>
void	push (R &&arrays)
	Adds a range of arrays to the stream.
template<layout A>
void	push (A &&array)
	Adds a single array to the stream.
SPARROW_API std::optional< array >	pop ()
	Retrieves the next array from the stream.

Detailed Description

C++ proxy class for managing ArrowArrayStream objects.

This class provides a C++ interface for working with ArrowArrayStream objects as defined by the Arrow C Stream Interface specification. It manages the lifetime of the stream and provides convenient methods for adding and retrieving data chunks.

The Arrow C Stream Interface is designed for streaming data exchange between different libraries or components within a single process. A stream exposes a source of data chunks, where each chunk has the same schema.

Key features:

• Automatic resource management through RAII
• Type-safe push/pop operations for array data
• Schema validation when adding arrays
• Proper implementation of all mandatory ArrowArrayStream callbacks

Thread safety:

• The stream is not thread-safe by design (per specification)
• Concurrent calls to get_next or pop must be externally synchronized

Note

This class implements the producer side of the Arrow C Stream Interface. It creates streams that can be consumed by other libraries that understand the ArrowArrayStream C interface.

See also

https://arrow.apache.org/docs/format/CStreamInterface.html

Definition at line 56 of file arrow_array_stream_proxy.hpp.

Constructor & Destructor Documentation

arrow_array_stream_proxy() [1/5]

SPARROW_API sparrow::arrow_array_stream_proxy::arrow_array_stream_proxy

(

)

Constructs a new ArrowArrayStream producer.

Creates a new stream with an empty queue of arrays. The stream must be populated with a schema and arrays before it can be consumed.

Note

The created stream has all callbacks properly initialized according to the Arrow C Stream Interface specification.

Here is the caller graph for this function:

arrow_array_stream_proxy() [2/5]

SPARROW_API sparrow::arrow_array_stream_proxy::arrow_array_stream_proxy ( ArrowArrayStream && stream )

explicit

Constructs from an existing ArrowArrayStream by taking ownership.

Moves an externally created ArrowArrayStream into this proxy. This allows stack-allocated or otherwise-owned ArrowArrayStream objects to be transferred into the proxy without additional heap allocation.

Parameters

stream

The ArrowArrayStream to move and take ownership of.

Postcondition

This proxy owns the stream and will release it on destruction

arrow_array_stream_proxy() [3/5]

SPARROW_API sparrow::arrow_array_stream_proxy::arrow_array_stream_proxy ( ArrowArrayStream * stream )

explicit

Constructs from an existing ArrowArrayStream pointer by referencing it.

References an externally created ArrowArrayStream without taking ownership. The stream must remain valid for the lifetime of this proxy.

Parameters

stream

Pointer to the ArrowArrayStream to reference (not owned).

Precondition

stream must be a valid pointer to ArrowArrayStream

External stream must remain valid for the lifetime of this proxy

Postcondition

This proxy does not own the stream

External stream must be managed by the caller

arrow_array_stream_proxy() [4/5]

sparrow::arrow_array_stream_proxy::arrow_array_stream_proxy ( const arrow_array_stream_proxy & )

delete

Here is the call graph for this function:

arrow_array_stream_proxy() [5/5]

sparrow::arrow_array_stream_proxy::arrow_array_stream_proxy ( arrow_array_stream_proxy && other )

noexcept

Here is the call graph for this function:

~arrow_array_stream_proxy()

SPARROW_API sparrow::arrow_array_stream_proxy::~arrow_array_stream_proxy

(

)

Destructor that releases all resources.

Calls the release callback on both the schema and stream if they are not already released. This ensures proper cleanup of all Arrow C interface objects.

Member Function Documentation

export_stream()

SPARROW_API ArrowArrayStream * sparrow::arrow_array_stream_proxy::export_stream

(

)

Export the stream pointer.

Returns a pointer to the stream. If this proxy owns the stream, ownership is transferred. If this proxy references an external stream, a pointer to that stream is returned.

This is useful for passing the stream to external C APIs that will take ownership.

Returns

Pointer to the ArrowArrayStream.

Postcondition

If stream was owned, this proxy is left in a released state

If stream was referenced, pointer to external stream is returned

operator=() [1/2]

arrow_array_stream_proxy & sparrow::arrow_array_stream_proxy::operator= ( arrow_array_stream_proxy && other )

noexcept

Here is the call graph for this function:

operator=() [2/2]

arrow_array_stream_proxy & sparrow::arrow_array_stream_proxy::operator= ( const arrow_array_stream_proxy & )

delete

Here is the call graph for this function:

pop()

SPARROW_API std::optional< array > sparrow::arrow_array_stream_proxy::pop

(

)

Retrieves the next array from the stream.

Removes and returns the next array from the stream's queue. This implements the consumer-side pop operation, similar to calling get_next on the ArrowArrayStream.

Returns

The next array in the stream.

Exceptions

std::system_error	If getting the schema fails.
std::runtime_error	If the stream is immutable.

Note

If the queue is empty, returns a released (empty) array, indicating end of stream.

push() [1/2]

template<layout A>

void sparrow::arrow_array_stream_proxy::push ( A && array )

inline

Adds a single array to the stream.

Pushes a single array into the stream's queue. The array must have a schema compatible with the stream's schema.

Template Parameters

A	A type satisfying the layout concept.

Parameters

array

The array to add to the stream.

Exceptions

std::runtime_error	If the array has an incompatible schema.
std::runtime_error	If the stream is immutable (released or not initialized).

Definition at line 188 of file arrow_array_stream_proxy.hpp.

Here is the call graph for this function:

push() [2/2]

template<std::ranges::input_range R>
requires layout<std::ranges::range_value_t<R>>

void sparrow::arrow_array_stream_proxy::push ( R && arrays )

inline

Adds a range of arrays to the stream.

Pushes multiple arrays into the stream's queue. All arrays must have schemas compatible with the stream's schema. Arrays are validated before being added.

Template Parameters

R	A range type whose value type satisfies the layout concept.

Parameters

arrays

The range of arrays to add to the stream.

Exceptions

std::runtime_error	If any array has an incompatible schema.
std::runtime_error	If the stream is immutable (released or not initialized).

Definition at line 144 of file arrow_array_stream_proxy.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

---

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

• /home/runner/work/sparrow/sparrow/include/sparrow/arrow_interface/arrow_array_stream_proxy.hpp