Fix: src.ctf.lttng-live: emitting stream end msg with no stream

[babeltrace.git] / doc / api / dox / main-page.dox

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