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