<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <style xmlns="" type="text/css">
    /* This style sets a margin around the entire page */
        html, body {
            margin: 10px;
        }

        p {
            font: normal 16px verdana, sans-serif;
            margin: 0;
            padding-bottom:12px;
        }

        h1 {
            font: bold 25px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h2 {
            font: bold 19px verdana, sans-serif;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h3 {
            font: bold 19px verdana, sans-serif !important;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        li {
            font: normal 16px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 18px;
            padding-top: 0;
            padding-bottom: 0;
        }

        .pdparam {
            font: italic 16px verdana, sans-serif;
        }

                .term {
                        font: italic 16px verdana, sans-serif;
                        font-weight: normal;
                }

                .type {
                        font: normal 16px verdana, sans-serif !important;
                }

                .parameter {
                        font-style: italic;
                        }

        a:link, a:visited {
            color: blue;
            text-decoration: none;
            font: normal 16px;
        }

        a:hover {
            background-color: #FFFF99;
            font: normal 16px;
        }

        div.funcsynopsis {
            text-align: left;
            background-color: #e6e6e6;
            font: normal 16px verdana, sans-serif;
                        padding-top: 10px;
                        padding-bottom: 10px;
        }

        div.funcsynopsis table {
            border-collapse: separate;
            font: normal 16px verdana, sans-serif;
        }

        div.funcsynopsis td {
            background-color: #e6e6e6;
            border: 0 solid #000;
            padding: 1px;
            font: normal 16px verdana, sans-serif;
        }

        div.refsect1 {
            font-family: verdana, sans-serif;
            font-size: 16px;
        }

        code.constant {
            font: normal 16px courier new, monospace !important;
        }

                span.errorname {
            font: normal 16px verdana, sans-serif !important;
        }

        code.function {
            font: bold 16px verdana, sans-serif !important;
        }

        b.fsfunc {
            font: bold 16px verdana, sans-serif !important;
        }

        code.varname {
            font: italic 16px verdana, sans-serif;
        }

        code.replaceable {
            font: italic 16px courier new, monospace;
        }

        code.funcdef {
            font: normal 16px verdana, sans-serif !important;
        }

        .citerefentry {
            font: normal 16px verdana, sans-serif !important;
        }

        .parameter {
            font-style: italic;
        }

        code.fsfunc {
            font: normal 16px verdana, sans-serif !important;
        }

        /* PARAMETER: This style controls spacing between the terms in Parameter section */
        dt {
            margin-top: 15px;
        }

        /* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */
        div.refsect1 table {
            width: 100%;
                        margin-top: 10px;
            background-color: #FFF;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
                        font: normal 16px verdana, sans-serif;
        }

        div.refsect1 th {
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: bold 16px verdana, sans-serif;
        }

        div.refsect1 td {
            background-color: #FFF;
            padding: 5px;
            vertical-align: text-top;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: normal 16px verdana, sans-serif;
        }

                  div.refsect1 p{
            font: normal 16px verdana, sans-serif;
            margin-top: 8px;
            margin-bottom: 8px;
            padding-top: 0;
            padding-bottom: 0;
        }


        /* EXAMPLE: These styles apply only to the Example section */
        div.refsect2 {
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 table {
            margin-top: 0;
            background-color: #e6e6e6;
            width: 100%;
            border: 0 solid #000;
            padding: 2px;
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 td {
            background-color: #e6e6e6;
            font: normal 16px courier new, monospace !important;
                        white-space:pre;
        }

        /* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */
        div.refsect3 {
            font: normal 11px verdana, sans-serif;
            margin-top: 50px;
            margin-bottom: 20px;
            padding-top: 0;
            padding-bottom: 0;
        }

</style>
    <title>capture_event_profiling_info</title>
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <meta name="keywords" content="capture_event_profiling_info" />
  </head>
  <body>
    <div class="refentry">
      <a id="id-1"></a>
      <div class="titlepage"></div>
      <div xmlns="" class="refnamediv">
        <a xmlns="http://www.w3.org/1999/xhtml" id="capture_event_profiling_info"></a>
        <h1>capture_event_profiling_info</h1>
        <p>
            Captures the profiling information for command associated with <code xmlns="http://www.w3.org/1999/xhtml" class="varname">event</code>.
        </p>
      </div>
      <div class="refsynopsisdiv">
        <h2></h2>
        <div class="funcsynopsis">
          <table xmlns="" border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
            <tr valign="bottom">
              <td>
                <code xmlns="http://www.w3.org/1999/xhtml" class="funcdef">
                    <a class="link" href="scalarDataTypes.html" target="pagedisplay">void</a>
                    <strong class="fsfunc">
                        capture_event_profiling_info
                    </strong>
                (</code>
                <td>
                <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="otherDataTypes.html" target="pagedisplay">clk_event_t</a>
                 <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">event</var>
            , </td>
              </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td>
                <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="otherDataTypes.html" target="pagedisplay">clk_profiling_info</a>
                 <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">name</var>
            , </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td>
                global <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">void</a>
                * <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">value</var>
            <code>)</code></td>
            </tr>
          </table>
        </div>
      </div>
      <div class="refsect1">
        <a id="description"></a>
        <h2>Description</h2>
        <p>
            Captures the profiling information for functions
            that are enqueued as commands. The specific
            function being referred to is: enqueue_kernel.
            These enqueued commands are identified by
            unique event objects. The profiling information
            will be available in <code class="varname">value</code> once the command
            identified by <code class="varname">event</code> has completed.

        </p>
        <p>
            <code class="varname">event</code> must be an event returned by 
            <a class="citerefentry" href="enqueue_kernel.html"><span class="citerefentry"><span class="refentrytitle">enqueue_kernel</span></span></a>.
        </p>
        <p>
           <code class="varname">name</code> identifies which profiling information is to 
           be queried and can be <code class="constant">CLK_PROFILING_COMMAND_EXEC_TIME</code>.
        </p>
        <p>
           <code class="varname">value</code> is a pointer to two 64-bit values. 
        </p>
        <p>
            The first 64-bit value describes the elapsed time
            <code class="constant">CL_PROFILING_COMMAND_END</code> –
            <code class="constant">CL_PROFLING_COMMAND_START</code> for the
            command identified by <code class="varname">event</code> in nanoseconds.
        </p>
        <p>
            The second 64-bit value describes the elapsed
            time <code class="constant">CL_PROFILING_COMMAND_COMPLETE</code>
            – <code class="constant">CL_PROFILING_COMAMND_START</code> for the 
            command identified by <code class="varname">event</code> in nanoseconds.
        </p>
        <p>
            NOTE: The behavior of 
            <code class="function">capture_event_profling_info</code> when 
            called multiple times for the same <code class="varname">event</code> is 
            undefined
        </p>
      </div>
      <div class="refsect1">
        <a id="notes"></a>
        <h2>Notes</h2>
        <h4><a id="id-1.6.2"></a>General information about event functions</h4>
        <p>
    Events can be used to identify commands enqueued to a command-queue from the host. 
    These events created by the OpenCL runtime can only be used on the host i.e. as events passed 
    in <code class="varname">event_wait_list</code> argument to various clEnqueue APIs or runtime APIs that take 
    events as arguments such as <a class="citerefentry" href="clRetainEvent.html"><span class="citerefentry"><span class="refentrytitle">clRetainEvent</span></span></a>, 
    <a class="citerefentry" href="clReleaseEvent.html"><span class="citerefentry"><span class="refentrytitle">clReleaseEvent</span></span></a>, 
    <a class="citerefentry" href="clGetEventProfilingInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetEventProfilingInfo</span></span></a>.
  </p>
        <p> 
    Similarly, events can be used to identify commands enqueued to a device queue (from a kernel).
    These event objects cannot be passed to the host or used by OpenCL runtime APIs such as the 
    clEnqueueAPIs or runtime APIs that take event arguments.
  </p>
        <p>
    <a class="citerefentry" href="clRetainEvent.html"><span class="citerefentry"><span class="refentrytitle">clRetainEvent</span></span></a> and 
    <a class="citerefentry" href="clReleaseEvent.html"><span class="citerefentry"><span class="refentrytitle">clReleaseEvent</span></span></a> will return 
    <span class="errorname">CL_INVALID_OPERATION</span> if <code class="varname">event</code>
    specified is an event that refers to any kernel enqueued to a device queue using
    <a class="citerefentry" href="enqueue_kernel.html"><span class="citerefentry"><span class="refentrytitle">enqueue_kernel</span></span></a> or
    <a class="citerefentry" href="enqueue_marker.html"><span class="citerefentry"><span class="refentrytitle">enqueue_marker</span></span></a>
    or is a user event created by 
    <a class="citerefentry" href="create_user_event.html"><span class="citerefentry"><span class="refentrytitle">create_user_event</span></span></a>.
  </p>
        <p>
    Similarly, 
    <a class="citerefentry" href="clSetUserEventStatus.html"><span class="citerefentry"><span class="refentrytitle">clSetUserEventStatus</span></span></a> 
    can only be used to set the execution status of events created using 
    <a class="citerefentry" href="clCreateUserEvent.html"><span class="citerefentry"><span class="refentrytitle">clCreateUserEvent</span></span></a>. 
    User events created on the device can be set using
    <a class="citerefentry" href="set_user_event_status.html"><span class="citerefentry"><span class="refentrytitle">set_user_event_status</span></span></a> built-in function.
  </p>
        <div class="refsect2">
          <a id="example1"></a>
          <h3>
            Example
        </h3>
          <p>
            The example below shows how events can be used with 
            kernels enqueued to multiple device queues.
        </p>
          <div class="informaltable">
            <table border="0">
              <colgroup>
                <col align="left" class="col1" />
              </colgroup>
              <tbody>
                <tr>
                  <td align="left">
extern void barA_kernel(...);
extern void barB_kernel(...);

kernel void
foo(queue_t q0, queue q1, ...)
{
    ...
    clk_event_t evt0;

    // enqueue kernel to queue q0
    enqueue_kernel(q0, 
                   CLK_ENQUEUE_FLAGS_NO_WAIT,
                   ndrange_A,
                   0, NULL, &amp;evt0,
                   ^{barA_kernel(...);} );

    // enqueue kernel to queue q1 
    enqueue_kernel(q1, 
                   CLK_ENQUEUE_FLAGS_NO_WAIT,
                   ndrange_B,
                   1, &amp;evt0, NULL,
                   ^{barB_kernel(...);} );

    // release event evt0. This will get released
    // after barA_kernel enqueued in queue q0 has finished 
    // execution and barB_kernel enqueued in queue q1 and 
    // waits for evt0 is submitted for execution i.e. wait 
    // for evt0 is satisfied.
    release_event(evt0);
}
                        </td>
                </tr>
              </tbody>
            </table>
          </div>
          <p>
            The example below shows how the marker command can 
            be used with kernels enqueued to a device queue.
        </p>
          <div class="informaltable">
            <table border="0">
              <colgroup>
                <col align="left" class="col1" />
              </colgroup>
              <tbody>
                <tr>
                  <td align="left">
kernel void
foo(queue_t q, ...)
{
    ...
    clk_event_t marker_event;
    clk_event_t events[2];

    enqueue_kernel(q,
                  CLK_ENQUEUE_FLAGS_NO_WAIT,
                  ndrange,
                  0, NULL, &amp;events[0],
                  ^{barA_kernel(...);} );

    enqueue_kernel(q,
                  CLK_ENQUEUE_FLAGS_NO_WAIT,
                  ndrange,
                  0, NULL, &amp;events[1],
                  ^{barB_kernel(...);} );

    // barA_kernel and barB_kernel can be executed
    // out of order. we need to wait for both these 
    // kernels to finish execution before barC_kernel 
    // starts execution so we enqueue a marker command and
    // then enqueue barC_kernel that waits on the event 
    // associated with the marker. 

    enqueue_marker(q, 2, events, &amp;marker_event);

    enqueue_kernel(q, 
                   CLK_ENQUEUE_FLAGS_NO_WAIT, 
                   1, &amp;marker_event, NULL,
                   ^{barC_kernel(...);} ); 

    release_event(events[0];
    release_event(events[1]);
    release_event(marker_event);
}
                        </td>
                </tr>
              </tbody>
            </table>
          </div>
        </div>
        <p>
          The behavior of <code class="function">capture_event_profling_info</code> when 
          called multiple times for the same <code class="varname">event</code> is undefined.
        </p>
      </div>
      <div class="refsect1">
        <a id="specification"></a>
        <h2>Specification</h2>
        <p>
            <img src="pdficon_small1.gif" />

            <a href="https://www.khronos.org/registry/cl/specs/opencl-2.1-openclc.pdf#page=171" target="OpenCL Spec">OpenCL Specification</a>
        </p>
      </div>
      <div class="refsect1">
        <a id="seealso"></a>
        <h2>Also see</h2>
        <p>
            <a class="citerefentry" href="eventFunctions.html"><span class="citerefentry"><span class="refentrytitle">Event Functions</span></span></a>
        </p>
      </div>
      <div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4><img xmlns="http://www.w3.org/1999/xhtml" src="KhronosLogo.jpg" /><p xmlns="http://www.w3.org/1999/xhtml"></p>Copyright © 2007-2015 The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.
</div>
    </div>
  </body>
</html>