Buffer

Buffer#

2026-03-31

5 min read time

Applies to Linux

The buffer classes provide abstractions over raw memory pointers. ucxx::Buffer is the abstract base class, with ucxx::HostBuffer for host memory and ucxx::RMMBuffer for GPU device memory managed by hipMM (which preserves the upstream rmm namespace).

#include <ucxx/buffer.h>

namespace ucxx

enum class ucxx::BufferType#

The type of a buffer.

The type of a buffer that can be used to match among the different supported types.

Values:

enumerator Host#

enumerator RMM#

enumerator Invalid#

class Buffer#

A simple object to simplify managing buffers.

UCXX can work with raw pointers in most cases, but in some circumstances it’s required to know more information about the buffer, such as with ucxx::RequestTagMulti. In such circumstances it may need to allocate buffers internally and UCXX can utilize objects of this type to describe the internally-allocated buffers.

Subclassed by ucxx::HostBuffer, ucxx::RMMBuffer

Public Functions

virtual ~Buffer( )#

Virtual destructor.

Virtual destructor with empty implementation.

BufferType getType( ) const noexcept#

Get the type of buffer the object holds.

The type of buffer the object holds is important to ensure proper casting of the object into the correct derived type.

Returns:: the type of buffer the object holds

size_t getSize( ) const noexcept#

Get the size of the contained buffer.

The size in bytes of the contained buffer.

Returns:: the size of the contained buffer.

virtual void *data( ) = 0#

Abstract method returning void pointer to buffer.

Get the void pointer to the underlying buffer that holds the data. This is meant to return the actual allocation, and not a pointer to some container to the buffer it holds.

Returns:: the void pointer to the buffer.

class HostBuffer : public ucxx::Buffer #

A simple object containing a host buffer.

A buffer encapsulating a host buffer with its properties.

Public Functions

explicit HostBuffer( const size_t size )#

Constructor of concrete type HostBuffer.

Constructor to materialize a buffer holding host memory. The internal buffer is allocated using malloc, and thus should be freed with free.

// Allocate host buffer of 1KiB
auto buffer = HostBuffer(1024);

Parameters:: size – [in] the size of the host buffer to allocate.

HostBuffer( const void *buffer, const size_t size )#

Construct a host buffer by deep copying the contents of another buffer.

auto buffer_copy = HostBuffer(buffer.data(), buffer.getSize());

Parameters:

buffer – [in] the data to copy from.
size – [in] the size of the host buffer to allocate.

~HostBuffer( )#

Destructor of concrete type HostBuffer.

Frees the underlying buffer, unless the underlying buffer was released to the user after a call to release.

void *release( )#

Release the allocated host buffer to the caller.

Release ownership of the buffer to the caller. After this method is called, the caller becomes responsible for its deallocation once it is not needed anymore. The buffer is allocated with malloc, and should be properly disposed of by a call to free.

The original HostBuffer object becomes invalid.

// Allocate host buffer of 1KiB
auto buffer = HostBuffer(1024);
void* bufferPtr = buffer.release();

// do work on bufferPtr

// Free buffer
free(bufferPtr);

Throws:: std::runtime_error – if object has been released.
Returns:: the void pointer to the buffer.

virtual void *data( ) override#

Get a pointer to the allocated raw host buffer.

Get a pointer to the underlying buffer, but does not release ownership.

// Allocate host buffer of 1KiB
auto buffer = HostBuffer(1024);
void* bufferPtr = buffer.data();

// do work on bufferPtr

// Memory is freed once `buffer` goes out-of-scope.

Throws:: std::runtime_error – if object has been released.
Returns:: the void pointer to the buffer.

class RMMBuffer : public ucxx::Buffer #

A simple object containing a RMM (CUDA) buffer.

A buffer encapsulating an RMM (CUDA) buffer with its properties.

Public Functions

explicit RMMBuffer( const size_t size )#

Constructor of concrete type RMMBuffer.

Constructor to materialize a buffer holding device memory. The internal buffer holds a std::unique_ptr<rmm::device_buffer> and is destroyed when the object goes out-of-scope or is explicitly deleted.

// Allocate host buffer of 1KiB
auto buffer = RMMBuffer(1024);

Parameters:: size – [in] the size of the device buffer to allocate.

explicit RMMBuffer( std::unique_ptr<rmm::device_buffer> rmm_buffer )#

Construct from an existing rmm::device_buffer.

Parameters:: rmm_buffer – [in] the rmm::device_buffer to hold.

std::unique_ptr<rmm::device_buffer> release( )#

Release the allocated rmm::device_buffer to the caller.

Release ownership of the rmm::device_buffer to the caller. After this method is called, the caller becomes responsible for the destruction of the object once it is not needed anymore. The rmm::device_buffer is held owned by the unique_ptr and will be deallocated once it goes out-of-scope or gets explicitly deleted.

The original RMMBuffer object becomes invalid.

// Allocate RMM buffer of 1KiB
auto buffer = RMMBuffer(1024);
std::unique_ptr<RMMBuffer> rmmBuffer= buffer.release();

// do work on rmmBuffer

// `rmm::device_buffer` is destroyed and device Memory is freed once
// `rmmBuffer` goes out-of-scope.

Throws:: std::runtime_error – if object has been released.
Returns:: the void pointer to the buffer.

virtual void *data( ) override#

Get a pointer to the allocated raw device buffer.

Get a pointer to the underlying buffer, but does not release ownership.

// Allocate device buffer of 1KiB
auto buffer = RMMBuffer(1024);
void* bufferPtr = buffer.data();

// do work on bufferPtr

// `rmm::device_buffer` is destroyed and device Memory is freed once
// `buffer` goes out-of-scope.

Throws:: std::runtime_error – if object has been released.
Returns:: the void pointer to the device buffer.

Buffer

Contents

Buffer#