xpcom/build/perfprobe.h

   1 /* -*-  Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2; -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /**
   7  * A mechanism for interacting with operating system-provided
   8  * debugging/profiling tools such as Microsoft EWT/Windows Performance Toolkit.
   9  */
  10
  11 #ifndef mozilla_perfprobe_h
  12 #define mozilla_perfprobe_h
  13
  14 #if !defined(XP_WIN)
  15 #error "For the moment, perfprobe.h is defined only for Windows platforms"
  16 #endif
  17
  18 #include "nsError.h"
  19 #include "nsStringGlue.h"
  20 #include "prlog.h"
  21 #include "nsTArray.h"
  22 #include "nsAutoPtr.h"
  23 #include <windows.h>
  24 #undef GetStartupInfo //Prevent Windows from polluting global namespace
  25 #include <wmistr.h>
  26 #include <evntrace.h>
  27
  28 namespace mozilla {
  29 namespace probes {
  30
  31 class ProbeManager;
  32
  33 /**
  34  * A data structure supporting a trigger operation that can be used to
  35  * send information to the operating system.
  36  */
  37
  38 class Probe
  39 {
  40 public:
  41   NS_INLINE_DECL_REFCOUNTING(Probe)
  42
  43   /**
  44    * Trigger the event.
  45    *
  46    * Note: Can be called from any thread.
  47    */
  48   nsresult Trigger();
  49   ~Probe() {};
  50
  51 protected:
  52   Probe(const nsCID &aGUID,
  53         const nsACString &aName,
  54          ProbeManager *aManager);
  55   friend class ProbeManager;
  56
  57 protected:
  58
  59   /**
  60    * The system GUID associated to this probe. See the documentation
  61    * of |ProbeManager::Make| for more details.
  62    */
  63   const GUID mGUID;
  64
  65   /**
  66    * The name of this probe. See the documentation
  67    * of |ProbeManager::Make| for more details.
  68    */
  69   const nsCString mName;
  70
  71   /**
  72    * The ProbeManager managing this probe.
  73    *
  74    * Note: This is a weak reference to avoid a useless cycle.
  75    */
  76   class ProbeManager *mManager;
  77 };
  78
  79
  80 /**
  81  * A manager for a group of probes.
  82  *
  83  * You can have several managers in one application, provided that they all
  84  * have distinct IDs and names. However, having more than 2 is considered a bad
  85  * practice.
  86  */
  87 class ProbeManager
  88 {
  89 public:
  90   NS_INLINE_DECL_REFCOUNTING(ProbeManager)
  91
  92   /**
  93    * Create a new probe manager.
  94    *
  95    * This constructor should be called from the main thread.
  96    *
  97    * @param uid The unique ID of the probe. Under Windows, this unique
  98    * ID must have been previously registered using an external tool.
  99    * See MyCategory on http://msdn.microsoft.com/en-us/library/aa364100.aspx
 100    * @param name A name for the probe. Currently used only for logging purposes.
 101    * In the future, may be attached to the data sent to the operating system.
 102    *
 103    * Note: If two ProbeManagers are constructed with the same uid and/or name,
 104    * behavior is unspecified.
 105    */
 106   ProbeManager(const nsCID &applicationUID,
 107                const nsACString &applicationName);
 108
 109   /**
 110    * Acquire a probe.
 111    *
 112    * Note: Only probes acquired before the call to SetReady are taken into
 113    * account
 114    * Note: Can be called only from the main thread.
 115    *
 116    * @param eventUID The unique ID of the probe. Under Windows, this unique
 117    * ID must have been previously registered using an external tool.
 118    * See MyCategory on http://msdn.microsoft.com/en-us/library/aa364100.aspx
 119    * @param eventMame A name for the probe. Currently used only for logging
 120    * purposes. In the
 121    * future, may be attached to the data sent to the operating system.
 122    * @return Either |null| in case of error or a valid |Probe*|.
 123    *
 124    * Note: If this method is called twice with the same uid and/or name,
 125    * behavior is undefined.
 126    */
 127   already_AddRefed<Probe> GetProbe(const nsCID &eventUID,
 128                                    const nsACString &eventName);
 129
 130   /**
 131    * Start/stop the measuring session.
 132    *
 133    * This method should be called from the main thread.
 134    *
 135    * Note that starting an already started probe manager has no effect,
 136    * nor does stopping an already stopped probe manager.
 137    */
 138   nsresult StartSession();
 139   nsresult StopSession();
 140
 141   /**
 142    * @return true If measures are currently on, i.e. if triggering probes is any
 143    * is useful. You do not have to check this before triggering a probe, unless
 144    * this can avoid complex computations.
 145    */
 146   bool IsActive();
 147
 148   ~ProbeManager();
 149
 150 protected:
 151   nsresult StartSession(nsTArray<nsRefPtr<Probe> > &probes);
 152   nsresult Init(const nsCID &applicationUID, const nsACString &applicationName);
 153
 154 protected:
 155   /**
 156    * `true` if a session is in activity, `false` otherwise.
 157    */
 158   bool mIsActive;
 159
 160   /**
 161    * The UID of this manager.
 162    * See documentation above for registration steps that you
 163    * may have to take.
 164    */
 165   nsCID mApplicationUID;
 166
 167   /**
 168    * The name of the application.
 169    */
 170   nsCString mApplicationName;
 171
 172   /**
 173    * All the probes that have been created for this manager.
 174    */
 175   nsTArray<nsRefPtr<Probe> > mAllProbes;
 176
 177   /**
 178    * Handle used for triggering events
 179    */
 180   TRACEHANDLE mSessionHandle;
 181
 182   /**
 183    * Handle used for registration/unregistration
 184    */
 185   TRACEHANDLE mRegistrationHandle;
 186
 187   /**
 188    * `true` if initialization has been performed, `false` until then.
 189    */
 190   bool mInitialized;
 191
 192   friend class Probe;//Needs to access |mSessionHandle|
 193   friend ULONG WINAPI ControlCallback(
 194                                       WMIDPREQUESTCODE RequestCode,
 195                                       PVOID Context,
 196                                       ULONG *Reserved,
 197                                       PVOID Buffer
 198                                       );//Sets |mSessionHandle|
 199 };
 200 }
 201 }
 202
 203 #endif //mozilla_perfprobe_h