class TraceCollection:
"""
- The TraceCollection is the object that contains all currently opened traces.
+ A :class:`TraceCollection` is a collection of opened traces.
+
+ In general, once a trace collection is created, you add one to many
+ independent traces to it using :meth:`add_trace` or
+ :meth:`add_traces_recursive`, and then iterate the ordered events
+ of all traces merged together using :attr:`events`.
+
+ You may use :meth:`remove_trace` to close and remove a specific
+ trace from a trace collection, although all the traces of a given
+ trace collection will be automatically removed when it is garbage
+ collected.
"""
def __init__(self):
+ """
+ Creates an empty trace collection.
+ """
+
self._tc = nbt._bt_context_create()
def __del__(self):
def add_trace(self, path, format_str):
"""
- Add a trace by path to the TraceCollection.
+ Adds a trace to the trace collection.
- Open a trace.
+ The trace is located at the file system path *path*. This
+ function **does not** recurse directories to find the trace:
+ *path* must point to the exact trace location (see
+ :meth:`add_traces_recursive` for a recursive version of this
+ function).
- path is the path to the trace, it is not recursive.
- If "path" is None, stream_list is used instead as a list
- of mmap streams to open for the trace.
+ *format_str* is a string indicating the Babeltrace type of the
+ trace to add. ``ctf`` is the only currently supported trace
+ format.
- format is a string containing the format name in which the trace was
- produced.
+ Once added, the trace is opened.
- Return: the corresponding TraceHandle on success or None on error.
+ Returns the corresponding :class:`TraceHandle` instance for
+ this opened trace on success, or ``None`` on error.
"""
ret = nbt._bt_context_add_trace(self._tc, path, format_str,
def add_traces_recursive(self, path, format_str):
"""
- Open a trace recursively.
+ Adds traces to this trace collection by recursively searching
+ in the *path* directory.
- Find each trace present in the subdirectory starting from the given
- path, and add them to the TraceCollection.
+ *format_str* is a string indicating the Babeltrace type of the
+ traces to find and add. ``ctf`` is the only currently supported
+ trace format.
- Return a dict of TraceHandle instances (the full path is the key).
- Return None on error.
+ See also :meth:`add_trace`.
+
+ Returns a :class:`dict` object mapping full paths to trace
+ handles for each trace found, or ``None`` on error.
"""
trace_handles = {}
def remove_trace(self, trace_handle):
"""
- Remove a trace from the TraceCollection.
- Effectively closing the trace.
+ Removes a trace from the trace collection using its trace
+ handle *trace_handle*.
+
+ :class:`TraceHandle` objects are returned by :meth:`add_trace`
+ and :meth:`add_traces_recursive`.
+
+ The trace is closed before being removed.
"""
try:
@property
def events(self):
"""
- Generator function to iterate over the events of open in the current
- TraceCollection.
+ Generates the ordered :class:`Event` objects of all the opened
+ traces contained in this trace collection. Iterate this function
+ to iterate actual events.
Due to limitations of the native Babeltrace API, only one event
- may be "alive" at a time (i.e. a user should never store a copy
- of the events returned by this function for ulterior use). Users
- shall make sure to copy the information they need from an event
- before accessing the next one.
+ may be "alive" at a given time, i.e. a user **should never**
+ store a copy of the events returned by this function for
+ ulterior use. Users shall make sure to copy the information
+ they need *from* an event before accessing the next one.
- Furthermore, event objects become invalid when the generator goes
- out of scope as the underlying iterator will be reclaimed. Using an
- event after the the generator has gone out of scope may result in a
- crash or data corruption.
+ Furthermore, :class:`Event` objects become invalid when the
+ generator goes out of scope as the underlying iterator will be
+ reclaimed. Using an event after the the generator has gone out
+ of scope may result in a crash or data corruption.
"""
begin_pos_ptr = nbt._bt_iter_pos()
def events_timestamps(self, timestamp_begin, timestamp_end):
"""
- Generator function to iterate over the events of open in the current
- TraceCollection from timestamp_begin to timestamp_end.
+ Generates the ordered :class:`Event` objects of all the opened
+ traces contained in this trace collection from *timestamp_begin*
+ to *timestamp_end*.
+
+ See :attr:`events` for notes and limitations.
"""
begin_pos_ptr = nbt._bt_iter_pos()
@property
def timestamp_begin(self):
+ """
+ Trace collection's begin timestamp.
+ """
+
pos_ptr = nbt._bt_iter_pos()
pos_ptr.type = nbt.SEEK_BEGIN
@property
def timestamp_end(self):
+ """
+ Trace collection's end timestamp.
+ """
+
pos_ptr = nbt._bt_iter_pos()
pos_ptr.type = nbt.SEEK_LAST
nbt._bt_ctf_iter_destroy(ctf_it_ptr)
-def print_format_list(babeltrace_file):
- """
- Print a list of available formats to file.
-
- babeltrace_file must be a File instance opened in write mode.
- """
-
- try:
- if babeltrace_file._file is not None:
- nbt._bt_print_format_list(babeltrace_file._file)
- except AttributeError:
- raise TypeError("in print_format_list, argument 1 must be a File instance")
-
-
# Based on enum bt_clock_type in clock-type.h
-class ClockType:
+class _ClockType:
CLOCK_CYCLES = 0
CLOCK_REAL = 1
class TraceHandle:
"""
- The TraceHandle allows the user to manipulate a trace file directly.
- It is a unique identifier representing a trace file.
- Do not instantiate.
+ A :class:`TraceHandle` is a handle allowing the user to manipulate
+ a specific trace directly. It is a unique identifier representing a
+ trace, and is not meant to be instantiated by the user.
"""
def __init__(self):
@property
def id(self):
- """Return the TraceHandle id."""
+ """
+ Trace handle's numeric ID.
+ """
return self._id
@property
def path(self):
- """Return the path of a TraceHandle."""
+ """
+ Path of the underlying trace.
+ """
return nbt._bt_trace_handle_get_path(self._trace_collection._tc,
self._id)
@property
def timestamp_begin(self):
- """Return the creation time of the buffers of a trace."""
+ """
+ Buffers creation timestamp (nanoseconds since Epoch) of the
+ underlying trace.
+ """
return nbt._bt_trace_handle_get_timestamp_begin(self._trace_collection._tc,
self._id,
- ClockType.CLOCK_REAL)
+ _ClockType.CLOCK_REAL)
@property
def timestamp_end(self):
- """Return the destruction timestamp of the buffers of a trace."""
+ """
+ Buffers destruction timestamp (nanoseconds since Epoch) of the
+ underlying trace.
+ """
return nbt._bt_trace_handle_get_timestamp_end(self._trace_collection._tc,
self._id,
- ClockType.CLOCK_REAL)
+ _ClockType.CLOCK_REAL)
@property
def events(self):
"""
- Generator returning all events (EventDeclaration) in a trace.
+ Generates all the :class:`EventDeclaration` objects of the
+ underlying trace.
+
+ Note that this doesn't generate actual trace *events*, but
+ rather their declarations, i.e. their layouts and metadata.
"""
ret = nbt._bt_python_event_decl_listcaller(self.id,
class CTFStringEncoding:
+ """
+ CTF string encodings.
+ """
+
+ #: None
NONE = 0
+
+ #: UTF-8
UTF8 = 1
+
+ #: ASCII
ASCII = 2
+
+ #: Unknown
UNKNOWN = 3
# Based on the enum in ctf-writer/writer.h
class ByteOrder:
+ """
+ Byte orders.
+ """
+
+ #: Native byte order
BYTE_ORDER_NATIVE = 0
+
+ #: Little-endian
BYTE_ORDER_LITTLE_ENDIAN = 1
+
+ #: Big-endian
BYTE_ORDER_BIG_ENDIAN = 2
+
+ #: Network byte order (big-endian)
BYTE_ORDER_NETWORK = 3
+
+ #: Unknown byte order
BYTE_ORDER_UNKNOWN = 4 # Python-specific entry
# These are taken directly from ctf/events.h
# All changes to enums must also be made here
class CTFTypeId:
+ """
+ CTF numeric type identifiers.
+ """
+
+ #: Unknown type
UNKNOWN = 0
+
+ #: Integer
INTEGER = 1
+
+ #: Floating point number
FLOAT = 2
+
+ #: Enumeration
ENUM = 3
+
+ #: String
STRING = 4
+
+ #: Structure
STRUCT = 5
+
+ #: Untagged variant
UNTAGGED_VARIANT = 6
+
+ #: Variant
VARIANT = 7
+
+ #: Array
ARRAY = 8
+
+ #: Sequence
SEQUENCE = 9
+
NR_CTF_TYPES = 10
def type_name(id):
+ """
+ Returns the name of the CTF numeric type identifier *id*.
+ """
+
name = "UNKNOWN_TYPE"
constants = [
attr for attr in dir(CTFTypeId) if not callable(
class CTFScope:
+ """
+ CTF scopes.
+ """
+
+ #: Packet header
TRACE_PACKET_HEADER = 0
+
+ #: Packet context
STREAM_PACKET_CONTEXT = 1
+
+ #: Event header
STREAM_EVENT_HEADER = 2
+
+ #: Stream event context
STREAM_EVENT_CONTEXT = 3
+
+ #: Event context
EVENT_CONTEXT = 4
+
+ #: Event fields
EVENT_FIELDS = 5
def scope_name(scope):
+ """
+ Returns the name of the CTF scope *scope*.
+ """
+
name = "UNKNOWN_SCOPE"
constants = [
attr for attr in dir(CTFScope) if not callable(
class Event(collections.Mapping):
"""
- This class represents an event from the trace.
- It is obtained using the TraceCollection generator functions.
- Do not instantiate.
+ An :class:`Event` object represents a trace event. :class:`Event`
+ objects are returned by :attr:`TraceCollection.events` and are
+ not meant to be instantiated by the user.
+
+ :class:`Event` has a :class:`dict`-like interface for accessing
+ an event's field value by field name:
+
+ .. code-block:: python
+
+ event['my_field']
+
+ If a field name exists in multiple scopes, the value of the first
+ field found is returned. The scopes are searched in the following
+ order:
+
+ 1. Event fields (:attr:`CTFScope.EVENT_FIELDS`)
+ 2. Event context (:attr:`CTFScope.EVENT_CONTEXT`)
+ 3. Stream event context (:attr:`CTFScope.STREAM_EVENT_CONTEXT`)
+ 4. Event header (:attr:`CTFScope.STREAM_EVENT_HEADER`)
+ 5. Packet context (:attr:`CTFScope.STREAM_PACKET_CONTEXT`)
+ 6. Packet header (:attr:`CTFScope.TRACE_PACKET_HEADER`)
+
+ It is still possible to obtain a field's value from a specific
+ scope using :meth:`field_with_scope`.
+
+ Field values are returned as native Python types, that is:
+
+ +-----------------------+----------------------------------+
+ | Field type | Python type |
+ +=======================+==================================+
+ | Integer | :class:`int` |
+ +-----------------------+----------------------------------+
+ | Floating point number | :class:`float` |
+ +-----------------------+----------------------------------+
+ | Enumeration | :class:`str` (enumeration label) |
+ +-----------------------+----------------------------------+
+ | String | :class:`str` |
+ +-----------------------+----------------------------------+
+ | Array | :class:`list` of native Python |
+ | | objects |
+ +-----------------------+----------------------------------+
+ | Sequence | :class:`list` of native Python |
+ | | objects |
+ +-----------------------+----------------------------------+
+ | Structure | :class:`dict` mapping field |
+ | | names to native Python objects |
+ +-----------------------+----------------------------------+
+
+ For example, printing the third element of a sequence named ``seq``
+ in a structure named ``my_struct`` of the ``event``'s field named
+ ``my_field`` is done this way:
+
+ .. code-block:: python
+
+ print(event['my_field']['my_struct']['seq'][2])
"""
def __init__(self):
@property
def name(self):
- """Return the name of the event or None on error."""
+ """
+ Event's name or ``None`` on error.
+ """
return nbt._bt_ctf_event_name(self._e)
@property
def cycles(self):
"""
- Return the timestamp of the event as written in
- the packet (in cycles) or -1ULL on error.
+ Event's timestamp in cycles or -1 on error.
"""
return nbt._bt_ctf_get_cycles(self._e)
@property
def timestamp(self):
"""
- Return the timestamp of the event offset with the
- system clock source or -1ULL on error.
+ Event's timestamp (nanoseconds since Epoch) or -1 on error.
"""
return nbt._bt_ctf_get_timestamp(self._e)
@property
def datetime(self):
"""
- Return a datetime object based on the event's
- timestamp. Note that the datetime class' precision
- is limited to microseconds.
+ Event's timestamp as a standard :class:`datetime.datetime`
+ object.
+
+ Note that the :class:`datetime.datetime` class' precision
+ is limited to microseconds, whereas :attr:`timestamp` provides
+ the event's timestamp with a nanosecond resolution.
"""
return datetime.fromtimestamp(self.timestamp / 1E9)
def field_with_scope(self, field_name, scope):
"""
- Get field_name's value in scope.
- None is returned if no field matches field_name.
+ Returns the value of a field named *field_name* within the
+ scope *scope*, or ``None`` if the field cannot be found.
+
+ *scope* must be one of :class:`CTFScope` constants.
"""
if scope not in _scopes:
return field.value
def field_list_with_scope(self, scope):
- """Return a list of field names in scope."""
+ """
+ Returns a list of field names in the scope *scope*.
+ """
if scope not in _scopes:
raise ValueError("Invalid scope provided")
@property
def handle(self):
"""
- Get the TraceHandle associated with this event
- Return None on error
+ :class:`TraceHandle` object containing this event, or ``None``
+ on error.
"""
ret = nbt._bt_ctf_event_get_handle_id(self._e)
@property
def trace_collection(self):
"""
- Get the TraceCollection associated with this event.
- Return None on error.
+ :class:`TraceCollection` object containing this event, or
+ ``None`` on error.
"""
trace_collection = TraceCollection()
return trace_collection
def __getitem__(self, field_name):
- """
- Get field_name's value. If the field_name exists in multiple
- scopes, the first field found is returned. The scopes are searched
- in the following order:
- 1) EVENT_FIELDS
- 2) EVENT_CONTEXT
- 3) STREAM_EVENT_CONTEXT
- 4) STREAM_EVENT_HEADER
- 5) STREAM_PACKET_CONTEXT
- 6) TRACE_PACKET_HEADER
- None is returned if no field matches field_name.
-
- Use field_with_scope() to explicitly access fields in a given
- scope.
- """
-
field = self._field(field_name)
if field is not None:
return self._field(field_name) is not None
def keys(self):
- """Return a list of field names."""
+ """
+ Returns the list of field names.
+
+ Note: field names are unique within the returned list, although
+ a field name could exist in multiple scopes. Use
+ :meth:`field_list_with_scope` to obtain the list of field names
+ of a given scope.
+ """
field_names = set()
return list(field_names)
def get(self, field_name, default=None):
+ """
+ Returns the value of the field named *field_name*, or *default*
+ when not found.
+
+ See :class:`Event` note about how fields are retrieved by
+ name when multiple fields share the same name in different
+ scopes.
+ """
+
field = self._field(field_name)
if field is None:
return field.value
def items(self):
+ """
+ Generates pairs of (field name, field value).
+
+ This method iterates :meth:`keys` to find field names, which
+ means some fields could be unavailable if other fields share
+ their names in scopes with higher priorities.
+ """
+
for field in self.keys():
yield (field, self[field])
class FieldError(Exception):
+ """
+ Field error, raised when a field's value cannot be accessed.
+ """
+
def __init__(self, value):
self.value = value
class EventDeclaration:
- """Event declaration class. Do not instantiate."""
+ """
+ An event declaration contains the properties of a class of events,
+ that is, the common properties and fields layout of all the actual
+ recorded events associated with this declaration.
+
+ This class is not meant to be instantiated by the user. It is
+ returned by :attr:`TraceHandle.events`.
+ """
MAX_UINT64 = 0xFFFFFFFFFFFFFFFF
@property
def name(self):
- """Return the name of the event or None on error"""
+ """
+ Event's name, or ``None`` on error.
+ """
return nbt._bt_ctf_get_decl_event_name(self._ed)
@property
def id(self):
- """Return the event-ID of the event or -1 on error"""
+ """
+ Event's numeric ID, or -1 on error.
+ """
id = nbt._bt_ctf_get_decl_event_id(self._ed)
@property
def fields(self):
"""
- Generator returning all FieldDeclarations of an event, going through
+ Generates all the event's field declarations, going through
each scope in the following order:
- 1) EVENT_FIELDS
- 2) EVENT_CONTEXT
- 3) STREAM_EVENT_CONTEXT
- 4) STREAM_EVENT_HEADER
- 5) STREAM_PACKET_CONTEXT
- 6) TRACE_PACKET_HEADER
+
+ 1. Event fields (:attr:`CTFScope.EVENT_FIELDS`)
+ 2. Event context (:attr:`CTFScope.EVENT_CONTEXT`)
+ 3. Stream event context (:attr:`CTFScope.STREAM_EVENT_CONTEXT`)
+ 4. Event header (:attr:`CTFScope.STREAM_EVENT_HEADER`)
+ 5. Packet context (:attr:`CTFScope.STREAM_PACKET_CONTEXT`)
+ 6. Packet header (:attr:`CTFScope.TRACE_PACKET_HEADER`)
+
+ All the generated field declarations inherit
+ :class:`FieldDeclaration`, and are among:
+
+ * :class:`IntegerFieldDeclaration`
+ * :class:`FloatFieldDeclaration`
+ * :class:`EnumerationFieldDeclaration`
+ * :class:`StringFieldDeclaration`
+ * :class:`ArrayFieldDeclaration`
+ * :class:`SequenceFieldDeclaration`
+ * :class:`StructureFieldDeclaration`
+ * :class:`VariantFieldDeclaration`
"""
for scope in _scopes:
def fields_scope(self, scope):
"""
- Generator returning FieldDeclarations of the current event in scope.
+ Generates all the field declarations of the event's scope
+ *scope*.
+
+ *scope* must be one of :class:`CTFScope` constants.
+
+ All the generated field declarations inherit
+ :class:`FieldDeclaration`, and are among:
+
+ * :class:`IntegerFieldDeclaration`
+ * :class:`FloatFieldDeclaration`
+ * :class:`EnumerationFieldDeclaration`
+ * :class:`StringFieldDeclaration`
+ * :class:`ArrayFieldDeclaration`
+ * :class:`SequenceFieldDeclaration`
+ * :class:`StructureFieldDeclaration`
+ * :class:`VariantFieldDeclaration`
"""
ret = nbt._by_python_field_decl_listcaller(self._ed, scope)
class FieldDeclaration:
- """Field declaration class. Do not instantiate."""
+ """
+ Base class for concrete field declarations.
+
+ This class is not meant to be instantiated by the user.
+ """
def __init__(self):
raise NotImplementedError("FieldDeclaration cannot be instantiated")
@property
def name(self):
- """Return the name of a FieldDeclaration or None on error."""
+ """
+ Field's name, or ``None`` on error.
+ """
return self._name
@property
def type(self):
"""
- Return the FieldDeclaration's type. One of the entries in class
- CTFTypeId.
+ Field's type (one of :class:`CTFTypeId` constants).
"""
return nbt._bt_ctf_field_type(self._fd)
@property
def scope(self):
"""
- Return the FieldDeclaration's scope.
+ Field's scope (one of :class:`CTFScope` constants).
"""
return self._s
class EnumerationFieldDeclaration(FieldDeclaration):
- """Do not instantiate."""
+ """
+ Enumeration field declaration.
+
+ .. note::
+
+ As of this version, this class is missing some properties.
+ """
def __init__(self):
raise NotImplementedError("EnumerationFieldDeclaration cannot be instantiated")
class ArrayFieldDeclaration(FieldDeclaration):
- """Do not instantiate."""
+ """
+ Static array field declaration.
+ """
def __init__(self):
raise NotImplementedError("ArrayFieldDeclaration cannot be instantiated")
@property
def length(self):
"""
- Return the length of an array or a negative
- value on error.
+ Static array's fixed length (number of contained elements), or
+ a negative value on error.
"""
return nbt._bt_ctf_get_array_len(self._fd)
@property
def element_declaration(self):
"""
- Return element declaration.
+ Underlying element's field declaration.
"""
field_decl_ptr = nbt._bt_python_get_array_element_declaration(self._fd)
class SequenceFieldDeclaration(FieldDeclaration):
- """Do not instantiate."""
+ """
+ Sequence (dynamic array) field declaration.
+
+ .. note::
+
+ As of this version, this class is missing some properties.
+ """
def __init__(self):
raise NotImplementedError("SequenceFieldDeclaration cannot be instantiated")
@property
def element_declaration(self):
"""
- Return element declaration.
+ Underlying element's field declaration.
"""
field_decl_ptr = nbt._bt_python_get_sequence_element_declaration(self._fd)
class FloatFieldDeclaration(FieldDeclaration):
- """Do not instantiate."""
+ """
+ Floating point number field declaration.
+
+ .. note::
+
+ As of this version, this class is missing some properties.
+ """
def __init__(self):
raise NotImplementedError("FloatFieldDeclaration cannot be instantiated")
class StructureFieldDeclaration(FieldDeclaration):
- """Do not instantiate."""
+ """
+ Structure (ordered map of field names to field declarations) field
+ declaration.
+
+ .. note::
+
+ As of this version, this class is missing some properties.
+ """
def __init__(self):
raise NotImplementedError("StructureFieldDeclaration cannot be instantiated")
class StringFieldDeclaration(FieldDeclaration):
- """Do not instantiate."""
+ """
+ String (NULL-terminated array of bytes) field declaration.
+
+ .. note::
+
+ As of this version, this class is missing some properties.
+ """
def __init__(self):
raise NotImplementedError("StringFieldDeclaration cannot be instantiated")
class VariantFieldDeclaration(FieldDeclaration):
- """Do not instantiate."""
+ """
+ Variant (dynamic selection between different types) field declaration.
+
+ .. note::
+
+ As of this version, this class is missing some properties.
+ """
def __init__(self):
raise NotImplementedError("VariantFieldDeclaration cannot be instantiated")
if ret < 0:
raise ValueError("Could not set mantissa digit count.")
+ class FloatingPointFieldDeclaration(FloatFieldDeclaration):
+ pass
+
class StructureFieldDeclaration(FieldDeclaration):
def __init__(self):
"""
elif isinstance(field_type, CTFWriter.EnumerationFieldDeclaration):
return CTFWriter.EnumerationField(field_type)
elif isinstance(field_type, CTFWriter.FloatFieldDeclaration):
- return CTFWriter.FloatFieldingPoint(field_type)
+ return CTFWriter.FloatingPointField(field_type)
elif isinstance(field_type, CTFWriter.StructureFieldDeclaration):
return CTFWriter.StructureField(field_type)
elif isinstance(field_type, CTFWriter.VariantFieldDeclaration):
def _create_field_from_native_instance(native_field_instance):
type_dict = {
CTFTypeId.INTEGER: CTFWriter.IntegerField,
- CTFTypeId.FLOAT: CTFWriter.FloatFieldingPoint,
+ CTFTypeId.FLOAT: CTFWriter.FloatingPointField,
CTFTypeId.ENUM: CTFWriter.EnumerationField,
CTFTypeId.STRING: CTFWriter.StringField,
CTFTypeId.STRUCT: CTFWriter.StructureField,
self.container.value = value
- class FloatFieldingPoint(Field):
+ class FloatingPointField(Field):
@property
def value(self):
"""
if ret < 0:
raise ValueError("Could not set floating point field value.")
+ # oops!! This class is provided to ensure backward-compatibility since
+ # a stable release publicly exposed this abomination.
+ class FloatFieldingPoint(FloatingPointField):
+ pass
+
class StructureField(Field):
def field(self, field_name):
"""
raise ValueError("Failed to set packet context type.")
class Stream:
- def __init__(self, stream_class):
- """
- Create a stream of the given class.
- """
-
- if not isinstance(stream_class, CTFWriter.StreamClass):
- raise TypeError("Invalid stream_class argument must be of type StreamClass.")
-
- self._s = nbt._bt_ctf_stream_create(stream_class._sc)
-
- if self._s is None:
- raise ValueError("Stream creation failed.")
+ def __init__(self):
+ raise NotImplementedError("Stream cannot be instantiated; use Writer.create_stream()")
def __del__(self):
nbt._bt_ctf_stream_put(self._s)
projects / babeltrace.git / blobdiff