dpctl.SyclQueue.keep_args_alive

SyclQueue.keep_args_alive(args, depends=None)

Keeps objects in args alive until the work on this queue that uses them completes.

Parameters:

  • args (object) – Python object to keep alive, typically a tuple of the arguments passed to an offloaded task.

  • depends (Iterable[dpctl.SyclEvent], optional) – Gating events. On an out-of-order queue these decide when the objects stop being used, so every task using them must be covered. Default: None.

Returns:

An event that completes once args have stopped being used. Its completion does not mean that args were released, only that releasing them has come due.

Return type:

dpctl.SyclEvent

Raises:

  • TypeError – If depends is not an iterable of dpctl.SyclEvent.

  • RuntimeError – If the release could not be scheduled. The reference taken on args is then leaked deliberately, as the work using them may still be running.

Increments the reference count of args and defers the matching decrement until an empty kernel, submitted to this queue after depends, has completed. On an in-order queue it is ordered after everything submitted before it, so depends may be omitted.

It is suggested to call this on the queue running the work that uses args: the kernel is ordered only against work submitted to the queue it goes to, so on any other queue depends alone gates the release.

Example:
import dpctl

q = dpctl.SyclQueue()
e = q.submit_async(kernel, [x_usm], [n])
q.keep_args_alive((x_usm,), [e])

# an in-order queue needs no event
q_in_order = dpctl.SyclQueue(property="in_order")
q_in_order.submit_async(kernel, [y_usm], [n])
q_in_order.keep_args_alive((y_usm,))

Note

On a free-threaded build, the thread dropping the reference does not own the object, so its __del__ may run later than the decrement.