Core#
2026-03-31
5 min read time
This page provides ucxx class and function references for the publicly-exposed elements of the ucxx.core module. This module provides the primary interface for initializing UCX, creating listeners and endpoints, and managing the communication lifecycle.
Initialization and Configuration#
- ucxx.core.init(options={}, env_takes_precedence=False, progress_mode=None, enable_delayed_submission=None, enable_python_future=None, connect_timeout=None)#
Initiate UCX.
Usually this is done automatically at the first API call but this function makes it possible to set UCX options programmable. Alternatively, UCX options can be specified through environment variables.
- options: dict, optional
UCX options send to the underlying UCX library
- env_takes_precedence: bool, optional
Whether environment variables takes precedence over the options specified here.
- progress_mode: string, optional
If None, thread UCX progress mode is used unless the environment variable UCXPY_PROGRESS_MODE is defined. Otherwise the options are ‘blocking’, ‘polling’, ‘thread’.
- enable_delayed_submission: boolean, optional
If None, delayed submission is disabled unless UCXPY_ENABLE_DELAYED_SUBMISSION is defined with a value other than 0.
- enable_python_future: boolean, optional
If None, request notification via Python futures is disabled unless UCXPY_ENABLE_PYTHON_FUTURE is defined with a value other than 0.
- connect_timeout: float, optional
The timeout in seconds for exchanging endpoint information upon endpoint establishment. If None, use the value from UCXPY_CONNECT_TIMEOUT if defined, otherwise fallback to the default of 5 seconds.
- ucxx.core.reset()#
Resets the UCX library by shutting down all of UCX.
The library is initiated at next API call.
- ucxx.core.get_config()#
Returns all UCX configuration options as a dict.
If UCX is uninitialized, the options returned are the options used if UCX were to be initialized now. Notice, this function doesn’t initialize UCX.
- dict
The current UCX configuration options
- ucxx.core.get_ucx_version()#
Return the version of the underlying UCX installation
Notice, this function doesn’t initialize UCX.
- tuple
The version as a tuple e.g. (1, 7, 0)
Communication#
- ucxx.core.create_listener(callback_func, port=None, endpoint_error_handling=True, connect_timeout=5.0)#
Create and start a listener to accept incoming connections
callback_func is the function or coroutine that takes one argument – the Endpoint connected to the client.
Notice, the listening is closed when the returned Listener goes out of scope thus remember to keep a reference to the object.
- callback_func: function or coroutine
A callback function that gets invoked when an incoming connection is accepted
- port: int, optional
An unused port number for listening, or 0 to let UCX assign an unused port.
- endpoint_error_handling: boolean, optional
If True (default) enable endpoint error handling raising exceptions when an error occurs, may incur in performance penalties but prevents a process from terminating unexpectedly that may happen when disabled. If False endpoint endpoint error handling is disabled.
- connect_timeout: float
Timeout in seconds for exchanging peer info. In some cases, exchanging peer information may hang indefinitely, a timeout prevents that. If the chosen value is too high it may cause the operation to be stuck for too long rather than quickly raising a TimeoutError that may be recovered from by the application, but under high-load a higher timeout may be helpful to prevent exchanging peer info from failing too fast.
- Listener
The new listener. When this object is deleted, the listening stops
- ucxx.core.progress()#
Try to progress the communication layer
Warning, it is illegal to call this from a call-back function such as the call-back function given to create_listener.
- ucxx.core.continuous_ucx_progress(event_loop=None)#
Guarantees continuous UCX progress
Use this function to associate UCX progress with an event loop. Notice, multiple event loops can be associate with UCX progress.
This function is automatically called when calling create_listener() or create_endpoint().
- event_loop: asyncio.event_loop, optional
The event loop to evoke UCX progress. If None, asyncio.get_event_loop() (asyncio.new_event_loop() in Python 3.10+) is used.
Worker and Context Information#
- ucxx.core.get_ucp_context_info()#
- Gets information on the current UCX context, obtained from
ucp_context_print_info.
- ucxx.core.get_ucp_worker_info()#
- Gets information on the current UCX worker, obtained from
ucp_worker_print_info.
- ucxx.core.get_active_transports()#
- Returns a list of all transports that are available and are currently
active in UCX, meaning UCX may use them depending on the type of transfers and how it is configured but is not required to do so.
- ucxx.core.get_worker_address()#
- ucxx.core.get_ucp_worker()#
- Returns the underlying UCP worker handle (ucp_worker_h)
as a Python integer.
- ucxx.core.get_ucxx_worker()#
- ucxx.core.get_ucx_address_from_buffer(buffer)#
Thread Management#
- ucxx.core.stop_notifier_thread()#
Stop Python future notifier thread
Stop the notifier thread if context is running with Python future notification enabled via UCXPY_ENABLE_PYTHON_FUTURE=1 or ucxx.init(…, enable_python_future=True).
Warning
When the notifier thread is enabled it may be necessary to explicitly call this method before shutting down the process or or application, otherwise it may block indefinitely waiting for the thread to terminate. Executing ucxx.reset() will also run this method, so it’s not necessary to have both.