doc/bindings/python/source/writer.rst

   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: