diff --git a/cpp/src/arrow/c/abi.h b/cpp/src/arrow/c/abi.h index 9327b8476fa0f..9dc142bd080df 100644 --- a/cpp/src/arrow/c/abi.h +++ b/cpp/src/arrow/c/abi.h @@ -321,7 +321,9 @@ struct ArrowAsyncProducer { // Any additional metadata tied to a specific stream of data. This must either be NULL // or a valid pointer to metadata which is encoded in the same way schema metadata - // would be. Non-null metadata must be valid for the lifetime of this object. + // would be. Non-null metadata must be valid for the lifetime of this object. As an + // example a producer could use this to provide the total number of rows and/or batches + // in the stream if known. const char* additional_metadata; // producer-specific opaque data. diff --git a/docs/source/format/CDeviceDataInterface.rst b/docs/source/format/CDeviceDataInterface.rst index b348ca63d94a6..fbb2012c3059b 100644 --- a/docs/source/format/CDeviceDataInterface.rst +++ b/docs/source/format/CDeviceDataInterface.rst @@ -811,10 +811,12 @@ The structure has the following fields: *Mandatory.* The producer object that the consumer will use to request additional data or cancel. - This object *MUST* be populated before calling the :c:member:`ArrowAsyncDeviceStreamHandler.on_schema` + This object *MUST* be populated by the producer before calling the :c:member:`ArrowAsyncDeviceStreamHandler.on_schema` callback. The producer maintains ownership of this object and must clean it up *after* calling the release callback on the ``ArrowAsyncDeviceStreamHandler``. + The consumer *CANNOT* assume that this is valid until the ``on_schema`` callback is called. + .. c:member:: void* ArrowAsyncDeviceStreamHandler.private_data *Optional.* An opaque pointer to consumer-provided private data. @@ -913,6 +915,8 @@ This producer-provided and managed object has the following fields: *Optional.* An additional metadata string to provide any extra context to the consumer. This *MUST* either be ``NULL`` or a valid string that is encoded in the same way as :c:member:`ArrowSchema.metadata`. + As an example, a producer could utilize this metadata to provide the total number of rows and/or batches + in the stream if known. If not ``NULL`` it *MUST* be valid for at least the lifetime of this object.