rapidsmpf::Buffer Class Reference

Buffer representing device or host memory. More...

#include <buffer.hpp>

Public Types
using	DeviceStorageT = std::unique_ptr< rmm::device_buffer >
	Storage type for the device buffer.
using	HostStorageT = std::unique_ptr< std::vector< uint8_t > >
	Storage type for the host buffer.
using	StorageT = std::variant< DeviceStorageT, HostStorageT >
	Storage type in Buffer, which could be either host or device memory.

Public Member Functions
HostStorageT const &	host () const
	Access the underlying host memory buffer (const). More...
DeviceStorageT const &	device () const
	Access the underlying device memory buffer (const). More...
std::byte const *	data () const
	Access the underlying memory buffer (host or device memory). More...
template<typename F >
auto	write_access (F &&f) -> std::invoke_result_t< F, std::byte *, rmm::cuda_stream_view >
	Provides stream-ordered write access to the buffer. More...
std::byte *	exclusive_data_access ()
	Acquire non-stream-ordered exclusive access to the buffer's memory. More...
void	unlock ()
	Release the exclusive lock acquired by exclusive_data_access().
constexpr MemoryType	mem_type () const
	Get the memory type of the buffer. More...
constexpr rmm::cuda_stream_view	stream () const noexcept
	Get the associated CUDA stream. More...
bool	is_latest_write_done () const
	Check whether the buffer's most recent write has completed. More...
	Buffer (Buffer &&)=delete
	Delete move and copy constructors and assignment operators.
	Buffer (Buffer const &)=delete
Buffer &	operator= (Buffer &o)=delete
Buffer &	operator= (Buffer &&o)=delete

Public Attributes
std::size_t const	size
	The size of the buffer in bytes.

Friends
class	BufferResource

Detailed Description

Buffer representing device or host memory.

Note

The constructors are private, use BufferResource to construct buffers.

The memory type (e.g., host or device) is constant and cannot change during the buffer's lifetime.

This buffer is stream-ordered and has an associated CUDA stream (see stream()). All work (host and device) that reads or writes the buffer must either be enqueued on that stream or be synchronized with it before accessing the memory.

When passing the buffer to a non-stream-aware API (e.g., MPI, host-only code), you must ensure the last write has completed before the hand-off. Either synchronize the buffer's stream (e.g., stream().synchronize()) or verify completion via is_latest_write_done().

Definition at line 53 of file buffer.hpp.

Member Function Documentation

data()

std::byte const* rapidsmpf::Buffer::data

(

)

const

Access the underlying memory buffer (host or device memory).

Returns

A const pointer to the underlying host or device memory.

Exceptions

std::logic_error	if the buffer does not manage any memory.
std::logic_error	If the buffer is locked.

device()

DeviceStorageT const& rapidsmpf::Buffer::device

(

)

const

Access the underlying device memory buffer (const).

Returns

A const reference to the unique pointer managing the device memory.

Exceptions

std::logic_error	if the buffer does not manage device memory.
std::logic_error	If the buffer is locked.

exclusive_data_access()

std::byte* rapidsmpf::Buffer::exclusive_data_access

(

)

Acquire non-stream-ordered exclusive access to the buffer's memory.

Alternative to write_access(). Acquires an internal exclusive lock so that any other access through the Buffer API (including write_access()) will fail with std::logic_error while the lock is held. The lock remains held until unlock() is called. This lock is not a concurrency mechanism; it only prevents accidental access to the Buffer through the rest of the Buffer API while locked.

Use this when integrating with non-stream-aware consumer APIs that require a raw pointer and cannot be expressed as work on a CUDA stream (e.g., MPI, blocking host I/O).

Note

Prefer write_access(...) if you can express the operation as a single callable on a stream, even if that requires manually synchronizing the stream before the callable returns.

Returns

Pointer to the underlying storage.

Exceptions

std::logic_error	If the buffer is already locked.
std::logic_error	If is_latest_write_done() != true.

See also

