Deprecate detail::available_device_memory, most detail/aligned.hpp ut…

…ilities, and optional pool_memory_resource initial size (#1424)

Follow-on to #1417, this PR deprecates the following:

 - `rmm::detail::available_device_memory` in favor of rmm::available_device_memory
 - `rmm::detail::is_aligned`, `rmm::detail::align_up` and related alignment utility functions in favor of the `rmm::` top level namespace versions.
 - The `rmm::pool_memory_resource` constructors that take an optional initial size parameter.

Should be merged after the following:
 - rapidsai/cugraph#4086
 - rapidsai/cudf#14741
 - rapidsai/raft#2088

Authors:
  - Mark Harris (https://github.com/harrism)

Approvers:
  - Michael Schellenberger Costa (https://github.com/miscco)
  - Rong Ou (https://github.com/rongou)

URL: #1424

include/rmm/aligned.hpp

@@ -47,7 +47,10 @@ static constexpr std::size_t CUDA_ALLOCATION_ALIGNMENT{256};
  *
  * @return Whether the input a power of two with non-negative exponent
  */
-constexpr bool is_pow2(std::size_t value) { return (value != 0U) && ((value & (value - 1)) == 0U); }
+[[nodiscard]] constexpr bool is_pow2(std::size_t value) noexcept
+{
+  return (value != 0U) && ((value & (value - 1)) == 0U);
+}
 
 /**
  * @brief Returns whether or not `alignment` is a valid memory alignment.
@@ -56,7 +59,10 @@ constexpr bool is_pow2(std::size_t value) { return (value != 0U) && ((value & (v
  *
  * @return Whether the alignment is valid
  */
-constexpr bool is_supported_alignment(std::size_t alignment) { return is_pow2(alignment); }
+[[nodiscard]] constexpr bool is_supported_alignment(std::size_t alignment) noexcept
+{
+  return is_pow2(alignment);
+}
 
 /**
  * @brief Align up to nearest multiple of specified power of 2
@@ -66,7 +72,7 @@ constexpr bool is_supported_alignment(std::size_t alignment) { return is_pow2(al
  *
  * @return Return the aligned value, as one would expect
  */
-constexpr std::size_t align_up(std::size_t value, std::size_t alignment) noexcept
+[[nodiscard]] constexpr std::size_t align_up(std::size_t value, std::size_t alignment) noexcept
 {
   assert(is_supported_alignment(alignment));
   return (value + (alignment - 1)) & ~(alignment - 1);
@@ -80,7 +86,7 @@ constexpr std::size_t align_up(std::size_t value, std::size_t alignment) noexcep
  *
  * @return Return the aligned value, as one would expect
  */
-constexpr std::size_t align_down(std::size_t value, std::size_t alignment) noexcept
+[[nodiscard]] constexpr std::size_t align_down(std::size_t value, std::size_t alignment) noexcept
 {
   assert(is_supported_alignment(alignment));
   return value & ~(alignment - 1);
@@ -94,7 +100,7 @@ constexpr std::size_t align_down(std::size_t value, std::size_t alignment) noexc
  *
  * @return true if aligned
  */
-constexpr bool is_aligned(std::size_t value, std::size_t alignment) noexcept
+[[nodiscard]] constexpr bool is_aligned(std::size_t value, std::size_t alignment) noexcept
 {
   assert(is_supported_alignment(alignment));
   return value == align_down(value, alignment);
@@ -108,7 +114,8 @@ constexpr bool is_aligned(std::size_t value, std::size_t alignment) noexcept
  *
  * @return true if the pointer is aligned
  */
-inline bool is_pointer_aligned(void* ptr, std::size_t alignment = CUDA_ALLOCATION_ALIGNMENT)
+[[nodiscard]] inline bool is_pointer_aligned(
+  void* ptr, std::size_t alignment = CUDA_ALLOCATION_ALIGNMENT) noexcept
 {
   // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
   return is_aligned(reinterpret_cast<std::uintptr_t>(ptr), alignment);

include/rmm/cuda_device.hpp

@@ -125,7 +125,7 @@ namespace detail {
  *
  * @return The available and total device memory in bytes for the current device as a std::pair.
  */
-//[[deprecated("Use `rmm::available_device_memory` instead.")]]  //
+[[deprecated("Use `rmm::available_device_memory` instead.")]]  //
 const auto available_device_memory = rmm::available_device_memory;
 
 }  // namespace detail

include/rmm/detail/aligned.hpp

@@ -16,6 +16,8 @@
 
 #pragma once
 
+#include <rmm/aligned.hpp>
+
 #include <cassert>
 #include <cstddef>
 #include <cstdint>
@@ -28,25 +30,34 @@ namespace rmm::detail {
  * @brief Default alignment used for host memory allocated by RMM.
  *
  */
-static constexpr std::size_t RMM_DEFAULT_HOST_ALIGNMENT{alignof(std::max_align_t)};
+[[deprecated("Use rmm::RMM_DEFAULT_HOST_ALIGNMENT instead.")]] static constexpr std::size_t
+  RMM_DEFAULT_HOST_ALIGNMENT{rmm::RMM_DEFAULT_HOST_ALIGNMENT};
 
 /**
  * @brief Default alignment used for CUDA memory allocation.
  *
  */
-static constexpr std::size_t CUDA_ALLOCATION_ALIGNMENT{256};
+[[deprecated("Use rmm::CUDA_ALLOCATION_ALIGNMENT instead.")]] static constexpr std::size_t
+  CUDA_ALLOCATION_ALIGNMENT{rmm::CUDA_ALLOCATION_ALIGNMENT};
 
 /**
  * @brief Returns whether or not `n` is a power of 2.
  *
  */
-constexpr bool is_pow2(std::size_t value) { return (value != 0U) && ((value & (value - 1)) == 0U); }
+[[deprecated("Use rmm::is_pow2 instead.")]] constexpr bool is_pow2(std::size_t value) noexcept
+{
+  return rmm::is_pow2(value);
+}
 
 /**
  * @brief Returns whether or not `alignment` is a valid memory alignment.
  *
  */
-constexpr bool is_supported_alignment(std::size_t alignment) { return is_pow2(alignment); }
+[[deprecated("Use rmm::is_supported_alignment instead.")]] constexpr bool is_supported_alignment(
+  std::size_t alignment) noexcept
+{
+  return rmm::is_pow2(alignment);
+}
 
 /**
  * @brief Align up to nearest multiple of specified power of 2
@@ -56,10 +67,10 @@ constexpr bool is_supported_alignment(std::size_t alignment) { return is_pow2(al
  *
  * @return Return the aligned value, as one would expect
  */
-constexpr std::size_t align_up(std::size_t value, std::size_t alignment) noexcept
+[[deprecated("Use rmm::align_up instead.")]] constexpr std::size_t align_up(
+  std::size_t value, std::size_t alignment) noexcept
 {
-  assert(is_supported_alignment(alignment));
-  return (value + (alignment - 1)) & ~(alignment - 1);
+  return rmm::align_up(value, alignment);
 }
 
 /**
@@ -70,10 +81,10 @@ constexpr std::size_t align_up(std::size_t value, std::size_t alignment) noexcep
  *
  * @return Return the aligned value, as one would expect
  */
-constexpr std::size_t align_down(std::size_t value, std::size_t alignment) noexcept
+[[deprecated("Use rmm::align_down instead.")]] constexpr std::size_t align_down(
+  std::size_t value, std::size_t alignment) noexcept
 {
-  assert(is_supported_alignment(alignment));
-  return value & ~(alignment - 1);
+  return rmm::align_down(value, alignment);
 }
 
 /**
@@ -84,16 +95,16 @@ constexpr std::size_t align_down(std::size_t value, std::size_t alignment) noexc
  *
  * @return true if aligned
  */
-constexpr bool is_aligned(std::size_t value, std::size_t alignment) noexcept
+[[deprecated("Use rmm::is_aligned instead.")]] constexpr bool is_aligned(
+  std::size_t value, std::size_t alignment) noexcept
 {
-  assert(is_supported_alignment(alignment));
-  return value == align_down(value, alignment);
+  return rmm::is_aligned(value, alignment);
 }
 
-inline bool is_pointer_aligned(void* ptr, std::size_t alignment = CUDA_ALLOCATION_ALIGNMENT)
+[[deprecated("Use rmm::is_pointer_aligned instead.")]] inline bool is_pointer_aligned(
+  void* ptr, std::size_t alignment = rmm::CUDA_ALLOCATION_ALIGNMENT)
 {
-  // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
-  return rmm::detail::is_aligned(reinterpret_cast<std::uintptr_t>(ptr), alignment);
+  return rmm::is_pointer_aligned(ptr, alignment);
 }
 
 /**
@@ -126,7 +137,7 @@ inline bool is_pointer_aligned(void* ptr, std::size_t alignment = CUDA_ALLOCATIO
 template <typename Alloc>
 void* aligned_allocate(std::size_t bytes, std::size_t alignment, Alloc alloc)
 {
-  assert(is_pow2(alignment));
+  assert(rmm::is_pow2(alignment));
 
   // allocate memory for bytes, plus potential alignment correction,
   // plus store of the correction offset

include/rmm/mr/device/device_memory_resource.hpp

@@ -173,7 +173,7 @@ class device_memory_resource {
    */
   void* allocate(std::size_t bytes, std::size_t alignment)
   {
-    return do_allocate(rmm::detail::align_up(bytes, alignment), cuda_stream_view{});
+    return do_allocate(rmm::align_up(bytes, alignment), cuda_stream_view{});
   }
 
   /**
@@ -191,7 +191,7 @@ class device_memory_resource {
    */
   void deallocate(void* ptr, std::size_t bytes, std::size_t alignment)
   {
-    do_deallocate(ptr, rmm::detail::align_up(bytes, alignment), cuda_stream_view{});
+    do_deallocate(ptr, rmm::align_up(bytes, alignment), cuda_stream_view{});
   }
 
   /**
@@ -209,7 +209,7 @@ class device_memory_resource {
    */
   void* allocate_async(std::size_t bytes, std::size_t alignment, cuda_stream_view stream)
   {
-    return do_allocate(rmm::detail::align_up(bytes, alignment), stream);
+    return do_allocate(rmm::align_up(bytes, alignment), stream);
   }
 
   /**
@@ -248,7 +248,7 @@ class device_memory_resource {
                         std::size_t alignment,
                         cuda_stream_view stream)
   {
-    do_deallocate(ptr, rmm::detail::align_up(bytes, alignment), stream);
+    do_deallocate(ptr, rmm::align_up(bytes, alignment), stream);
   }
 
   /**

include/rmm/mr/device/pool_memory_resource.hpp

@@ -126,7 +126,7 @@ class pool_memory_resource final
    * @param maximum_pool_size Maximum size, in bytes, that the pool can grow to. Defaults to all
    * of the available memory from the upstream resource.
    */
-  //[[deprecated("Must specify initial_pool_size")]]  //
+  [[deprecated("Must specify initial_pool_size")]]  //
   explicit pool_memory_resource(Upstream* upstream_mr,
                                 thrust::optional<std::size_t> initial_pool_size = thrust::nullopt,
                                 thrust::optional<std::size_t> maximum_pool_size = thrust::nullopt)
@@ -153,7 +153,7 @@ class pool_memory_resource final
    */
   template <typename Upstream2                                               = Upstream,
             cuda::std::enable_if_t<cuda::mr::async_resource<Upstream2>, int> = 0>
-  //[[deprecated("Must specify initial_pool_size")]]  //
+  [[deprecated("Must specify initial_pool_size")]]  //
   explicit pool_memory_resource(Upstream2& upstream_mr,
                                 thrust::optional<std::size_t> initial_pool_size = thrust::nullopt,
                                 thrust::optional<std::size_t> maximum_pool_size = thrust::nullopt)