[DO NOT COMMIT] Refactor systrace to support new clock sync design

systrace/systrace/tracing_agents/__init__.py

Index: systrace/systrace/tracing_agents/__init__.py
diff --git a/systrace/systrace/tracing_agents/__init__.py b/systrace/systrace/tracing_agents/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..5dfec7407b0d0313c857d2a4d79a4c5dcc947a31
--- /dev/null
+++ b/systrace/systrace/tracing_agents/__init__.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2016 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.
+
+'''Tracing agent interface for systrace.
+
+This class represents an agent that captures traces from a particular
+tool (e.g. atrace, ftrace.)
+'''
+
+from collections import namedtuple
+
+TraceResults = namedtuple('TraceResults', ['data_name',
+                                           'trace_data'])
+
+class TracingAgent(object):
+  def __init__(self):
+    pass
+
+  def StartAgentTracing(self, options, categories, timeout=10):
+    '''Starts running the trace for this agent. Stops with timeout if
+    not completed within timeout.
+

[Zhen Wang, 2016/03/30 16:14:08]

nit: document the parameters.

[alexandermont, 2016/03/30 19:33:25]

Done

+    Returns:
+        Boolean value indicating whether or not the trace started successfully.
+    '''
+    pass
+
+  def StopAgentTracing(self, timeout=10):
+    '''Stops running the trace for this agent and returns immediately.
+    Stops with timeout if not completed within self._options.timeout seconds.
+

[Zhen Wang, 2016/03/30 16:14:08]

nit: document the parameters.

[alexandermont, 2016/03/30 19:33:25]

Done

+    Returns:
+        Boolean value indicating whether or not the trace started successfully.
+    '''
+    pass
+
+  def SupportsExplicitClockSync(self):
+    '''Find out if this agent supports recording of clock sync markers.
+
+    Returns:
+        Boolean value indicating whether this agent supports recording
+        of clock sync markers.
+    '''
+    raise NotImplementedError
+
+  def RecordClockSyncMarker(self, sync_id, did_record_sync_marker_callback):
+    '''Record a clock sync marker for this agent.
+
+    Args:
+        sync_id: Clock sync ID string.
+        callback: Callback function to call (with arguments: timestamp
+        and sync_id) after the clock sync marker is recorded.
+    '''
+    raise NotImplementedError
+
+  def GetResults(self, timeout=30):
+    '''Get the completed trace for this agent, stopping with timeout
+
+    Get the completed trace for this agent. Call only after
+    StopAgentTracing is done. This function blocks until the result
+    is collected (note; this may take several seconds). Stops with timeout
+    if not completed within self._options.collection_timeout seconds.
+

[Zhen Wang, 2016/03/30 16:14:08]

nit: document the parameters.

[alexandermont, 2016/03/30 19:33:25]

Done

+    Returns:
+        Completed trace for this agent.
+    '''
+    pass