write_access(), is_locked(), unlock()

host()

HostStorageT const& rapidsmpf::Buffer::host

(

)

const

Access the underlying host memory buffer (const).

Returns

A reference to the unique pointer managing the host memory.

Exceptions

std::logic_error	if the buffer does not manage host memory.
std::logic_error	If the buffer is locked.

is_latest_write_done()

bool rapidsmpf::Buffer::is_latest_write_done

(

)

const

Check whether the buffer's most recent write has completed.

Returns whether the CUDA event that tracks the most recent write into this buffer has been signaled.

Use this to guard non-stream-ordered consumer-APIs that do not accept a CUDA stream (e.g., MPI sends/receives, host-side reads).

Note

This is a non-blocking, point-in-time status check and is subject to TOCTOU races: another thread may enqueue additional writes after this returns true. Ensure no further writes are enqueued, or establish stronger synchronization (e.g., synchronize the buffer's stream) before using the buffer.

Returns

true if the last recorded write event has completed; false otherwise.

Exceptions

std::logic_error

If the buffer is locked.

// Example: send the buffer via MPI (non-stream-ordered).
if (buffer.is_latest_write_done()) {
  MPI_Isend(buffer.data(), buffer.size(), MPI_BYTE, dst, tag, comm, &req);
} else {
  // Ensure completion before handing to MPI.
  buffer.stream().synchronize();
  MPI_Isend(buffer.data(), buffer.size(), MPI_BYTE, dst, tag, comm, &req);
}

mem_type()

constexpr MemoryType rapidsmpf::Buffer::mem_type ( ) const

inlineconstexpr

Get the memory type of the buffer.

Returns

The memory type of the buffer.

Exceptions

std::logic_error

if the buffer is not initialized.

Definition at line 200 of file buffer.hpp.

stream()

constexpr rmm::cuda_stream_view rapidsmpf::Buffer::stream ( ) const

inlineconstexprnoexcept

Get the associated CUDA stream.

All operations must either use this stream or synchronize with it before accessing the underlying data (both host and device memory).

Returns

The associated CUDA stream.

Definition at line 218 of file buffer.hpp.

write_access()

template<typename F >

auto rapidsmpf::Buffer::write_access ( F &&  f ) -> std::invoke_result_t<F, std::byte*, rmm::cuda_stream_view>

inline

Provides stream-ordered write access to the buffer.

Calls f with a pointer to the buffer's memory and the buffer's stream (i.e., this->stream()).

The callable must be invocable as:

• R(std::byte*, rmm::cuda_stream_view).

All work performed by f must be stream-ordered on the buffer's stream. Enqueuing work on any other stream without synchronizing with the buffer's stream before and after the call is undefined behavior. In other words, f must behave as a single stream-ordered operation, similar to issuing one cudaMemcpyAsync on the buffer's stream. For non-stream-aware integrations, use exclusive_data_access().

After f returns, an event is recorded on the buffer's stream, establishing the new "latest write" for this buffer.

Warning

The pointer is valid only for the duration of the call. Using it outside of f is undefined behavior.

Template Parameters

F	Callable type.

Parameters

f	Callable that accepts (std::byte*, rmm::cuda_stream_view).

Returns

Whatever f returns (void if none).

Exceptions

std::logic_error

If the buffer is locked.

// Snippet: copy data from `src_ptr` into `buffer` on the buffer's stream.
buffer.write_access([&](std::byte* buffer_ptr, rmm::cuda_stream_view stream) {
  assert(buffer.stream().value() == stream.value());
  RAPIDSMPF_CUDA_TRY_ALLOC(cudaMemcpyAsync(
      buffer_ptr,
      src_ptr,
      num_bytes,
      cudaMemcpyDefault,
      stream
  ));
});

Definition at line 141 of file buffer.hpp.

---

The documentation for this class was generated from the following file:

• /__w/rapidsmpf/rapidsmpf/cpp/include/rapidsmpf/buffer/buffer.hpp