ppapi/api/dev/ppb_trace_event_dev.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_Trace_Event</code> interface. It is meant
   8  * to be used in plugins as the API that trace macros from trace_event.h use.
   9  */
  10
  11 label Chrome {
  12   M25 = 0.1,
  13   M29 = 0.2
  14 };
  15
  16 /**
  17  * A trace event timestamp.
  18  */
  19 typedef int64_t PP_TraceEventTime;
  20
  21 interface PPB_Trace_Event_Dev {
  22   /**
  23    * Gets a pointer to a character for identifying a category name in the
  24    * tracing system as well as for being able to early exit in client-side
  25    * tracing code.
  26    *
  27    * NB: This mem_t return value should technically be const, but return values
  28    * for Pepper IDL of mem_t type are not const.  The same is true for the arg
  29    * |category_enabled| for AddTraceEvent.
  30    */
  31   mem_t GetCategoryEnabled([in] cstr_t category_name);
  32
  33   /**
  34    * Adds a trace event to the platform tracing system. This function call is
  35    * usually the result of a TRACE_* macro from trace_event.h when tracing and
  36    * the category of the particular trace are enabled. It is not advisable to
  37    * call this function on its own; it is really only meant to be used by the
  38    * trace macros.
  39    */
  40   void AddTraceEvent(
  41       [in] int8_t phase,
  42       [in] mem_t category_enabled,
  43       [in] cstr_t name,
  44       [in] uint64_t id,
  45       [in] uint32_t num_args,
  46       [in, size_as=num_args] str_t[] arg_names,
  47       [in, size_as=num_args] uint8_t[] arg_types,
  48       [in, size_as=num_args] uint64_t[] arg_values,
  49       [in] uint8_t flags);
  50
  51   /**
  52    * Version of the above interface that allows specifying a custom thread id
  53    * and timestamp. This is useful for when tracing data cannot be registered
  54    * in real time. For example, this could be used by storing timestamps
  55    * internally and then registering the events retroactively.
  56    */
  57   [version=0.2]
  58   void AddTraceEventWithThreadIdAndTimestamp(
  59       [in] int8_t phase,
  60       [in] mem_t category_enabled,
  61       [in] cstr_t name,
  62       [in] uint64_t id,
  63       [in] int32_t thread_id,
  64       [in] PP_TraceEventTime timestamp,
  65       [in] uint32_t num_args,
  66       [in, size_as=num_args] str_t[] arg_names,
  67       [in, size_as=num_args] uint8_t[] arg_types,
  68       [in, size_as=num_args] uint64_t[] arg_values,
  69       [in] uint8_t flags);
  70
  71   /**
  72    * Get the current clock value. Since this uses the same function as the trace
  73    * events use internally, it can be used to create events with explicit time
  74    * stamps.
  75    */
  76   [version=0.2]
  77   PP_TraceEventTime Now();
  78
  79   /**
  80    * Sets the thread name of the calling thread in the tracing system so it will
  81    * show up properly in chrome://tracing.
  82    */
  83   void SetThreadName([in] cstr_t thread_name);
  84 };