Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update memory_resource docs #1883

Merged
merged 6 commits into from
Jul 25, 2024
Merged

Update memory_resource docs #1883

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
530e453
Drop the synopsis
miscco Jun 12, 2024
a6fa2da
Update memory_resource docs
miscco Jun 13, 2024
e28c15e
Use the ugly names in documentation
miscco Jul 23, 2024
9b4fe00
Also uglify the tparam
miscco Jul 23, 2024
a8a696c
Address more review comments
miscco Jul 23, 2024
7879d7f
Apply suggestions from code review
miscco Jul 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 30 additions & 49 deletions libcudacxx/include/cuda/__memory_resource/cuda_managed_memory_resource.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,7 @@

_LIBCUDACXX_BEGIN_NAMESPACE_CUDA_MR

/**
* @brief `cuda_managed_memory_resource` uses cudaMallocManaged / cudaFree for allocation/deallocation.
*/
//! @brief \c cuda_managed_memory_resource uses `cudaMallocManaged` / `cudaFree` for allocation / deallocation.
class cuda_managed_memory_resource
{
private:
Expand All @@ -55,13 +53,11 @@ class cuda_managed_memory_resource
_LIBCUDACXX_ASSERT(__flags_ == __flags, "Unexpected flags passed to cuda_managed_memory_resource");
}

/**
* @brief Allocate CUDA unified memory of size at least \p __bytes.
* @param __bytes The size in bytes of the allocation.
* @param __alignment The requested alignment of the allocation.
* @throw cuda::cuda_error of the returned error code
* @return Pointer to the newly allocated memory
*/
//! @brief Allocate CUDA unified memory of size at least \p __bytes.
//! @param __bytes The size in bytes of the allocation.
//! @param __alignment The requested alignment of the allocation.
//! @throw cuda::cuda_error of the returned error code
//! @return Pointer to the newly allocated memory
_CCCL_NODISCARD void* allocate(const size_t __bytes, const size_t __alignment = default_cuda_malloc_alignment) const
{
// We need to ensure that the provided alignment matches the minimal provided alignment
Expand All @@ -76,12 +72,10 @@ class cuda_managed_memory_resource
return __ptr;
}

/**
* @brief Deallocate memory pointed to by \p __ptr.
* @param __ptr Pointer to be deallocated. Must have been allocated through a call to `allocate`
* @param __bytes The number of bytes that was passed to the `allocate` call that returned \p __ptr.
* @param __alignment The alignment that was passed to the `allocate` call that returned \p __ptr.
*/
//! @brief Deallocate memory pointed to by \p __ptr.
//! @param __ptr Pointer to be deallocated. Must have been allocated through a call to `allocate`
//! @param __bytes The number of bytes that was passed to the `allocate` call that returned \p __ptr.
//! @param __alignment The alignment that was passed to the `allocate` call that returned \p __ptr.
void deallocate(void* __ptr, const size_t, const size_t __alignment = default_cuda_malloc_alignment) const
{
// We need to ensure that the provided alignment matches the minimal provided alignment
Expand All @@ -91,32 +85,28 @@ class cuda_managed_memory_resource
(void) __alignment;
}

/**
* @brief Equality comparison with another cuda_managed_memory_resource
* @return Whether both cuda_managed_memory_resource were constructed with the same flags
*/
//! @brief Equality comparison with another \c cuda_managed_memory_resource
//! @param __other The other \c cuda_managed_memory_resource
//! @return Whether both \c cuda_managed_memory_resource were constructed with the same flags
_CCCL_NODISCARD constexpr bool operator==(cuda_managed_memory_resource const& __other) const noexcept
{
return __flags_ == __other.__flags_;
}
# if _CCCL_STD_VER <= 2017
/**
* @brief Inequality comparison with another cuda_managed_memory_resource
* @return Whether both cuda_managed_memory_resource were constructed with different flags
*/
//! @brief Inequality comparison with another \c cuda_managed_memory_resource
//! @param __other The other \c cuda_managed_memory_resource
//! @return Whether both \c cuda_managed_memory_resource were constructed with different flags
_CCCL_NODISCARD constexpr bool operator!=(cuda_managed_memory_resource const& __other) const noexcept
{
return __flags_ != __other.__flags_;
}
# endif // _CCCL_STD_VER <= 2017

