Merge pull request oneapi-src#1720 from aarongreig/aaron/addReleaseTags

Add [release] tag to parameters where appropriate.

include/ur_api.h

@@ -622,7 +622,7 @@ urLoaderConfigRetain(
 ///         + `NULL == hLoaderConfig`
 UR_APIEXPORT ur_result_t UR_APICALL
 urLoaderConfigRelease(
-    ur_loader_config_handle_t hLoaderConfig ///< [in] config handle to release
+    ur_loader_config_handle_t hLoaderConfig ///< [in][release] config handle to release
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -845,7 +845,7 @@ urAdapterGet(
 ///         + `NULL == hAdapter`
 UR_APIEXPORT ur_result_t UR_APICALL
 urAdapterRelease(
-    ur_adapter_handle_t hAdapter ///< [in] Adapter handle to release
+    ur_adapter_handle_t hAdapter ///< [in][release] Adapter handle to release
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -1764,7 +1764,7 @@ urDeviceRetain(
 ///         + `NULL == hDevice`
 UR_APIEXPORT ur_result_t UR_APICALL
 urDeviceRelease(
-    ur_device_handle_t hDevice ///< [in] handle of the device to release.
+    ur_device_handle_t hDevice ///< [in][release] handle of the device to release.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2271,7 +2271,7 @@ typedef enum ur_context_info_t {
 ///         + `NULL == hContext`
 UR_APIEXPORT ur_result_t UR_APICALL
 urContextRelease(
-    ur_context_handle_t hContext ///< [in] handle of the context to release.
+    ur_context_handle_t hContext ///< [in][release] handle of the context to release.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2761,7 +2761,7 @@ urMemRetain(
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urMemRelease(
-    ur_mem_handle_t hMem ///< [in] handle of the memory object to release
+    ur_mem_handle_t hMem ///< [in][release] handle of the memory object to release
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -3153,7 +3153,7 @@ urSamplerRetain(
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL
 urSamplerRelease(
-    ur_sampler_handle_t hSampler ///< [in] handle of the sampler object to release
+    ur_sampler_handle_t hSampler ///< [in][release] handle of the sampler object to release
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -3712,7 +3712,7 @@ urUSMPoolRetain(
 ///         + `NULL == pPool`
 UR_APIEXPORT ur_result_t UR_APICALL
 urUSMPoolRelease(
-    ur_usm_pool_handle_t pPool ///< [in] pointer to USM memory pool
+    ur_usm_pool_handle_t pPool ///< [in][release] pointer to USM memory pool
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -4061,7 +4061,7 @@ urPhysicalMemRetain(
 ///         + `NULL == hPhysicalMem`
 UR_APIEXPORT ur_result_t UR_APICALL
 urPhysicalMemRelease(
-    ur_physical_mem_handle_t hPhysicalMem ///< [in] handle of the physical memory object to release.
+    ur_physical_mem_handle_t hPhysicalMem ///< [in][release] handle of the physical memory object to release.
 );
 
 #if !defined(__GNUC__)
@@ -4354,7 +4354,7 @@ urProgramRetain(
 ///         + `NULL == hProgram`
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramRelease(
-    ur_program_handle_t hProgram ///< [in] handle for the Program to release
+    ur_program_handle_t hProgram ///< [in][release] handle for the Program to release
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5005,7 +5005,7 @@ urKernelRetain(
 ///         + `NULL == hKernel`
 UR_APIEXPORT ur_result_t UR_APICALL
 urKernelRelease(
-    ur_kernel_handle_t hKernel ///< [in] handle for the Kernel to release
+    ur_kernel_handle_t hKernel ///< [in][release] handle for the Kernel to release
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5516,7 +5516,7 @@ urQueueRetain(
 ///     - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
 UR_APIEXPORT ur_result_t UR_APICALL
 urQueueRelease(
-    ur_queue_handle_t hQueue ///< [in] handle of the queue object to release
+    ur_queue_handle_t hQueue ///< [in][release] handle of the queue object to release
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5905,7 +5905,7 @@ urEventRetain(
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urEventRelease(
-    ur_event_handle_t hEvent ///< [in] handle of the event object
+    ur_event_handle_t hEvent ///< [in][release] handle of the event object
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7551,7 +7551,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesUnsampledImageHandleDestroyExp(
     ur_context_handle_t hContext, ///< [in] handle of the context object
     ur_device_handle_t hDevice,   ///< [in] handle of the device object
-    ur_exp_image_handle_t hImage  ///< [in] pointer to handle of image object to destroy
+    ur_exp_image_handle_t hImage  ///< [in][release] pointer to handle of image object to destroy
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7576,7 +7576,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesSampledImageHandleDestroyExp(
     ur_context_handle_t hContext, ///< [in] handle of the context object
     ur_device_handle_t hDevice,   ///< [in] handle of the device object
-    ur_exp_image_handle_t hImage  ///< [in] pointer to handle of image object to destroy
+    ur_exp_image_handle_t hImage  ///< [in][release] pointer to handle of image object to destroy
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7636,7 +7636,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesImageFreeExp(
     ur_context_handle_t hContext,       ///< [in] handle of the context object
     ur_device_handle_t hDevice,         ///< [in] handle of the device object
-    ur_exp_image_mem_handle_t hImageMem ///< [in] handle of image memory to be freed
+    ur_exp_image_mem_handle_t hImageMem ///< [in][release] handle of image memory to be freed
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7850,7 +7850,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesMipmapFreeExp(
     ur_context_handle_t hContext,  ///< [in] handle of the context object
     ur_device_handle_t hDevice,    ///< [in] handle of the device object
-    ur_exp_image_mem_handle_t hMem ///< [in] handle of image memory to be freed
+    ur_exp_image_mem_handle_t hMem ///< [in][release] handle of image memory to be freed
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7941,7 +7941,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesReleaseInteropExp(
     ur_context_handle_t hContext,           ///< [in] handle of the context object
     ur_device_handle_t hDevice,             ///< [in] handle of the device object
-    ur_exp_interop_mem_handle_t hInteropMem ///< [in] handle of interop memory to be freed
+    ur_exp_interop_mem_handle_t hInteropMem ///< [in][release] handle of interop memory to be freed
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -7997,7 +7997,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesDestroyExternalSemaphoreExp(
     ur_context_handle_t hContext,                       ///< [in] handle of the context object
     ur_device_handle_t hDevice,                         ///< [in] handle of the device object
-    ur_exp_interop_semaphore_handle_t hInteropSemaphore ///< [in] handle of interop semaphore to be destroyed
+    ur_exp_interop_semaphore_handle_t hInteropSemaphore ///< [in][release] handle of interop semaphore to be destroyed
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -8271,7 +8271,7 @@ urCommandBufferRetainExp(
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urCommandBufferReleaseExp(
-    ur_exp_command_buffer_handle_t hCommandBuffer ///< [in] Handle of the command-buffer object.
+    ur_exp_command_buffer_handle_t hCommandBuffer ///< [in][release] Handle of the command-buffer object.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -8819,7 +8819,7 @@ urCommandBufferRetainCommandExp(
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
 UR_APIEXPORT ur_result_t UR_APICALL
 urCommandBufferReleaseCommandExp(
-    ur_exp_command_buffer_command_handle_t hCommand ///< [in] Handle of the command-buffer command.
+    ur_exp_command_buffer_command_handle_t hCommand ///< [in][release] Handle of the command-buffer command.
 );
 
 ///////////////////////////////////////////////////////////////////////////////

scripts/YaML.md

@@ -625,7 +625,7 @@ class ur_name_t(Structure):
       - `range` is used for params that are array pointers to specify the valid range that the is valid to read
         + `start` and `end` must be an ISO-C standard identifier or literal
         + `start` is inclusive and `end` is exclusive
-      - `release` is used for params that are handles or pointers to handles where the function will destroy any backing memory associated with the handle(s)
+      - `release` is used for params that are handles or pointers to handles where the function will decrement the handle's reference count, potentially leaving it in an invalid state if the reference count reaches zero.
       - `typename` is used to denote the type enum for params that are opaque pointers to values of tagged data types.
       - `bounds` is used for params that are memory objects or USM allocations. It specifies the range within the memory allocation represented by the param that will be accessed by the operation.
         + `offset` and `size` must be an ISO-C standard identifier or literal

scripts/core/adapter.yml

@@ -56,7 +56,7 @@ params:
   - type: "$x_adapter_handle_t"
     name: hAdapter
     desc: |
-          [in] Adapter handle to release
+          [in][release] Adapter handle to release
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Get a reference to the adapter handle."

scripts/core/context.yml

@@ -129,7 +129,7 @@ params:
     - type: "$x_context_handle_t"
       name: hContext
       desc: |
-            [in] handle of the context to release.
+            [in][release] handle of the context to release.
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves various information about context"

scripts/core/device.yml

@@ -524,7 +524,7 @@ params:
     - type: "$x_device_handle_t"
       name: hDevice
       desc: |
-            [in] handle of the device to release.
+            [in][release] handle of the device to release.
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Device affinity domain"

scripts/core/event.yml

@@ -246,7 +246,7 @@ analogue:
 params:
     - type: $x_event_handle_t
       name: hEvent
-      desc: "[in] handle of the event object"
+      desc: "[in][release] handle of the event object"
 returns:
     - $X_RESULT_ERROR_INVALID_EVENT
     - $X_RESULT_ERROR_OUT_OF_RESOURCES

scripts/core/exp-bindless-images.yml

@@ -357,7 +357,7 @@ params:
       desc: "[in] handle of the device object"
     - type: $x_exp_image_handle_t
       name: hImage
-      desc: "[in] pointer to handle of image object to destroy"
+      desc: "[in][release] pointer to handle of image object to destroy"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -378,7 +378,7 @@ params:
       desc: "[in] handle of the device object"
     - type: $x_exp_image_handle_t
       name: hImage
-      desc: "[in] pointer to handle of image object to destroy"
+      desc: "[in][release] pointer to handle of image object to destroy"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -431,7 +431,7 @@ params:
       desc: "[in] handle of the device object"
     - type: $x_exp_image_mem_handle_t
       name: hImageMem
-      desc: "[in] handle of image memory to be freed"
+      desc: "[in][release] handle of image memory to be freed"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -642,7 +642,7 @@ params:
       desc: "[in] handle of the device object"
     - type: $x_exp_image_mem_handle_t
       name: hMem
-      desc: "[in] handle of image memory to be freed"
+      desc: "[in][release] handle of image memory to be freed"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -727,7 +727,7 @@ params:
       desc: "[in] handle of the device object"
     - type: $x_exp_interop_mem_handle_t
       name: hInteropMem
-      desc: "[in] handle of interop memory to be freed"
+      desc: "[in][release] handle of interop memory to be freed"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE
@@ -775,7 +775,7 @@ params:
       desc: "[in] handle of the device object"
     - type: $x_exp_interop_semaphore_handle_t
       name: hInteropSemaphore
-      desc: "[in] handle of interop semaphore to be destroyed"
+      desc: "[in][release] handle of interop semaphore to be destroyed"
 returns:
     - $X_RESULT_ERROR_INVALID_CONTEXT
     - $X_RESULT_ERROR_INVALID_VALUE

scripts/core/exp-command-buffer.yml

@@ -265,7 +265,7 @@ name: ReleaseExp
 params:
     - type: $x_exp_command_buffer_handle_t
       name: hCommandBuffer
-      desc: "[in] Handle of the command-buffer object."
+      desc: "[in][release] Handle of the command-buffer object."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
@@ -893,7 +893,7 @@ name: ReleaseCommandExp
 params:
     - type: $x_exp_command_buffer_command_handle_t
       name: hCommand
-      desc: "[in] Handle of the command-buffer command."
+      desc: "[in][release] Handle of the command-buffer command."
 returns:
     - $X_RESULT_ERROR_INVALID_COMMAND_BUFFER_COMMAND_HANDLE_EXP
     - $X_RESULT_ERROR_OUT_OF_RESOURCES

scripts/core/kernel.yml

@@ -309,7 +309,7 @@ details:
 params:
     - type: $x_kernel_handle_t
       name: hKernel
-      desc: "[in] handle for the Kernel to release"
+      desc: "[in][release] handle for the Kernel to release"
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Properties for for $xKernelSetArgPointer."

scripts/core/loader.yml

@@ -67,7 +67,7 @@ details:
 params:
     - type: $x_loader_config_handle_t
       name: hLoaderConfig
-      desc: "[in] config handle to release"
+      desc: "[in][release] config handle to release"
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Supported loader info"

scripts/core/memory.yml

@@ -368,7 +368,7 @@ analogue:
 params:
     - type: $x_mem_handle_t
       name: hMem
-      desc: "[in] handle of the memory object to release"
+      desc: "[in][release] handle of the memory object to release"
 returns:
     - $X_RESULT_ERROR_INVALID_MEM_OBJECT
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY

scripts/core/program.yml

@@ -279,7 +279,7 @@ details:
 params:
     - type: $x_program_handle_t
       name: hProgram
-      desc: "[in] handle for the Program to release"
+      desc: "[in][release] handle for the Program to release"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves a device function pointer to a user-defined function."

scripts/core/queue.yml

@@ -204,7 +204,7 @@ details:
 params:
     - type: $x_queue_handle_t
       name: hQueue
-      desc: "[in] handle of the queue object to release"
+      desc: "[in][release] handle of the queue object to release"
 returns:
     - $X_RESULT_ERROR_INVALID_QUEUE
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY

scripts/core/sampler.yml

@@ -132,7 +132,7 @@ analogue:
 params:
     - type: $x_sampler_handle_t
       name: hSampler
-      desc: "[in] handle of the sampler object to release"
+      desc: "[in][release] handle of the sampler object to release"
 returns:
     - $X_RESULT_ERROR_INVALID_SAMPLER
     - $X_RESULT_ERROR_OUT_OF_HOST_MEMORY

scripts/core/usm.yml

@@ -449,7 +449,7 @@ details:
 params:
     - type: $x_usm_pool_handle_t
       name: pPool
-      desc: "[in] pointer to USM memory pool"
+      desc: "[in][release] pointer to USM memory pool"
 returns:
     - $X_RESULT_ERROR_INVALID_NULL_HANDLE
 --- #--------------------------------------------------------------------------

scripts/core/virtual_memory.yml

@@ -302,4 +302,4 @@ name: Release
 params:
     - type: $x_physical_mem_handle_t
       name: hPhysicalMem
-      desc: "[in] handle of the physical memory object to release."
+      desc: "[in][release] handle of the physical memory object to release."

scripts/templates/ldrddi.cpp.mako

@@ -271,15 +271,17 @@ namespace ur_loader
         del add_local
         %>
         %for i, item in enumerate(epilogue):
-        %if 0 == i:
+        %if 0 == i and not item['release']:
         if( ${X}_RESULT_SUCCESS != result )
             return result;
 
         %endif
-        %if item['release']:
-        // release loader handle
-        ${item['factory']}.release( ${item['name']} );
-        %elif not '_native_object_' in item['obj']:
+        ## Before we can re-enable the releases we will need ref-counted object_t.
+        ## See unified-runtime github issue #1784
+        ##%if item['release']:
+        ##// release loader handle
+        ##${item['factory']}.release( ${item['name']} );
+        %if not item['release'] and not '_native_object_' in item['obj'] or th.make_func_name(n, tags, obj) == 'urPlatformCreateWithNativeHandle':
         try
         {
             %if 'typename' in item: