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
  29 def _create_event_declaration(event_class):
  30     event_declaration = EventDeclaration.__new__(EventDeclaration)
  31     event_declaration._event_class = event_class
  32     return event_declaration
  33
  34
  35 class EventDeclaration:
  36     """
  37     An event declaration contains the properties of a class of events,
  38     that is, the common properties and fields layout of all the actual
  39     recorded events associated with this declaration.
  40
  41     This class is not meant to be instantiated by the user. It is
  42     returned by :attr:`TraceHandle.events`.
  43     """
  44     def __init__(self):
  45         raise NotImplementedError("EventDeclaration cannot be instantiated")
  46
  47     def _get_scope_field_type(self, scope):
  48         try:
  49             ec = self._event_class
  50             if scope is common.CTFScope.EVENT_FIELDS:
  51                 return ec.payload_field_type
  52
  53             if scope is common.CTFScope.EVENT_CONTEXT:
  54                 return ec.context_field_type
  55
  56             if scope is common.CTFScope.STREAM_EVENT_CONTEXT:
  57                 return ec.stream_class.event_context_field_type
  58
  59             if scope is common.CTFScope.STREAM_EVENT_HEADER:
  60                 return ec.stream_class.event_header_field_type
  61
  62             if scope is common.CTFScope.STREAM_PACKET_CONTEXT:
  63                 return ec.stream_class.packet_context_field_type
  64
  65             if scope is common.CTFScope.TRACE_PACKET_HEADER:
  66                 return ec.stream_class.trace.packet_header_field_type
  67         except bt2.Error:
  68             return
  69
  70         raise ValueError("Invalid scope provided")
  71
  72     @property
  73     def name(self):
  74         """
  75         Event name, or ``None`` on error.
  76         """
  77
  78         return self._event_class.name
  79
  80     @property
  81     def id(self):
  82         """
  83         Event numeric ID, or -1 on error.
  84         """
  85
  86         return self._event_class.id
  87
  88     @property
  89     def fields(self):
  90         """
  91         Generates all the field declarations of this event, going
  92         through each scope in the following order:
  93
  94         1. Event fields (:attr:`babeltrace.common.CTFScope.EVENT_FIELDS`)
  95         2. Event context (:attr:`babeltrace.common.CTFScope.EVENT_CONTEXT`)
  96         3. Stream event context (:attr:`babeltrace.common.CTFScope.STREAM_EVENT_CONTEXT`)
  97         4. Event header (:attr:`babeltrace.common.CTFScope.STREAM_EVENT_HEADER`)
  98         5. Packet context (:attr:`babeltrace.common.CTFScope.STREAM_PACKET_CONTEXT`)
  99         6. Packet header (:attr:`babeltrace.common.CTFScope.TRACE_PACKET_HEADER`)
 100
 101         All the generated field declarations inherit
 102         :class:`FieldDeclaration`, and are among:
 103
 104         * :class:`IntegerFieldDeclaration`
 105         * :class:`FloatFieldDeclaration`
 106         * :class:`EnumerationFieldDeclaration`
 107         * :class:`StringFieldDeclaration`
 108         * :class:`ArrayFieldDeclaration`
 109         * :class:`SequenceFieldDeclaration`
 110         * :class:`StructureFieldDeclaration`
 111         * :class:`VariantFieldDeclaration`
 112         """
 113
 114         for scope in _SCOPES:
 115             for declaration in self.fields_scope(scope):
 116                 yield declaration
 117
 118     def fields_scope(self, scope):
 119         """
 120         Generates all the field declarations of the event's scope
 121         *scope*.
 122
 123         *scope* must be one of :class:`babeltrace.common.CTFScope` constants.
 124
 125         All the generated field declarations inherit
 126         :class:`FieldDeclaration`, and are among:
 127
 128         * :class:`IntegerFieldDeclaration`
 129         * :class:`FloatFieldDeclaration`
 130         * :class:`EnumerationFieldDeclaration`
 131         * :class:`StringFieldDeclaration`
 132         * :class:`ArrayFieldDeclaration`
 133         * :class:`SequenceFieldDeclaration`
 134         * :class:`StructureFieldDeclaration`
 135         * :class:`VariantFieldDeclaration`
 136         """
 137
 138         scope_field_type = self._get_scope_field_type(scope)
 139         for name, field_type in scope_field_type.items():
 140             yield field_declaration._create_field_declaration(field_type, name,
 141                                                               scope)
 142
 143
 144 # Priority of the scopes when searching for event fields
 145 _SCOPES = [
 146     common.CTFScope.EVENT_FIELDS,
 147     common.CTFScope.EVENT_CONTEXT,
 148     common.CTFScope.STREAM_EVENT_CONTEXT,
 149     common.CTFScope.STREAM_EVENT_HEADER,
 150     common.CTFScope.STREAM_PACKET_CONTEXT,
 151     common.CTFScope.TRACE_PACKET_HEADER
 152 ]