Class event

| Home | Libraries | People | FAQ | More

## Class event

boost::compute::event — An event corresponding to an operation on a compute device.

## Synopsis

    // In header: <boost/compute/event.hpp>

    class event {
    public:
      // construct/copy/destruct
      event();
      explicit event(cl_event, bool = true);
      event(const event &);
      event(event &&) noexcept;
      event & operator=(const event &);
      event & operator=(event &&) noexcept;
      ~event();

      // public member functions
      cl_event & get() const;
      cl_int status() const;
      cl_command_type get_command_type() const;
      template<typename T> T get_info(cl_event_info) const;
      template<int Enum> unspecified get_info() const;
      template<typename T> T get_profiling_info(cl_profiling_info) const;
      void wait() const;
      void set_callback(void(BOOST_COMPUTE_CL_CALLBACK *callback)(cl_event event, cl_int status, void *user_data),
                        cl_int = CL_COMPLETE, void * = 0);
      template<typename Function>
        void set_callback(Function, cl_int = CL_COMPLETE);
      template<typename Duration>
        Duration duration(cl_profiling_info = CL_PROFILING_COMMAND_START,
                          cl_profiling_info = CL_PROFILING_COMMAND_END) const;
      bool operator==(const event &) const;
      bool operator!=(const event &) const;
    };

## Description

Event objects are used to track operations running on the device (such as kernel executions and memory transfers). Event objects are returned by the various `enqueue_*` methods of the command_queue class.

Events can be used to synchronize operations between the host and the device. The `wait()` method will block execution on the host until the operation corresponding to the event on the device has completed. The status of the operation can also be polled with the `status()` method.

Event objects can also be used for performance profiling. In order to use events for profiling, the command queue must be constructed with the `CL_QUEUE_PROFILING_ENABLE` flag. Then the `duration()` method can be used to retrieve the total duration of the operation on the device:

    std::cout << "time = " << e.duration<std::chrono::milliseconds>().count() << "ms\n";

See Also:

future<T>, wait_list

### `event` public construct/copy/destruct

1.     event();

   Creates a null event object.

2.     explicit event(cl_event event, bool retain = true);

3.     event(const event & other);

   Makes a new event as a copy of `other`.

4.     event(event && other) noexcept;

   Move-constructs a new event object from `other`.

5.     event & operator=(const event & other);

   Copies the event object from `other` to `*this`.

6.     event & operator=(event && other) noexcept;

   Move-assigns the event from `other` to `*this`.

7.     ~event();

   Destroys the event object.

### `event` public member functions

1.     cl_event & get() const;

   Returns a reference to the underlying OpenCL event object.

2.     cl_int status() const;

   Returns the status of the event.

3.     cl_command_type get_command_type() const;

   Returns the command type for the event.

4.     template<typename T> T get_info(cl_event_info info) const;

   Returns information about the event.

   See the documentation for clGetEventInfo() for more information.

5.     template<int Enum> unspecified get_info() const;

   This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

6.     template<typename T> T get_profiling_info(cl_profiling_info info) const;

   Returns profiling information for the event.

   See Also:

   event::duration()

   See the documentation for clGetEventProfilingInfo() for more information.

7.     void wait() const;

   Blocks until the actions corresponding to the event have completed.

8.     void set_callback(void(BOOST_COMPUTE_CL_CALLBACK *callback)(cl_event event, cl_int status, void *user_data),
                         cl_int status = CL_COMPLETE, void * user_data = 0);

   Registers a function to be called when the event status changes to `status` (by default CL_COMPLETE). The callback is passed the OpenCL event object, the event status, and a pointer to arbitrary user data.

   See the documentation for clSetEventCallback() for more information.

   | Warning
   This method is only available if the OpenCL version is 1.1 or later.

9.     template<typename Function>
         void set_callback(Function callback, cl_int status = CL_COMPLETE);

   Registers a generic function to be called when the event status changes to `status` (by default `CL_COMPLETE`).

   The function specified by `callback` must be invokable with zero arguments (e.g. `callback()`).

   | Warning
   This method is only available if the OpenCL version is 1.1 or later.

10.     template<typename Duration>
          Duration duration(cl_profiling_info start = CL_PROFILING_COMMAND_START,
                            cl_profiling_info end = CL_PROFILING_COMMAND_END) const;

    Returns the total duration of the event from `start` to `end`.

    For example, to print the number of milliseconds the event took to execute:

        std::cout << event.duration<std::chrono::milliseconds>().count() << " ms" << std::endl;

    See Also:

    event::get_profiling_info()

11.     bool operator==(const event & other) const;

    Returns `true` if the event is the same as `other`.

12.     bool operator!=(const event & other) const;

    Returns `true` if the event is different from `other`.