DevTools/OperationInstrument: Difference between revisions

DevTools/OperationInstrument (view source)

Revision as of 10:06, 3 August 2015

656 bytes added , 3 August 2015

Update documentation to reflect the new API

Victor.porof

Confirmed users

29

edits

@@ Line 28: / Line 28: @@
 == 1. Adding the Instrumentation to Gecko ==
-The easiest way to trace Gecko events/tasks with start and end timeline markers is to use the '''<code>mozilla::AutoTimelineMarker</code>''' RAII class. It automatically adds the start marker on construction, and adds the end marker on destruction. Don't worry too much about potential performance impact! It only actually adds the markers when the given docshell is being recorded.
+Depending on the required fine level of control, there's a couple of ways to do this, and more coming soon. Currently, markers may only be added from the main thread, with plans to support them everywhere in the near future (see ''<code>otmt-markers</code>'' [https://bugzilla.mozilla.org/show_bug.cgi?id=1183219 bug 1183219]).
- --- a/dom/base/nsContentUtils.cpp
+===== Using ''<code>mozilla::AutoTimelineMarker</code>'' =====
- +++ b/dom/base/nsContentUtils.cpp
+The easiest way to trace Gecko events/tasks with start and end timeline markers is to use the '''<code>mozilla::AutoTimelineMarker</code>''' RAII class. It automatically adds the start marker on construction, and adds the end marker on destruction. Don't worry too much about potential performance impact! It only actually adds the markers when the given docshell is being observed by a timeline consumer, so essentially nothing will happen if a tool to inspect those markers isn't specifically open.
- @@ -4241,16 +4242,18 @@
-  nsresult
-  nsContentUtils::ParseFragmentHTML(const nsAString& aSourceBuffer,
-                                    nsIContent* aTargetNode,
-                                    nsIAtom* aContextLocalName,
-                                    int32_t aContextNamespace,
-                                    bool aQuirks,
-                                    bool aPreventScriptExecution)
-  {
- +  AutoTimelineMarker marker(aTargetNode->OwnerDoc()->GetDocShell(), "Parse HTML");
- +
-    if (nsContentUtils::sFragmentParsingActive) {
-      NS_NOTREACHED("Re-entrant fragment parsing attempted.");
-      return NS_ERROR_DOM_INVALID_STATE_ERR;
-    }
-    mozilla::AutoRestore<bool> guard(nsContentUtils::sFragmentParsingActive);
-    nsContentUtils::sFragmentParsingActive = true;
-    if (!sHTMLFragmentParser) {
-      NS_ADDREF(sHTMLFragmentParser = new nsHtml5StringParser());
-Alternatively, you can use [https://dxr.mozilla.org/mozilla-central/search?q=nsDocShell%3A%3AAddProfileTimelineMarker <code>nsDocShell::AddProfilerTimelineMarker</code>] method to manually add start and end marker pairs.
+This class may be used on the main thread only and pointer to a docshell is necessary. If the docshell is a nullptr, nothing happens and this operation fails silently.
+Example:
+''<code>AutoTimelineMarker marker(aTargetNode->OwnerDoc()->GetDocShell(), "Parse HTML");</code>''
+===== Using ''<code>mozilla::AutoGlobalTimelineMarker</code>'' =====
+Similar to the previous RAII class, but doesn't expect a specific docshell, and the marker will be visible in all timeline consumers. This is useful for generic operations that don't involve a particular dochsell, or where a docshell isn't accessible. May also be used on the main thread only.
+Example:
+''<code>AutoGlobalTimelineMarker marker("Some global operation");</code>''
+===== Using ''<code>TimelineConsumers</code>'' =====
+A few static methods exist on the [https://dxr.mozilla.org/mozilla-central/source/docshell/base/timeline/TimelineConsumers.h?from=TimelineConsumers <code>TimelineConsumers</code>] class, like ''<code>AddMarkerForDocShell</code>'', ''<code>AddMarkerToDocShellsList</code>'', ''<code>AddMarkerToAllObservedDocShells</code>'' that give you fine grained control over creating the markers and what meta-data is attached to them.
+Example:
+''<code>TimelineConsumers::AddMarkerToDocShellsList(aDocShells, "Some specific operation", aMetaData);</code>''
 == 2. Telling the DevTools Frontend About the New Markers ==