Skip to content

Commit 2d50d1c

Browse files
Petr Veselyveselypeta
Petr Vesely
authored and
veselypeta
committed
[ur] Clarify REFERENCE_COUNT semantics
1 parent e5d6a6f commit 2d50d1c

File tree

9 files changed

+92
-33
lines changed

9 files changed

+92
-33
lines changed

‎include/ur.py‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,9 @@ class ur_context_info_v(IntEnum):
253253
DEVICES = 1 ## [::ur_context_handle_t...] The array of the device handles in the
254254
## context
255255
REFERENCE_COUNT = 2 ## [uint32_t] Reference count of the context object.
256+
## The reference count returned should be considered immediately stale.
257+
## It is unsuitable for general use in applications. This feature is
258+
## provided for identifying memory leaks.
256259
USM_MEMCPY2D_SUPPORT = 3 ## [bool] to indicate if the ::urEnqueueUSMMemcpy2D entrypoint is
257260
## supported.
258261
USM_FILL2D_SUPPORT = 4 ## [bool] to indicate if the ::urEnqueueUSMFill2D entrypoint is
@@ -357,7 +360,10 @@ class ur_event_info_v(IntEnum):
357360
CONTEXT = 1 ## [::ur_context_handle_t] Context information of an event object
358361
COMMAND_TYPE = 2 ## [::ur_command_t] Command type information of an event object
359362
COMMAND_EXECUTION_STATUS = 3 ## [::ur_event_status_t] Command execution status of an event object
360-
REFERENCE_COUNT = 4 ## [uint32_t] Reference count of an event object
363+
REFERENCE_COUNT = 4 ## [uint32_t] Reference count of the event object.
364+
## The reference count returned should be considered immediately stale.
365+
## It is unsuitable for general use in applications. This feature is
366+
## provided for identifying memory leaks.
361367

362368
class ur_event_info_t(c_int):
363369
def __str__(self):
@@ -556,14 +562,15 @@ def __str__(self):
556562
###############################################################################
557563
## @brief Query queue info
558564
class ur_queue_info_v(IntEnum):
559-
CONTEXT = 0 ## ::ur_queue_handle_t: context associated with this queue.
560-
DEVICE = 1 ## ::ur_device_handle_t: device associated with this queue.
561-
DEVICE_DEFAULT = 2 ## ::ur_queue_handle_t: the current default queue of the underlying
562-
## device.
563-
PROPERTIES = 3 ## ::ur_queue_flags_t: the properties associated with
564-
## ::UR_QUEUE_PROPERTIES_FLAGS.
565-
REFERENCE_COUNT = 4 ## Queue reference count
566-
SIZE = 5 ## uint32_t: The size of the queue
565+
CONTEXT = 0 ## Queue context info
566+
DEVICE = 1 ## Queue device info
567+
DEVICE_DEFAULT = 2 ## Queue device default info
568+
PROPERTIES = 3 ## Queue properties info
569+
REFERENCE_COUNT = 4 ## [uint32_t] Reference count of the queue object.
570+
## The reference count returned should be considered immediately stale.
571+
## It is unsuitable for general use in applications. This feature is
572+
## provided for identifying memory leaks.
573+
SIZE = 5 ## Queue size info
567574

