Skip to content

Commit 31fe24d

Browse files
GH-41126: [Python] Basic bindings for Device and MemoryManager classes (#41685)
### Rationale for this change Add bindings for the C++ `arrow::Device` and `arrow::MemoryManager` classes. ### What changes are included in this PR? Basic bindings by adding the `pyarrow.Device` and `pyarrow.MemoryManager` classes, and just tested for CPU. What is not included here are additional methods on the `MemoryManager` class (eg to allocate or copy buffers), and this is also not yet tested for CUDA. Planning to do this as follow-ups, and first doing those basic bindings should enable further enhancements to be done in parallel. ### Are these changes tested? Yes, for the CPU device only. * GitHub Issue: #41126 Authored-by: Joris Van den Bossche <[email protected]> Signed-off-by: Joris Van den Bossche <[email protected]>
1 parent 052c330 commit 31fe24d

8 files changed

Lines changed: 301 additions & 0 deletions

File tree

‎python/pyarrow/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,9 @@ def print_entry(label, value):
236236
RunEndEncodedScalar, ExtensionScalar)
237237

238238
# Buffers, allocation
239+
from pyarrow.lib import (DeviceAllocationType, Device, MemoryManager,
240+
default_cpu_memory_manager)
241+
239242
from pyarrow.lib import (Buffer, ResizableBuffer, foreign_buffer, py_buffer,
240243
Codec, compress, decompress, allocate_buffer)
241244

‎python/pyarrow/device.pxi‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
# cython: profile=False
19+
# distutils: language = c++
20+
# cython: embedsignature = True
21+
22+
23+
cpdef enum DeviceAllocationType:
24+
CPU = <char> CDeviceAllocationType_kCPU
25+
CUDA = <char> CDeviceAllocationType_kCUDA
26+
CUDA_HOST = <char> CDeviceAllocationType_kCUDA_HOST
27+
OPENCL = <char> CDeviceAllocationType_kOPENCL
28+
VULKAN = <char> CDeviceAllocationType_kVULKAN
29+
METAL = <char> CDeviceAllocationType_kMETAL
30+
VPI = <char> CDeviceAllocationType_kVPI
31+
ROCM = <char> CDeviceAllocationType_kROCM
32+
ROCM_HOST = <char> CDeviceAllocationType_kROCM_HOST
33+
EXT_DEV = <char> CDeviceAllocationType_kEXT_DEV
34+
CUDA_MANAGED = <char> CDeviceAllocationType_kCUDA_MANAGED
35+
ONEAPI = <char> CDeviceAllocationType_kONEAPI
36+
WEBGPU = <char> CDeviceAllocationType_kWEBGPU
37+
HEXAGON = <char> CDeviceAllocationType_kHEXAGON
38+
39+
40+
cdef object _wrap_device_allocation_type(CDeviceAllocationType device_type):
41+
return DeviceAllocationType(<char> device_type)
42+
43+
44+
cdef class Device(_Weakrefable):
45+
"""
46+
Abstract interface for hardware devices
47+
48+
This object represents a device with access to some memory spaces.
49+
When handling a Buffer or raw memory address, it allows deciding in which
50+
context the raw memory address should be interpreted
51+
(e.g. CPU-accessible memory, or embedded memory on some particular GPU).
52+
"""
53+
54+
def __init__(self):
55+
raise TypeError("Do not call Device's constructor directly, "
56+
"use the device attribute of the MemoryManager instead.")
57+
58+
cdef void init(self, const shared_ptr[CDevice]& device):
59+
self.device = device
60+
61+
@staticmethod
62+
cdef wrap(const shared_ptr[CDevice]& device):
63+
cdef Device self = Device.__new__(Device)
64+
self.init(device)
65+
return self
66+
67+
def __eq__(self, other):
68+
if not isinstance(other, Device):
69+
return False
70+
return self.device.get().Equals(deref((<Device>other).device.get()))
71+
72+
def __repr__(self):
73+
return "<pyarrow.Device: {}>".format(frombytes(self.device.get().ToString()))
74+
75+
@property
76+
def type_name(self):
77+
"""
78+
A shorthand for this device's type.
79+
"""
80+
return frombytes(self.device.get().type_name())
81+
82+
@property
83+
def device_id(self):
84+
"""
85+
A device ID to identify this device if there are multiple of this type.
86+
87+
If there is no "device_id" equivalent (such as for the main CPU device on
88+
non-numa systems) returns -1.
89+
"""
90+
return self.device.get().device_id()
91+
92+
@property
93+
def is_cpu(self):
94+
"""
95+
Whether this device is the main CPU device.
96+
97+
This shorthand method is very useful when deciding whether a memory address
98+
is CPU-accessible.
99+
"""
100+
return self.device.get().is_cpu()
101+
102+
@property
103+
def device_type(self):
104+
"""
105+
Return the DeviceAllocationType of this device.
106+
"""
107+
return _wrap_device_allocation_type(self.device.get().device_type())
108+
109+
110+
cdef class MemoryManager(_Weakrefable):
111+
"""
112+
An object that provides memory management primitives.
113+
114+
A MemoryManager is always tied to a particular Device instance.
115+
It can also have additional parameters (such as a MemoryPool to
116+
allocate CPU memory).
117+
118+
"""
119+
120+
def __init__(self):
121+
raise TypeError("Do not call MemoryManager's constructor directly, "
122+
"use pyarrow.default_cpu_memory_manager() instead.")
123+
124+
cdef void init(self, const shared_ptr[CMemoryManager]& mm):
125+
self.memory_manager = mm
126+
127+
@staticmethod
128+
cdef wrap(const shared_ptr[CMemoryManager]& mm):
129+
cdef MemoryManager self = MemoryManager.__new__(MemoryManager)
130+
self.init(mm)
131+
return self
132+
133+
def __repr__(self):
134+
return "<pyarrow.MemoryManager device: {}>".format(
135+
frombytes(self.memory_manager.get().device().get().ToString())
136+
)
137+
138+
@property
139+
def device(self):
140+
"""
141+
The device this MemoryManager is tied to.
142+
"""
143+
return Device.wrap(self.memory_manager.get().device())
144+
145+
@property
146+
def is_cpu(self):
147+
"""
148+
Whether this MemoryManager is tied to the main CPU device.
149+
150+
This shorthand method is very useful when deciding whether a memory
151+
address is CPU-accessible.
152+
"""
153+
return self.memory_manager.get().is_cpu()
154+
155+
156+
def default_cpu_memory_manager():
157+
"""
158+
Return the default CPU MemoryManager instance.
159+
160+
The returned singleton instance uses the default MemoryPool.
161+
"""
162+
return MemoryManager.wrap(c_default_cpu_memory_manager())

