+++ /dev/null
-.. _ctf-writer-api:
-
-**************
-CTF writer API
-**************
-
-.. currentmodule:: babeltrace.writer
-
-The **CTF writer API** allows to write native
-`CTF <http://www.efficios.com/ctf>`_ traces from a Python environment.
-
-A CTF trace is made of one or more CTF streams. Streams contain
-packets, which in turn contain serialized events. CTF readers, such as
-Babeltrace, are able to merge streams and iterate on events in order
-when reading a CTF trace.
-
-The CTF writer API is exposed as a set of classes available in the
-:mod:`babeltrace.writer` module.
-
-.. seealso::
-
- :ref:`ctf-writer-api-examples`
-
-There is a clear distinction to be made between field declaration
-and field objects. A field declaration describes the properties, or
-metadata, of a field. It does not contain a value. For example,
-an integer *field declaration* contains a size in bits, a byte order,
-a display base, whether it's signed or not, and so on. On the other
-hand, an integer *field* is linked with a specific integer field
-declaration, but contains an actual integer value. Thus, the layout and
-properties of fields are described once in field declarations, and then
-all concrete fields carry a value and a field declaration reference.
-The same applies to event classes vs. events, as well as to stream
-classes vs. streams.
-
-The main interface to write a CTF trace is the :class:`Writer` class:
-
-.. class:: Writer
- :noindex:
-
- Writing object in which clocks and streams may be registered, and
- other common trace properties may be set.
-
-A concrete :class:`Stream` object may be created from a
-:class:`StreamClass` using :meth:`Writer.create_stream` method. A
-stream class is also associated with a clock (:class:`Clock`), which
-must also be registered to the writer object.
-
-.. class:: StreamClass
- :noindex:
-
- Stream class.
-
-.. class:: Stream
- :noindex:
-
- Stream, based on a stream class.
-
-.. class:: Clock
- :noindex:
-
- Reference clock of one to many streams.
-
-Events, before being created, must be described in an event class
-(:class:`EventClass`). An event class must be added to a stream class
-using :meth:`StreamClass.add_event_class` before appending an event
-to an actual stream linked with this stream class.
-
-.. class:: EventClass
- :noindex:
-
- Event class.
-
-.. class:: Event
- :noindex:
-
- Event, based on an event class.
-
-An event class is created by instantiating an :class:`EventClass`
-object and using its :meth:`~EventClass.add_field` method to add an
-instance of one of the following field declarations:
-
-.. class:: IntegerFieldDeclaration
- :noindex:
-
- Integer field declaration.
-
-.. class:: FloatingPointFieldDeclaration
- :noindex:
-
- Floating point number field declaration.
-
-.. class:: EnumerationFieldDeclaration
- :noindex:
-
- Enumeration field declaration (mapping from labels to ranges of
- integers).
-
-.. class:: StringFieldDeclaration
- :noindex:
-
- String (NULL-terminated array of bytes) field declaration.
-
-.. class:: ArrayFieldDeclaration
- :noindex:
-
- Static array field declaration.
-
-.. class:: SequenceFieldDeclaration
- :noindex:
-
- Sequence (dynamic array) field declaration.
-
-.. class:: StructureFieldDeclaration
- :noindex:
-
- Structure (ordered map of field names to field declarations) field
- declaration.
-
-.. class:: VariantFieldDeclaration
- :noindex:
-
- Variant (dynamic selection between different field declarations)
- field declaration.
-
-Once an event class is created, a concrete event may be created by
-instantiating an :class:`Event` object. Its :meth:`~Event.payload`
-method may be used to access the actual event's fields and set their
-values. Those fields are instances of the following types:
-
-.. class:: IntegerField
- :noindex:
-
- Integer field.
-
-.. class:: FloatingPointField
- :noindex:
-
- Floating point number field.
-
-.. class:: EnumerationField
- :noindex:
-
- Enumeration field (mapping from labels to ranges of integers).
-
-.. class:: StringField
- :noindex:
-
- String (NULL-terminated array of bytes) field.
-
-.. class:: ArrayField
- :noindex:
-
- Static array field.
-
-.. class:: SequenceField
- :noindex:
-
- Sequence (dynamic array) field.
-
-.. class:: StructureField
- :noindex:
-
- Structure (ordered map of field names to field declarations) field.
-
-.. class:: VariantField
- :noindex:
-
- Variant (dynamic selection between different field declarations)
- field.
-
-The subclass relationship for the CTF writer API is the following::
-
- object
- FieldDeclaration
- IntegerFieldDeclaration
- FloatingPointFieldDeclaration
- EnumerationFieldDeclaration
- StringFieldDeclaration
- ArrayFieldDeclaration
- SequenceFieldDeclaration
- StructureFieldDeclaration
- VariantFieldDeclaration
- Field
- IntegerField
- FloatingPointField
- EnumerationField
- StringField
- ArrayField
- SequenceField
- StructureField
- VariantField
- EnumerationMapping
- EventClass
- Event
- Clock
- StreamClass
- Stream
- Writer
-
-Most of these classes' methods and properties raise :exc:`ValueError`
-on error.
-
-
-:class:`Writer`
-===============
-
-.. autoclass:: Writer
- :members:
-
- .. automethod:: __init__
-
-
-:class:`StreamClass`
-====================
-
-.. autoclass:: StreamClass
- :members:
-
- .. automethod:: __init__
-
-
-:class:`Stream`
-===============
-
-.. autoclass:: Stream
- :members:
-
-
-:class:`Clock`
-==============
-
-.. autoclass:: Clock
- :members:
-
- .. automethod:: __init__
-
-
-:class:`EventClass`
-===================
-
-.. autoclass:: EventClass
- :members:
-
- .. automethod:: __init__
-
-
-:class:`Event`
-==============
-
-.. autoclass:: Event
- :members:
-
- .. automethod:: __init__
-
-
-:class:`FieldDeclaration`
-=========================
-
-.. autoclass:: FieldDeclaration
- :members:
-
-
-:class:`IntegerBase`
-====================
-
-.. autoclass:: IntegerBase
- :members:
-
-
-:class:`IntegerFieldDeclaration`
-================================
-
-.. autoclass:: IntegerFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`FloatingPointFieldDeclaration`
-======================================
-
-.. autoclass:: FloatingPointFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`EnumerationMapping`
-===========================
-
-.. autoclass:: EnumerationMapping
- :members:
-
- .. automethod:: __init__
-
-
-:class:`EnumerationFieldDeclaration`
-====================================
-
-.. autoclass:: EnumerationFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`StringFieldDeclaration`
-===============================
-
-.. autoclass:: StringFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`ArrayFieldDeclaration`
-==============================
-
-.. autoclass:: ArrayFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`SequenceFieldDeclaration`
-=================================
-
-.. autoclass:: SequenceFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`StructureFieldDeclaration`
-==================================
-
-.. autoclass:: StructureFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`VariantFieldDeclaration`
-================================
-
-.. autoclass:: VariantFieldDeclaration
- :members:
- :show-inheritance:
-
- .. automethod:: __init__
-
-
-:class:`Field`
-==============
-
-.. autoclass:: Field
- :members:
-
-
-:class:`IntegerField`
-=====================
-
-.. autoclass:: IntegerField
- :members:
- :show-inheritance:
-
-
-:class:`FloatingPointField`
-===========================
-
-.. autoclass:: FloatingPointField
- :members:
- :show-inheritance:
-
-
-:class:`EnumerationField`
-=========================
-
-.. autoclass:: EnumerationField
- :members:
- :show-inheritance:
-
-
-:class:`StringField`
-====================
-
-.. autoclass:: StringField
- :members:
- :show-inheritance:
-
-
-:class:`ArrayField`
-===================
-
-.. autoclass:: ArrayField
- :members:
- :show-inheritance:
-
-
-:class:`SequenceField`
-======================
-
-.. autoclass:: SequenceField
- :members:
- :show-inheritance:
-
-
-:class:`StructureField`
-=======================
-
-.. autoclass:: StructureField
- :members:
- :show-inheritance:
-
-
-:class:`VariantField`
-=====================
-
-.. autoclass:: VariantField
- :members:
- :show-inheritance:
projects / babeltrace.git / blobdiff