Commit | Line | Data |
---|---|---|
4f5f37d9 PP |
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: |