568575
class ur_queue_info_t(c_int):
569576
def __str__(self):
@@ -605,7 +612,10 @@ def __str__(self):
605612
###############################################################################
606613
## @brief Get sample object information
607614
class ur_sampler_info_v(IntEnum):
608-
REFERENCE_COUNT = 0 ## Sampler reference count info
615+
REFERENCE_COUNT = 0 ## [uint32_t] Reference count of the sampler object.
616+
## The reference count returned should be considered immediately stale.
617+
## It is unsuitable for general use in applications. This feature is
618+
## provided for identifying memory leaks.
609619
CONTEXT = 1 ## Sampler context info
610620
NORMALIZED_COORDS = 2 ## Sampler normalized coordindate setting
611621
ADDRESSING_MODE = 3 ## Sampler addressing mode setting
@@ -777,7 +787,10 @@ class ur_device_info_v(IntEnum):
777787
QUEUE_ON_HOST_PROPERTIES = 61 ## ::ur_queue_flags_t: host queue property bit-field
778788
BUILT_IN_KERNELS = 62 ## char[]: a semi-colon separated list of built-in kernels
779789
PLATFORM = 63 ## ::ur_platform_handle_t: the platform associated with the device
780-
REFERENCE_COUNT = 64 ## uint32_t: reference count
790+
REFERENCE_COUNT = 64 ## [uint32_t] Reference count of the device object.
791+
## The reference count returned should be considered immediately stale.
792+
## It is unsuitable for general use in applications. This feature is
793+
## provided for identifying memory leaks.
781794
IL_VERSION = 65 ## char[]: IL version
782795
NAME = 66 ## char[]: Device name
783796
VENDOR = 67 ## char[]: Device vendor
@@ -942,7 +955,10 @@ def __str__(self):
942955
class ur_kernel_info_v(IntEnum):
943956
FUNCTION_NAME = 0 ## Return Kernel function name, return type char[]
944957
NUM_ARGS = 1 ## Return Kernel number of arguments
945-
REFERENCE_COUNT = 2 ## Return Kernel reference count
958+
REFERENCE_COUNT = 2 ## [uint32_t] Reference count of the kernel object.
959+
## The reference count returned should be considered immediately stale.
960+
## It is unsuitable for general use in applications. This feature is
961+
## provided for identifying memory leaks.
946962
CONTEXT = 3 ## Return Context object associated with Kernel
947963
PROGRAM = 4 ## Return Program object associated with Kernel
948964
ATTRIBUTES = 5 ## Return Kernel attributes, return type char[]
@@ -1090,7 +1106,10 @@ class ur_program_properties_t(Structure):
10901106
###############################################################################
10911107
## @brief Get Program object information
10921108
class ur_program_info_v(IntEnum):
1093-
REFERENCE_COUNT = 0 ## Program reference count info
1109+
REFERENCE_COUNT = 0 ## [uint32_t] Reference count of the program object.
1110+
## The reference count returned should be considered immediately stale.
1111+
## It is unsuitable for general use in applications. This feature is
1112+
## provided for identifying memory leaks.
10941113
CONTEXT = 1 ## Program context info
10951114
NUM_DEVICES = 2 ## Return number of devices associated with Program
10961115
DEVICES = 3 ## Return list of devices associated with Program, return type

