.. Licensed to the Apache Software Foundation (ASF) under one
.. or more contributor license agreements.  See the NOTICE file
.. distributed with this work for additional information
.. regarding copyright ownership.  The ASF licenses this file
.. to you under the Apache License, Version 2.0 (the
.. "License"); you may not use this file except in compliance
.. with the License.  You may obtain a copy of the License at

..   http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing,
.. software distributed under the License is distributed on an
.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
.. KIND, either express or implied.  See the License for the
.. specific language governing permissions and limitations
.. under the License.

.. default-domain:: cpp
.. highlight:: cpp
.. cpp:namespace:: arrow::ipc

========================================
Reading and writing the Arrow IPC format
========================================

.. seealso::
   :ref:`Arrow IPC format specification <format-ipc>`.

   :doc:`API reference for IPC readers and writers <api/ipc>`.

Arrow C++ provides readers and writers for the Arrow IPC format which wrap
lower level input/output, handled through the :doc:`IO interfaces <io>`.
For reading, there is also an event-driven API that enables feeding
arbitrary data into the IPC decoding layer asynchronously.

Reading IPC streams and files
=============================

Synchronous reading
-------------------

For most cases, it is most convenient to use the :class:`RecordBatchStreamReader`
or :class:`RecordBatchFileReader` class, depending on which variant of the IPC
format you want to read.  The former requires a :class:`~arrow::io::InputStream`
source, while the latter requires a :class:`~arrow::io::RandomAccessFile`.

Reading Arrow IPC data is inherently zero-copy if the source allows it.
For example, a :class:`~arrow::io::BufferReader` or :class:`~arrow::io::MemoryMappedFile`
can typically be zero-copy.  Exceptions are when the data must be transformed
on the fly, e.g. when buffer compression has been enabled on the IPC stream
or file.

Event-driven reading
--------------------

When it is necessary to process the IPC format without blocking (for example
to integrate Arrow with an event loop), or if data is coming from an unusual
source, use the event-driven :class:`StreamDecoder`.  You will need to define
a subclass of :class:`Listener` and implement the virtual methods for the
desired events (for example, implement :func:`Listener::OnRecordBatchDecoded`
to be notified of each incoming :class:`RecordBatch`).

Writing IPC streams and files
=============================

Use one of the factory functions, :func:`MakeStreamWriter` or
:func:`MakeFileWriter`, to obtain a :class:`RecordBatchWriter` instance for
the given IPC format variant.

Configuring
===========

Various aspects of reading and writing the IPC format can be configured
using the :class:`IpcReadOptions` and :class:`IpcWriteOptions` classes,
respectively.