From 19a745ee21c8e9f73b7b2c3479e584ee09b33344 Mon Sep 17 00:00:00 2001 From: Mark Harris Date: Wed, 19 May 2021 07:53:26 +1000 Subject: [PATCH] Document synchronization requirements on device_buffer copy ctors (#772) Document caller synchronization expectations for copy constructors of `device_buffer`. Fixes #766 Authors: - Mark Harris (https://github.com/harrism) Approvers: - Rong Ou (https://github.com/rongou) - Jason Lowe (https://github.com/jlowe) - Conor Hoekstra (https://github.com/codereport) URL: https://github.com/rapidsai/rmm/pull/772 --- include/rmm/device_buffer.hpp | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/include/rmm/device_buffer.hpp b/include/rmm/device_buffer.hpp index 97095f3b2..d9ba0a4b8 100644 --- a/include/rmm/device_buffer.hpp +++ b/include/rmm/device_buffer.hpp @@ -103,8 +103,13 @@ class device_buffer { } /** - * @brief Construct a new device buffer by copying from a raw pointer to an - * existing host or device memory allocation. + * @brief Construct a new device buffer by copying from a raw pointer to an existing host or + * device memory allocation. + * + * @note This function does not synchronize `stream`. `source_data` is copied on `stream`, so the + * caller is responsible for correct synchronization to ensure that `source_data` is valid when + * the copy occurs. This includes destroying `source_data` in stream order after this function is + * called, or synchronizing or waiting on `stream` after this function returns as necessary. * * @throws rmm::bad_alloc If creating the new allocation fails. * @throws rmm::logic_error If `source_data` is null, and `size != 0`. @@ -135,6 +140,11 @@ class device_buffer { *`other.size() != other.capacity()`, then the size and capacity of the newly * constructed `device_buffer` will be equal to `other.size()`. * + * @note This function does not synchronize `stream`. `other` is copied on `stream`, so the + * caller is responsible for correct synchronization to ensure that `other` is valid when + * the copy occurs. This includes destroying `other` in stream order after this function is + * called, or synchronizing or waiting on `stream` after this function returns as necessary. + * * @throws rmm::bad_alloc If creating the new allocation fails. * @throws rmm::cuda_error if copying from `other` fails. *