Events

sycl::event

class event;

A sycl::event is an object that represents the status of an operation that is being executed by the SYCL runtime.

Although an event represents the status of a particular operation, the dependencies of a certain event can be used to keep track of multiple steps required to synchronize said operation.

A sycl::event is returned by the submission of a command group. The dependencies of the event returned via the submission of the command group are the implementation-defined commands associated with the command group execution.

The sycl::event` class provides the common reference semantics.

See also

SYCL Specification Section 4.6.6

(constructors)

event();

Constructs an sycl::event that is immediately ready.

The sycl::event has no dependencies and no associated commands.

Waiting on this sycl::event will return immediately and querying its status will return sycl::info::event_command_status::complete.

The sycl::event is constructed as though it was created from a default-constructed sycl::queue. Therefore, its backend is the same as the backend from the default device.

Member functions

get_backend

backend get_backend() const noexcept;

Returns a sycl::backend identifying the SYCL backend associated with this sycl::event.

get_wait_list

std::vector<sycl::event> get_wait_list();

Return the list of events that this event waits for in the dependence graph.

Only direct dependencies are returned, and not transitive dependencies that direct dependencies wait on. Whether already completed events are included in the returned list is implementation-defined.

wait

void wait();

Wait for the event and the command associated with it to complete.

wait_and_throw

void wait_and_throw();

Wait for the event and the command associated with it to complete.

Any unconsumed asynchronous errors from the event's queue will be passed to the sycl::async_handler that is associated with the queue or with the queue's context. If neither the queue nor the context has a user defined sycl::async_handler, then an implementation-defined default sycl::async_handler is called to handle any errors.

get_info

template <typename Param>
typename Param::return_type get_info() const;

Queries this sycl::event for information requested by the template parameter Param.

The type alias Param::return_type must be defined in accordance with the information parameters to facilitate returning the type associated with the Param parameter.

get_backend_info

template <typename Param>
typename Param::return_type get_backend_info() const;

Queries this sycl::event for SYCL backend-specific information requested by the template parameter Param.

The type alias Param::return_type must be defined in accordance with the SYCL backend specification.

Exceptions

sycl::errc::backend_mismatch

If the SYCL backend that corresponds with Param is different from the SYCL backend that is associated with this event.

get_profiling_info

template <typename Param>
typename Param::return_type get_profiling_info() const;

Queries this sycl::event for profiling information requested by the parameter Param.

If the requested profiling information is unavailable when get_profiling_info is called due to incompletion of command groups associated with the event, then the call to get_profiling_info will block until the requested profiling information is available.

An example is asking for sycl::info::event_profiling::command_end when the associated command group action has yet to finish execution.

The type alias Param::return_type must be defined in accordance with the information profiling parameters to facilitate returning the type associated with the Param parameter.

Exceptions

sycl::errc::invalid

if the sycl::queue which submitted the command group this sycl::event is associated with was not constructed with the sycl::property::queue::enable_profiling property.

Example

See event-elapsed-time.

Static member functions

wait

static void wait(const std::vector<sycl::event>& eventList);

Synchronously wait on a list of events.

wait_and_throw

static void wait_and_throw(const std::vector<sycl::event>& eventList);

Synchronously wait on a list of events.

Any unconsumed asynchronous errors from the event's queue will be passed to the sycl::async_handler that is associated with the queue or with the queue's context. If neither the queue nor the context has a user defined sycl::async_handler, then an implementation-defined default sycl::async_handler is called to handle any errors.

Information and profiling descriptors

sycl::info::event

namespace sycl::info::event {

struct command_execution_status;

} // namespace sycl::info::event

Used as a template parameter for get_info to determine the type of information.

sycl::info::event::command_execution_status

Returns the event status of the command group and contained action (e.g. kernel invocation) associated with this SYCL event.

Return type: sycl::info::event_command_status

Return types

sycl::info::event_command_status

namespace sycl::info {

enum class event_command_status : /* unspecified */ {
  submitted,
  running,
  complete
};

} // namespace sycl::info

sycl::info::event_command_status::submitted	Indicates that the command has been submitted to the SYCL queue but has not yet started running on the device.
sycl::info::event_command_status::running	Indicates that the command has started running on the device but has not yet completed.
sycl::info::event_command_status::complete	Indicates that the command has finished running on the device. Attempting to wait on such an event will not block.

sycl::info::event_profiling

namespace sycl::info::event_profiling  {

struct command_submit;
struct command_start;
struct command_end;

} // namespace sycl::info::event_profiling

Used as a template parameter for get_profiling_info to determine the type of information.

Each profiling descriptor returns a 64-bit timestamp that represents the number of nanoseconds that have elapsed since some implementation-defined timebase.

All events that share the same backend are guaranteed to share the same timebase, therefore the difference between two timestamps from the same backend yields the number of nanoseconds that have elapsed between those events.

sycl::info::event_profiling::command_submit

Returns a timestamp telling when the associated command group was submitted to the sycl::queue.

This is always some time after the command group function object returns and before the associated call to sycl::queue::submit returns.

Return type: uint64_t

sycl::info::event_profiling::command_start

Querying this profiling descriptor blocks until the event's state becomes either sycl::info::event_command_status::running or sycl::info::event_command_status::complete.

The returned timestamp tells when the action associated with the command group (e.g. kernel invocation) started executing on the device.

For any given event, this timestamp is always greater than or equal to the sycl::info::event_profiling::command_submit timestamp.

Implementations are encouraged to return a timestamp that is as close as possible to the point when the action starts running on the device, but there is no specific accuracy that is guaranteed.

Return type: uint64_t

sycl::info::event_profiling::command_end

Querying this profiling descriptor blocks until the event's state becomes sycl::info::event_command_status::complete.

The returned timestamp tells when the action associated with the command group (e.g. kernel invocation) finished executing on the device.

For any given event, this timestamp is always greater than or equal to the sycl::info::event_profiling::command_start timestamp.

Return type: uint64_t

Example

See event-elapsed-time.

Example 1

Measure the elapsed time of a memcpy executed on a device with event profiling info.

#include <sycl/sycl.hpp>

#include <cstdlib>
#include <cstring>

int main() {
  sycl::property_list properties{sycl::property::queue::enable_profiling()};
  auto q = sycl::queue(sycl::default_selector_v, properties);

  std::cout
      << "  Platform: "
      << q.get_device().get_platform().get_info<sycl::info::platform::name>()
      << std::endl;

  const int num_ints = 1024 * 1024;
  const size_t num_bytes = num_ints * sizeof(int);
  const int alignment = 8;

  // Alloc memory on host
  auto src = std::aligned_alloc(alignment, num_bytes);
  std::memset(src, 1, num_bytes);

  // Alloc memory on device
  auto dst = sycl::malloc_device<int>(num_ints, q);
  q.memset(dst, 0, num_bytes).wait();

  // Copy from host to device
  auto event = q.memcpy(dst, src, num_bytes);
  event.wait();

  auto end =
      event.get_profiling_info<sycl::info::event_profiling::command_end>();
  auto start =
      event.get_profiling_info<sycl::info::event_profiling::command_start>();

  std::cout << "Elapsed time: " << (end - start) / 1.0e9 << " seconds\n";

  sycl::free(dst, q);
}

Output example:

  Platform: Intel(R) OpenCL
Elapsed time: 0.0003652 seconds