Clarify spec around isNativeHandleOwned.

aarongreig · aarongreig · commit f11d1a3cd367 · 2025-01-21T11:51:06.000Z
diff --git a/scripts/core/PROG.rst b/scripts/core/PROG.rst
@@ -340,3 +340,39 @@ through ${x}_usm_desc_t structure. Allocations that specify different pool handl
 isolated and not reside on the same page. Memory pool is subject to limits specified during pool creation.
 
 Even if no ${x}_usm_pool_handle_t is provided to an allocation function, each adapter may still perform memory pooling.
+
+Native Handles
+==============
+
+In addition to the regular object creation APIs, ${X} objects can be
+constructed with handles obtained directly from an adapter's associated
+backend. This is achieved by casting the backend handle to a
+${x}_native_handle_t and passing it to the relevant ``CreateWithNativeHandle``
+entry point.
+
+
+.. note::
+   Not all backends have a 1:1 equivalent for every ${X} handle type, as such
+   any ``CreateWithNativeHandle`` or ``GetNativeHandle`` entry point *may* fail
+   with the error code ${X}_RESULT_ERROR_UNSUPPORTED_FEATURE for a given
+   adapter.
+
+Native Handle Ownership
+-----------------------
+
+By default a ${X} object constructed from a native handle doesn't own the
+native handle, it is guaranteed not to modify the native handle's reference
+count or otherwise cause its resources to be released. A ${X} object that
+doesn't own its associated native handle **must** be destroyed before the
+native handle is.
+
+Ownership of the native handle can be tranferred to the ${X} object by passing
+``isNativeHandleOwned = true`` in the native properties struct when calling the
+``CreateWithNativeHandle`` entry point. A ${X} object that owns a native handle
+will attempt to release the native resources associated with that handle on
+destruction. The same native handle **must not** have its ownership transferred
+to more than one ${X} object.
+
+Ownership of a native handle obtained from a ${X} object via a
+``GetNativeHandle`` entry point **must not** be transferred to a new ${X}
+object.
diff --git a/scripts/core/context.yml b/scripts/core/context.yml
@@ -209,9 +209,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime context object from native context handle."
diff --git a/scripts/core/device.yml b/scripts/core/device.yml
@@ -803,10 +803,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-          [in] Indicates UR owns the native handle or if it came from an
-          interoperability operation in the application that asked to not
-          transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime device object from native device handle."
diff --git a/scripts/core/event.yml b/scripts/core/event.yml
@@ -289,9 +289,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime event object from native event handle."
diff --git a/scripts/core/kernel.yml b/scripts/core/kernel.yml
@@ -513,9 +513,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime kernel object from native kernel handle."
diff --git a/scripts/core/memory.yml b/scripts/core/memory.yml
@@ -474,10 +474,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-        [in] Indicates UR owns the native handle or if it came from an
-        interoperability operation in the application that asked to not
-        transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime buffer memory object from native memory handle."
diff --git a/scripts/core/platform.yml b/scripts/core/platform.yml
@@ -202,10 +202,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-          [in] Indicates UR owns the native handle or if it came from an
-          interoperability operation in the application that asked to not
-          transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime platform object from native platform handle."
diff --git a/scripts/core/program.yml b/scripts/core/program.yml
@@ -584,10 +584,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-          [in] Indicates UR owns the native handle or if it came from an
-          interoperability operation in the application that asked to not
-          transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime program object from native program handle."
diff --git a/scripts/core/queue.yml b/scripts/core/queue.yml
@@ -262,9 +262,9 @@ members:
     - type: bool
       name: isNativeHandleOwned
       desc: |
-            [in] Indicates UR owns the native handle or if it came from an interoperability
-            operation in the application that asked to not transfer the ownership to
-            the unified-runtime.
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime queue object from native queue handle."
diff --git a/scripts/core/sampler.yml b/scripts/core/sampler.yml
@@ -206,10 +206,10 @@ base: $x_base_properties_t
 members:
     - type: bool
       name: isNativeHandleOwned
-      desc: >
-          [in] Indicates UR owns the native handle or if it came from an
-          interoperability operation in the application that asked to not
-          transfer the ownership to the unified-runtime.
+      desc: |
+            [in] If true then ownership of the native handle is tranferred to
+            the resultant object. This means the object will be responsible for
+            releasing the native resources at the end of its lifetime.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create runtime sampler object from native sampler handle."
diff --git a/test/conformance/context/urContextCreateWithNativeHandle.cpp b/test/conformance/context/urContextCreateWithNativeHandle.cpp
@@ -19,9 +19,8 @@ TEST_P(urContextCreateWithNativeHandleTest, Success) {
   // We can however convert the native_handle back into a unified-runtime handle
   // and perform some query on it to verify that it works.
   ur_context_handle_t ctx = nullptr;
-  ur_context_native_properties_t props{};
   UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(urContextCreateWithNativeHandle(
-      native_context, adapter, 1, &device, &props, &ctx));
+      native_context, adapter, 1, &device, nullptr, &ctx));
   ASSERT_NE(ctx, nullptr);
 
   uint32_t n_devices = 0;
@@ -31,21 +30,8 @@ TEST_P(urContextCreateWithNativeHandleTest, Success) {
   ASSERT_SUCCESS(urContextRelease(ctx));
 }
 
