bindings/python/babeltrace/babeltrace/reader_event_declaration.py

   1 # The MIT License (MIT)
   2 #
   3 # Copyright (c) 2013-2017 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining a copy
   6 # of this software and associated documentation files (the "Software"), to deal
   7 # in the Software without restriction, including without limitation the rights
   8 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 # copies of the Software, and to permit persons to whom the Software is
  10 # furnished to do so, subject to the following conditions:
  11 #
  12 # The above copyright notice and this permission notice shall be included in
  13 # all copies or substantial portions of the Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  21 # THE SOFTWARE.
  22
  23 import bt2
  24 import babeltrace.common as common
  25 import babeltrace.reader_field_declaration as field_declaration
  26 import collections
  27
  28 def _create_event_declaration(event_class):
  29     event_declaration = EventDeclaration.__new__(EventDeclaration)
  30     event_declaration._event_class = event_class
  31     return event_declaration
  32
  33 class EventDeclaration:
  34     """
  35     An event declaration contains the properties of a class of events,
  36     that is, the common properties and fields layout of all the actual
  37     recorded events associated with this declaration.
  38
  39     This class is not meant to be instantiated by the user. It is
  40     returned by :attr:`TraceHandle.events`.
  41     """
  42     def __init__(self):
  43         raise NotImplementedError("EventDeclaration cannot be instantiated")
  44
  45     def _get_scope_field_type(self, scope):
  46         try:
  47             ec = self._event_class
  48             if scope is common.CTFScope.EVENT_FIELDS:
  49                 return ec.payload_field_type
  50
  51             if scope is common.CTFScope.EVENT_CONTEXT:
  52                 return ec.context_field_type
  53
  54             if scope is common.CTFScope.STREAM_EVENT_CONTEXT:
  55                 return ec.stream_class.event_context_field_type
  56
  57             if scope is common.CTFScope.STREAM_EVENT_HEADER:
  58                 return ec.stream_class.event_header_field_type
  59
  60             if scope is common.CTFScope.STREAM_PACKET_CONTEXT:
  61                 return ec.stream_class.packet_context_field_type
  62
  63             if scope is common.CTFScope.TRACE_PACKET_HEADER:
  64                 return ec.stream_class.trace.packet_header_field_type
  65         except bt2.Error:
  66             return
  67
  68         raise ValueError("Invalid scope provided")
  69
  70     @property
  71     def name(self):
  72         """
  73         Event name, or ``None`` on error.
  74         """
  75
  76         return self._event_class.name
  77
  78     @property
  79     def id(self):
  80         """
  81         Event numeric ID, or -1 on error.
  82         """
  83
  84         return self._event_class.id
  85
  86     @property
  87     def fields(self):
  88         """
  89         Generates all the field declarations of this event, going
  90         through each scope in the following order:
  91
  92         1. Event fields (:attr:`babeltrace.common.CTFScope.EVENT_FIELDS`)
  93         2. Event context (:attr:`babeltrace.common.CTFScope.EVENT_CONTEXT`)
  94         3. Stream event context (:attr:`babeltrace.common.CTFScope.STREAM_EVENT_CONTEXT`)
  95         4. Event header (:attr:`babeltrace.common.CTFScope.STREAM_EVENT_HEADER`)
  96         5. Packet context (:attr:`babeltrace.common.CTFScope.STREAM_PACKET_CONTEXT`)
  97         6. Packet header (:attr:`babeltrace.common.CTFScope.TRACE_PACKET_HEADER`)
  98
  99         All the generated field declarations inherit
 100         :class:`FieldDeclaration`, and are among:
 101
 102         * :class:`IntegerFieldDeclaration`
 103         * :class:`FloatFieldDeclaration`
 104         * :class:`EnumerationFieldDeclaration`
 105         * :class:`StringFieldDeclaration`
 106         * :class:`ArrayFieldDeclaration`
 107         * :class:`SequenceFieldDeclaration`
 108         * :class:`StructureFieldDeclaration`
 109         * :class:`VariantFieldDeclaration`
 110         """
 111
 112         for scope in _SCOPES:
 113             for declaration in self.fields_scope(scope):
 114                 yield declaration
 115
 116     def fields_scope(self, scope):
 117         """
 118         Generates all the field declarations of the event's scope
 119         *scope*.
 120
 121         *scope* must be one of :class:`babeltrace.common.CTFScope` constants.
 122
 123         All the generated field declarations inherit
 124         :class:`FieldDeclaration`, and are among:
 125
 126         * :class:`IntegerFieldDeclaration`
 127         * :class:`FloatFieldDeclaration`
 128         * :class:`EnumerationFieldDeclaration`
 129         * :class:`StringFieldDeclaration`
 130         * :class:`ArrayFieldDeclaration`
 131         * :class:`SequenceFieldDeclaration`
 132         * :class:`StructureFieldDeclaration`
 133         * :class:`VariantFieldDeclaration`
 134         """
 135
 136         scope_field_type = self._get_scope_field_type(scope)
 137         for name, field_type in scope_field_type.items():
 138             yield field_declaration._create_field_declaration(field_type, name,
 139                                                               scope)
 140
 141 # Priority of the scopes when searching for event fields
 142 _SCOPES = [
 143     common.CTFScope.EVENT_FIELDS,
 144     common.CTFScope.EVENT_CONTEXT,
 145     common.CTFScope.STREAM_EVENT_CONTEXT,
 146     common.CTFScope.STREAM_EVENT_HEADER,
 147     common.CTFScope.STREAM_PACKET_CONTEXT,
 148     common.CTFScope.TRACE_PACKET_HEADER
 149 ]