This is an automated email from the ASF dual-hosted git repository.
apitrou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new cc627ee7e3 GH-38599: [Docs] Update Headers (#38696)
cc627ee7e3 is described below
commit cc627ee7e35807a98717603d0a2520685919e17c
Author: Hyunseok Seo <[email protected]>
AuthorDate: Wed Nov 15 19:01:43 2023 +0900
GH-38599: [Docs] Update Headers (#38696)
### 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]>
---
docs/source/format/CDeviceDataInterface.rst | 29 ++++++++++++++---------------
1 file changed, 14 insertions(+), 15 deletions(-)
diff --git a/docs/source/format/CDeviceDataInterface.rst
b/docs/source/format/CDeviceDataInterface.rst
index b54e6eabe0..a584852df8 100644
--- a/docs/source/format/CDeviceDataInterface.rst
+++ b/docs/source/format/CDeviceDataInterface.rst
@@ -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.
@@ -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:
@@ -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.
@@ -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.
@@ -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.
@@ -501,7 +501,6 @@ could be used for any device:
arr->array.release(&arr->array);
}
-=======================
Device Stream Interface
=======================
@@ -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
@@ -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:
@@ -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
@@ -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
@@ -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
