From 19c44dbe9e555b4e882ebbbb363cd66160c26b78 Mon Sep 17 00:00:00 2001 From: Vyas Ramasubramani Date: Mon, 25 Sep 2023 10:48:42 -0700 Subject: [PATCH] Enable doxygen XML and fix issues (#1348) doxygen catches more doc issues (of the types fixed in https://github.com/rapidsai/rmm/pull/1317) when more build outputs are turned on, which is indicative of some bugs/limitations in doxygen. XML builds will be necessary to leverage Breathe (see #1324) so this PR enables XML builds and fixes the associated issues. Authors: - Vyas Ramasubramani (https://github.com/vyasr) Approvers: - Rong Ou (https://github.com/rongou) URL: https://github.com/rapidsai/rmm/pull/1348 --- .gitignore | 1 + doxygen/Doxyfile | 2 +- include/rmm/cuda_stream_view.hpp | 2 +- .../mr/device/aligned_resource_adaptor.hpp | 2 +- .../rmm/mr/device/arena_memory_resource.hpp | 3 +- .../rmm/mr/device/binning_memory_resource.hpp | 5 ++-- .../mr/device/callback_memory_resource.hpp | 23 +++++++++++++++ .../mr/device/cuda_async_memory_resource.hpp | 22 +++++++------- .../cuda_async_view_memory_resource.hpp | 21 ++++++++------ .../rmm/mr/device/cuda_memory_resource.hpp | 26 +++++++++-------- .../rmm/mr/device/device_memory_resource.hpp | 2 +- .../mr/device/limiting_resource_adaptor.hpp | 5 ++-- .../mr/device/logging_resource_adaptor.hpp | 4 +++ .../rmm/mr/device/managed_memory_resource.hpp | 29 ++++++++++--------- include/rmm/thrust_rmm_allocator.h | 4 +-- 15 files changed, 95 insertions(+), 56 deletions(-) diff --git a/.gitignore b/.gitignore index ad6c8ebf7..8d5823ab2 100644 --- a/.gitignore +++ b/.gitignore @@ -91,6 +91,7 @@ thirdparty/googletest/ ## Doxygen doxygen/html +doxygen/xml #Java target diff --git a/doxygen/Doxyfile b/doxygen/Doxyfile index 2ace4abba..28a789a9f 100644 --- a/doxygen/Doxyfile +++ b/doxygen/Doxyfile @@ -2012,7 +2012,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/include/rmm/cuda_stream_view.hpp b/include/rmm/cuda_stream_view.hpp index 150fe3957..b6e3cc022 100644 --- a/include/rmm/cuda_stream_view.hpp +++ b/include/rmm/cuda_stream_view.hpp @@ -166,7 +166,7 @@ inline bool operator!=(cuda_stream_view lhs, cuda_stream_view rhs) { return not( * @brief Output stream operator for printing / logging streams * * @param os The output ostream - * @param sv The cuda_stream_view to output + * @param stream The cuda_stream_view to output * @return std::ostream& The output ostream */ inline std::ostream& operator<<(std::ostream& os, cuda_stream_view stream) diff --git a/include/rmm/mr/device/aligned_resource_adaptor.hpp b/include/rmm/mr/device/aligned_resource_adaptor.hpp index 0b933fb56..f79f0c15a 100644 --- a/include/rmm/mr/device/aligned_resource_adaptor.hpp +++ b/include/rmm/mr/device/aligned_resource_adaptor.hpp @@ -140,7 +140,7 @@ class aligned_resource_adaptor final : public device_memory_resource { * * @throws Nothing. * - * @param p Pointer to be deallocated + * @param ptr Pointer to be deallocated * @param bytes Size of the allocation * @param stream Stream on which to perform the deallocation */ diff --git a/include/rmm/mr/device/arena_memory_resource.hpp b/include/rmm/mr/device/arena_memory_resource.hpp index e16fbaf7c..882cbf694 100644 --- a/include/rmm/mr/device/arena_memory_resource.hpp +++ b/include/rmm/mr/device/arena_memory_resource.hpp @@ -293,7 +293,8 @@ class arena_memory_resource final : public device_memory_resource { * @param stream to execute on. * @return std::pair containing free_size and total_size of memory. */ - std::pair do_get_mem_info(cuda_stream_view) const override + std::pair do_get_mem_info( + [[maybe_unused]] cuda_stream_view stream) const override { return std::make_pair(0, 0); } diff --git a/include/rmm/mr/device/binning_memory_resource.hpp b/include/rmm/mr/device/binning_memory_resource.hpp index 705df63c6..54cccca28 100644 --- a/include/rmm/mr/device/binning_memory_resource.hpp +++ b/include/rmm/mr/device/binning_memory_resource.hpp @@ -182,7 +182,7 @@ class binning_memory_resource final : public device_memory_resource { * * @throws nothing * - * @param p Pointer to be deallocated + * @param ptr Pointer to be deallocated * @param bytes The size in bytes of the allocation. This must be equal to the * value of `bytes` that was passed to the `allocate` call that returned `p`. * @param stream Stream on which to perform deallocation @@ -201,7 +201,8 @@ class binning_memory_resource final : public device_memory_resource { * @param stream the stream being executed on * @return std::pair with available and free memory for resource */ - [[nodiscard]] std::pair do_get_mem_info(cuda_stream_view) const override + [[nodiscard]] std::pair do_get_mem_info( + [[maybe_unused]] cuda_stream_view stream) const override { return std::make_pair(0, 0); } diff --git a/include/rmm/mr/device/callback_memory_resource.hpp b/include/rmm/mr/device/callback_memory_resource.hpp index 2d9695be2..289ceb9d6 100644 --- a/include/rmm/mr/device/callback_memory_resource.hpp +++ b/include/rmm/mr/device/callback_memory_resource.hpp @@ -100,11 +100,34 @@ class callback_memory_resource final : public device_memory_resource { default; ///< @default_move_assignment{callback_memory_resource} private: + /** + * @brief Allocates memory of size at least \p bytes. + * + * The returned pointer will have at minimum 256 byte alignment. + * + * If supported by the callback, this operation may optionally be executed on + * a stream. Otherwise, the stream is ignored and the null stream is used. + * + * @param bytes The size of the allocation + * @param stream Stream on which to perform allocation + * @return void* Pointer to the newly allocated memory + */ void* do_allocate(std::size_t bytes, cuda_stream_view stream) override { return allocate_callback_(bytes, stream, allocate_callback_arg_); } + /** + * @brief Deallocate memory pointed to by \p p. + * + * If supported by the callback, this operation may optionally be executed on + * a stream. Otherwise, the stream is ignored and the null stream is used. + * + * @param ptr Pointer to be deallocated + * @param bytes The size in bytes of the allocation. This must be equal to the + * value of `bytes` that was passed to the `allocate` call that returned `p`. + * @param stream Stream on which to perform deallocation + */ void do_deallocate(void* ptr, std::size_t bytes, cuda_stream_view stream) override { deallocate_callback_(ptr, bytes, stream, deallocate_callback_arg_); diff --git a/include/rmm/mr/device/cuda_async_memory_resource.hpp b/include/rmm/mr/device/cuda_async_memory_resource.hpp index 329d8f29a..9bbd9cc09 100644 --- a/include/rmm/mr/device/cuda_async_memory_resource.hpp +++ b/include/rmm/mr/device/cuda_async_memory_resource.hpp @@ -173,13 +173,12 @@ class cuda_async_memory_resource final : public device_memory_resource { #endif /** - * @brief Allocates memory of size at least `bytes` using cudaMalloc. + * @brief Allocates memory of size at least \p bytes. * - * The returned pointer has at least 256B alignment. + * The returned pointer will have at minimum 256 byte alignment. * - * @throws `rmm::bad_alloc` if the requested allocation could not be fulfilled - * - * @param bytes The size, in bytes, of the allocation + * @param bytes The size of the allocation + * @param stream Stream on which to perform allocation * @return void* Pointer to the newly allocated memory */ void* do_allocate(std::size_t bytes, rmm::cuda_stream_view stream) override @@ -197,17 +196,18 @@ class cuda_async_memory_resource final : public device_memory_resource { /** * @brief Deallocate memory pointed to by \p p. * - * @throws Nothing. - * - * @param p Pointer to be deallocated + * @param ptr Pointer to be deallocated + * @param bytes The size in bytes of the allocation. This must be equal to the + * value of `bytes` that was passed to the `allocate` call that returned `p`. + * @param stream Stream on which to perform deallocation */ - void do_deallocate(void* ptr, std::size_t size, rmm::cuda_stream_view stream) override + void do_deallocate(void* ptr, std::size_t bytes, rmm::cuda_stream_view stream) override { #ifdef RMM_CUDA_MALLOC_ASYNC_SUPPORT - pool_.deallocate(ptr, size, stream); + pool_.deallocate(ptr, bytes, stream); #else (void)ptr; - (void)size; + (void)bytes; (void)stream; #endif } diff --git a/include/rmm/mr/device/cuda_async_view_memory_resource.hpp b/include/rmm/mr/device/cuda_async_view_memory_resource.hpp index c685cd75f..569f65df7 100644 --- a/include/rmm/mr/device/cuda_async_view_memory_resource.hpp +++ b/include/rmm/mr/device/cuda_async_view_memory_resource.hpp @@ -108,13 +108,12 @@ class cuda_async_view_memory_resource final : public device_memory_resource { #endif /** - * @brief Allocates memory of size at least `bytes` using cudaMalloc. + * @brief Allocates memory of size at least \p bytes. * - * The returned pointer has at least 256B alignment. + * The returned pointer will have at minimum 256 byte alignment. * - * @throws `rmm::bad_alloc` if the requested allocation could not be fulfilled - * - * @param bytes The size, in bytes, of the allocation + * @param bytes The size of the allocation + * @param stream Stream on which to perform allocation * @return void* Pointer to the newly allocated memory */ void* do_allocate(std::size_t bytes, rmm::cuda_stream_view stream) override @@ -135,11 +134,14 @@ class cuda_async_view_memory_resource final : public device_memory_resource { /** * @brief Deallocate memory pointed to by \p p. * - * @throws Nothing. - * - * @param p Pointer to be deallocated + * @param ptr Pointer to be deallocated + * @param bytes The size in bytes of the allocation. This must be equal to the + * value of `bytes` that was passed to the `allocate` call that returned `p`. + * @param stream Stream on which to perform deallocation */ - void do_deallocate(void* ptr, std::size_t, rmm::cuda_stream_view stream) override + void do_deallocate(void* ptr, + [[maybe_unused]] std::size_t bytes, + rmm::cuda_stream_view stream) override { #ifdef RMM_CUDA_MALLOC_ASYNC_SUPPORT if (ptr != nullptr) { @@ -147,6 +149,7 @@ class cuda_async_view_memory_resource final : public device_memory_resource { } #else (void)ptr; + (void)bytes; (void)stream; #endif } diff --git a/include/rmm/mr/device/cuda_memory_resource.hpp b/include/rmm/mr/device/cuda_memory_resource.hpp index b0bf9ae09..5164bc5c5 100644 --- a/include/rmm/mr/device/cuda_memory_resource.hpp +++ b/include/rmm/mr/device/cuda_memory_resource.hpp @@ -55,18 +55,17 @@ class cuda_memory_resource final : public device_memory_resource { private: /** - * @brief Allocates memory of size at least `bytes` using cudaMalloc. + * @brief Allocates memory of size at least \p bytes. * - * The returned pointer has at least 256B alignment. + * The returned pointer will have at minimum 256 byte alignment. * - * @note Stream argument is ignored + * The stream argument is ignored. * - * @throws `rmm::bad_alloc` if the requested allocation could not be fulfilled - * - * @param bytes The size, in bytes, of the allocation + * @param bytes The size of the allocation + * @param stream This argument is ignored * @return void* Pointer to the newly allocated memory */ - void* do_allocate(std::size_t bytes, cuda_stream_view) override + void* do_allocate(std::size_t bytes, [[maybe_unused]] cuda_stream_view stream) override { void* ptr{nullptr}; RMM_CUDA_TRY_ALLOC(cudaMalloc(&ptr, bytes)); @@ -76,13 +75,16 @@ class cuda_memory_resource final : public device_memory_resource { /** * @brief Deallocate memory pointed to by \p p. * - * @note Stream argument is ignored. - * - * @throws Nothing. + * The stream argument is ignored. * - * @param p Pointer to be deallocated + * @param ptr Pointer to be deallocated + * @param bytes The size in bytes of the allocation. This must be equal to the + * value of `bytes` that was passed to the `allocate` call that returned `p`. + * @param stream This argument is ignored. */ - void do_deallocate(void* ptr, std::size_t, cuda_stream_view) override + void do_deallocate(void* ptr, + [[maybe_unused]] std::size_t bytes, + [[maybe_unused]] cuda_stream_view stream) override { RMM_ASSERT_CUDA_SUCCESS(cudaFree(ptr)); } diff --git a/include/rmm/mr/device/device_memory_resource.hpp b/include/rmm/mr/device/device_memory_resource.hpp index 5f511e393..1813fb726 100644 --- a/include/rmm/mr/device/device_memory_resource.hpp +++ b/include/rmm/mr/device/device_memory_resource.hpp @@ -201,7 +201,7 @@ class device_memory_resource { * If supported, this operation may optionally be executed on a stream. * Otherwise, the stream is ignored and the null stream is used. * - * @param p Pointer to be deallocated + * @param ptr Pointer to be deallocated * @param bytes The size in bytes of the allocation. This must be equal to the * value of `bytes` that was passed to the `allocate` call that returned `p`. * @param stream Stream on which to perform deallocation diff --git a/include/rmm/mr/device/limiting_resource_adaptor.hpp b/include/rmm/mr/device/limiting_resource_adaptor.hpp index 895c404b0..ebc67fed1 100644 --- a/include/rmm/mr/device/limiting_resource_adaptor.hpp +++ b/include/rmm/mr/device/limiting_resource_adaptor.hpp @@ -185,7 +185,8 @@ class limiting_resource_adaptor final : public device_memory_resource { * @param stream Stream on which to get the mem info. * @return std::pair contaiing free_size and total_size of memory */ - [[nodiscard]] std::pair do_get_mem_info(cuda_stream_view) const override + [[nodiscard]] std::pair do_get_mem_info( + [[maybe_unused]] cuda_stream_view stream) const override { return {allocation_limit_ - allocated_bytes_, allocation_limit_}; } @@ -209,7 +210,7 @@ class limiting_resource_adaptor final : public device_memory_resource { * * @tparam Upstream Type of the upstream `device_memory_resource`. * @param upstream Pointer to the upstream resource - * @param limit Maximum amount of memory to allocate + * @param allocation_limit Maximum amount of memory to allocate */ template limiting_resource_adaptor make_limiting_adaptor(Upstream* upstream, diff --git a/include/rmm/mr/device/logging_resource_adaptor.hpp b/include/rmm/mr/device/logging_resource_adaptor.hpp index 0ff9e950b..c59fdf61a 100644 --- a/include/rmm/mr/device/logging_resource_adaptor.hpp +++ b/include/rmm/mr/device/logging_resource_adaptor.hpp @@ -329,6 +329,8 @@ class logging_resource_adaptor final : public device_memory_resource { * @param upstream Pointer to the upstream resource * @param filename Name of the file to write log info. If not specified, * retrieves the log file name from the environment variable "RMM_LOG_FILE". + * @param auto_flush If true, flushes the log for every (de)allocation. Warning, this will degrade + * performance. */ template logging_resource_adaptor make_logging_adaptor( @@ -346,6 +348,8 @@ logging_resource_adaptor make_logging_adaptor( * @tparam Upstream Type of the upstream `device_memory_resource`. * @param upstream Pointer to the upstream resource * @param stream The ostream to write log info. + * @param auto_flush If true, flushes the log for every (de)allocation. Warning, this will degrade + * performance. */ template logging_resource_adaptor make_logging_adaptor(Upstream* upstream, diff --git a/include/rmm/mr/device/managed_memory_resource.hpp b/include/rmm/mr/device/managed_memory_resource.hpp index 4a0f7701a..e987de15d 100644 --- a/include/rmm/mr/device/managed_memory_resource.hpp +++ b/include/rmm/mr/device/managed_memory_resource.hpp @@ -55,18 +55,17 @@ class managed_memory_resource final : public device_memory_resource { private: /** - * @brief Allocates memory of size at least `bytes` using cudaMallocManaged. + * @brief Allocates memory of size at least \p bytes. * - * The returned pointer has at least 256B alignment. + * The returned pointer will have at minimum 256 byte alignment. * - * @note Stream argument is ignored + * The stream is ignored. * - * @throws `rmm::bad_alloc` if the requested allocation could not be fulfilled - * - * @param bytes The size, in bytes, of the allocation + * @param bytes The size of the allocation + * @param stream This argument is ignored * @return void* Pointer to the newly allocated memory */ - void* do_allocate(std::size_t bytes, cuda_stream_view) override + void* do_allocate(std::size_t bytes, [[maybe_unused]] cuda_stream_view stream) override { // FIXME: Unlike cudaMalloc, cudaMallocManaged will throw an error for 0 // size allocations. @@ -78,15 +77,18 @@ class managed_memory_resource final : public device_memory_resource { } /** - * @brief Deallocate memory pointed to by `ptr`. - * - * @note Stream argument is ignored. + * @brief Deallocate memory pointed to by \p p. * - * @throws Nothing. + * The stream is ignored. * * @param ptr Pointer to be deallocated + * @param bytes The size in bytes of the allocation. This must be equal to the + * value of `bytes` that was passed to the `allocate` call that returned `p`. + * @param stream This argument is ignored */ - void do_deallocate(void* ptr, std::size_t, cuda_stream_view) override + void do_deallocate(void* ptr, + [[maybe_unused]] std::size_t bytes, + [[maybe_unused]] cuda_stream_view stream) override { RMM_ASSERT_CUDA_SUCCESS(cudaFree(ptr)); } @@ -116,7 +118,8 @@ class managed_memory_resource final : public device_memory_resource { * @param stream to execute on * @return std::pair contaiing free_size and total_size of memory */ - [[nodiscard]] std::pair do_get_mem_info(cuda_stream_view) const override + [[nodiscard]] std::pair do_get_mem_info( + [[maybe_unused]] cuda_stream_view stream) const override { std::size_t free_size{}; std::size_t total_size{}; diff --git a/include/rmm/thrust_rmm_allocator.h b/include/rmm/thrust_rmm_allocator.h index 3bbcab0a5..0b78d5497 100644 --- a/include/rmm/thrust_rmm_allocator.h +++ b/include/rmm/thrust_rmm_allocator.h @@ -33,9 +33,9 @@ using exec_policy_t = std::unique_ptr; * @brief Returns a unique_ptr to a Thrust CUDA execution policy that uses RMM * for temporary memory allocation. * - * @Param stream The stream that the allocator will use + * @param stream The stream that the allocator will use * - * @Returns A Thrust execution policy that will use RMM for temporary memory + * @return A Thrust execution policy that will use RMM for temporary memory * allocation. */ [[deprecated("Use new exec_policy in rmm/exec_policy.hpp")]] inline exec_policy_t exec_policy(