+++ /dev/null
-/**
-@mainpage Welcome!
-
-Welcome to the
-<strong><em>Babeltrace \btversion C API</em></strong> documentation!
-
-<a href="http://diamon.org/babeltrace">Babeltrace</a> is an open
-source converter of
-<a href="https://en.wikipedia.org/wiki/Tracing_(software)">trace</a>
-formats. You can use its C API to
-write custom source, sink, and filter
-\link btcomponents component classes\endlink which you can package as user
-\link btplugins plugins\endlink.
-
-
-@section intro What's this API for?
-
-The goal of using this API is to create user
-\link btplugins <em>plugins</em>\endlink.
-
-A Babeltrace plugin contains one or more
-\link btcomponents <em>component classes</em>\endlink.
-
-A component class is either:
-
-- 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 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. 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. 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. <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
-\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 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.
-*/
projects / babeltrace.git / blobdiff