doc/bindings/python/source/reader.rst

   1 .. _reader-api:
   2
   3 **********
   4 Reader API
   5 **********
   6
   7 .. currentmodule:: babeltrace.reader
   8
   9 The classes documented below are related to **reading traces**
  10 operations. Common operations such as adding traces to a trace
  11 collection, iterating on their events, reading event names,
  12 timestamps, contexts and payloads can be accomplished by using these
  13 classes.
  14
  15 The Babeltrace Python bindings' reader API exposes two categories of
  16 classes. The first category is used to open traces and iterate on
  17 theirs events. The typical procedure for reading traces is:
  18
  19 1. Create a :class:`TraceCollection` instance.
  20 2. Add traces to this collection using
  21    :meth:`TraceCollection.add_trace`.
  22 3. Iterate on :attr:`TraceCollection.events` to get :class:`Event`
  23    objects and perform the desired computation on event data.
  24
  25 .. seealso::
  26
  27    :ref:`reader-api-examples`
  28
  29 .. class:: TraceCollection
  30    :noindex:
  31
  32    A collection of opened traces.
  33
  34 .. class:: TraceHandle
  35    :noindex:
  36
  37    A trace handle. Allows the user to manipulate a specific trace
  38    directly.
  39
  40 .. class:: Event
  41    :noindex:
  42
  43    An event.
  44
  45 .. exception:: FieldError
  46    :noindex:
  47
  48    A field error. Raised when a field's value cannot be accessed.
  49
  50 The second category of classes is a set of declaration classes that
  51 are returned when inspecting the layout of a trace's events, through
  52 :attr:`TraceHandle.events`. The following classes are not meant to be
  53 instantiated by the user:
  54
  55 .. class:: EventDeclaration
  56    :noindex:
  57
  58    Event declaration.
  59
  60 .. class:: FieldDeclaration
  61    :noindex:
  62
  63    Event field declaration (base class for all the following types).
  64
  65 .. class:: IntegerFieldDeclaration
  66    :noindex:
  67
  68    Integer field declaration.
  69
  70 .. class:: FloatFieldDeclaration
  71    :noindex:
  72
  73    Floating point number field declaration.
  74
  75 .. class:: EnumerationFieldDeclaration
  76    :noindex:
  77
  78    Enumeration field declaration.
  79
  80 .. class:: StringFieldDeclaration
  81    :noindex:
  82
  83    String (NULL-terminated array of bytes) field declaration.
  84
  85 .. class:: ArrayFieldDeclaration
  86    :noindex:
  87
  88    Static array field declaration.
  89
  90 .. class:: SequenceFieldDeclaration
  91    :noindex:
  92
  93    Sequence (dynamic array) field declaration.
  94
  95 .. class:: StructureFieldDeclaration
  96    :noindex:
  97
  98    Structure field declaration. A structure is an ordered map of field
  99    names to field values.
 100
 101 .. class:: VariantFieldDeclaration
 102    :noindex:
 103
 104    Variant field declaration. A variant is dynamic selection between
 105    different types.
 106
 107 Here is the subclass relationship for the reader API::
 108
 109     object
 110         TraceCollection
 111         TraceHandle
 112         Event
 113         FieldError
 114         EventDeclaration
 115         FieldDeclaration
 116             IntegerFieldDeclaration
 117             FloatFieldDeclaration
 118             EnumerationFieldDeclaration
 119             StringFieldDeclaration
 120             ArrayFieldDeclaration
 121             SequenceFieldDeclaration
 122             StructureFieldDeclaration
 123             VariantFieldDeclaration
 124
 125 :class:`TraceCollection`
 126 ========================
 127
 128 .. autoclass:: TraceCollection
 129    :members:
 130
 131    .. automethod:: __init__
 132
 133
 134 :class:`TraceHandle`
 135 ====================
 136
 137 .. autoclass:: TraceHandle
 138    :members:
 139
 140
 141 :class:`Event`
 142 ==============
 143
 144 .. autoclass:: Event
 145    :members:
 146
 147
 148 :exc:`FieldError`
 149 =================
 150
 151 .. autoexception:: FieldError
 152    :members:
 153
 154
 155 :class:`EventDeclaration`
 156 =========================
 157
 158 .. autoclass:: EventDeclaration
 159    :members:
 160
 161
 162 :class:`FieldDeclaration`
 163 =========================
 164
 165 .. autoclass:: FieldDeclaration
 166    :members:
 167
 168
 169 :class:`IntegerFieldDeclaration`
 170 ================================
 171
 172 .. autoclass:: IntegerFieldDeclaration
 173    :members:
 174    :show-inheritance:
 175
 176
 177 :class:`FloatFieldDeclaration`
 178 ==============================
 179
 180 .. autoclass:: FloatFieldDeclaration
 181    :members:
 182    :show-inheritance:
 183
 184
 185 :class:`EnumerationFieldDeclaration`
 186 ====================================
 187
 188 .. autoclass:: EnumerationFieldDeclaration
 189    :members:
 190    :show-inheritance:
 191
 192
 193 :class:`StringFieldDeclaration`
 194 ===============================
 195
 196 .. autoclass:: StringFieldDeclaration
 197    :members:
 198    :show-inheritance:
 199
 200
 201 :class:`ArrayFieldDeclaration`
 202 ==============================
 203
 204 .. autoclass:: ArrayFieldDeclaration
 205    :members:
 206    :show-inheritance:
 207
 208
 209 :class:`SequenceFieldDeclaration`
 210 =================================
 211
 212 .. autoclass:: SequenceFieldDeclaration
 213    :members:
 214    :show-inheritance:
 215
 216
 217 :class:`StructureFieldDeclaration`
 218 ==================================
 219
 220 .. autoclass:: StructureFieldDeclaration
 221    :members:
 222    :show-inheritance:
 223
 224
 225 :class:`VariantFieldDeclaration`
 226 ================================
 227
 228 .. autoclass:: VariantFieldDeclaration
 229    :members: