[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..90de315e38da16fb049e393a45b982cf56c33581
--- /dev/null
+++ b/systrace/systrace/tracing_agents/__init__.py
@@ -0,0 +1,107 @@
+#!/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
+from devil.utils import timeout_retry
+
+TraceResults = namedtuple('TraceResults', ['data_name',
+                                           'trace_data'])
+
+class TracingAgent(object):
+  def __init__(self, options, categories):
+    self._options = options
+    self._categories = categories

[Zhen Wang, 2016/03/29 18:53:40]

In general, the interface class should not contain any states. Do not pass in
options and categories here. We should just have a bunch of public functions in
this class.

In addition, we should limit the access to the states as much as possible. This
means that concrete agents should not store options and categories as their
member variables, either.

For example, StartAgentTracing needs options and categories. But
StopAgentTracing and GetResults only needs timeout value.

[alexandermont, 2016/03/30 01:04:24]

Done

+
+  def _StartAgentTracing_func(self):

[Zhen Wang, 2016/03/29 18:53:40]

Is this function "private" or "protected"? I guess you mean "protected" here,
because subclasses need to override it. We do not have a way to distinguish
between "protected" and "private" functions in python. People will be confused
and think this is "private" function. (prepending single underscore means
"private".)

TracingAgent is the interface for all agents. It should just contain public
interfaces.

This applies to StopAgentTracing and GetResults too.

[alexandermont, 2016/03/30 01:04:24]

Done

+    '''Starts running the trace for this agent. This is the inner function
+    that does the work.
+
+    Returns:
+        Boolean value indicating whether or not the trace started successfully.
+    '''
+    raise NotImplementedError
+
+  def _StopAgentTracing_func(self):
+    '''Stops running the trace for this agent and returns immediately.
+    This is the inner function that does the work.
+
+    Returns immediately (without waiting for data)
+
+    Returns:
+        Boolean value indicating whether or not the trace stopped successfully.
+    '''
+    raise NotImplementedError
+
+  def StartAgentTracing(self):

[Zhen Wang, 2016/03/29 18:53:39]

def StartAgentTracing(self, options, categories)

[alexandermont, 2016/03/30 01:04:24]

Done

+    '''Starts running the trace for this agent. Stops with timeout if
+    not completed within self._options.timeout seconds.
+
+    Returns:
+        Boolean value indicating whether or not the trace started successfully.
+    '''
+    return timeout_retry.Run(self._StartAgentTracing_func,
+                             self._options.timeout, 1)

[Zhen Wang, 2016/03/29 18:53:40]

How to handle timeout should be dedicated to each concrete agent. Not all agents
can use timeout_retry.

For example, later we will add Chrome tracing agent (merging with Telemetry
tracing facilities). The timeout value will be passed to the websocket to
DevTools and be handled there. (WebSocketTimeoutException will be thrown.)

So this interface should just raise NotImplementedError. Not doing timeout_retry
here also solve the problem above in for _StartAgentTracing_func(). You will
then just have public interfaces.

This applies to StopAgentTracing and GetResults too.

[alexandermont, 2016/03/30 01:04:24]

Done

+
+  def StopAgentTracing(self):

[Zhen Wang, 2016/03/29 18:53:40]

def StopAgentTracing(self, timeout)

[alexandermont, 2016/03/30 01:04:24]

Done

[alexandermont, 2016/03/30 01:04:24]

Done

+    '''Stops running the trace for this agent and returns immediately.
+    Stops with timeout if not completed within self._options.timeout seconds.
+
+    Returns:
+        Boolean value indicating whether or not the trace started successfully.
+    '''
+    return timeout_retry.Run(self._StopAgentTracing_func,
+                             self._options.timeout, 1)
+
+  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_func(self):
+    '''Get the completed trace for this agent.
+
+    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
+
+  def GetResults(self):

[Zhen Wang, 2016/03/29 18:53:40]

def GetResults(self, timeout)

[alexandermont, 2016/03/30 01:04:24]

Done

+    '''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.
+
+    Returns:
+        Completed trace for this agent.
+    '''
+    return timeout_retry.Run(self._GetResults_func,
+                             self._options.collection_timeout, 1)