Host task concept#

A host task is a native C++ callable which is scheduled by the SYCL runtime. A host task is submitted to a sycl::queue via a command group by a host task command.

When a host task command is submitted to a sycl::queue it is scheduled based on its data dependencies with other commands including kernel invocation commands and asynchronous copies, resolving any requisites created by accessors attached to the command group as defined in SYCL Specification Section 3.8.1.

Since a host task is invoked directly by the SYCL runtime rather than being compiled as a SYCL kernel function, it does not have the same restrictions as a SYCL kernel function, and can therefore contain any arbitrary C++ code.

Capturing accessors in a host task is allowed, however, capturing or using any other SYCL class that has reference semantics (see SYCL Specification Section 4.5.2) is undefined behavior.

A host task can be enqueued on any sycl::queue and the callable will be invoked directly by the SYCL runtime, regardless of which sycl::device the queue is associated with.

A host task is enqueued on a sycl::queue via the sycl::host_task member function of the sycl::handler class. The event returned by the submission of the associated command group enters the completed state (corresponding to a status of sycl::info::event_command_status::complete) once the invocation of the provided C++ callable has returned. Any uncaught exception thrown during the execution of a host task will be turned into an asynchronous error that can be handled as described in SYCL Specification Section 4.13.1.1.

A host task can optionally be used to interoperate with the native backend objects associated with the sycl::queue executing the host task, the context that the sycl::queue is associated with, the sycl::device that the sycl::queue is associated with and the accessors that have been captured in the callable, via an optional sycl::interop_handle parameter.

This allows host tasks to be used for two purposes: either as a task which can perform arbitrary C++ code within the scheduling of the SYCL runtime or as a task which can perform interoperability at a point within the scheduling of the SYCL runtime.

For the former use case, construct a buffer accessor with sycl::target::host_task or an image accessor with sycl::image_target::host_task. This makes the buffer or image available on the host during execution of the host task.

For the latter case, construct a buffer accessor with sycl::target::device or sycl::target::constant_buffer, or construct an image accessor with sycl::image_target::device. This makes the buffer or image available on the sycl::device that is associated with the sycl::queue used to submit the host task, so that it can be accessed via interoperability member functions provided by the sycl::interop_handle class.