Support int64_t in BackendOption variant for pointer-sized opaque handles (#19232)

Summary:

Add an `int64_t` alternative to the `OptionValue` variant in
`executorch/runtime/backend/options.h`, plus a matching `set_option(int64_t)`
overload on `BackendOptions` and an extended `get_runtime_spec<int64_t>`
template in `BackendInitContext`.

## Motivation

Backends increasingly need to receive pointer-sized opaque handles at
`Method::load_method()` time via the existing `runtime_specs` channel:
- NVIDIA CUDA driver handles (e.g., `CUgreenCtx` for green-context-aware
  TensorRT inference, where the runtime user pre-creates a green context
  and binds the engine's stream to it via `cuGreenCtxStreamCreate`).
- Externally-created CUDA streams shared across delegates.
- Vulkan/Metal command queue handles, etc.

The current `OptionValue` variant supports `bool`, `int`, and a 256-byte
char array. None of these safely round-trips a 64-bit pointer on LP64
platforms — `int` is 32-bit and would silently truncate the upper half of
a pointer, producing use-after-free or segfaults at the consumer side.

A workaround using the `const char*` arm (stringify the pointer to hex,
parse with `strtoull` in the backend) is possible but ugly, error-prone,
and unnecessary given how trivial the additive fix is.

## Scope of change

- Add `int64_t` to the `OptionValue` variant alternatives.
- Add a `set_option(const char (&key)[N], int64_t value)` overload on
  `BackendOptions`.
- Extend `BackendInitContext::get_runtime_spec<T>` template's
  `static_assert` to allow `T = int64_t` in addition to `bool`, `int`,
  `const char*`. The internal `std::get_if<T>` already works with the new
  variant alternative — no other body changes needed.
- Add `<cstdint>` include in both headers.

## Properties

This change is purely additive:

- **Existing consumers see no behavior change.** The `bool`, `int`, and
  `const char*` paths are untouched. Variant alternatives are appended,
  not reordered, so `std::variant::index()` semantics for existing values
  are preserved.
- **No serialized format changes.** `runtime_specs` are passed in-process
  at `Method::load_method` and are never serialized into the .pte file.
  AOT `CompileSpec` lives in a separate Python schema (flatbuffer-backed)
  and is unchanged here.
- **No public API removed or renamed.** The new `int64_t` overload is
  selected only when callers explicitly pass `int64_t`-typed values;
  integer literals continue to bind to the `int` overload.

## Caller usage

The intended usage pattern, illustrated for the green-context case:

  // 1) User creates the opaque resource and owns its lifetime
  CUgreenCtx green = nullptr;
  cuGreenCtxCreate(&green, desc, device, CU_GREEN_CTX_DEFAULT_STREAM);

  // 2) Pass as a runtime spec at Method::load_method time
  BackendOption opt{};
  std::strcpy(opt.key, "green_context");
  opt.value =
      static_cast<int64_t>(reinterpret_cast<intptr_t>(green));
  Span<const BackendOption> specs(&opt, 1);
  // ... thread `specs` through Module::load_program / load_method

  // 3) In the backend's init():
  auto h = context.get_runtime_spec<int64_t>("green_context");
  if (h.ok()) {
    auto green = reinterpret_cast<CUgreenCtx>(h.get());
    CUstream raw_stream;
    cuGreenCtxStreamCreate(
        &raw_stream, green, CU_STREAM_NON_BLOCKING, /*priority=*/0);
    // bind raw_stream to the engine for enqueueV3...
  }

Differential Revision: D103241865

Author: shoumikhin

runtime/backend/backend_init_context.h

@@ -15,6 +15,7 @@
 #include <executorch/runtime/core/result.h>
 #include <executorch/runtime/core/span.h>
 
+#include <cstdint>
 #include <cstring>
 
 #ifdef __GNUC__
@@ -97,7 +98,7 @@ class BackendInitContext final {
   /**
    * Get a runtime spec value by key and type.
    *
-   * @tparam T The expected type (bool, int, or const char*)
+   * @tparam T The expected type (bool, int, int64_t, or const char*)
    * @param key The option key to look up.
    * @return Result containing the value if found and type matches,
    *         Error::NotFound if key doesn't exist,
@@ -107,8 +108,8 @@ class BackendInitContext final {
   Result<T> get_runtime_spec(const char* key) const {
     static_assert(
         std::is_same_v<T, bool> || std::is_same_v<T, int> ||
-            std::is_same_v<T, const char*>,
-        "get_runtime_spec<T> only supports bool, int, and const char*");
+            std::is_same_v<T, int64_t> || std::is_same_v<T, const char*>,
+        "get_runtime_spec<T> only supports bool, int, int64_t, and const char*");
 
     for (size_t i = 0; i < runtime_specs_.size(); ++i) {
       const auto& opt = runtime_specs_[i];

runtime/backend/options.h

@@ -11,6 +11,7 @@
 #include <executorch/runtime/core/span.h>
 #include <array>
 #include <cstddef>
+#include <cstdint>
 #include <cstring>
 #include <variant>
 
@@ -23,8 +24,10 @@ static constexpr size_t kMaxOptionValueLength = 256;
 // All string keys and values must have static storage duration (string
 // literals, static const char arrays, or global constants). The BackendOptions
 // class does NOT take ownership of strings.
+// int64_t is included so callers can pass pointer-sized opaque handles
+// (e.g., driver handles like CUgreenCtx) by reinterpret_cast to/from int64_t.
 using OptionValue =
-    std::variant<bool, int, std::array<char, kMaxOptionValueLength>>;
+    std::variant<bool, int, int64_t, std::array<char, kMaxOptionValueLength>>;
 
 struct BackendOption {
   // key is the name of the backend option, like num_threads, enable_profiling,
@@ -40,7 +43,9 @@ struct BackendOption {
  *
  * This class provides a type-safe way to store key-value pairs for backend
  * configuration, with compile-time capacity limits and runtime type checking.
- * It supports bool, int, and const char* value types.
+ * It supports bool, int, int64_t, and const char* value types. The int64_t
+ * arm allows callers to pass pointer-sized opaque handles (e.g., driver
+ * handles like CUgreenCtx) by reinterpret_cast to/from int64_t.
  *
  * @tparam MaxCapacity The maximum number of options that can be stored
  */
@@ -113,6 +118,22 @@ class BackendOptions {
     return set_option_impl(key, value);
   }
 
+  /**
+   * Sets an int64_t option value for the given key.
+   * Useful for pointer-sized opaque handles (cast via reinterpret_cast).
+   * If the key already exists, updates its value. Otherwise, adds a new option.
+   *
+   * @tparam N The length of the key string (automatically deduced)
+   * @param key The option key (must be a string literal or array)
+   * @param value The int64_t value to set
+   * @return Error::Ok on success, Error::InvalidArgument if storage is full
+   */
+  template <size_t N>
+  Error set_option(const char (&key)[N], int64_t value) noexcept {
+    static_assert(N <= kMaxOptionKeyLength, "Option key is too long");
+    return set_option_impl(key, value);
+  }
+
   /**
    * Sets a string option value for the given key.
    * If the key already exists, updates its value. Otherwise, adds a new option.
@@ -137,7 +158,8 @@ class BackendOptions {
   /**
    * Retrieves an option value by key and type.
    *
-   * @tparam T The expected type of the option value (bool, int, or const char*)
+   * @tparam T The expected type of the option value (bool, int, int64_t, or
+   * const char*)
    * @tparam KeyLen The length of the key string (automatically deduced)
    * @param key The option key to look up
    * @param out Reference to store the retrieved value
@@ -157,7 +179,7 @@ class BackendOptions {
             return Error::Ok;
           }
         }
-        // Default handling for bool/int
+        // Default handling for bool/int/int64_t
         else if (auto* val = std::get_if<T>(&options_[i].value)) {
           out = *val;
           return Error::Ok;
@@ -176,7 +198,7 @@ class BackendOptions {
    * Internal implementation for setting option values.
    * Handles both updating existing options and adding new ones.
    *
-   * @tparam T The type of the value (bool, int, or const char*)
+   * @tparam T The type of the value (bool, int, int64_t, or const char*)
    * @param key The option key
    * @param value The value to set
    * @return Error::Ok on success, Error::InvalidArgument if storage is full

runtime/backend/test/backend_options_test.cpp

@@ -61,6 +61,28 @@ TEST_F(BackendOptionsTest, HandlesIntOptions) {
   EXPECT_EQ(num_threads, 256);
 }
 
+// Test int64_t options - exercises the variant arm that holds pointer-sized
+// opaque handles. Uses a value with the high 32 bits set to ensure the value
+// is not silently routed through (or truncated by) the int arm.
+TEST_F(BackendOptionsTest, HandlesInt64Options) {
+  constexpr int64_t kHandle = static_cast<int64_t>(0x123456789ABCDEF0LL);
+  options.set_option("handle", kHandle);
+
+  int64_t handle = 0;
+  EXPECT_EQ(options.get_option("handle", handle), Error::Ok);
+  EXPECT_EQ(handle, kHandle);
+
+  // Reading the same key as int should fail because the variant arm differs.
+  int as_int = 0;
+  EXPECT_EQ(options.get_option("handle", as_int), Error::InvalidArgument);
+
+  // Update existing key with a new int64_t value.
+  constexpr int64_t kHandle2 = static_cast<int64_t>(0xFEDCBA9876543210LL);
+  options.set_option("handle", kHandle2);
+  EXPECT_EQ(options.get_option("handle", handle), Error::Ok);
+  EXPECT_EQ(handle, kHandle2);
+}
+
 // Test error conditions
 TEST_F(BackendOptionsTest, HandlesErrors) {
   // Non-existent key