Future#
2026-03-31
3 min read time
The ucxx::Future class provides a future-based mechanism for tracking the completion
of asynchronous UCXX operations. Futures can be used to bridge UCXX requests with
external event loops (e.g., Python asyncio).
#include <ucxx/future.h>
namespace ucxx
-
class Future : public std::enable_shared_from_this<Future>#
Represent a future that may be notified by a specialized notifier.
Represent a future object that may postpone notification of its status to a more appropriate stage by a specialize notifier, such as
ucxx::Notifier.Subclassed by ucxx::python::Future
Public Functions
- inline virtual ~Future(
Virtual destructor.
Virtual destructor with empty implementation.
- virtual void notify(
- ucs_status_t status
Inform the notifier that the future has completed.
Inform the notifier that the future has completed so it can notify associated resources of that occurrence.
- Throws:
std::runtime_error – if the object is invalid or has been already released.
- Parameters:
status – [in] request completion status.
- virtual void set(
- ucs_status_t status
Set the future completion status.
Set the future status as completed, either with a successful completion or error.
- Throws:
std::runtime_error – if the object is invalid or has been already released.
- Parameters:
status – [in] request completion status.
- virtual void *getHandle(
Get the underlying handle but does not release ownership.
Get the underlying handle without releasing ownership. This can be useful for example for logging, where we want to see the address of the pointer but do not want to transfer ownership.
Warning
The destructor will also destroy the future, a pointer taken via this method will cause the object to become invalid.
- Throws:
std::runtime_error – if the object is invalid or has been already released.
- Returns:
The underlying handle.
- virtual void *release(
Get the underlying handle and release ownership.
Get the underlying handle releasing ownership. This should be used when the future needs to be permanently transferred to consumer code. After calling this method the object becomes invalid for any other uses.
- Throws:
std::runtime_error – if the object is invalid or has been already released.
- Returns:
The underlying handle.