<!DOCTYPE html>
<!--
Copyright (c) 2012 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.
-->
<link rel="import" href="/tracing/base/base.html">
<link rel="import" href="/tracing/base/extension_registry.html">
<script>
'use strict';

/**
 * @fileoverview Base class for linux perf event parsers.
 *
 * The linux perf trace event importer depends on subclasses of
 * Parser to parse event data.  Each subclass corresponds
 * to a group of trace events; e.g. SchedParser implements
 * parsing of sched:* kernel trace events.  Parser subclasses must
 * call Parser.register to arrange to be instantiated
 * and their constructor must register their event handlers with the
 * importer.  For example,
 *
 * var Parser = tr.e.importer.linux_perf.Parser;
 *
 * function WorkqueueParser(importer) {
 *   Parser.call(this, importer);
 *
 *   importer.registerEventHandler('workqueue_execute_start',
 *       WorkqueueParser.prototype.executeStartEvent.bind(this));
 *   importer.registerEventHandler('workqueue_execute_end',
 *       WorkqueueParser.prototype.executeEndEvent.bind(this));
 * }
 *
 * Parser.register(WorkqueueParser);
 *
 * When a registered event name is found in the data stream the associated
 * event handler is invoked:
 *
 *   executeStartEvent: function(eventName, cpuNumber, ts, eventBase)
 *
 * If the routine returns false the caller will generate an import error
 * saying there was a problem parsing it.  Handlers can also emit import
 * messages using this.importer.model.importWarning.  If this is done in lieu of
 * the generic import error it may be desirable for the handler to return
 * true.
 *
 * Trace events generated by writing to the trace_marker file are expected
 * to have a leading text marker followed by a ':'; e.g. the trace clock
 * synchronization event is:
 *
 *  tracing_mark_write: trace_event_clock_sync: parent_ts=0
 *
 * To register an event handler for these events, prepend the marker with
 * 'tracing_mark_write:'; e.g.
 *
 *    this.registerEventHandler('tracing_mark_write:trace_event_clock_sync',
 *
 * All subclasses should depend on importer.linux_perf.parser, e.g.
 *
 * tr.defineModule('importer.linux_perf.workqueue_parser')
 *   .dependsOn('importer.linux_perf.parser')
 *   .exportsTo('tracing', function()
 *
 * and be listed in the dependsOn of LinuxPerfImporter.  Beware that after
 * adding a new subclass you must run build/generate_about_tracing_contents.py
 * to regenerate tr.ui.e.about_tracing.*.
 */
tr.exportTo('tr.e.importer.linux_perf', function() {
  /**
   * Parses linux perf events.
   * @constructor
   */
  function Parser(importer) {
    this.importer = importer;
    this.model = importer.model;
  }

  Parser.prototype = {
    __proto__: Object.prototype
  };

  var options = new tr.b.ExtensionRegistryOptions(tr.b.BASIC_REGISTRY_MODE);
  options.mandatoryBaseClass = Parser;
  tr.b.decorateExtensionRegistry(Parser, options);

  return {
    Parser: Parser
  };
});
</script>