ucxx::Context Class Reference

Component encapsulating the UCP context. More...

#include <context.h>

Inheritance diagram for ucxx::Context:

Public Member Functions
	Context (const Context &)=delete
Context &	operator= (Context const &)=delete
	Context (Context &&o)=delete
Context &	operator= (Context &&o)=delete
	~Context ()
	ucxx::Context destructor
ConfigMap	getConfig ()
	Get the context configuration. More...
ucp_context_h	getHandle ()
	Get the underlying ucp_context_h handle. More...
std::string	getInfo ()
	Get information from UCP context. More...
uint64_t	getFeatureFlags () const
	Get feature flags that were used to construct the UCP context. More...
bool	hasCudaSupport () const
	Query whether CUDA support is available. More...
std::shared_ptr< Worker >	createWorker (const bool enableDelayedSubmission=false, const bool enableFuture=false)
	Create a new ucxx::Worker. More...
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>. More...
Public Member Functions inherited from ucxx::Component
void	setParent (std::shared_ptr< Component > parent)
	Set the internal parent reference. More...
std::shared_ptr< Component >	getParent () const
	Get the internal parent reference. More...

Static Public Attributes
static constexpr uint64_t	defaultFeatureFlags
	Suggested default context feature flags to use. More...

Friends
class	experimental::ContextBuilder
	Allow experimental::ContextBuilder to access private constructor.
std::shared_ptr< Context >	createContext (ConfigMap ucxConfig, const uint64_t featureFlags)
	Friend declaration for ucxx::createContext with parameters. More...

Additional Inherited Members
Protected Attributes inherited from ucxx::Component
std::shared_ptr< Component >	_parent {nullptr}
	A reference-counted pointer to the parent.

Detailed Description

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.

Use ucxx::createContext to create and configure Context instances.

Member Function Documentation

createMemoryHandle()

std::shared_ptr<MemoryHandle> ucxx::Context::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)
);

Exceptions

ucxx::Error

if either ucp_mem_map or ucp_mem_query fail.

Parameters

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

Returns

The shared_ptr<ucxx::MemoryHandle> object

createWorker()

std::shared_ptr<Worker> ucxx::Context::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

[in]	enableDelayedSubmission	whether the worker should delay transfer requests to the worker thread.
[in]	enableFuture	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.

getConfig()

ConfigMap ucxx::Context::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.

getFeatureFlags()

uint64_t ucxx::Context::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

getHandle()

ucp_context_h ucxx::Context::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

getInfo()

std::string ucxx::Context::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

hasCudaSupport()

bool ucxx::Context::hasCudaSupport

(

)

const

Query whether CUDA support is available.

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

1. Exactly all;
2. Contain a field starting with cuda;
3. Start with ^ (disable all listed transports) and NOT contain a field named either cuda or cuda_copy.

Returns

Whether CUDA support is available.

Friends And Related Function Documentation

createContext

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

friend

Friend declaration for ucxx::createContext with parameters.

This friend declaration allows the standalone ucxx::createContext function to access the private constructor. See the public declaration for full documentation.

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

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

Returns

The shared_ptr<ucxx::Context> object.

Member Data Documentation

defaultFeatureFlags

constexpr uint64_t ucxx::Context::defaultFeatureFlags

staticconstexpr

Initial value:

=
    UCP_FEATURE_TAG | UCP_FEATURE_WAKEUP | UCP_FEATURE_STREAM | UCP_FEATURE_AM |
    UCP_FEATURE_RMA

Suggested default context feature flags to use.

---

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

• /__w/ucxx/ucxx/cpp/include/ucxx/context.h