7 .. currentmodule:: babeltrace.reader
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
15 The Babeltrace Python legacy bindings' reader API exposes two categories
16 of classes. The first category is used to open traces and iterate on
17 theirs events. The typical procedure for reading traces is:
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.
27 :ref:`reader-api-examples`
29 .. class:: TraceCollection
32 A collection of opened traces.
34 .. class:: TraceHandle
37 A trace handle. Allows the user to manipulate a specific trace
45 .. exception:: FieldError
48 A field error. Raised when a field's value cannot be accessed.
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:
55 .. class:: EventDeclaration
60 .. class:: FieldDeclaration
63 Event field declaration (base class for all the following types).
65 .. class:: IntegerFieldDeclaration
68 Integer field declaration.
70 .. class:: FloatFieldDeclaration
73 Floating point number field declaration.
75 .. class:: EnumerationFieldDeclaration
78 Enumeration field declaration.
80 .. class:: StringFieldDeclaration
83 String (NULL-terminated array of bytes) field declaration.
85 .. class:: ArrayFieldDeclaration
88 Static array field declaration.
90 .. class:: SequenceFieldDeclaration
93 Sequence (dynamic array) field declaration.
95 .. class:: StructureFieldDeclaration
98 Structure field declaration. A structure is an ordered map of field
99 names to field values.
101 .. class:: VariantFieldDeclaration
104 Variant field declaration. A variant is dynamic selection between
107 Here is the subclass relationship for the reader API::
116 IntegerFieldDeclaration
117 FloatFieldDeclaration
118 EnumerationFieldDeclaration
119 StringFieldDeclaration
120 ArrayFieldDeclaration
121 SequenceFieldDeclaration
122 StructureFieldDeclaration
123 VariantFieldDeclaration
125 :class:`TraceCollection`
126 ========================
128 .. autoclass:: TraceCollection
131 .. automethod:: __init__
137 .. autoclass:: TraceHandle
151 .. autoexception:: FieldError
155 :class:`EventDeclaration`
156 =========================
158 .. autoclass:: EventDeclaration
162 :class:`FieldDeclaration`
163 =========================
165 .. autoclass:: FieldDeclaration
169 :class:`IntegerFieldDeclaration`
170 ================================
172 .. autoclass:: IntegerFieldDeclaration
177 :class:`FloatFieldDeclaration`
178 ==============================
180 .. autoclass:: FloatFieldDeclaration
185 :class:`EnumerationFieldDeclaration`
186 ====================================
188 .. autoclass:: EnumerationFieldDeclaration
193 :class:`StringFieldDeclaration`
194 ===============================
196 .. autoclass:: StringFieldDeclaration
201 :class:`ArrayFieldDeclaration`
202 ==============================
204 .. autoclass:: ArrayFieldDeclaration
209 :class:`SequenceFieldDeclaration`
210 =================================
212 .. autoclass:: SequenceFieldDeclaration
217 :class:`StructureFieldDeclaration`
218 ==================================
220 .. autoclass:: StructureFieldDeclaration
225 :class:`VariantFieldDeclaration`
226 ================================
228 .. autoclass:: VariantFieldDeclaration