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

systrace/systrace/tracing_agent.py

Index: systrace/systrace/tracing_agent.py
diff --git a/systrace/systrace/tracing_agent.py b/systrace/systrace/tracing_agent.py
new file mode 100644
index 0000000000000000000000000000000000000000..a4e477358ecded13b92ebf247d04a86bf0647cc9
--- /dev/null
+++ b/systrace/systrace/tracing_agent.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python

[Zhen Wang, 2016/03/14 17:11:27]

1. Rename agents/ to tracing_agents/
2. Move this file to tracing_agents/__init__.py

[alexandermont, 2016/03/14 22:19:28]

Done

+
+# 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',
+                                           'should_output_trace'])
+
+class TracingAgent(object):
+  def __init__(self):
+    pass
+
+  def StartAgentTracing(self):
+    '''
+    Starts running the trace for this agent.
+
+    Returns:
+        Boolean value indicating whether or not the trace started successfully.
+    '''
+    raise NotImplementedError
+
+  def StopAgentTracing(self):
+    '''
+    Stops running the trace for this agent. Returns immediately (without
+    waiting for data)
+
+    Returns:
+        Boolean value indicating whether or not the trace stopped successfully.
+    '''
+    raise NotImplementedError
+
+  def SupportsExplicitClockSync(self):
+    '''

[Zhen Wang, 2016/03/14 17:11:27]

nit: Add a sentence to explain what the function do here.

[alexandermont, 2016/03/14 22:19:28]

I'm confused: what's wrong with the current documentation "returns Boolean value
indicating whether this agent supports recording of clock sync markers?"

[Zhen Wang, 2016/03/16 16:54:29]

There is nothing wrong with the Returns part. I mean just add a one line
summary. See examples here:
https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments

+    Returns:
+        Boolean value indicating whether this agent supports recording
+        of clock sync markers.
+    '''
+    raise NotImplementedError
+
+  def RecordClockSyncMarker(self, sync_id, callback):

[nednguyen, 2016/03/14 17:48:11]

s/callback/did_record_sync_marker_callback

[alexandermont, 2016/03/14 22:19:28]

Done

+    '''
+    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):
+    '''
+    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)
+
+    Returns:
+        Completed trace for this agent.
+    '''
+    raise NotImplementedError