-TEST_P(urContextCreateWithNativeHandleTest, SuccessWithOwnedNativeHandle) {
-  ur_native_handle_t native_context = 0;
-
-  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
-      urContextGetNativeHandle(context, &native_context));
-
-  ur_context_handle_t ctx = nullptr;
-  ur_context_native_properties_t props{
-      UR_STRUCTURE_TYPE_CONTEXT_NATIVE_PROPERTIES, nullptr, true};
-  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(urContextCreateWithNativeHandle(
-      native_context, adapter, 1, &device, &props, &ctx));
-  ASSERT_NE(ctx, nullptr);
-}
-
-TEST_P(urContextCreateWithNativeHandleTest, SuccessWithUnOwnedNativeHandle) {
+TEST_P(urContextCreateWithNativeHandleTest,
+       SuccessExplicitUnOwnedNativeHandle) {
   ur_native_handle_t native_context = 0;
 
   UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
diff --git a/test/conformance/device/urDeviceCreateWithNativeHandle.cpp b/test/conformance/device/urDeviceCreateWithNativeHandle.cpp
@@ -29,23 +29,9 @@ TEST_P(urDeviceCreateWithNativeHandleTest, Success) {
                                  &dev_id, nullptr));
 }
 
-TEST_P(urDeviceCreateWithNativeHandleTest, SuccessWithOwnedNativeHandle) {
+TEST_F(urDeviceCreateWithNativeHandleTest,
+       SuccessWithExplicitUnOwnedNativeHandle) {
   ur_native_handle_t native_handle = 0;
-
-  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
-      urDeviceGetNativeHandle(device, &native_handle));
-
-  ur_device_handle_t dev = nullptr;
-  ur_device_native_properties_t props{
-      UR_STRUCTURE_TYPE_DEVICE_NATIVE_PROPERTIES, nullptr, true};
-  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
-      urDeviceCreateWithNativeHandle(native_handle, adapter, &props, &dev));
-  ASSERT_NE(dev, nullptr);
-}
-
-TEST_P(urDeviceCreateWithNativeHandleTest, SuccessWithUnOwnedNativeHandle) {
-  ur_native_handle_t native_handle = 0;
-
   UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
       urDeviceGetNativeHandle(device, &native_handle));
 
diff --git a/test/conformance/platform/urPlatformCreateWithNativeHandle.cpp b/test/conformance/platform/urPlatformCreateWithNativeHandle.cpp
@@ -37,29 +37,8 @@ TEST_P(urPlatformCreateWithNativeHandleTest, Success) {
   ASSERT_EQ(input_platform_name, created_platform_name);
 }
 
-TEST_P(urPlatformCreateWithNativeHandleTest, SuccessWithOwnedNativeHandle) {
-  ur_native_handle_t native_handle = 0;
-
-  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
-      urPlatformGetNativeHandle(platform, &native_handle));
-
-  // We cannot assume anything about a native_handle, not even if it's
-  // `nullptr` since this could be a valid representation within a backend.
-  // We can however convert the native_handle back into a unified-runtime
-  // handle and perform some query on it to verify that it works.
-  ur_platform_native_properties_t props = {
-      UR_STRUCTURE_TYPE_PLATFORM_NATIVE_PROPERTIES, nullptr, true};
-  ur_platform_handle_t plat = nullptr;
-  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
-      urPlatformCreateWithNativeHandle(native_handle, adapter, &props, &plat));
-  ASSERT_NE(plat, nullptr);
-
-  std::string input_platform_name = uur::GetPlatformName(platform);
-  std::string created_platform_name = uur::GetPlatformName(plat);
-  ASSERT_EQ(input_platform_name, created_platform_name);
-}
-
-TEST_P(urPlatformCreateWithNativeHandleTest, SuccessWithUnOwnedNativeHandle) {
+TEST_F(urPlatformCreateWithNativeHandleTest,
+       SuccessWithExplicitUnOwnedNativeHandle) {
   ur_native_handle_t native_handle = 0;
 
   UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
diff --git a/test/conformance/sampler/urSamplerCreateWithNativeHandle.cpp b/test/conformance/sampler/urSamplerCreateWithNativeHandle.cpp
@@ -22,7 +22,31 @@ TEST_P(urSamplerCreateWithNativeHandleTest, Success) {
   // We can however convert the native_handle back into a unified-runtime handle
   // and perform some query on it to verify that it works.
   ur_sampler_handle_t hSampler = nullptr;
-  ur_sampler_native_properties_t props{};
+  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(urSamplerCreateWithNativeHandle(
+      native_sampler, context, nullptr, &hSampler));
+  ASSERT_NE(hSampler, nullptr);
+
+  ur_sampler_addressing_mode_t addr_mode;
+  ASSERT_SUCCESS(urSamplerGetInfo(hSampler, UR_SAMPLER_INFO_ADDRESSING_MODE,
+                                  sizeof(addr_mode), &addr_mode, nullptr));
+  ASSERT_EQ(addr_mode, sampler_desc.addressingMode);
+  ASSERT_SUCCESS(urSamplerRelease(hSampler));
+}
+
+TEST_P(urSamplerCreateWithNativeHandleTest,
+       SuccessExplicitUnOwnedNativeHandle) {
+  ur_native_handle_t native_sampler = 0;
+
+  UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(
+      urSamplerGetNativeHandle(sampler, &native_sampler));
+
+  // We cannot assume anything about a native_handle, not even if it's
+  // `nullptr` since this could be a valid representation within a backend.
+  // We can however convert the native_handle back into a unified-runtime handle
+  // and perform some query on it to verify that it works.
+  ur_sampler_handle_t hSampler = nullptr;
+  ur_sampler_native_properties_t props{
+      UR_STRUCTURE_TYPE_SAMPLER_NATIVE_PROPERTIES, nullptr, false};
   UUR_ASSERT_SUCCESS_OR_UNSUPPORTED(urSamplerCreateWithNativeHandle(
       native_sampler, context, &props, &hSampler));
   ASSERT_NE(hSampler, nullptr);
