All Classes Namespaces Functions Variables Typedefs Enumerations Friends
Public Member Functions | Static Public Attributes | Friends | List of all members
ucxx::Context Class Reference

Component encapsulating the UCP context. More...

#include <context.h>

Inheritance diagram for ucxx::Context:
ucxx::Component

Public Member Functions

 Context (const Context &)=delete
 
Contextoperator= (Context const &)=delete
 
 Context (Context &&o)=delete
 
Contextoperator= (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< WorkercreateWorker (const bool enableDelayedSubmission=false, const bool enableFuture=false)
 Create a new ucxx::Worker. More...
 
std::shared_ptr< MemoryHandlecreateMemoryHandle (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< ComponentgetParent () const
 Get the internal parent reference. More...
 

Static Public Attributes

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

Friends

std::shared_ptr< ContextcreateContext (ConfigMap ucxConfig, const uint64_t featureFlags)
 Constructor of shared_ptr<ucxx::Context>. 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.

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::Errorif either ucp_mem_map or ucp_mem_query fail.
Parameters
[in]sizethe minimum size of the memory allocation.
[in]bufferthe pointer to an existing allocation or nullptr to allocate a new memory region.
[in]memoryTypethe 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]enableDelayedSubmissionwhether the worker should delay transfer requests to the worker thread.
[in]enableFutureif 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

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);
std::shared_ptr< Context > createContext(const ConfigMap ucxConfig, const uint64_t featureFlags)
Parameters
[in]ucxConfigconfigurations overriding UCX_* defaults and environment variables.
[in]featureFlagsfeature 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: