apache / apache/arrow

[Format][Docs] Describe C device interface on C data interface and C stream interface docs pages

Open
#44,535 3 comments 2 reactions 0 assignees View on GitHub
Component: Documentation Component: Format Status: needs champion Type: enhancement
Dominant language
C++
Stars
17.1k
Forks
4.3k
Avg merge
3d 13h
Merged PRs (30d)
88

Description

### Describe the enhancement requested

The following facts are not immediately obvious to readers of the C data interface and C stream interface docs pages:
- The C data interface is a CPU-only subset of the C device data interface.
- The C stream interface is a CPU-only subset of the C device stream interface.
- We will never remove the existing CPU-only C data/stream interfaces (because we must keep them to preserve compatibility with existing systems)...
- ... but when we add new structure definitions (for example as in #43632), we will add them _only_ to the C _device_ data/stream interfaces (to reduce duplication of efforts).
- In other words, the CPU-only C data/stream interfaces are in "maintenance mode."
- This will force developers that are currently using the CPU-only C data/stream interfaces and who wish to use the new structures to switch over to using the C _device_ data/stream interfaces. This is simple enough to do.

To make this clearer, we should add note boxes to to `CDataInterface.rst` and `CStreamInterface.rst` to explain some of this and to link to `CDeviceDataInterface.rst`. The note boxes should clearly state that the CPU-only C data/stream interfaces are in "maintenance mode."

### Component(s)

Documentation, Format

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.