‎include/ur_api.h‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -343,6 +343,9 @@ typedef enum ur_context_info_t {
343343
UR_CONTEXT_INFO_DEVICES = 1, ///< [::ur_context_handle_t...] The array of the device handles in the
344344
///< context
345345
UR_CONTEXT_INFO_REFERENCE_COUNT = 2, ///< [uint32_t] Reference count of the context object.
346+
///< The reference count returned should be considered immediately stale.
347+
///< It is unsuitable for general use in applications. This feature is
348+
///< provided for identifying memory leaks.
346349
UR_CONTEXT_INFO_USM_MEMCPY2D_SUPPORT = 3, ///< [bool] to indicate if the ::urEnqueueUSMMemcpy2D entrypoint is
347350
///< supported.
348351
UR_CONTEXT_INFO_USM_FILL2D_SUPPORT = 4, ///< [bool] to indicate if the ::urEnqueueUSMFill2D entrypoint is
@@ -1617,7 +1620,10 @@ typedef enum ur_event_info_t {
16171620
UR_EVENT_INFO_CONTEXT = 1, ///< [::ur_context_handle_t] Context information of an event object
16181621
UR_EVENT_INFO_COMMAND_TYPE = 2, ///< [::ur_command_t] Command type information of an event object
16191622
UR_EVENT_INFO_COMMAND_EXECUTION_STATUS = 3, ///< [::ur_event_status_t] Command execution status of an event object
1620-
UR_EVENT_INFO_REFERENCE_COUNT = 4, ///< [uint32_t] Reference count of an event object
1623+
UR_EVENT_INFO_REFERENCE_COUNT = 4, ///< [uint32_t] Reference count of the event object.
1624+
///< The reference count returned should be considered immediately stale.
1625+
///< It is unsuitable for general use in applications. This feature is
1626+
///< provided for identifying memory leaks.
16211627
/// @cond
16221628
UR_EVENT_INFO_FORCE_UINT32 = 0x7fffffff
16231629
/// @endcond
@@ -2325,14 +2331,15 @@ urTearDown(
23252331
///////////////////////////////////////////////////////////////////////////////
23262332
/// @brief Query queue info
23272333
typedef enum ur_queue_info_t {
2328-
UR_QUEUE_INFO_CONTEXT = 0, ///< ::ur_queue_handle_t: context associated with this queue.
2329-
UR_QUEUE_INFO_DEVICE = 1, ///< ::ur_device_handle_t: device associated with this queue.
2330-
UR_QUEUE_INFO_DEVICE_DEFAULT = 2, ///< ::ur_queue_handle_t: the current default queue of the underlying
2331-
///< device.
2332-
UR_QUEUE_INFO_PROPERTIES = 3, ///< ::ur_queue_flags_t: the properties associated with
2333-
///< ::UR_QUEUE_PROPERTIES_FLAGS.
2334-
UR_QUEUE_INFO_REFERENCE_COUNT = 4, ///< Queue reference count
2335-
UR_QUEUE_INFO_SIZE = 5, ///< uint32_t: The size of the queue
2334+
UR_QUEUE_INFO_CONTEXT = 0, ///< Queue context info
2335+
UR_QUEUE_INFO_DEVICE = 1, ///< Queue device info
2336+
UR_QUEUE_INFO_DEVICE_DEFAULT = 2, ///< Queue device default info
2337+
UR_QUEUE_INFO_PROPERTIES = 3, ///< Queue properties info
2338+
UR_QUEUE_INFO_REFERENCE_COUNT = 4, ///< [uint32_t] Reference count of the queue object.
2339+
///< The reference count returned should be considered immediately stale.
2340+
///< It is unsuitable for general use in applications. This feature is
2341+
///< provided for identifying memory leaks.
2342+
UR_QUEUE_INFO_SIZE = 5, ///< Queue size info
23362343
/// @cond
23372344
UR_QUEUE_INFO_FORCE_UINT32 = 0x7fffffff
23382345
/// @endcond
@@ -2604,7 +2611,10 @@ urQueueFlush(
26042611
///////////////////////////////////////////////////////////////////////////////
26052612
/// @brief Get sample object information
26062613
typedef enum ur_sampler_info_t {
2607-
UR_SAMPLER_INFO_REFERENCE_COUNT = 0, ///< Sampler reference count info
2614+
UR_SAMPLER_INFO_REFERENCE_COUNT = 0, ///< [uint32_t] Reference count of the sampler object.
2615+
///< The reference count returned should be considered immediately stale.
2616+
///< It is unsuitable for general use in applications. This feature is
2617+
///< provided for identifying memory leaks.
26082618
UR_SAMPLER_INFO_CONTEXT = 1, ///< Sampler context info
26092619
UR_SAMPLER_INFO_NORMALIZED_COORDS = 2, ///< Sampler normalized coordindate setting
26102620
UR_SAMPLER_INFO_ADDRESSING_MODE = 3, ///< Sampler addressing mode setting
@@ -3121,7 +3131,10 @@ typedef enum ur_device_info_t {
31213131
UR_DEVICE_INFO_QUEUE_ON_HOST_PROPERTIES = 61, ///< ::ur_queue_flags_t: host queue property bit-field
31223132
UR_DEVICE_INFO_BUILT_IN_KERNELS = 62, ///< char[]: a semi-colon separated list of built-in kernels
31233133
UR_DEVICE_INFO_PLATFORM = 63, ///< ::ur_platform_handle_t: the platform associated with the device
3124-
UR_DEVICE_INFO_REFERENCE_COUNT = 64, ///< uint32_t: reference count
3134+
UR_DEVICE_INFO_REFERENCE_COUNT = 64, ///< [uint32_t] Reference count of the device object.
3135+
///< The reference count returned should be considered immediately stale.
3136+
///< It is unsuitable for general use in applications. This feature is
3137+
///< provided for identifying memory leaks.
31253138
UR_DEVICE_INFO_IL_VERSION = 65, ///< char[]: IL version
31263139
UR_DEVICE_INFO_NAME = 66, ///< char[]: Device name
31273140
UR_DEVICE_INFO_VENDOR = 67, ///< char[]: Device vendor
@@ -3604,7 +3617,10 @@ urKernelSetArgLocal(
36043617
typedef enum ur_kernel_info_t {
36053618
UR_KERNEL_INFO_FUNCTION_NAME = 0, ///< Return Kernel function name, return type char[]
36063619
UR_KERNEL_INFO_NUM_ARGS = 1, ///< Return Kernel number of arguments
3607-
UR_KERNEL_INFO_REFERENCE_COUNT = 2, ///< Return Kernel reference count
3620+
UR_KERNEL_INFO_REFERENCE_COUNT = 2, ///< [uint32_t] Reference count of the kernel object.
3621+
///< The reference count returned should be considered immediately stale.
3622+
///< It is unsuitable for general use in applications. This feature is
3623+
///< provided for identifying memory leaks.
36083624
UR_KERNEL_INFO_CONTEXT = 3, ///< Return Context object associated with Kernel
36093625
UR_KERNEL_INFO_PROGRAM = 4, ///< Return Program object associated with Kernel
36103626
UR_KERNEL_INFO_ATTRIBUTES = 5, ///< Return Kernel attributes, return type char[]
@@ -4492,7 +4508,10 @@ urProgramGetFunctionPointer(
44924508
///////////////////////////////////////////////////////////////////////////////
44934509
/// @brief Get Program object information
44944510
typedef enum ur_program_info_t {
4495-
UR_PROGRAM_INFO_REFERENCE_COUNT = 0, ///< Program reference count info
4511+
UR_PROGRAM_INFO_REFERENCE_COUNT = 0, ///< [uint32_t] Reference count of the program object.
4512+
///< The reference count returned should be considered immediately stale.
4513+
///< It is unsuitable for general use in applications. This feature is
4514+
///< provided for identifying memory leaks.
44964515
UR_PROGRAM_INFO_CONTEXT = 1, ///< Program context info
44974516
UR_PROGRAM_INFO_NUM_DEVICES = 2, ///< Return number of devices associated with Program
44984517
UR_PROGRAM_INFO_DEVICES = 3, ///< Return list of devices associated with Program, return type

‎scripts/core/context.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,10 @@ etors:
6969
- name: DEVICES
7070
desc: "[$x_context_handle_t...] The array of the device handles in the context"
7171
- name: REFERENCE_COUNT
72-
desc: "[uint32_t] Reference count of the context object."
72+
desc: |
73+
[uint32_t] Reference count of the context object.
74+
The reference count returned should be considered immediately stale.
75+
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
7376
- name: USM_MEMCPY2D_SUPPORT
7477
desc: "[bool] to indicate if the $xEnqueueUSMMemcpy2D entrypoint is supported."
7578
- name: USM_FILL2D_SUPPORT

‎scripts/core/device.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,10 @@ etors:
206206
- name: PLATFORM
207207
desc: "$x_platform_handle_t: the platform associated with the device"
208208
- name: REFERENCE_COUNT
209-
desc: "uint32_t: reference count"
209+
desc: |
210+
[uint32_t] Reference count of the device object.
211+
The reference count returned should be considered immediately stale.
212+
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
210213
- name: IL_VERSION
211214
desc: "char[]: IL version"
212215
- name: NAME

‎scripts/core/event.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,10 @@ etors:
9898
- name: COMMAND_EXECUTION_STATUS
9999
desc: "[$x_event_status_t] Command execution status of an event object"
100100
- name: REFERENCE_COUNT
101-
desc: "[uint32_t] Reference count of an event object"
101+
desc: |
102+
[uint32_t] Reference count of the event object.
103+
The reference count returned should be considered immediately stale.
104+
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
102105
--- #--------------------------------------------------------------------------
103106
type: enum
104107
desc: "Profiling query information type"

‎scripts/core/kernel.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,10 @@ etors:
8686
- name: NUM_ARGS
8787
desc: "Return Kernel number of arguments"
8888
- name: REFERENCE_COUNT
89-
desc: "Return Kernel reference count"
89+
desc: |
90+
[uint32_t] Reference count of the kernel object.
91+
The reference count returned should be considered immediately stale.
92+
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
9093
- name: CONTEXT
9194
desc: "Return Context object associated with Kernel"
9295
- name: PROGRAM

‎scripts/core/program.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,10 @@ class: $xProgram
215215
name: $x_program_info_t
216216
etors:
217217
- name: REFERENCE_COUNT
218-
desc: "Program reference count info"
218+
desc: |
219+
[uint32_t] Reference count of the program object.
220+
The reference count returned should be considered immediately stale.
221+
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
219222
- name: CONTEXT
220223
desc: "Program context info"
221224
- name: NUM_DEVICES

‎scripts/core/queue.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,10 @@ etors:
2424
- name: PROPERTIES
2525
desc: "$x_queue_flags_t: the properties associated with $X_QUEUE_PROPERTIES_FLAGS."
2626
- name: REFERENCE_COUNT
27-
desc: "Queue reference count"
27+
desc: |
28+
[uint32_t] Reference count of the queue object.
29+
The reference count returned should be considered immediately stale.
30+
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
2831
- name: SIZE
2932
desc: "uint32_t: The size of the queue"
3033
--- #--------------------------------------------------------------------------

‎scripts/core/sampler.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@ class: $xSampler
1616
name: $x_sampler_info_t
1717
etors:
1818
- name: REFERENCE_COUNT
19-
desc: "Sampler reference count info"
19+
desc: |
20+
[uint32_t] Reference count of the sampler object.
21+
The reference count returned should be considered immediately stale.
22+
It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
2023
- name: CONTEXT
2124
desc: "Sampler context info"
2225
- name: NORMALIZED_COORDS

0 commit comments

Comments
 (0)