xpcom/base/VisualEventTracer.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* Visual event tracer, creates a log of events on each thread for visualization */
   8
   9 /**
  10  * The event tracer code is by default disabled in both build and run time.
  11  *
  12  * To enable this code at build time, add --enable-visual-profiling to your
  13  * configure options.
  14  *
  15  * To enable this code at run time, export MOZ_TRACE_FILE env var with a
  16  * path to the file to write the log to. This is all you need to * produce
  17  * the log of all events instrumentation in the mozilla code. Check
  18  * MOZ_EVENT_TRACER_* macros below to add your own.
  19  *
  20  * To let the event tracer log only some events to save disk space, export
  21  * MOZ_PROFILING_EVENTS with comma separated list of event names you want
  22  * to record in the log.
  23  */
  24
  25 #ifndef VisualEventTracer_h___
  26 #define VisualEventTracer_h___
  27
  28 #include <stdint.h>
  29 #include "mozilla/Attributes.h"
  30 #include "mozilla/GuardObjects.h"
  31
  32 #ifdef MOZ_VISUAL_EVENT_TRACER
  33 #include "nsIVisualEventTracer.h"
  34
  35 // Bind an object instance, usually |this|, to a name, usually URL or
  36 // host name, the instance deals with for its lifetime.  The name string
  37 // is duplicated.
  38 // IMPORTANT: it is up to the caller to pass the correct static_cast
  39 // of the |instance| pointer to all these macros ; otherwise the linking
  40 // of events and objects will not work!
  41 // The name will show in details of the events on the timeline and also
  42 // will allow events filtering by host names, URLs etc.
  43 #define MOZ_EVENT_TRACER_NAME_OBJECT(instance, name) \
  44   mozilla::eventtracer::Mark(mozilla::eventtracer::eName, instance, name)
  45
  46 // The same as MOZ_EVENT_TRACER_NAME_OBJECT, just simplifies building
  47 // names when it consists of two parts
  48 #define MOZ_EVENT_TRACER_COMPOUND_NAME(instance, name, name2) \
  49   mozilla::eventtracer::Mark(mozilla::eventtracer::eName, instance, name, name2)
  50
  51
  52 // Call the followings with the same |instance| reference as you have
  53 // previously called MOZ_EVENT_TRACER_NAME_OBJECT.
  54 // Let |name| be the name of the event happening, like "resolving",
  55 // "connecting", "loading" etc.
  56
  57 // This will crate a single-point-in-time event marked with an arrow
  58 // on the timeline, this is a way to indicate an event without a duration.
  59 #define MOZ_EVENT_TRACER_MARK(instance, name) \
  60   mozilla::eventtracer::Mark(mozilla::eventtracer::eShot, instance, name)
  61
  62 // Following macros are used to log events with duration.
  63 // There always has to be complete WAIT,EXEC,DONE or EXEC,DONE
  64 // uninterrupted and non-interferring tuple(s) for an event to be correctly
  65 // shown on the timeline.  Each can be called on any thread, the event tape is
  66 // finally displayed on the thread where it has been EXECuted.
  67
  68 // Example of 3 phases usage for "HTTP request channel":
  69 // WAIT: we've just created the channel and called AsyncOpen on it
  70 // EXEC: we've just got first call to OnDataAvailable, so we are actually
  71 //       receiving the content after some time like connection establising,
  72 //       opening a cache entry, sending the GET request...
  73 // DONE: we've just got OnStopRequest call that indicates the content
  74 //       has been completely delivered and the request is now finished
  75
  76 // Indicate an event pending start, on the timeline this will
  77 // start the event's interval tape with a pale color, the time will
  78 // show in details.  Usually used when an event is being posted or
  79 // we wait for a lock acquisition.
  80 // WAITING is not mandatory, some events don't have a pending phase.
  81 #define MOZ_EVENT_TRACER_WAIT(instance, name) \
  82   mozilla::eventtracer::Mark(mozilla::eventtracer::eWait, instance, name)
  83
  84 // Indicate start of an event actual execution, on the timeline this will
  85 // change the event's tape to a deeper color, the time will show in details.
  86 #define MOZ_EVENT_TRACER_EXEC(instance, name) \
  87   mozilla::eventtracer::Mark(mozilla::eventtracer::eExec, instance, name)
  88
  89 // Indicate the end of an event execution (the event has been done),
  90 // on the timeline this will end the event's tape and show the time in
  91 // event details.
  92 // NOTE: when the event duration is extremely short, like 1ms, it will convert
  93 // to an event w/o a duration - the same as MOZ_EVENT_TRACER_MARK would be used.
  94 #define MOZ_EVENT_TRACER_DONE(instance, name) \
  95   mozilla::eventtracer::Mark(mozilla::eventtracer::eDone, instance, name)
  96
  97 // The same meaning as the above macros, just for concurent events.
  98 // Concurent event means it can happen for the same instance on more
  99 // then just a single thread, e.g. a service method call, a global lock
 100 // acquisition, enter and release.
 101 #define MOZ_EVENT_TRACER_WAIT_THREADSAFE(instance, name) \
 102   mozilla::eventtracer::Mark(mozilla::eventtracer::eWait | mozilla::eventtracer::eThreadConcurrent, instance, name)
 103 #define MOZ_EVENT_TRACER_EXEC_THREADSAFE(instance, name) \
 104   mozilla::eventtracer::Mark(mozilla::eventtracer::eExec | mozilla::eventtracer::eThreadConcurrent, instance, name)
 105 #define MOZ_EVENT_TRACER_DONE_THREASAFE(instance, name) \
 106   mozilla::eventtracer::Mark(mozilla::eventtracer::eDone | mozilla::eventtracer::eThreadConcurrent, instance, name)
 107
 108 #else
 109
 110 // MOZ_VISUAL_EVENT_TRACER disabled
 111
 112 #define MOZ_EVENT_TRACER_NAME_OBJECT(instance, name) (void)0
 113 #define MOZ_EVENT_TRACER_COMPOUND_NAME(instance, name, name2) (void)0
 114 #define MOZ_EVENT_TRACER_MARK(instance, name) (void)0
 115 #define MOZ_EVENT_TRACER_WAIT(instance, name) (void)0
 116 #define MOZ_EVENT_TRACER_EXEC(instance, name) (void)0
 117 #define MOZ_EVENT_TRACER_DONE(instance, name) (void)0
 118 #define MOZ_EVENT_TRACER_WAIT_THREADSAFE(instance, name) (void)0
 119 #define MOZ_EVENT_TRACER_EXEC_THREADSAFE(instance, name) (void)0
 120 #define MOZ_EVENT_TRACER_DONE_THREASAFE(instance, name) (void)0
 121
 122 #endif
 123
 124
 125 namespace mozilla {
 126 namespace eventtracer {
 127
 128 // Initialize the event tracer engine, called automatically on XPCOM startup.
 129 void Init();
 130
 131 // Shuts the event tracer engine down and closes the log file, called
 132 // automatically during XPCOM shutdown.
 133 void Shutdown();
 134
 135 enum MarkType {
 136   eNone, // No operation, ignored
 137   eName, // This is used to bind an object instance with a name
 138
 139   eShot, // An event with no duration
 140   eWait, // Start of waiting for execution (lock acquire, post...)
 141   eExec, // Start of the execution it self
 142   eDone, // End of the execution
 143   eLast, // Sentinel
 144
 145   // Flags
 146
 147   // The same object can execute the same event on several threads concurently
 148   eThreadConcurrent = 0x10000
 149 };
 150
 151 // Records an event on the calling thread.
 152 // @param aType
 153 //    One of MarkType fields, can be bitwise or'ed with the flags.
 154 // @param aItem
 155 //    Reference to the object we want to bind a name to or the event is
 156 //    happening on.  Can be actually anything, but valid poitners should
 157 //    be used.
 158 // @param aText
 159 //    Text of the name (for eName) or event's name for others.  The string
 160 //    is duplicated.
 161 // @param aText2
 162 //    Optional second part of the instnace name, or event name.
 163 //    Event filtering does apply only to the first part (aText).
 164 void Mark(uint32_t aType, void* aItem,
 165           const char* aText, const char* aText2 = 0);
 166
 167
 168 // Helper guard object.  Use to mark an event in the constructor and a different
 169 // event in the destructor.
 170 //
 171 // Example:
 172 // int class::func()
 173 // {
 174 //    AutoEventTracer tracer(this, eventtracer::eExec, eventtracer::eDone, "func");
 175 //
 176 //    do_something_taking_a_long_time();
 177 // }
 178 class MOZ_STACK_CLASS AutoEventTracer
 179 {
 180 public:
 181   AutoEventTracer(void* aInstance,
 182                   uint32_t aTypeOn, // MarkType marked in constructor
 183                   uint32_t aTypeOff, // MarkType marked in destructor
 184                   const char* aName,
 185                   const char* aName2 = 0
 186                   MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
 187     : mInstance(aInstance)
 188     , mName(aName)
 189     , mName2(aName2)
 190     , mTypeOn(aTypeOn)
 191     , mTypeOff(aTypeOff)
 192   {
 193     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
 194
 195     ::mozilla::eventtracer::Mark(mTypeOn, mInstance, mName, mName2);
 196   }
 197
 198   ~AutoEventTracer()
 199   {
 200     ::mozilla::eventtracer::Mark(mTypeOff, mInstance, mName, mName2);
 201   }
 202
 203 private:
 204   void* mInstance;
 205   const char* mName;
 206   const char* mName2;
 207   uint32_t mTypeOn;
 208   uint32_t mTypeOff;
 209
 210   MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
 211 };
 212
 213 #ifdef MOZ_VISUAL_EVENT_TRACER
 214
 215 // The scriptable class that drives the event tracer
 216
 217 class VisualEventTracer MOZ_FINAL: public nsIVisualEventTracer
 218 {
 219   NS_DECL_ISUPPORTS
 220   NS_DECL_NSIVISUALEVENTTRACER
 221 private:
 222   ~VisualEventTracer() {}
 223 };
 224
 225 #define NS_VISUALEVENTTRACER_CID \
 226   { 0xb9e5e102, 0xc2f4, 0x497a,  \
 227     { 0xa6, 0xe4, 0x54, 0xde, 0xf3, 0x71, 0xf3, 0x9d } }
 228 #define NS_VISUALEVENTTRACER_CONTRACTID "@mozilla.org/base/visual-event-tracer;1"
 229 #define NS_VISUALEVENTTRACER_CLASSNAME "Visual Event Tracer"
 230
 231 #endif
 232
 233 } // eventtracer
 234 } // mozilla
 235
 236 #endif /* VisualEventTracer_h___ */