cuda::experimental::async_buffer

Defined in include/cuda/experimental/__container/async_buffer.cuh

template<class _Tp, class ..._Properties> class async_buffer

async_buffer

async_buffer is a container that provides resizable typed storage allocated from a given memory resource. It handles alignment, release and growth of the allocation. The elements are initialized during construction, which may require a kernel launch.

In addition to being type-safe, async_buffer also takes a set of properties to ensure that e.g. execution space constraints are checked at compile time. However, only stateless properties can be forwarded. To use a stateful property, implement get_property(const async_buffer&, Property).

Template Parameters

_Tp – the type to be stored in the buffer
_Properties... – The properties the allocated memory satisfies

Public Types

using value_type = _Tp 

using reference = _Tp&

using const_reference = const _Tp&

using pointer = _Tp*

using const_pointer = const _Tp*

using iterator = heterogeneous_iterator<_Tp, _Properties...>

using const_iterator = heterogeneous_iterator<const _Tp, _Properties...>

using reverse_iterator = cuda::std::reverse_iterator<iterator>

using const_reverse_iterator = cuda::std::reverse_iterator<const_iterator>

using size_type = cuda::std::size_t

using difference_type = cuda::std::ptrdiff_t

Public Functions

inline async_buffer(const async_buffer &__other)

Copy-constructs from a async_buffer.

Parameters: __other – The other async_buffer.

inline async_buffer(async_buffer &&__other) noexcept

Move-constructs from a async_buffer.

Parameters: __other – The other async_buffer. After move construction, the other buffer can only be assigned to or destroyed.

template<class ..._OtherProperties, ::cuda::std::enable_if_t<__properties_match<_OtherProperties...>, int> = 0> inline explicit async_buffer(const async_buffer<_Tp, _OtherProperties...> &__other)

Copy-constructs from a async_buffer with matching properties.

Parameters: __other – The other async_buffer.

template<class ..._OtherProperties, ::cuda::std::enable_if_t<__properties_match<_OtherProperties...>, int> = 0> inline explicit async_buffer(async_buffer<_Tp, _OtherProperties...> &&__other) noexcept

Move-constructs from a async_buffer with matching properties.

Parameters: __other – The other async_buffer. After move construction, the other buffer can only be assigned to or destroyed.

inline async_buffer(const __env_t &__env)

Constructs an empty async_buffer using an environment.

Note

No memory is allocated.

Parameters: __env – The environment providing the needed information

inline explicit async_buffer(const __env_t &__env, const size_type __size)

Constructs a async_buffer of size __size using a memory resource and value-initializes __size elements.

Note

If __size == 0 then no memory is allocated.

Parameters

__env – The environment used to query the memory resource.
__size – The size of the async_buffer. Defaults to zero

inline explicit async_buffer(const __env_t &__env, const size_type __size, const _Tp &__value)

Constructs a async_buffer of size __size using a memory resource and copy-constructs __size elements from __value.

Note

If __size == 0 then no memory is allocated.

Parameters

__env – The environment used to query the memory resource.
__size – The size of the async_buffer.
__value – The value all elements are copied from.

inline explicit async_buffer(const __env_t &__env, const size_type __size, ::cuda::experimental::no_init_t)

Constructs a async_buffer of size __size using a memory and leaves all elements uninitialized.

Warning

This constructor does NOT initialize any elements. It is the user’s responsibility to ensure that the elements within [vec.begin(), vec.end()) are properly initialized, e.g with cuda::std::uninitialized_copy. At the destruction of the async_buffer all elements in the range [vec.begin(), vec.end()) will be destroyed.

Parameters

__env – The environment used to query the memory resource.
__size – The size of the async_buffer.

template<class _Iter, ::cuda::std::enable_if_t<cuda::std::__is_cpp17_forward_iterator<_Iter>::value, int> = 0> inline async_buffer(const __env_t &__env, _Iter __first, _Iter __last)

Constructs a async_buffer using a memory resource and copy-constructs all elements from the forward range [__first, __last)

Note

If __first == __last then no memory is allocated

Parameters

__env – The environment used to query the memory resource.
__first – The start of the input sequence.
__last – The end of the input sequence.

inline async_buffer(const __env_t &__env, cuda::std::initializer_list<_Tp> __ilist)

Constructs a async_buffer using a memory resource and copy-constructs all elements from __ilist.

Note

If __ilist.size() == 0 then no memory is allocated

Parameters

__env – The environment used to query the memory resource.
__ilist – The initializer_list being copied into the async_buffer.

template<class _Range, ::cuda::std::enable_if_t<__compatible_range<_Range> && cuda::std::ranges::forward_range<_Range> && cuda::std::ranges::sized_range<_Range>, int> = 0> inline async_buffer(const __env_t &__env, _Range &&__range)

Constructs a async_buffer using a memory resource and an input range.

Note

If __range.size() == 0 then no memory is allocated.

Parameters

__env – The environment used to query the memory resource.
__range – The input range to be moved into the async_buffer.

inline iterator begin() noexcept

