1# Copyright 2014 The Chromium Authors. All rights reserved.
2# Use of this source code is governed by a BSD-style license that can be
3# found in the LICENSE file.
4
5
6class TracingAgent(object):
7  """A tracing agent provided by the platform.
8
9  A tracing agent can gather data with Start() until Stop().
10  Before constructing an TracingAgent, check whether it's supported on the
11  platform with IsSupported method first.
12
13  NOTE: All subclasses of TracingAgent must not change the constructor's
14  parameters so the agents can be dynamically constructed in
15  tracing_controller_backend.
16
17  """
18
19  def __init__(self, platform_backend):
20    self._platform_backend = platform_backend
21
22  @classmethod
23  def IsSupported(cls, platform_backend):
24    del platform_backend  # unused
25    return False
26
27  def StartAgentTracing(self, config, timeout):
28    """ Override to add tracing agent's custom logic to start tracing.
29
30    Depending on trace_options and category_filter, the tracing agent may choose
31    to start or not start tracing.
32
33    Args:
34      config: tracing_config instance that contains trace_option and
35        category_filter
36        trace_options: an instance of tracing_options.TracingOptions that
37          control which core tracing systems should be enabled.
38        category_filter: an instance of
39          tracing_category_filter.TracingCategoryFilter
40      timeout: number of seconds that this tracing agent should try to start
41        tracing until time out.
42
43    Returns:
44      True if tracing agent started successfully.
45    """
46    raise NotImplementedError
47
48  def StopAgentTracing(self, trace_data_builder):
49    """ Override to add tracing agent's custom logic to stop tracing.
50
51    StopAgentTracing() should guarantee tracing is stopped, even if there may
52    be exception.
53    """
54    raise NotImplementedError
55
56  def SupportsFlushingAgentTracing(self):
57    """ Override to indicate support of flushing tracing. """
58    return False
59
60  def FlushAgentTracing(self, config, timeout, trace_data_builder):
61    """ Override to add tracing agent's custom logic to flush tracing. """
62    del config, timeout, trace_data_builder  # unused
63    raise NotImplementedError
64
65  def SupportsExplicitClockSync(self):
66    """ Override to indicate support of explicit clock syncing. """
67    return False
68
69  def RecordClockSyncMarker(self, sync_id,
70                            record_controller_clocksync_marker_callback):
71    """ Override to record clock sync marker.
72
73    Only override if supports explicit clock syncing.
74    Args:
75      sync_id: Unqiue id for sync event.
76      record_controller_clocksync_marker_callback: Function that takes sync_id
77        and a timestamp as argument.
78    """
79    del sync_id # unused
80    del record_controller_clocksync_marker_callback # unused
81    raise NotImplementedError
82