Context builder

cpp/CMakeLists.txt

@@ -114,6 +114,7 @@ add_library(
   src/context.cpp
   src/delayed_submission.cpp
   src/endpoint.cpp
+  src/experimental/context_builder.cpp
   src/header.cpp
   src/inflight_requests.cpp
   src/internal/request_am.cpp

cpp/include/ucxx/context.h

@@ -1,5 +1,5 @@
 /**
- * SPDX-FileCopyrightText: Copyright (c) 2022-2023, NVIDIA CORPORATION & AFFILIATES.
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2025, NVIDIA CORPORATION & AFFILIATES.
  * SPDX-License-Identifier: BSD-3-Clause
  */
 #pragma once
@@ -17,6 +17,10 @@
 
 namespace ucxx {
 
+namespace experimental {
+class ContextBuilder;
+}  // namespace experimental
+
 class MemoryHandle;
 class Worker;
 
@@ -25,6 +29,8 @@ class Worker;
  *
  * 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.
  */
 class Context : public Component {
  private:
@@ -57,23 +63,18 @@ class Context : public Component {
   Context& operator=(Context&& o)    = delete;
 
   /**
-   * @brief 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.
-   *
-   * @code{.cpp}
-   *   auto context = ucxx::createContext({}, UCP_FEATURE_WAKEUP | UCP_FEATURE_TAG);
-   * @endcode
+   * @brief Friend declaration for `ucxx::createContext` with parameters.
    *
-   * @param[in] ucxConfig configurations overriding `UCX_*` defaults and environment
-   *                      variables.
-   * @param[in] featureFlags feature flags to be used at UCP context construction time.
-   * @return The `shared_ptr<ucxx::Context>` object
+   * This friend declaration allows the standalone `ucxx::createContext` function to access
+   * the private constructor. See the public declaration for full documentation.
    */
   friend std::shared_ptr<Context> createContext(ConfigMap ucxConfig, const uint64_t featureFlags);
 
+  /**
+   * @brief Allow experimental::ContextBuilder to access private constructor.
+   */
+  friend class experimental::ContextBuilder;
+
   /**
    * @brief `ucxx::Context` destructor
    */
@@ -221,4 +222,24 @@ class Context : public Component {
     const size_t size, void* buffer, const ucs_memory_type_t memoryType = UCS_MEMORY_TYPE_HOST);
 };
 
+/**
+ * @brief Constructor of `shared_ptr<ucxx::Context>` with parameters.
+ *
+ * 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.
+ *
+ * @code{.cpp}
+ *   auto context = ucxx::createContext({}, UCP_FEATURE_WAKEUP | UCP_FEATURE_TAG);
+ * @endcode
+ *
+ * @param[in] ucxConfig configurations overriding `UCX_*` defaults and environment variables.
+ * @param[in] featureFlags feature flags to be used at UCP context construction time.
+ * @return The `shared_ptr<ucxx::Context>` object.
+ */
+std::shared_ptr<Context> createContext(ConfigMap ucxConfig, const uint64_t featureFlags);
+
 }  // namespace ucxx
+
+// Include experimental features
+#include <ucxx/experimental/context_builder.h>

cpp/include/ucxx/experimental/context_builder.h

@@ -0,0 +1,113 @@
+/**
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2025, NVIDIA CORPORATION & AFFILIATES.
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+#pragma once
+
+#include <memory>
+
+#include <ucxx/typedefs.h>
+
+namespace ucxx {
+
+// Forward declarations
+class Context;
+
+namespace experimental {
+
+/**
+ * @brief Builder class for constructing `std::shared_ptr<ucxx::Context>` objects.
+ *
+ * This class implements the builder pattern for `std::shared_ptr<ucxx::Context>`, allowing
+ * optional parameters to be specified via method chaining. Construction happens immediately
+ * when the builder expression completes, ensuring one-time construction with immediate
+ * evaluation.
+ *
+ * The feature flags are required and must be provided to `createContext()`.
+ * The `configMap()` method is optional.
+ *
+ * @code{.cpp}
+ *   // Minimal usage (only featureFlags required)
+ *   auto ctx = ucxx::experimental::createContext(UCP_FEATURE_TAG | UCP_FEATURE_WAKEUP).build();
+ *
+ *   // With optional configMap
+ *   auto context = ucxx::experimental::createContext(UCP_FEATURE_TAG | UCP_FEATURE_WAKEUP)
+ *                    .configMap({{"TLS", "tcp"}})
+ *                    .build();
+ *
+ *   // Using implicit conversion
+ *   std::shared_ptr<ucxx::Context> ctx = ucxx::experimental::createContext(UCP_FEATURE_RMA);
+ * @endcode
+ */
+class ContextBuilder {
+ private:
+  ConfigMap _configMap{};  ///< Configuration map for UCP context
+  uint64_t _featureFlags;  ///< Feature flags for UCP context (required)
+
+ public:
+  /**
+   * @brief Constructor for `ContextBuilder` with required feature flags.
+   *
+   * @param[in] featureFlags feature flags to be used at UCP context construction time (required).
+   */
+  explicit ContextBuilder(uint64_t featureFlags);
+
+  /**
+   * @brief Set the configuration map for the context.
+   *
+   * @param[in] configMap configurations overriding `UCX_*` defaults and environment variables.
+   * @return Reference to this builder for method chaining.
+   */
+  ContextBuilder& configMap(ConfigMap configMap);
+
+  /**
+   * @brief Build and return the `Context`.
+   *
+   * This method constructs the `Context` with the specified parameters and returns it.
+   * Each call to build() creates a new `Context` instance with the current parameters.
+   *
+   * @return The constructed `shared_ptr<ucxx::Context>` object.
+   */
+  std::shared_ptr<Context> build() const;
+
+  /**
+   * @brief Implicit conversion operator to `shared_ptr<Context>`.
+   *
+   * This operator enables automatic construction of the `Context` when the builder
+   * is used in a context requiring a `shared_ptr<Context>`. This allows seamless
+   * use with `auto` variables.
+   *
+   * @return The constructed `shared_ptr<ucxx::Context>` object.
+   */
+  operator std::shared_ptr<Context>() const;
+};
+
+/**
+ * @brief Create a ContextBuilder for constructing a `shared_ptr<ucxx::Context>`.
+ *
+ * This function returns a builder object that allows setting optional context parameters
+ * via method chaining. The feature flags are required and must be provided as an argument.
+ * The actual context is constructed when the builder is converted to a `shared_ptr<Context>`
+ * or when `build()` is called.
+ *
+ * @code{.cpp}
+ *   // Minimal usage (only featureFlags required)
+ *   auto context = ucxx::experimental::createContext(UCP_FEATURE_TAG | UCP_FEATURE_WAKEUP).build();
+ *
+ *   // With optional configMap
+ *   auto context = ucxx::experimental::createContext(UCP_FEATURE_TAG)
+ *                    .configMap({{"TLS", "tcp"}})
+ *                    .build();
+ *
+ *   // Using implicit conversion
+ *   std::shared_ptr<ucxx::Context> context = ucxx::experimental::createContext(UCP_FEATURE_RMA);
+ * @endcode
+ *
+ * @param[in] featureFlags feature flags to be used at UCP context construction time (required).
+ * @return A ContextBuilder object that can be used to set optional parameters.
+ */
+inline ContextBuilder createContext(uint64_t featureFlags) { return ContextBuilder(featureFlags); }
+
+}  // namespace experimental
+
+}  // namespace ucxx