‎python/pyarrow/includes/libarrow.pxd‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -316,6 +316,38 @@ cdef extern from "arrow/api.h" namespace "arrow" nogil:
316316
cdef cppclass CProxyMemoryPool" arrow::ProxyMemoryPool"(CMemoryPool):
317317
CProxyMemoryPool(CMemoryPool*)
318318

319+
ctypedef enum CDeviceAllocationType "arrow::DeviceAllocationType":
320+
CDeviceAllocationType_kCPU "arrow::DeviceAllocationType::kCPU"
321+
CDeviceAllocationType_kCUDA "arrow::DeviceAllocationType::kCUDA"
322+
CDeviceAllocationType_kCUDA_HOST "arrow::DeviceAllocationType::kCUDA_HOST"
323+
CDeviceAllocationType_kOPENCL "arrow::DeviceAllocationType::kOPENCL"
324+
CDeviceAllocationType_kVULKAN "arrow::DeviceAllocationType::kVULKAN"
325+
CDeviceAllocationType_kMETAL "arrow::DeviceAllocationType::kMETAL"
326+
CDeviceAllocationType_kVPI "arrow::DeviceAllocationType::kVPI"
327+
CDeviceAllocationType_kROCM "arrow::DeviceAllocationType::kROCM"
328+
CDeviceAllocationType_kROCM_HOST "arrow::DeviceAllocationType::kROCM_HOST"
329+
CDeviceAllocationType_kEXT_DEV "arrow::DeviceAllocationType::kEXT_DEV"
330+
CDeviceAllocationType_kCUDA_MANAGED "arrow::DeviceAllocationType::kCUDA_MANAGED"
331+
CDeviceAllocationType_kONEAPI "arrow::DeviceAllocationType::kONEAPI"
332+
CDeviceAllocationType_kWEBGPU "arrow::DeviceAllocationType::kWEBGPU"
333+
CDeviceAllocationType_kHEXAGON "arrow::DeviceAllocationType::kHEXAGON"
334+
335+
cdef cppclass CDevice" arrow::Device":
336+
const char* type_name()
337+
c_string ToString()
338+
c_bool Equals(const CDevice& other)
339+
int64_t device_id()
340+
c_bool is_cpu() const
341+
shared_ptr[CMemoryManager] default_memory_manager()
342+
CDeviceAllocationType device_type()
343+
344+
cdef cppclass CMemoryManager" arrow::MemoryManager":
345+
const shared_ptr[CDevice] device()
346+
c_bool is_cpu() const
347+
348+
shared_ptr[CMemoryManager] c_default_cpu_memory_manager \
349+
" arrow::default_cpu_memory_manager"()
350+
319351
cdef cppclass CBuffer" arrow::Buffer":
320352
CBuffer(const uint8_t* data, int64_t size)
321353
const uint8_t* data()
@@ -328,6 +360,9 @@ cdef extern from "arrow/api.h" namespace "arrow" nogil:
328360
c_bool is_mutable() const
329361
c_string ToHexString()
330362
c_bool Equals(const CBuffer& other)
363+
shared_ptr[CDevice] device()
364+
const shared_ptr[CMemoryManager] memory_manager()
365+
CDeviceAllocationType device_type()
331366