inline const_iterator begin() const noexcept: Returns an immutable iterator to the first element of the async_buffer. If the async_buffer is empty, the returned iterator will be equal to end().

inline const_iterator cbegin() const noexcept: Returns an immutable iterator to the first element of the async_buffer. If the async_buffer is empty, the returned iterator will be equal to end().

inline iterator end() noexcept: Returns an iterator to the element following the last element of the async_buffer. This element acts as a placeholder; attempting to access it results in undefined behavior.

inline const_iterator end() const noexcept: Returns an immutable iterator to the element following the last element of the async_buffer. This element acts as a placeholder; attempting to access it results in undefined behavior.

inline const_iterator cend() const noexcept: Returns an immutable iterator to the element following the last element of the async_buffer. This element acts as a placeholder; attempting to access it results in undefined behavior.

inline reverse_iterator rbegin() noexcept: Returns a reverse iterator to the first element of the reversed async_buffer. It corresponds to the last element of the non-reversed async_buffer. If the async_buffer is empty, the returned iterator is equal to rend().

inline const_reverse_iterator rbegin() const noexcept: Returns an immutable reverse iterator to the first element of the reversed async_buffer. It corresponds to the last element of the non-reversed async_buffer. If the async_buffer is empty, the returned iterator is equal to rend().

inline const_reverse_iterator crbegin() const noexcept: Returns an immutable reverse iterator to the first element of the reversed async_buffer. It corresponds to the last element of the non-reversed async_buffer. If the async_buffer is empty, the returned iterator is equal to rend().

inline reverse_iterator rend() noexcept: Returns a reverse iterator to the element following the last element of the reversed async_buffer. It corresponds to the element preceding the first element of the non-reversed async_buffer. This element acts as a placeholder, attempting to access it results in undefined behavior.

inline const_reverse_iterator rend() const noexcept: Returns an immutable reverse iterator to the element following the last element of the reversed async_buffer. It corresponds to the element preceding the first element of the non-reversed async_buffer. This element acts as a placeholder, attempting to access it results in undefined behavior.

inline const_reverse_iterator crend() const noexcept: Returns an immutable reverse iterator to the element following the last element of the reversed async_buffer. It corresponds to the element preceding the first element of the non-reversed async_buffer. This element acts as a placeholder, attempting to access it results in undefined behavior.

inline pointer data() noexcept: Returns a pointer to the first element of the async_buffer. If the async_buffer has not allocated memory the pointer will be null.

inline const_pointer data() const noexcept: Returns a pointer to the first element of the async_buffer. If the async_buffer has not allocated memory the pointer will be null.

inline reference get_unsynchronized(const size_type __n) noexcept

inline const_reference get_unsynchronized(const size_type __n) const noexcept

Returns a reference to the __n ‘th element of the async_vector.

Note

Does not synchronize with the stored stream

Parameters: __n – The index of the element we want to access

inline size_type size() const noexcept

inline bool empty() const noexcept: Returns true if the async_buffer is empty.

inline const __resource_t &memory_resource() const noexcept

Returns a c const reference to the any_resource that holds the memory resource used to allocate the async_buffer

inline constexpr stream_ref stream() const noexcept: Returns the stored stream.

inline constexpr void set_stream(stream_ref __new_stream)

Replaces the stored stream.

Note

Always synchronizes with the old stream

Parameters: __new_stream – the new stream

inline constexpr void set_stream_unsynchronized(stream_ref __new_stream) noexcept

Replaces the stored stream.

Warning

This does not synchronize between __new_stream and the current stream. It is the user’s responsibility to ensure proper stream order going forward

Parameters: __new_stream – the new stream

inline void operator=(async_buffer &&__other)

Move assignment operator.

Parameters: __other – The other async_buffer. After move assignment, the other buffer can only be assigned to or destroyed.

inline void swap(async_buffer &__other) noexcept

Swaps the contents of a async_buffer with those of __other.

Parameters: __other – The other async_buffer.

inline void destroy(): Destroys the async_buffer, deallocates the buffer and destroys the memory resource.

Warning

After this explicit destroy call, the buffer can only be assigned to or destroyed.

Friends

friend class async_buffer

inline friend void swap(async_buffer &__lhs, async_buffer &__rhs) noexcept

Swaps the contents of two async_buffers.

Parameters

__lhs – One async_buffer.
__rhs – The other async_buffer.

template<class _DeviceAccessible = device_accessible> inline friend auto transform_device_argument(::cuda::stream_ref, async_buffer &__self) noexcept -> cuda::std::span<_Tp> requires (cuda::std::__is_included_in_v<_DeviceAccessible, _Properties...>)

Causes the buffer to be treated as a span when passed to cudax::launch.

Pre: The buffer must have the cuda::mr::device_accessible property.

template<class _DeviceAccessible = device_accessible> inline friend auto transform_device_argument(::cuda::stream_ref, const async_buffer &__self) noexcept -> cuda::std::span<const _Tp> requires (cuda::std::__is_included_in_v<_DeviceAccessible, _Properties...>)

Causes the buffer to be treated as a span when passed to cudax::launch.

Pre: The buffer must have the cuda::mr::device_accessible property.