.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. -*/