Commit | Line | Data |
---|---|---|
4f5f37d9 PP |
1 | .. _ctf-writer-api: |
2 | ||
3 | ************** | |
4 | CTF writer API | |
5 | ************** | |
6 | ||
7 | .. currentmodule:: babeltrace.writer | |
8 | ||
9 | The **CTF writer API** allows to write native | |
10 | `CTF <http://www.efficios.com/ctf>`_ traces from a Python environment. | |
11 | ||
12 | A CTF trace is made of one or more CTF streams. Streams contain | |
13 | packets, which in turn contain serialized events. CTF readers, such as | |
14 | Babeltrace, are able to merge streams and iterate on events in order | |
15 | when reading a CTF trace. | |
16 | ||
17 | The CTF writer API is exposed as a set of classes available in the | |
18 | :mod:`babeltrace.writer` module. | |
19 | ||
20 | .. seealso:: | |
21 | ||
22 | :ref:`ctf-writer-api-examples` | |
23 | ||
24 | There is a clear distinction to be made between field declaration | |
25 | and field objects. A field declaration describes the properties, or | |
26 | metadata, of a field. It does not contain a value. For example, | |
27 | an integer *field declaration* contains a size in bits, a byte order, | |
28 | a display base, whether it's signed or not, and so on. On the other | |
29 | hand, an integer *field* is linked with a specific integer field | |
30 | declaration, but contains an actual integer value. Thus, the layout and | |
31 | properties of fields are described once in field declarations, and then | |
32 | all concrete fields carry a value and a field declaration reference. | |
33 | The same applies to event classes vs. events, as well as to stream | |
34 | classes vs. streams. | |
35 | ||
36 | The main interface to write a CTF trace is the :class:`Writer` class: | |
37 | ||
38 | .. class:: Writer | |
39 | :noindex: | |
40 | ||
41 | Writing object in which clocks and streams may be registered, and | |
42 | other common trace properties may be set. | |
43 | ||
44 | A concrete :class:`Stream` object may be created from a | |
45 | :class:`StreamClass` using :meth:`Writer.create_stream` method. A | |
46 | stream class is also associated with a clock (:class:`Clock`), which | |
47 | must also be registered to the writer object. | |
48 | ||
49 | .. class:: StreamClass | |
50 | :noindex: | |
51 | ||
52 | Stream class. | |
53 | ||
54 | .. class:: Stream | |
55 | :noindex: | |
56 | ||
57 | Stream, based on a stream class. | |
58 | ||
59 | .. class:: Clock | |
60 | :noindex: | |
61 | ||
62 | Reference clock of one to many streams. | |
63 | ||
64 | Events, before being created, must be described in an event class | |
65 | (:class:`EventClass`). An event class must be added to a stream class | |
66 | using :meth:`StreamClass.add_event_class` before appending an event | |
67 | to an actual stream linked with this stream class. | |
68 | ||
69 | .. class:: EventClass | |
70 | :noindex: | |
71 | ||
72 | Event class. | |
73 | ||
74 | .. class:: Event | |
75 | :noindex: | |
76 | ||
77 | Event, based on an event class. | |
78 | ||
79 | An event class is created by instantiating an :class:`EventClass` | |
80 | object and using its :meth:`~EventClass.add_field` method to add an | |
81 | instance of one of the following field declarations: | |
82 | ||
83 | .. class:: IntegerFieldDeclaration | |
84 | :noindex: | |
85 | ||
86 | Integer field declaration. | |
87 | ||
88 | .. class:: FloatingPointFieldDeclaration | |
89 | :noindex: | |
90 | ||
91 | Floating point number field declaration. | |
92 | ||
93 | .. class:: EnumerationFieldDeclaration | |
94 | :noindex: | |
95 | ||
96 | Enumeration field declaration (mapping from labels to ranges of | |
97 | integers). | |
98 | ||
99 | .. class:: StringFieldDeclaration | |
100 | :noindex: | |
101 | ||
102 | String (NULL-terminated array of bytes) field declaration. | |
103 | ||
104 | .. class:: ArrayFieldDeclaration | |
105 | :noindex: | |
106 | ||
107 | Static array field declaration. | |
108 | ||
109 | .. class:: SequenceFieldDeclaration | |
110 | :noindex: | |
111 | ||
112 | Sequence (dynamic array) field declaration. | |
113 | ||
114 | .. class:: StructureFieldDeclaration | |
115 | :noindex: | |
116 | ||
117 | Structure (ordered map of field names to field declarations) field | |
118 | declaration. | |
119 | ||
120 | .. class:: VariantFieldDeclaration | |
121 | :noindex: | |
122 | ||
123 | Variant (dynamic selection between different field declarations) | |
124 | field declaration. | |
125 | ||
126 | Once an event class is created, a concrete event may be created by | |
127 | instantiating an :class:`Event` object. Its :meth:`~Event.payload` | |
128 | method may be used to access the actual event's fields and set their | |
129 | values. Those fields are instances of the following types: | |
130 | ||
131 | .. class:: IntegerField | |
132 | :noindex: | |
133 | ||
134 | Integer field. | |
135 | ||
136 | .. class:: FloatingPointField | |
137 | :noindex: | |
138 | ||
139 | Floating point number field. | |
140 | ||
141 | .. class:: EnumerationField | |
142 | :noindex: | |
143 | ||
144 | Enumeration field (mapping from labels to ranges of integers). | |
145 | ||
146 | .. class:: StringField | |
147 | :noindex: | |
148 | ||
149 | String (NULL-terminated array of bytes) field. | |
150 | ||
151 | .. class:: ArrayField | |
152 | :noindex: | |
153 | ||
154 | Static array field. | |
155 | ||
156 | .. class:: SequenceField | |
157 | :noindex: | |
158 | ||
159 | Sequence (dynamic array) field. | |
160 | ||
161 | .. class:: StructureField | |
162 | :noindex: | |
163 | ||
164 | Structure (ordered map of field names to field declarations) field. | |
165 | ||
166 | .. class:: VariantField | |
167 | :noindex: | |
168 | ||
169 | Variant (dynamic selection between different field declarations) | |
170 | field. | |
171 | ||
172 | The subclass relationship for the CTF writer API is the following:: | |
173 | ||
174 | object | |
175 | FieldDeclaration | |
176 | IntegerFieldDeclaration | |
177 | FloatingPointFieldDeclaration | |
178 | EnumerationFieldDeclaration | |
179 | StringFieldDeclaration | |
180 | ArrayFieldDeclaration | |
181 | SequenceFieldDeclaration | |
182 | StructureFieldDeclaration | |
183 | VariantFieldDeclaration | |
184 | Field | |
185 | IntegerField | |
186 | FloatingPointField | |
187 | EnumerationField | |
188 | StringField | |
189 | ArrayField | |
190 | SequenceField | |
191 | StructureField | |
192 | VariantField | |
193 | EnumerationMapping | |
194 | EventClass | |
195 | Event | |
196 | Clock | |
197 | StreamClass | |
198 | Stream | |
199 | Writer | |
200 | ||
201 | Most of these classes' methods and properties raise :exc:`ValueError` | |
202 | on error. | |
203 | ||
204 | ||
205 | :class:`Writer` | |
206 | =============== | |
207 | ||
208 | .. autoclass:: Writer | |
209 | :members: | |
210 | ||
211 | .. automethod:: __init__ | |
212 | ||
213 | ||
214 | :class:`StreamClass` | |
215 | ==================== | |
216 | ||
217 | .. autoclass:: StreamClass | |
218 | :members: | |
219 | ||
220 | .. automethod:: __init__ | |
221 | ||
222 | ||
223 | :class:`Stream` | |
224 | =============== | |
225 | ||
226 | .. autoclass:: Stream | |
227 | :members: | |
228 | ||
229 | ||
230 | :class:`Clock` | |
231 | ============== | |
232 | ||
233 | .. autoclass:: Clock | |
234 | :members: | |
235 | ||
236 | .. automethod:: __init__ | |
237 | ||
238 | ||
239 | :class:`EventClass` | |
240 | =================== | |
241 | ||
242 | .. autoclass:: EventClass | |
243 | :members: | |
244 | ||
245 | .. automethod:: __init__ | |
246 | ||
247 | ||
248 | :class:`Event` | |
249 | ============== | |
250 | ||
251 | .. autoclass:: Event | |
252 | :members: | |
253 | ||
254 | .. automethod:: __init__ | |
255 | ||
256 | ||
257 | :class:`FieldDeclaration` | |
258 | ========================= | |
259 | ||
260 | .. autoclass:: FieldDeclaration | |
261 | :members: | |
262 | ||
263 | ||
264 | :class:`IntegerBase` | |
265 | ==================== | |
266 | ||
267 | .. autoclass:: IntegerBase | |
268 | :members: | |
269 | ||
270 | ||
271 | :class:`IntegerFieldDeclaration` | |
272 | ================================ | |
273 | ||
274 | .. autoclass:: IntegerFieldDeclaration | |
275 | :members: | |
276 | :show-inheritance: | |
277 | ||
278 | .. automethod:: __init__ | |
279 | ||
280 | ||
281 | :class:`FloatingPointFieldDeclaration` | |
282 | ====================================== | |
283 | ||
284 | .. autoclass:: FloatingPointFieldDeclaration | |
285 | :members: | |
286 | :show-inheritance: | |
287 | ||
288 | .. automethod:: __init__ | |
289 | ||
290 | ||
291 | :class:`EnumerationMapping` | |
292 | =========================== | |
293 | ||
294 | .. autoclass:: EnumerationMapping | |
295 | :members: | |
296 | ||
297 | .. automethod:: __init__ | |
298 | ||
299 | ||
300 | :class:`EnumerationFieldDeclaration` | |
301 | ==================================== | |
302 | ||
303 | .. autoclass:: EnumerationFieldDeclaration | |
304 | :members: | |
305 | :show-inheritance: | |
306 | ||
307 | .. automethod:: __init__ | |
308 | ||
309 | ||
310 | :class:`StringFieldDeclaration` | |
311 | =============================== | |
312 | ||
313 | .. autoclass:: StringFieldDeclaration | |
314 | :members: | |
315 | :show-inheritance: | |
316 | ||
317 | .. automethod:: __init__ | |
318 | ||
319 | ||
320 | :class:`ArrayFieldDeclaration` | |
321 | ============================== | |
322 | ||
323 | .. autoclass:: ArrayFieldDeclaration | |
324 | :members: | |
325 | :show-inheritance: | |
326 | ||
327 | .. automethod:: __init__ | |
328 | ||
329 | ||
330 | :class:`SequenceFieldDeclaration` | |
331 | ================================= | |
332 | ||
333 | .. autoclass:: SequenceFieldDeclaration | |
334 | :members: | |
335 | :show-inheritance: | |
336 | ||
337 | .. automethod:: __init__ | |
338 | ||
339 | ||
340 | :class:`StructureFieldDeclaration` | |
341 | ================================== | |
342 | ||
343 | .. autoclass:: StructureFieldDeclaration | |
344 | :members: | |
345 | :show-inheritance: | |
346 | ||
347 | .. automethod:: __init__ | |
348 | ||
349 | ||
350 | :class:`VariantFieldDeclaration` | |
351 | ================================ | |
352 | ||
353 | .. autoclass:: VariantFieldDeclaration | |
354 | :members: | |
355 | :show-inheritance: | |
356 | ||
357 | .. automethod:: __init__ | |
358 | ||
359 | ||
360 | :class:`Field` | |
361 | ============== | |
362 | ||
363 | .. autoclass:: Field | |
364 | :members: | |
365 | ||
366 | ||
367 | :class:`IntegerField` | |
368 | ===================== | |
369 | ||
370 | .. autoclass:: IntegerField | |
371 | :members: | |
372 | :show-inheritance: | |
373 | ||
374 | ||
375 | :class:`FloatingPointField` | |
376 | =========================== | |
377 | ||
378 | .. autoclass:: FloatingPointField | |
379 | :members: | |
380 | :show-inheritance: | |
381 | ||
382 | ||
383 | :class:`EnumerationField` | |
384 | ========================= | |
385 | ||
386 | .. autoclass:: EnumerationField | |
387 | :members: | |
388 | :show-inheritance: | |
389 | ||
390 | ||
391 | :class:`StringField` | |
392 | ==================== | |
393 | ||
394 | .. autoclass:: StringField | |
395 | :members: | |
396 | :show-inheritance: | |
397 | ||
398 | ||
399 | :class:`ArrayField` | |
400 | =================== | |
401 | ||
402 | .. autoclass:: ArrayField | |
403 | :members: | |
404 | :show-inheritance: | |
405 | ||
406 | ||
407 | :class:`SequenceField` | |
408 | ====================== | |
409 | ||
410 | .. autoclass:: SequenceField | |
411 | :members: | |
412 | :show-inheritance: | |
413 | ||
414 | ||
415 | :class:`StructureField` | |
416 | ======================= | |
417 | ||
418 | .. autoclass:: StructureField | |
419 | :members: | |
420 | :show-inheritance: | |
421 | ||
422 | ||
423 | :class:`VariantField` | |
424 | ===================== | |
425 | ||
426 | .. autoclass:: VariantField | |
427 | :members: | |
428 | :show-inheritance: |