Skip to content

Commit

Permalink
GH-38599: [Docs] Update Headers (#38696)
Browse files Browse the repository at this point in the history
### Rationale for this change

Noticed wrong section headings on the web doc and proposing a fix.

### Are these changes tested?

Yes. Built and verified the documentation locally.

<img width="1049" alt="image" src="https://github.com/apache/arrow/assets/6668548/793d6222-2bc5-4f55-ab67-5abe5283add4">

### Are there any user-facing changes?

No.
* Closes: #38599

Authored-by: Hyunseok Seo <[email protected]>
Signed-off-by: Antoine Pitrou <[email protected]>
  • Loading branch information
llama90 authored Nov 15, 2023
1 parent 5b17b84 commit cc627ee
Showing 1 changed file with 14 additions and 15 deletions.
29 changes: 14 additions & 15 deletions docs/source/format/CDeviceDataInterface.rst
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ has the following fields:
to access the memory in the buffers.

If an event is provided, then the producer MUST ensure that the exported
data is available on the device before the event is triggered. The
data is available on the device before the event is triggered. The
consumer SHOULD wait on the event before trying to access the exported
data.

Expand All @@ -290,7 +290,7 @@ has the following fields:
As non-CPU development expands, there may be a need to expand this
structure. In order to do so without potentially breaking ABI changes,
we reserve 24 bytes at the end of the object. These bytes MUST be zero'd
out after initialization by the producer in order to ensure safe
out after initialization by the producer in order to ensure safe
evolution of the ABI in the future.

.. _c-device-data-interface-event-types:
Expand All @@ -300,7 +300,7 @@ Synchronization event types

The table below lists the expected event types for each device type.
If no event type is supported ("N/A"), then the ``sync_event`` member
should always be null.
should always be null.

Remember that the event *CAN* be null if synchronization is not needed
to access the data.
Expand Down Expand Up @@ -352,7 +352,7 @@ Memory management
-----------------

First and foremost: Out of everything in this interface, it is *only* the
data buffers themselves which reside in device memory (i.e. the ``buffers``
data buffers themselves which reside in device memory (i.e. the ``buffers``
member of the ``ArrowArray`` struct). Everything else should be in CPU
memory.

Expand Down Expand Up @@ -408,7 +408,7 @@ see inconsistent data while the other is mutating it.
Synchronization
---------------

If the ``sync_event`` member is non-NULL, the consumer should not attempt
If the ``sync_event`` member is non-NULL, the consumer should not attempt
to access or read the data until they have synchronized on that event. If
the ``sync_event`` member is NULL, then it MUST be safe to access the data
without any synchronization necessary on the part of the consumer.
Expand Down Expand Up @@ -501,7 +501,6 @@ could be used for any device:
arr->array.release(&arr->array);
}
=======================
Device Stream Interface
=======================

Expand All @@ -510,7 +509,7 @@ interface also specifies a higher-level structure for easing communication
of streaming data within a single process.

Semantics
=========
---------

An Arrow C device stream exposes a streaming source of data chunks, each with
the same schema. Chunks are obtained by calling a blocking pull-style iteration
Expand All @@ -520,7 +519,7 @@ to provide a stream of data on multiple device types, a producer should
provide a separate stream object for each device type.

Structure definition
====================
--------------------

The C device stream interface is defined by a single ``struct`` definition:

Expand Down Expand Up @@ -554,7 +553,7 @@ The C device stream interface is defined by a single ``struct`` definition:
kept exactly as-is when these definitions are copied.

The ArrowDeviceArrayStream structure
------------------------------------
''''''''''''''''''''''''''''''''''''

The ``ArrowDeviceArrayStream`` provides a device type that can access the
resulting data along with the required callbacks to interact with a
Expand Down Expand Up @@ -627,20 +626,20 @@ streaming source of Arrow arrays. It has the following fields:
handled by the producer, and especially by the release callback.

Result lifetimes
----------------
''''''''''''''''

The data returned by the ``get_schema`` and ``get_next`` callbacks must be
released independantly. Their lifetimes are not tied to that of
``ArrowDeviceArrayStream``.

Stream lifetime
---------------
'''''''''''''''

Lifetime of the C stream is managed using a release callback with similar
usage as in :ref:`C data interface <c-data-interface-released>`.

Thread safety
-------------
'''''''''''''

The stream source is not assumed to be thread-safe. Consumers wanting to
call ``get_next`` from several threads should ensure those calls are
Expand All @@ -652,9 +651,9 @@ Interoperability with other interchange formats
Other interchange APIs, such as the `CUDA Array Interface`_, include
members to pass the shape and the data types of the data buffers being
exported. This information is necessary to interpret the raw bytes in the
device data buffers that are being shared. Rather than store the
shape / types of the data alongside the ``ArrowDeviceArray``, users
should utilize the existing ``ArrowSchema`` structure to pass any data
device data buffers that are being shared. Rather than store the
shape / types of the data alongside the ``ArrowDeviceArray``, users
should utilize the existing ``ArrowSchema`` structure to pass any data
type and shape information.

Updating this specification
Expand Down

0 comments on commit cc627ee

Please sign in to comment.