class StreamClass:
+ """
+ A stream class contains the properties of specific
+ streams (:class:`Stream`). Any concrete stream must be linked with
+ a :class:`StreamClass`, usually by calling
+ :meth:`Writer.create_stream`.
+
+ Some attributes are automatically set when creating a stream class.
+ For example, if no clock is explicitly set using the
+ :attr:`clock` attribute, a default clock will be created
+ when needed.
+ """
+
def __init__(self, name):
"""
- Create a new stream class of the given name.
+ Creates a stream class named *name*.
+
+ :exc:`ValueError` is raised on error.
"""
self._sc = nbt._bt_ctf_stream_class_create(name)
@property
def name(self):
"""
- Get a stream class' name.
+ Stream class' name.
+
+ :exc:`TypeError` is raised on error.
"""
name = nbt._bt_ctf_stream_class_get_name(self._sc)
@property
def clock(self):
"""
- Get a stream class' clock.
+ Stream class' clock (:class:`Clock` object).
+
+ Set this attribute to change the clock of this stream class.
+
+ :exc:`ValueError` is raised on error.
"""
clock_instance = nbt._bt_ctf_stream_class_get_clock(self._sc)
@clock.setter
def clock(self, clock):
- """
- Assign a clock to a stream class.
- """
-
if not isinstance(clock, Clock):
raise TypeError("Invalid clock type.")
@property
def id(self):
"""
- Get a stream class' id.
+ Stream class' numeric ID.
+
+ Set this attribute to change the ID of this stream class.
+
+ :exc:`ValueError` is raised on error.
"""
ret = nbt._bt_ctf_stream_class_get_id(self._sc)
@id.setter
def id(self, id):
- """
- Assign an id to a stream class.
- """
-
ret = nbt._bt_ctf_stream_class_set_id(self._sc, id)
if ret < 0:
@property
def event_classes(self):
"""
- Generator returning the stream class' event classes.
+ Generates the event classes (:class:`EventClass` objects) of
+ this stream class.
+
+ :exc:`TypeError` is raised on error.
"""
count = nbt._bt_ctf_stream_class_get_event_class_count(self._sc)
def add_event_class(self, event_class):
"""
- Add an event class to a stream class. New events can be added even after a
- stream has been instantiated and events have been appended. However, a stream
- will not accept events of a class that has not been added to the stream
- class beforehand.
+ Registers the :class:`EventClass` *event_class* to this stream
+ class.
+
+ Once the event class is registered, it will be generated as one
+ of the event classes generated by :attr:`event_classes`.
+
+ :exc:`ValueError` is raised on error.
"""
if not isinstance(event_class, EventClass):
@property
def packet_context_type(self):
"""
- Get the StreamClass' packet context type (StructureFieldDeclaration)
+ Stream packet context declaration.
+
+ Set this attribute to change the stream packet context
+ declaration (must be an instance of
+ :class:`StructureFieldDeclaration`).
+
+ :exc:`ValueError` is raised on error.
+
"""
field_type_native = nbt._bt_ctf_stream_class_get_packet_context_type(self._sc)
@packet_context_type.setter
def packet_context_type(self, field_type):
- """
- Set a StreamClass' packet context type. Must be of type
- StructureFieldDeclaration.
- """
-
if not isinstance(field_type, StructureFieldDeclaration):
raise TypeError("field_type argument must be of type StructureFieldDeclaration.")
class Stream:
+ """
+ Streams are specific instances of stream classes, which means they
+ may contain actual, concrete events.
+
+ :class:`Stream` objects are returned by
+ :meth:`Writer.create_stream`; they are not meant to be
+ instantiated by the user.
+
+ Concrete :class:`Event` objects are appended to
+ :class:`Stream` objects using :meth:`append_event`.
+
+ When :meth:`flush` is called, a CTF packet is created, containing
+ all the appended events since the last flush. Although the stream
+ is flushed on object destruction, it is **strongly recommended**
+ that the user call :meth:`flush` manually before exiting the
+ script, as :meth:`__del__` is not always reliable.
+ """
+
def __init__(self):
raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()")
@property
def discarded_events(self):
"""
- Get a stream's discarded event count.
+ Number of discarded (lost) events in this stream so far.
+
+ :exc:`ValueError` is raised on error.
"""
ret, count = nbt._bt_ctf_stream_get_discarded_events_count(self._s)
if ret < 0:
- raise ValueError("Could not get the stream's discarded events count")
+ raise ValueError("Could not get the stream discarded events count")
return count
def append_discarded_events(self, event_count):
"""
- Increase the current packet's discarded event count.
+ Appends *event_count* discarded events to this stream.
"""
nbt._bt_ctf_stream_append_discarded_events(self._s, event_count)
def append_event(self, event):
"""
- Append "event" to the stream's current packet. The stream's associated clock
- will be sampled during this call. The event shall not be modified after
- being appended to a stream.
+ Appends event *event* (:class:`Event` object) to this stream.
+
+ The stream's associated clock will be sampled during this call.
+ *event* **shall not** be modified after being appended to this
+ stream.
+
+ :exc:`ValueError` is raised on error.
"""
ret = nbt._bt_ctf_stream_append_event(self._s, event._e)
@property
def packet_context(self):
"""
- Get a Stream's packet context field (a StructureField).
+ Stream packet context field (instance of
+ :class:`StructureField`).
+
+ Set this attribute to assign a stream packet context field
+ to this stream.
+
+ :exc:`ValueError` is raised on error.
"""
native_field = nbt._bt_ctf_stream_get_packet_context(self._s)
@packet_context.setter
def packet_context(self, field):
- """
- Set a Stream's packet context field (must be a StructureField).
- """
-
if not isinstance(field, StructureField):
raise TypeError("Argument field must be of type StructureField")
def flush(self):
"""
- The stream's current packet's events will be flushed to disk. Events
- subsequently appended to the stream will be added to a new packet.
+ Flushes the current packet of this stream to disk. Events
+ subsequently appended to the stream will be added to a new
+ packet.
+
+ :exc:`ValueError` is raised on error.
"""
ret = nbt._bt_ctf_stream_flush(self._s)
class Writer:
+ """
+ This object is the CTF writer API context. It oversees its streams
+ and clocks, and is responsible for writing one CTF trace.
+ """
+
def __init__(self, path):
"""
- Create a new writer that will produce a trace in the given path.
+ Creates a CTF writer, initializing a new CTF trace at path
+ *path*.
+
+ *path* must be an existing directory, since a CTF trace is
+ made of multiple files.
+
+ :exc:`ValueError` is raised if the creation fails.
"""
self._w = nbt._bt_ctf_writer_create(path)
def create_stream(self, stream_class):
"""
- Create a new stream instance and register it to the writer.
+ Creates and registers a new stream based on stream class
+ *stream_class*.
+
+ This is the standard way of creating a :class:`Stream` object:
+ the user is not allowed to instantiate this class.
+
+ Returns a new :class:`Stream` object.
"""
if not isinstance(stream_class, StreamClass):
def add_environment_field(self, name, value):
"""
- Add an environment field to the trace.
+ Sets the CTF environment variable named *name* to value *value*
+ (converted to a string).
+
+ :exc:`ValueError` is raised on error.
"""
ret = nbt._bt_ctf_writer_add_environment_field(self._w, str(name),
def add_clock(self, clock):
"""
- Add a clock to the trace. Clocks assigned to stream classes must be
- registered to the writer.
+ Registers :class:`Clock` object *clock* to the writer.
+
+ You *must* register CTF clocks assigned to stream classes
+ to the writer.
+
+ :exc:`ValueError` is raised if the creation fails.
"""
ret = nbt._bt_ctf_writer_add_clock(self._w, clock._c)
@property
def metadata(self):
"""
- Get the trace's TSDL meta-data.
+ Current metadata of this trace (:class:`str`).
"""
return nbt._bt_ctf_writer_get_metadata_string(self._w)
def flush_metadata(self):
"""
- Flush the trace's metadata to the metadata file.
+ Flushes the trace's metadata to the metadata file.
"""
nbt._bt_ctf_writer_flush_metadata(self._w)
@property
def byte_order(self):
"""
- Get the trace's byte order. Must be a constant from the ByteOrder
- class.
+ Native byte order of this trace (one of
+ :class:`babeltrace.common.ByteOrder` constants).
+
+ This is the actual byte order that is used when a field
+ declaration has the
+ :attr:`babeltrace.common.ByteOrder.BYTE_ORDER_NATIVE`
+ value.
+
+ Set this attribute to change the trace's native byte order.
+
+ Defaults to the host machine's endianness.
+
+ :exc:`ValueError` is raised on error.
"""
raise NotImplementedError("Getter not implemented.")
@byte_order.setter
def byte_order(self, byte_order):
- """
- Set the trace's byte order. Must be a constant from the ByteOrder
- class. Defaults to the host machine's endianness
- """
-
ret = nbt._bt_ctf_writer_set_byte_order(self._w, byte_order)
if ret < 0:
- raise ValueError("Could not set trace's byte order.")
+ raise ValueError("Could not set trace byte order.")
projects / babeltrace.git / blobdiff