From 75b39a0424f108a2247e81c03c2a4024eb1c0a39 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 27 Feb 2025 14:07:50 +0000 Subject: [PATCH 1/3] Migrate sycl::free table to new apidef format --- adoc/chapters/programming_interface.adoc | 46 +++++++++++------------- 1 file changed, 21 insertions(+), 25 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index af92ab35..8d259de6 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -11777,35 +11777,31 @@ necessary [code]#device#. ==== Memory deallocation functions -[[table.usm.free]] -.USM Deallocation Functions -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Function @ Description -a@ -[source] +.[apidef]#free# +[source,role=synopsis,id=api:free] ---- -void sycl::free(void* ptr, const context& syclContext) +void free(void* ptr, const context& ctxt); (1) +void free(void* ptr, const queue& q); (2) ---- -a@ Frees an allocation. -The memory pointed to by [code]#ptr# must have been allocated using one of the -USM allocation routines or it must be a null pointer. -If [code]#ptr# is not null, the [code]#syclContext# must be the same -[code]#context# that was used to allocate the memory. -If [code]#ptr# is null, this function has no effect. -Otherwise, the memory is freed without waiting for <> -operating on it to be completed. -If <> that use this memory are in-progress or are enqueued, -the behavior is undefined. -a@ -[source] ----- -void sycl::free(void* ptr, const queue& syclQueue) ----- -a@ Alternate form where [code]#syclQueue# provides the [code]#context#. +*Overload (1):* -|==== +_Preconditions_: + +* [code]#ptr# points to memory allocated against [code]#ctxt# using one of the + USM allocation routines, or is a null pointer; and + +* There are no in-progress or enqueued <> using the memory + pointed to by [code]#ptr#. + +_Effects_: The memory pointed to by [code]#ptr# is freed, without waiting for +<> operating on it to be completed. + +_Remarks_: If [code]#ptr# is null, this function has no effect. + +*Overload (2):* + +_Effects_: Equivalent to [code]#return free(ptr, q.get_context());#. === Unified shared memory pointer queries From 0464d594a1b5ba02681bace871be273c04587994 Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 27 Feb 2025 14:14:58 +0000 Subject: [PATCH 2/3] Remove unnecessary statement about free "waiting" The previous wording that memory is deallocated "without waiting for commands operating on it to be completed" is unnecessary, because calling free with such a command in-progress is already defined as undefined behavior. --- adoc/chapters/programming_interface.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 8d259de6..63c8990b 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -11794,8 +11794,7 @@ _Preconditions_: * There are no in-progress or enqueued <> using the memory pointed to by [code]#ptr#. -_Effects_: The memory pointed to by [code]#ptr# is freed, without waiting for -<> operating on it to be completed. +_Effects_: The memory pointed to by [code]#ptr# is deallocated. _Remarks_: If [code]#ptr# is null, this function has no effect. From 49d2047f702452c212487062d4b3639c4b8d472e Mon Sep 17 00:00:00 2001 From: John Pennycook Date: Thu, 27 Feb 2025 14:25:51 +0000 Subject: [PATCH 3/3] Clarify free is not guaranteed to be non-blocking The previous wording about "not waiting" could have been read as a guarantee that calls to sycl::free are always non-blocking. In practice, calls to sycl::free may need to block until the device can satisfy the deallocation request (depending on implementation details tied to specific backends). Although the new wording cannot be read this way, adding a non-normative note may help developers to understand that they should not rely on the behavior of specific implementations. --- adoc/chapters/programming_interface.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 63c8990b..4f18fd21 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -11796,6 +11796,10 @@ _Preconditions_: _Effects_: The memory pointed to by [code]#ptr# is deallocated. +{note}Whether [code]#free# is blocking or non-blocking is unspecified. +Applications should not rely on [code]#free# for synchronization, nor assume +that [code]#free# cannot cause deadlocks.{endnote} + _Remarks_: If [code]#ptr# is null, this function has no effect. *Overload (2):*