.so or .dll files) and loaded by the \c
babeltrace converter program. You can also get plugin objects from a
shared object file or from a directory containing shared object files
thanks to the C API. The converter program is responsible for passing
notifications and events from source components to filter components, if
any, and from filter components to sink components.
@image html babeltrace-cli.png
@section mainpagectfir CTF IR
The internal representations of a trace, a stream, and an event follow
the Common Trace Format model.
Within the Babeltrace C API, this representation is called the
Common Trace Format Intermediate Representation, or
\link ctfir CTF IR\endlink. CTF IR is flexible enough to represent
almost any trace or logging format.
The CTF IR model contains the following objects, amongst others:
- A \link ctfirfieldtypes field type\endlink is the type of concrete
\link ctfirfields fields\endlink.
For example, an integer field type contains the size (in bits) of the
integer fields it creates, as well as their byte order, whether or not
they are signed, and so on. An integer field that you create out of an
integer field type, however, only contains a raw integral value. You
can create many fields from a single field type.
- An \link ctfireventclass event class\endlink is the type of
a concrete \link ctfirevent event\endlink.
An event class contains the field types of its various scopes, while
an event contains the actual fields holding their values.
- A \link ctfirstreamclass stream class\endlink is the type of
a concrete \link ctfirstream stream\endlink.
A stream class contains the field types of its various scopes, while
\link ctfirpacket packets\endlink attached to a
\link ctfirstream stream\endlink instantiated from a
stream class contains the actual
fields holding their values. A stream class is the parent of one or more event classes. - A \link ctfirtraceclass trace class\endlink describes traces. A trace class is the parent of one or more stream classes. - A \link ctfirclockclass clock class\endlink holds the common properties of clock values that are instantiated in \link ctfirevent events\endlink. @section mainpagevalues Value objects Some parts of the Babeltrace API require typical, generic scalar values (boolean, integer, floating point number, string) organized in compound objects (array, map). This is similar to the model that JSON offers. For example, the environment of a \link ctfirtraceclass CTF IR trace class\endlink maps strings to strings or to integers, and the parameters passed to component instances take the form of a map. For this purpose, the API uses \link values value objects\endlink. @section mainpageref Reference counting All the Babeltrace objects have a reference count to make them shareable. When you use a Babeltrace object creation function (for example, bt_value_bool_create()), you get a new reference to the created object. When you add this object to another one, the latter takes its own reference using bt_get(), incrementing the shared object's reference count. When you are done with an object, you must call bt_put() to drop your reference, decrementing its reference count. When an object's reference count reaches 0, the object is considered \em destroyed and cannot be used anymore. See \ref refs for more details. The postconditions of the functions and macros documented here indicate what you can expect from the reference counts of the Babeltrace objects passed as parameters to and returned from API functions. @section mainpagefreeze Frozen objects The Babeltrace library can \em freeze almost all of the Babeltrace objects. A frozen object is considered \em immutable, although you can still get and put references to this object. The preconditions of the functions and macros documented here indicate when they expect unfrozen objects. The postconditions indicate when the functions and macros freeze an object. */