rmm
rmm copied to clipboard
rapidsai
Allow specifying mr in DeviceBuffer construction, and document ownership requirements in Python/C++ interfacing
Description
On the C++ side, device_buffers store raw pointers for the memory resource that was used in their allocation. Consequently, it is unsafe to take ownership of a device_buffer in Python unless we controlled the provenance of the memory resource that was used in its allocation. The only way to do that is to pass the memory resource from Python into C++ and then use it when constructing the DeviceBuffer.
Add discussion of this with some examples and a section on pitfalls if only relying on get_current_device_resource and set_current_device_resource.
To allow Python users of DeviceBuffer objects to follow best practices,
introduce explicit (defaulting to the current device resource) mr
arguments in both c_from_unique_ptr and the DeviceBuffer constructor.
- Closes #1492
Checklist
- [x] I am familiar with the Contributing Guidelines.
- [x] New or existing tests cover these changes.
- [x] The documentation is up to date with these changes.
This PR changes the Python code in addition to documenting. Perhaps the PR title and description should cover that?
@harrism good point, let me pull that out into a separate change (I wanted these so I could actually make the recommendation to do the right thing in the docs).
I think there's no real need to separate it; just to clarify the title and description.
I think there's no real need to separate it; just to clarify the title and description.
Ok, done. I also added a test of the new functionality.
Can we close #1132 with this change?
Yes, though I didn't cover as many APIs as that one (exposing everywhere is tracked in #1515).
This all looks great. My only question is whether
README.mdis getting too big. Maybe this belongs in the Python docs instead? e.g.guide.md?
Arguably yes, a question then arises as to whether we want to do a split properly. Right now, some of the information in README is replicated in the python guide. AFAICT, the README is the "canonical" source of user documentation for the C++ API, I don't know if we would rather incorporate it into the doxygen docs.