cuda::experimental::async_buffer#

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.

template<class _Property, ::cuda::std::enable_if_t _Properties...> inline friend void get_property( const async_buffer&, _Property, ) noexcept#: Forwards the passed properties.