332367
CResult[shared_ptr[CBuffer]] SliceBufferSafe(
333368
const shared_ptr[CBuffer]& buffer, int64_t offset)

‎python/pyarrow/io.pxi‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1327,6 +1327,39 @@ cdef class Buffer(_Weakrefable):
13271327
"""
13281328
return self.buffer.get().is_cpu()
13291329

1330+
@property
1331+
def device(self):
1332+
"""
1333+
The device where the buffer resides.
1334+
1335+
Returns
1336+
-------
1337+
Device
1338+
"""
1339+
return Device.wrap(self.buffer.get().device())
1340+
1341+
@property
1342+
def memory_manager(self):
1343+
"""
1344+
The memory manager associated with the buffer.
1345+
1346+
Returns
1347+
-------
1348+
MemoryManager
1349+
"""
1350+
return MemoryManager.wrap(self.buffer.get().memory_manager())
1351+
1352+
@property
1353+
def device_type(self):
1354+
"""
1355+
The device type where the buffer resides.
1356+
1357+
Returns
1358+
-------
1359+
DeviceAllocationType
1360+
"""
1361+
return _wrap_device_allocation_type(self.buffer.get().device_type())
1362+
13301363
@property
13311364
def parent(self):
13321365
cdef shared_ptr[CBuffer] parent_buf = self.buffer.get().parent()

‎python/pyarrow/lib.pxd‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -524,6 +524,26 @@ cdef class RecordBatch(_Tabular):
524524
cdef void init(self, const shared_ptr[CRecordBatch]& table)
525525

526526

527+
cdef class Device(_Weakrefable):
528+
cdef:
529+
shared_ptr[CDevice] device
530+
531+
cdef void init(self, const shared_ptr[CDevice]& device)
532+
533+
@staticmethod
534+
cdef wrap(const shared_ptr[CDevice]& device)
535+
536+
537+
cdef class MemoryManager(_Weakrefable):
538+
cdef:
539+
shared_ptr[CMemoryManager] memory_manager
540+
541+
cdef void init(self, const shared_ptr[CMemoryManager]& memory_manager)
542+
543+
@staticmethod
544+
cdef wrap(const shared_ptr[CMemoryManager]& mm)
545+
546+
527547
cdef class Buffer(_Weakrefable):
528548
cdef:
529549
shared_ptr[CBuffer] buffer

‎python/pyarrow/lib.pyx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,9 @@ include "pandas-shim.pxi"
162162
# Memory pools and allocation
163163
include "memory.pxi"
164164

165+
# Device type and memory manager
166+
include "device.pxi"
167+
165168
# DataType, Field, Schema
166169
include "types.pxi"
167170

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
import pyarrow as pa
19+
20+
21+
def test_device_memory_manager():
22+
mm = pa.default_cpu_memory_manager()
23+
assert mm.is_cpu
24+
device = mm.device
25+
assert device.is_cpu
26+
assert device.device_id == -1
27+
assert device.device_type == pa.DeviceAllocationType.CPU
28+
assert device.type_name == "arrow::CPUDevice"
29+
assert device == device
30+
assert repr(device) == "<pyarrow.Device: CPUDevice()>"
31+
assert repr(mm) == "<pyarrow.MemoryManager device: CPUDevice()>"
32+
33+
34+
def test_buffer_device():
35+
arr = pa.array([0, 1, 2])
36+
buf = arr.buffers()[1]
37+
assert buf.device_type == pa.DeviceAllocationType.CPU
38+
assert isinstance(buf.device, pa.Device)
39+
assert isinstance(buf.memory_manager, pa.MemoryManager)
40+
assert buf.is_cpu
41+
assert buf.device.is_cpu
42+
assert buf.device == pa.default_cpu_memory_manager().device
43+
assert buf.memory_manager.is_cpu

‎python/pyarrow/tests/test_misc.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,8 @@ def test_set_timezone_db_path_non_windows():
242242
pa.MemoryPool,
243243
pa.LoggingMemoryPool,
244244
pa.ProxyMemoryPool,
245+
pa.Device,
246+
pa.MemoryManager,
245247
])
246248
def test_extension_type_constructor_errors(klass):
247249
# ARROW-2638: prevent calling extension class constructors directly

0 commit comments

Comments
 (0)