/**
* @brief Equality comparison between a cuda_memory_resource and another resource
* @param __lhs The cuda_memory_resource
* @param __rhs The resource to compare to
* @return If the underlying types are equality comparable, returns the result of equality comparison of both
* resources. Otherwise, returns false.
*/
//! @brief Equality comparison between a \c cuda_memory_resource and another resource
//! @param __lhs The \c cuda_memory_resource
//! @param __rhs The resource to compare to
//! @return If the underlying types are equality comparable, returns the result of equality comparison of both
//! resources. Otherwise, returns false.
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator==(cuda_managed_memory_resource const& __lhs, _Resource const& __rhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_managed_memory_resource, _Resource>)
Expand All @@ -125,29 +115,26 @@ class cuda_managed_memory_resource
== resource_ref<>{const_cast<_Resource&>(__rhs)};
}
# if _CCCL_STD_VER <= 2017
/**
* @copydoc cuda_managed_memory_resource::operator<_Resource>==(cuda_managed_memory_resource const&, _Resource const&)
*/
//! @copydoc cuda_managed_memory_resource::operator<_Resource>==(cuda_managed_memory_resource const&, _Resource
//! const&)
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator==(_Resource const& __rhs, cuda_managed_memory_resource const& __lhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_managed_memory_resource, _Resource>)
{
return resource_ref<>{const_cast<cuda_managed_memory_resource&>(__lhs)}
== resource_ref<>{const_cast<_Resource&>(__rhs)};
}
/**
* @copydoc cuda_managed_memory_resource::operator<_Resource>==(cuda_managed_memory_resource const&, _Resource const&)
*/
//! @copydoc cuda_managed_memory_resource::operator<_Resource>==(cuda_managed_memory_resource const&, _Resource
//! const&)
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator!=(cuda_managed_memory_resource const& __lhs, _Resource const& __rhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_managed_memory_resource, _Resource>)
{
return resource_ref<>{const_cast<cuda_managed_memory_resource&>(__lhs)}
!= resource_ref<>{const_cast<_Resource&>(__rhs)};
}
/**
* @copydoc cuda_managed_memory_resource::operator<_Resource>==(cuda_managed_memory_resource const&, _Resource const&)
*/
//! @copydoc cuda_managed_memory_resource::operator<_Resource>==(cuda_managed_memory_resource const&, _Resource
//! const&)
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator!=(_Resource const& __rhs, cuda_managed_memory_resource const& __lhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_managed_memory_resource, _Resource>)
Expand All @@ -157,18 +144,12 @@ class cuda_managed_memory_resource
}
# endif // _CCCL_STD_VER <= 2017

/**
* @brief Enables the `device_accessible` property
*/
//! @brief Enables the \c device_accessible property
friend constexpr void get_property(cuda_managed_memory_resource const&, device_accessible) noexcept {}
/**
* @brief Enables the `host_accessible` property
*/
//! @brief Enables the \c host_accessible property
friend constexpr void get_property(cuda_managed_memory_resource const&, host_accessible) noexcept {}

