[Tracing Clock Sync] Add TracingAgent interface in Chrome

base/trace_event/tracing_agent.h

Index: base/trace_event/tracing_agent.h
diff --git a/base/trace_event/tracing_agent.h b/base/trace_event/tracing_agent.h
new file mode 100644
index 0000000000000000000000000000000000000000..97ed9961f151636403a928cd3f3f619d7f4d15ec
--- /dev/null
+++ b/base/trace_event/tracing_agent.h
@@ -0,0 +1,96 @@
+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BASE_TRACE_EVENT_TRACING_AGENT_H_
+#define BASE_TRACE_EVENT_TRACING_AGENT_H_
+
+#include "base/base_export.h"
+#include "base/callback.h"
+#include "base/memory/ref_counted_memory.h"
+#include "base/values.h"
+
+namespace base {
+
+class TimeTicks;
+
+namespace trace_event {
+
+class TraceConfig;
+
+// A tracing agent is the entity that records its own sort of trace. Each
+// tracing method that produces its own trace log should implement this
+// interface. And all tracing agents are and should only be controlled by the
+// TracingController.

[stevenjb, 2015/12/14 18:22:40]

s/the entity/an entity/
s/And all//All/
s/are and should only/must only/
s/the TracingController/TracingController/ (or 'the TracingController instance')

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+//

[stevenjb, 2015/12/14 18:22:39]

No blank line in single comment block

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+// Some existing examples include TracingControllerImpl for Chrome trace events,
+// DebugDaemonClient for CrOs system trace, EtwSystemEventConsumer for Windows
+// system trace and PowerTracingAgent for BattOr power trace.
+class BASE_EXPORT TracingAgent {
+ public:
+  using StopAgentTracingCallback = base::Callback<void(
+      const std::string& agent_name,
+      const std::string& events_label,
+      const scoped_refptr<base::RefCountedString>& events_str_ptr)>;
+  using RecordClockSyncMarkerCallback = base::Callback<void(
+      int sync_id,
+      const TimeTicks& sync_ts,
+      const TimeTicks& sync_end_ts)>;
+
+  virtual ~TracingAgent() {}

[stevenjb, 2015/12/14 18:22:39]

Since this is not a pure interface class (last two methods are implemented),
don't inline the destructor.

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+
+  // Get the name of the tracing agent. Each tracing agent's name should be

[stevenjb, 2015/12/14 18:22:39]

Gets

[Zhen Wang, 2015/12/14 21:03:57]

Done.

+  // unique.
+  virtual std::string GetTracingAgentName() = 0;
+
+  // Get the trace event label of this tracing agent. The label will be used to

[stevenjb, 2015/12/14 18:22:40]

Gets

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+  // label this agent's trace when all traces from different tracing agents are
+  // combined.
+  //

[stevenjb, 2015/12/14 18:22:40]

Avoid blank lines in comment blocks unless they are truly length such as with 
RecordClockSyncMarker below.

[Zhen Wang, 2015/12/14 21:03:57]

Done.

+  // Multiple tracing agents could have the same label. But the tracing agents

[stevenjb, 2015/12/14 18:22:39]

s/But the/The/

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+  // using the same label should not be able to run at the same time. For
+  // example, ETW on Windows and CrOS system tracing both use
+  // "systemTraceEvents" as the label. And those two agents never run at the

[stevenjb, 2015/12/14 18:22:39]

s/And those/Those/
(Last sentence isn't actually necessary, it should be obvious to the reader).

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+  // same time because they are for different platforms.
+  virtual std::string GetTraceEventLabel() = 0;
+
+  // Start tracing on the tracing agent with the trace configuration.

[stevenjb, 2015/12/14 18:22:40]

s/Start/Starts/

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+  virtual bool StartAgentTracing(const TraceConfig& trace_config) = 0;
+
+  // Stop tracing on the tracing agent. The trace data will be passed back to

[stevenjb, 2015/12/14 18:22:40]

s/Stop/Stops/

[Zhen Wang, 2015/12/14 21:03:57]

Done.

+  // the TracingController via the callback.
+  virtual void StopAgentTracing(const StopAgentTracingCallback& callback) = 0;
+
+  // Check if the tracing agent supports explicit clock synchronization.

[stevenjb, 2015/12/14 18:22:40]

s/Check/Checks/

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+  virtual bool SupportsExplicitClockSync();
+
+  // Record a clock sync marker issued by another tracing agent. This is only

[stevenjb, 2015/12/14 18:22:40]

s/Record/Records/

[Zhen Wang, 2015/12/14 21:03:57]

Done.

+  // used if the tracing agent supports explicit clock synchronization.
+  //
+  // Two things need to be done:
+  // 1. The issuer asks the receiver to record the clock sync marker.
+  // 2. The issuer records how long the receiver takes to do the recording.
+  //
+  // In Chrome, the receiver thread also runs in Chrome and it will talk to the
+  // real receiver entity, e.g., power monitor or Android device system, via
+  // different communication methods, e.g., through USB or file reading/writing.
+  // The 2nd thing measures that communication latency.

[stevenjb, 2015/12/14 18:22:40]

s/thing/task/

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+  //
+  // Having a reliable timing measurement for the 2nd thing requires synchronous

[stevenjb, 2015/12/14 18:22:40]

task

[Zhen Wang, 2015/12/14 21:03:56]

Done.

+  // function call without any cross-thread or cross-process activity. However,
+  // tracing agents in Chrome run in their own threads. Therefore, the issuer
+  // needs to dedicate the 2nd thing to the receiver to take time measurements

[stevenjb, 2015/12/14 18:22:39]

task

[Zhen Wang, 2015/12/14 21:03:57]

Done.

+  // in the receiver thread, and the receiver thread needs to pass them back to
+  // the issuer in the callback.
+  //
+  // The assumption is that the receiver thread knows the issuer's clock, which
+  // is true in Chrome because all agent threads' clocks are Chrome clock.
+  virtual void RecordClockSyncMarker(
+      int sync_id,
+      const RecordClockSyncMarkerCallback& callback);
+};
+
+}  // namespace trace_event
+}  // namespace base
+
+#endif  // BASE_TRACE_EVENT_TRACING_AGENT_H_