\link btplugins plugins\endlink.
-@section intro Introduction
+@section intro What's this API for?
The goal of using this API is to create user
\link btplugins <em>plugins</em>\endlink.
A component class is either:
-- A \b source, or producer of trace events.
-- A \b sink, or consumer of trace events.
-- A \b filter, that is, both a producer and a consumer of trace
+- A \b source component class: creates producers of trace
events.
+- A \b sink component class: creates consumers of trace events.
+- A \b filter component class: creates components which are both a
+ producers and consumers of trace events.
-A program or library can instantiate a component class as many times as
-needed as concrete \em components. At component instantiation time, the
-constructor function receives custom parameters.
+A program or library can instantiate as many concrete \em components as
+needed from a single component class. At component instantiation time,
+the component class's registered user initialization function is called
+with custom user parameters.
Plugins, as of Babeltrace \btversion, are built as dynamic libraries
(<code>.so</code> or <code>.dll</code> files) and loaded by the \c
-babeltrace converter program. 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.
+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 <a href="http://diamon.org/ctf">Common Trace Format</a> model.
Within the Babeltrace C API, this representation is called the
<em>Common Trace Format Intermediate Representation</em>, or
-\link ctfir CTF IR\endlink.
+\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:
-<ul>
-<li>
-A \link ctfirfieldtypes field type\endlink is a template for creating
-a concrete \link ctfirfields field\endlink.
-<p>
-For example, an integer field type contains the size (in bits) of the
-integer fields it describes, as well as their byte order, whether or not
-they are signed, and so on. An integer field created out of an integer
-field type, however, only contains a raw integer value. You can create
-many fields from a single field type template.
-
-<li>
-An \link ctfireventclass event class\endlink is a template for
-creating a concrete \link ctfirevent event\endlink.
-<p>
-An event class contains the field types of its various scopes, while an
-event contains the actual fields holding their values.
-
-<li>
-A \link ctfirstreamclass stream class\endlink is a template for
-creating a concrete \link ctfirstream stream\endlink.
-<p>
-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. <p> A stream class is the parent of one or
-more event classes.
-
-<li>
-A \link ctfirtraceclass trace class\endlink describes traces.
-<p>
-A trace class is the parent of one or more stream classes.
-
-<li>
-A \link ctfirclockclass clock class\endlink holds the common properties
-of clock values that are instantiated in \link ctfirevent events\endlink.
-</ul>
-
-Some parts of the API require typical scalar value objects (boolean,
-integer, floating point number, string) and compound value objects
-(array, map). For example, the environment of a
+- 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. <p> 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
+<a href="http://json.org/">JSON</a> 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
+the form of a map.
+
+For this purpose, the API uses
\link values value objects\endlink.
+@section mainpageref Reference counting
+
All the <em>Babeltrace objects</em> have a
<a href="https://en.wikipedia.org/wiki/Reference_counting">reference count</a>
to make them shareable.
-When you create a Babeltrace object, its reference count is
-initialized to 1: you are its sole owner. 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.
+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 of the reference counts of the Babeltrace objects
-passed as parameters and returned.
+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
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.
-
-Have a look at \ref quickstart to learn more about the available
-modules of the Babeltrace C API.
*/
projects / babeltrace.git / commitdiff