/**
* @brief Checks whether the passed in alignment is valid
*/
//! @brief Checks whether the passed in alignment is valid
static constexpr bool __is_valid_alignment(const size_t __alignment) noexcept
{
return __alignment <= default_cuda_malloc_alignment && (default_cuda_malloc_alignment % __alignment == 0);
Expand Down
70 changes: 24 additions & 46 deletions libcudacxx/include/cuda/__memory_resource/cuda_memory_resource.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,18 +38,14 @@

_LIBCUDACXX_BEGIN_NAMESPACE_CUDA_MR

/**
* @brief `cuda_memory_resource` uses cudaMalloc / cudaFree for allocation/deallocation.
*/
//! @brief cuda_memory_resource uses `cudaMalloc` / `cudaFree` for allocation / deallocation.
struct cuda_memory_resource
{
/**
* @brief Allocate device memory of size at least \p __bytes.
* @param __bytes The size in bytes of the allocation.
* @param __alignment The requested alignment of the allocation.
* @throw std::bad_alloc in case of invalid alignment or cuda::cuda_error of the returned error code.
* @return Pointer to the newly allocated memory
*/
//! @brief Allocate device memory of size at least \p __bytes.
//! @param __bytes The size in bytes of the allocation.
//! @param __alignment The requested alignment of the allocation.
//! @throw std::bad_alloc in case of invalid alignment or \c cuda::cuda_error of the returned error code.
//! @return Pointer to the newly allocated memory
_CCCL_NODISCARD void* allocate(const size_t __bytes, const size_t __alignment = default_cuda_malloc_alignment) const
{
// We need to ensure that the provided alignment matches the minimal provided alignment
Expand All @@ -63,12 +59,10 @@ struct cuda_memory_resource
return __ptr;
}

/**
* @brief Deallocate memory pointed to by \p __ptr.
* @param __ptr Pointer to be deallocated. Must have been allocated through a call to `allocate`
* @param __bytes The number of bytes that was passed to the `allocate` call that returned \p __ptr.
* @param __alignment The alignment that was passed to the `allocate` call that returned \p __ptr.
*/
//! @brief Deallocate memory pointed to by \p __ptr.
//! @param __ptr Pointer to be deallocated. Must have been allocated through a call to `allocate`
//! @param __bytes The number of bytes that was passed to the `allocate` call that returned \p __ptr.
//! @param __alignment The alignment that was passed to the `allocate` call that returned \p __ptr.
void deallocate(void* __ptr, const size_t, const size_t __alignment = default_cuda_malloc_alignment) const
{
// We need to ensure that the provided alignment matches the minimal provided alignment
Expand All @@ -78,60 +72,48 @@ struct cuda_memory_resource
(void) __alignment;
}

/**
* @brief Equality comparison with another cuda_memory_resource
* @return true
*/
//! @brief Equality comparison with another \c cuda_memory_resource
//! @return true
_CCCL_NODISCARD constexpr bool operator==(cuda_memory_resource const&) const noexcept
{
return true;
}
# if _CCCL_STD_VER <= 2017
/**
* @brief Inequality comparison with another cuda_memory_resource
* @return false
*/
//! @brief Inequality comparison with another \c cuda_memory_resource
//! @return false
_CCCL_NODISCARD constexpr bool operator!=(cuda_memory_resource const&) const noexcept
{
return false;
}
# endif // _CCCL_STD_VER <= 2017

/**
* @brief Equality comparison between a cuda_memory_resource and another resource
* @param __lhs The cuda_memory_resource
* @param __rhs The resource to compare to
* @return If the underlying types are equality comparable, returns the result of equality comparison of both
* resources. Otherwise, returns false.
*/
//! @brief Equality comparison between a \c cuda_memory_resource and another resource
//! @param __lhs The \c cuda_memory_resource
//! @param __rhs The resource to compare to
//! @return If the underlying types are equality comparable, returns the result of equality comparison of both
//! resources. Otherwise, returns false.
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator==(cuda_memory_resource const& __lhs, _Resource const& __rhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_memory_resource, _Resource>)
{
return resource_ref<>{const_cast<cuda_memory_resource&>(__lhs)} == resource_ref<>{const_cast<_Resource&>(__rhs)};
}
# if _CCCL_STD_VER <= 2017
/**
* @copydoc cuda_memory_resource::operator==<_Resource>(cuda_memory_resource const&, _Resource const&)
*/
//! @copydoc cuda_memory_resource::operator==<_Resource>(cuda_memory_resource const&, _Resource const&)
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator==(_Resource const& __rhs, cuda_memory_resource const& __lhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_memory_resource, _Resource>)
{
return resource_ref<>{const_cast<cuda_memory_resource&>(__lhs)} == resource_ref<>{const_cast<_Resource&>(__rhs)};
}
/**
* @copydoc cuda_memory_resource::operator==<_Resource>(cuda_memory_resource const&, _Resource const&)
*/
//! @copydoc cuda_memory_resource::operator==<_Resource>(cuda_memory_resource const&, _Resource const&)
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator!=(cuda_memory_resource const& __lhs, _Resource const& __rhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_memory_resource, _Resource>)
{
return resource_ref<>{const_cast<cuda_memory_resource&>(__lhs)} != resource_ref<>{const_cast<_Resource&>(__rhs)};
}
/**
* @copydoc cuda_memory_resource::operator==<_Resource>(cuda_memory_resource const&, _Resource const&)
*/
//! @copydoc cuda_memory_resource::operator==<_Resource>(cuda_memory_resource const&, _Resource const&)
template <class _Resource>
_CCCL_NODISCARD_FRIEND auto operator!=(_Resource const& __rhs, cuda_memory_resource const& __lhs) noexcept
_LIBCUDACXX_TRAILING_REQUIRES(bool)(__different_resource<cuda_memory_resource, _Resource>)
Expand All @@ -140,14 +122,10 @@ struct cuda_memory_resource
}
# endif // _CCCL_STD_VER <= 2017

/**
* @brief Enables the `device_accessible` property
*/
//! @brief Enables the \c device_accessible property
friend constexpr void get_property(cuda_memory_resource const&, device_accessible) noexcept {}

/**
* @brief Checks whether the passed in alignment is valid
*/
//! @brief Checks whether the passed in alignment is valid
static constexpr bool __is_valid_alignment(const size_t __alignment) noexcept
{
return __alignment <= default_cuda_malloc_alignment && (default_cuda_malloc_alignment % __alignment == 0);
Expand Down
Loading
Loading