Skip to content

Commit 11de18c

Browse files
committed
Update data interchange page with notes on DLPack
Closes gh-192
1 parent b6f5ad7 commit 11de18c

File tree

1 file changed

+24
-6
lines changed

1 file changed

+24
-6
lines changed

spec/design_topics/data_interchange.md

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,11 @@ The interchange mechanism must offer the following:
3838
C/C++, and are released independently from each other. Hence a stable C
3939
ABI is required for packages to work well together._
4040

41-
The best candidate for this protocol is DLPack. See the
42-
[RFC to adopt DLPack](https://github.com/data-apis/consortium-feedback/issues/1)
43-
for details.
41+
The best candidate for this protocol is
42+
[DLPack](https://github.com/dmlc/dlpack), and hence that is what this
43+
standard has chosen as the primary/recommended protocol. Note that the
44+
`asarray` function also supports the Python buffer protocol (CPU-only) to
45+
support libraries that already implement buffer protocol support.
4446

4547
```{note}
4648
@@ -64,10 +66,26 @@ hardly has any support from array libraries. CPU interoperability is
6466
mostly dealt with via the NumPy-specific `__array__` (which, when called,
6567
means the object it is attached to must return a `numpy.ndarray`
6668
containing the data the object holds).
69+
70+
See the [RFC to adopt DLPack](https://github.com/data-apis/consortium-feedback/issues/1)
71+
for discussion that preceded the adoption of DLPack.
6772
```
6873

74+
## DLPack support
75+
76+
:::{note}
77+
DLPack is a standalone protocol/project and can therefore be used outside of
78+
this standard. Python libraries that want to implement only DLPack support
79+
are recommended to do so using the same syntax and semantics as outlined
80+
below. They are not required to return an array object from `from_dlpack`
81+
which conforms to this standard.
82+
83+
DLPack itself has no documentation currently outside of the inline comments in
84+
[dlpack.h](https://github.com/dmlc/dlpack/blob/main/include/dlpack/dlpack.h).
85+
In the future, the below content may be migrated to the (to-be-written) DLPack docs.
86+
:::
6987

70-
## Syntax for data interchange with DLPack
88+
### Syntax for data interchange with DLPack
7189

7290
The array API will offer the following syntax for data interchange:
7391

@@ -80,7 +98,7 @@ The array API will offer the following syntax for data interchange:
8098
stream, e.g. in the case of multiple GPUs) and to access the data.
8199

82100

83-
## Semantics
101+
### Semantics
84102

85103
DLPack describe the memory layout of strided, n-dimensional arrays.
86104
When a user calls `y = from_dlpack(x)`, the library implementing `x` (the
@@ -106,7 +124,7 @@ In the common case of the default stream being used, synchronization will be
106124
unnecessary so asynchronous execution is enabled.
107125

108126

109-
## Implementation
127+
### Implementation
110128

111129
_Note that while this API standard largely tries to avoid discussing implementation details, some discussion and requirements are needed here because data interchange requires coordination between implementers on, e.g., memory management._
112130

0 commit comments

Comments
 (0)