Bug 1850713: remove duplicated setting of early hint preloader id in `ScriptLoader...
[gecko.git] / xpcom / build / perfprobe.h
blobe5a0382322747e1603a862bd7534307cd38564b3
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/. */
7 /**
8 * A mechanism for interacting with operating system-provided
9 * debugging/profiling tools such as Microsoft EWT/Windows Performance Toolkit.
12 #ifndef mozilla_perfprobe_h
13 #define mozilla_perfprobe_h
15 #if !defined(XP_WIN)
16 # error "For the moment, perfprobe.h is defined only for Windows platforms"
17 #endif
19 #include "nsError.h"
20 #include "nsString.h"
21 #include "mozilla/Logging.h"
22 #include "nsTArray.h"
23 #include <windows.h>
24 #undef GetStartupInfo // Prevent Windows from polluting global namespace
25 #include <wmistr.h>
26 #include <evntrace.h>
28 namespace mozilla {
29 namespace probes {
31 class ProbeManager;
33 /**
34 * A data structure supporting a trigger operation that can be used to
35 * send information to the operating system.
38 class Probe {
39 public:
40 NS_INLINE_DECL_REFCOUNTING(Probe)
42 /**
43 * Trigger the event.
45 * Note: Can be called from any thread.
47 nsresult Trigger();
49 protected:
50 ~Probe(){};
52 Probe(const nsCID& aGUID, const nsACString& aName, ProbeManager* aManager);
53 friend class ProbeManager;
55 protected:
56 /**
57 * The system GUID associated to this probe. See the documentation
58 * of |ProbeManager::Make| for more details.
60 const GUID mGUID;
62 /**
63 * The name of this probe. See the documentation
64 * of |ProbeManager::Make| for more details.
66 const nsCString mName;
68 /**
69 * The ProbeManager managing this probe.
71 * Note: This is a weak reference to avoid a useless cycle.
73 class ProbeManager* mManager;
76 /**
77 * A manager for a group of probes.
79 * You can have several managers in one application, provided that they all
80 * have distinct IDs and names. However, having more than 2 is considered a bad
81 * practice.
83 class ProbeManager {
84 public:
85 NS_INLINE_DECL_REFCOUNTING(ProbeManager)
87 /**
88 * Create a new probe manager.
90 * This constructor should be called from the main thread.
92 * @param aApplicationUID The unique ID of the probe. Under Windows, this
93 * unique ID must have been previously registered using an external tool.
94 * See MyCategory on http://msdn.microsoft.com/en-us/library/aa364100.aspx
95 * @param aApplicationName A name for the probe. Currently used only for
96 * logging purposes. In the future, may be attached to the data sent to the
97 * operating system.
99 * Note: If two ProbeManagers are constructed with the same uid and/or name,
100 * behavior is unspecified.
102 ProbeManager(const nsCID& aApplicationUID,
103 const nsACString& aApplicationName);
106 * Acquire a probe.
108 * Note: Only probes acquired before the call to SetReady are taken into
109 * account
110 * Note: Can be called only from the main thread.
112 * @param aEventUID The unique ID of the probe. Under Windows, this unique
113 * ID must have been previously registered using an external tool.
114 * See MyCategory on http://msdn.microsoft.com/en-us/library/aa364100.aspx
115 * @param aEventName A name for the probe. Currently used only for logging
116 * purposes. In the
117 * future, may be attached to the data sent to the operating system.
118 * @return Either |null| in case of error or a valid |Probe*|.
120 * Note: If this method is called twice with the same uid and/or name,
121 * behavior is undefined.
123 already_AddRefed<Probe> GetProbe(const nsCID& aEventUID,
124 const nsACString& aEventName);
127 * Start/stop the measuring session.
129 * This method should be called from the main thread.
131 * Note that starting an already started probe manager has no effect,
132 * nor does stopping an already stopped probe manager.
134 nsresult StartSession();
135 nsresult StopSession();
138 * @return true If measures are currently on, i.e. if triggering probes is any
139 * is useful. You do not have to check this before triggering a probe, unless
140 * this can avoid complex computations.
142 bool IsActive();
144 protected:
145 ~ProbeManager();
147 nsresult StartSession(nsTArray<RefPtr<Probe>>& aProbes);
148 nsresult Init(const nsCID& aApplicationUID,
149 const nsACString& aApplicationName);
151 protected:
153 * `true` if a session is in activity, `false` otherwise.
155 bool mIsActive;
158 * The UID of this manager.
159 * See documentation above for registration steps that you
160 * may have to take.
162 nsCID mApplicationUID;
165 * The name of the application.
167 nsCString mApplicationName;
170 * All the probes that have been created for this manager.
172 nsTArray<RefPtr<Probe>> mAllProbes;
175 * Handle used for triggering events
177 TRACEHANDLE mSessionHandle;
180 * Handle used for registration/unregistration
182 TRACEHANDLE mRegistrationHandle;
185 * `true` if initialization has been performed, `false` until then.
187 bool mInitialized;
189 friend class Probe; // Needs to access |mSessionHandle|
190 friend ULONG WINAPI ControlCallback(WMIDPREQUESTCODE aRequestCode,
191 PVOID aContext, ULONG* aReserved,
192 PVOID aBuffer); // Sets |mSessionHandle|
195 } // namespace probes
196 } // namespace mozilla
198 #endif // mozilla_perfprobe_h