rapidsmpf::Buffer Class Reference

Buffer representing device or host memory. More...

#include <buffer.hpp>

Public Types
using	DeviceBufferT = std::unique_ptr< rmm::device_buffer >
	Storage type for a device buffer.
using	HostBufferT = std::unique_ptr< HostBuffer >
	Storage type for a host buffer.

Public Member Functions
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...
CudaEvent const &	latest_write_event () const noexcept
	Get the CUDA event that tracks the latest write into the buffer. More...
void	rebind_stream (rmm::cuda_stream_view new_stream)
	Rebind the buffer to a new 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.

Static Public Attributes
static constexpr std::array< MemoryType, 1 >	device_buffer_types {MemoryType::DEVICE}
	Memory types suitable for constructing a device backed buffer. More...
static constexpr std::array< MemoryType, 2 >	host_buffer_types
	Memory types suitable for constructing a host backed buffer. More...

Friends
class	BufferResource

Detailed Description

Buffer representing device or host memory.

A Buffer holds either device memory or host memory, determined by its memory type at construction. See device_buffer_types and host_buffer_types for the sets of memory types that result in device-backed and host-backed storage.

Buffers are stream ordered and have an associated CUDA stream (see stream()). All work that reads or writes the buffer must either be enqueued on that stream or be synchronized with it before accessing the memory. For example, when passing the buffer to a non-stream aware API (e.g., MPI or host-only code), the caller must ensure that the most recent write has completed before the hand off. This can be done by synchronizing the buffer's stream or by checking is_latest_write_done().

To obtain an rmm::device_buffer from a Buffer, first ensure that the buffer's memory type is one of the types listed in device_buffer_types (moving the buffer if necessary), then call release_device_buffer().

Note

The constructors are private. Buffers are created through BufferResource.

Definition at line 47 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.

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).

Warning

The Buffer does not track read access to its underlying storage, and so one should be aware of write-after-read anti-dependencies when obtaining exclusive access.

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()

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.

Warning

This check only confirms that there are no pending writes to the Buffer. Pending stream-ordered reads from the Buffer are not tracked and therefore one should be aware of write-after-read anti-dependencies when using this check to pass from stream-ordered to non-stream-ordered code.

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);
}

latest_write_event()

CudaEvent const& rapidsmpf::Buffer::latest_write_event ( ) const

inlinenoexcept

Get the CUDA event that tracks the latest write into the buffer.

Returns

The CUDA event that tracks the latest write into the buffer.

Definition at line 214 of file buffer.hpp.

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 193 of file buffer.hpp.

rebind_stream()

void rapidsmpf::Buffer::rebind_stream

(

rmm::cuda_stream_view

new_stream

)

Rebind the buffer to a new CUDA stream.

Changes the buffer's associated stream to new_stream and ensures proper synchronization: new_stream will wait for any pending work on the current stream before proceeding. The underlying storage stream (e.g., the stream of an rmm::device_buffer or HostBuffer) is also updated.

Parameters

new_stream

The new CUDA stream.

Exceptions

std::logic_error

If the buffer is locked.

// Example: merge buffers from different streams onto a single stream.
Buffer buffer_a = ...;  // associated with stream_a
Buffer buffer_b = ...;  // associated with stream_b
 
buffer_a.rebind_stream(merged_stream);
buffer_b.rebind_stream(merged_stream);
 
// Both buffers now use merged_stream with proper synchronization
buffer_copy(buffer_a, buffer_b, size);

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 205 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 130 of file buffer.hpp.

Member Data Documentation

device_buffer_types

constexpr std::array<MemoryType, 1> rapidsmpf::Buffer::device_buffer_types {MemoryType::DEVICE}

staticconstexpr

Memory types suitable for constructing a device backed buffer.

A buffer may use DeviceBufferT only if its memory type is listed here. This ensures that the buffer is backed by memory that behaves as device accessible memory.

Definition at line 64 of file buffer.hpp.

host_buffer_types

constexpr std::array<MemoryType, 2> rapidsmpf::Buffer::host_buffer_types

staticconstexpr

Initial value:

{
        MemoryType::HOST, MemoryType::PINNED_HOST
    }

Memory types suitable for constructing a host backed buffer.

A buffer may use HostBufferT only if its memory type is listed here. This ensures that the buffer is backed by memory that behaves as host accessible memory.

Definition at line 73 of file buffer.hpp.

---

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

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