cpp/src/context.cpp

@@ -1,12 +1,13 @@
 /**
- * SPDX-FileCopyrightText: Copyright (c) 2022-2023, NVIDIA CORPORATION & AFFILIATES.
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2025, NVIDIA CORPORATION & AFFILIATES.
  * SPDX-License-Identifier: BSD-3-Clause
  */
 #include <cstdio>
 #include <cstring>
 #include <iostream>
 #include <memory>
 #include <string>
+#include <utility>
 #include <vector>
 
 #include <ucxx/context.h>

cpp/src/experimental/context_builder.cpp

@@ -0,0 +1,35 @@
+/**
+ * SPDX-FileCopyrightText: Copyright (c) 2022-2025, NVIDIA CORPORATION & AFFILIATES.
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+#include <memory>
+#include <utility>
+
+#include <ucxx/context.h>
+#include <ucxx/experimental/context_builder.h>
+
+namespace ucxx {
+
+namespace experimental {
+
+ContextBuilder::ContextBuilder(uint64_t featureFlags) : _featureFlags(featureFlags) {}
+
+ContextBuilder& ContextBuilder::configMap(ConfigMap configMap)
+{
+  _configMap = std::move(configMap);
+  return *this;
+}
+
+std::shared_ptr<Context> ContextBuilder::build() const
+{
+  return std::shared_ptr<Context>(new Context(_configMap, _featureFlags));
+}
+
+ContextBuilder::operator std::shared_ptr<Context>() const
+{
+  return std::shared_ptr<Context>(new Context(_configMap, _featureFlags));
+}
+
+}  // namespace experimental
+
+}  // namespace ucxx