Context

Context#

2026-03-31

5 min read time

Applies to Linux

The ucxx::Context class encapsulates a UCP context (ucp_context_h). It is the top-level object in the UCXX hierarchy and must be created before any other UCXX objects. Contexts are created via the ucxx::createContext() factory function.

#include <ucxx/context.h>

namespace ucxx

class Context : public ucxx::Component #

Component encapsulating the UCP context.

The UCP layer provides a handle to access its context in form of ucp_context_h object, this class encapsulates that object and provides methods to simplify its handling.

Public Functions

~Context( )#: ucxx::Context destructor

ConfigMap getConfig( )#

Get the context configuration.

The context configuration is a ConfigMap containing entries of the UCX variables that were set upon creation of the UCP context. Only those variables known to UCP can be acquired.

// context is `std::shared_ptr<ucxx::Context>`
auto contextConfig = context->getConfig();

Returns:: A ConfigMap corresponding to the context’s configuration.

ucp_context_h getHandle( )#

Get the underlying ucp_context_h handle.

Lifetime of the ucp_context_h handle is managed by the ucxx::Context object and its ownership is non-transferrable. Once the ucxx::Context is destroyed the handle is not valid anymore, it is the user’s responsibility to ensure the owner’s lifetime while using the handle.

// context is `std::shared_ptr<ucxx::Context>`
ucp_context_h contextHandle = context->getHandle();

Returns:: The underlying ucp_context_h handle

std::string getInfo( )#

Get information from UCP context.

Get information from UCP context, including memory domains, transport resources, and other useful information. This method is a wrapper to ucp_context_print_info.

// context is `std::shared_ptr<ucxx::Context>`
auto contextInfo = context->getInfo();

Returns:: String containing context information

uint64_t getFeatureFlags( ) const#

Get feature flags that were used to construct the UCP context.

Get feature flags that were used to construct the UCP context, this has the same value that was specified by the user when creating the ucxx::Context object.

// context is `std::shared_ptr<ucxx::Context>`
uint64_t contextFeatureFlags= context->getFeatureFlags();

Returns:: Feature flags for this context

bool hasCudaSupport( ) const#

Query whether CUDA (or ROCm) support is available.

Query whether the UCP context has CUDA support available. This is a done through a combination of verifying whether CUDA/HIP memory support is available and UCX_TLS allows CUDA to be enabled, essentially UCX_TLS must explicitly be one of the following:

Exactly all;
Contain a field starting with cuda/rocm;
Start with ^ (disable all listed transports) and NOT contain a field named either cuda or cuda_copy (rocm or rocm_copy on AMD).

Returns:: Whether CUDA support is available.

std::shared_ptr<Worker> createWorker( const bool enableDelayedSubmission = false, const bool enableFuture = false )#

Create a new ucxx::Worker.

Create a new ucxx::Worker as a child of the current ucxx::Context. The ucxx::Context will retain ownership of the ucxx::Worker and will not be destroyed until all ucxx::Worker objects are destroyed first.

// context is `std::shared_ptr<ucxx::Context>`
auto worker = context->createWorker(true);

Parameters:

enableDelayedSubmission – [in] whether the worker should delay transfer requests to the worker thread.
enableFuture – [in] if true, notifies the future associated with each ucxx::Request, currently used only by ucxx::python::Worker.

Returns:

Shared pointer to the ucxx::Worker object.

std::shared_ptr<MemoryHandle> createMemoryHandle( const size_t size, void *buffer, const ucs_memory_type_t memoryType = UCS_MEMORY_TYPE_HOST )#

Create a new std::shared_ptr<ucxx::memoryHandle>.

Create a new std::shared_ptr<ucxx::MemoryHandle> as a child of the current ucxx::Context. The ucxx::Context will retain ownership of the underlying ucxx::MemoryHandle and will not be destroyed until all ucxx::MemoryHandle objects are destroyed first.

The allocation requires a size and a buffer. The actual size of the allocation may be larger than requested, and can later be found calling the getSize() method. The buffer provided may be either a nullptr, in which case UCP will allocate a new memory region for it, or an already existing allocation, in which case UCP will only map it for RMA and it’s the caller’s responsibility to keep buffer alive until this object is destroyed.

// `context` is `std::shared_ptr<ucxx::Context>`
// Allocate a 128-byte buffer with UCP.
auto memoryHandle = context->createMemoryHandle(128, nullptr);

// Map an existing 128-byte buffer with UCP.
size_t allocationSize = 128;
auto buffer = new uint8_t[allocationSize];
auto memoryHandleFromBuffer = context->createMemoryHandle(
   allocationSize * sizeof(*buffer), reinterpret_cast<void*>(buffer)
);

Throws:

ucxx::Error – if either ucp_mem_map or ucp_mem_query fail.

Parameters:

size – [in] the minimum size of the memory allocation.
buffer – [in] the pointer to an existing allocation or nullptr to allocate a new memory region.
memoryType – [in] the type of memory the handle points to.

Returns:

The shared_ptr<ucxx::MemoryHandle> object

Public Static Attributes

static constexpr uint64_t defaultFeatureFlags = UCP_FEATURE_TAG | UCP_FEATURE_WAKEUP | UCP_FEATURE_STREAM | UCP_FEATURE_AM | UCP_FEATURE_RMA#: Suggested default context feature flags to use.

Friends

friend std::shared_ptr<Context> createContext( ConfigMap ucxConfig, const uint64_t featureFlags )#

Constructor of shared_ptr<ucxx::Context>.

The constructor for a shared_ptr<ucxx::Context> object. The default constructor is made private to ensure all UCXX objects are shared pointers for correct lifetime management.

auto context = ucxx::createContext({}, UCP_FEATURE_WAKEUP | UCP_FEATURE_TAG);

Parameters:

ucxConfig – [in] configurations overriding UCX_* defaults and environment variables.
featureFlags – [in] feature flags to be used at UCP context construction time.

Returns:

The shared_ptr<ucxx::Context> object

Factory Functions#

#include <ucxx/constructors.h>

std::shared_ptr<Context> ucxx::createContext( const ConfigMap ucxConfig, const uint64_t featureFlags )#

The constructor for a shared_ptr<ucxx::Context> object. The default constructor is made private to ensure all UCXX objects are shared pointers for correct lifetime management.

auto context = ucxx::createContext({}, UCP_FEATURE_WAKEUP | UCP_FEATURE_TAG);

Parameters:

ucxConfig – [in] configurations overriding UCX_* defaults and environment variables.
featureFlags – [in] feature flags to be used at UCP context construction time.

Returns:

The shared_ptr<ucxx::Context> object

Context

Contents

Context#

Factory Functions#