parser.js revision 66a37686207944273ced825e0e8b6b6375f8c3de 
1// Copyright (c) 2012 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'use strict';
6
7/**
8 * @fileoverview Base class for linux perf event parsers.
9 *
10 * The linux perf trace event importer depends on subclasses of
11 * Parser to parse event data.  Each subclass corresponds
12 * to a group of trace events; e.g. SchedParser implements
13 * parsing of sched:* kernel trace events.  Parser subclasses must
14 * call Parser.registerSubtype to arrange to be instantiated
15 * and their constructor must register their event handlers with the
16 * importer.  For example,
17 *
18 * var Parser = tracing.importer.linux_perf.Parser;
19 *
20 * function WorkqueueParser(importer) {
21 *   Parser.call(this, importer);
22 *
23 *   importer.registerEventHandler('workqueue_execute_start',
24 *       WorkqueueParser.prototype.executeStartEvent.bind(this));
25 *   importer.registerEventHandler('workqueue_execute_end',
26 *       WorkqueueParser.prototype.executeEndEvent.bind(this));
27 * }
28 *
29 * Parser.registerSubtype(WorkqueueParser);
30 *
31 * When a registered event name is found in the data stream the associated
32 * event handler is invoked:
33 *
34 *   executeStartEvent: function(eventName, cpuNumber, ts, eventBase)
35 *
36 * If the routine returns false the caller will generate an import error
37 * saying there was a problem parsing it.  Handlers can also emit import
38 * messages using this.importer.importError.  If this is done in lieu of
39 * the generic import error it may be desirable for the handler to return
40 * true.
41 *
42 * Trace events generated by writing to the trace_marker file are expected
43 * to have a leading text marker followed by a ':'; e.g. the trace clock
44 * synchronization event is:
45 *
46 *  tracing_mark_write: trace_event_clock_sync: parent_ts=0
47 *
48 * To register an event handler for these events, prepend the marker with
49 * 'tracing_mark_write:'; e.g.
50 *
51 *    this.registerEventHandler('tracing_mark_write:trace_event_clock_sync',
52 *
53 * All subclasses should depend on importer.linux_perf.parser, e.g.
54 *
55 * base.defineModule('importer.linux_perf.workqueue_parser')
56 *   .dependsOn('importer.linux_perf.parser')
57 *   .exportsTo('tracing', function()
58 *
59 * and be listed in the dependsOn of LinuxPerfImporter.  Beware that after
60 * adding a new subclass you must run build/generate_about_tracing_contents.py
61 * to regenerate about_tracing.*.
62 */
63base.exportTo('tracing.importer.linux_perf', function() {
64
65  var subtypeConstructors = [];
66
67  /**
68   * Registers a subclass that will help parse linux perf events.
69   * The importer will call createParsers (below) before importing
70   * data so each subclass can register its handlers.
71   *
72   * @param {Function} subtypeConstructor The subtype's constructor function.
73   */
74  Parser.registerSubtype = function(subtypeConstructor) {
75    subtypeConstructors.push(subtypeConstructor);
76  };
77
78  Parser.getSubtypeConstructors = function() {
79    return subtypeConstructors;
80  };
81
82  /**
83   * Parses linux perf events.
84   * @constructor
85   */
86  function Parser(importer) {
87    this.importer = importer;
88    this.model = importer.model;
89  }
90
91  Parser.prototype = {
92    __proto__: Object.prototype
93  };
94
95  return {
96    Parser: Parser
97  };
98
99});
100