Fix: src.ctf.lttng-live: emitting stream end msg with no stream
[babeltrace.git] / doc / api / dox / main-page.dox
CommitLineData
d1dab1d2
PP
1/**
2@mainpage Welcome!
3
4Welcome to the
5<strong><em>Babeltrace \btversion C API</em></strong> documentation!
6
7<a href="http://diamon.org/babeltrace">Babeltrace</a> is an open
8source converter of
9<a href="https://en.wikipedia.org/wiki/Tracing_(software)">trace</a>
10formats. You can use its C API to
11write custom source, sink, and filter
12\link btcomponents component classes\endlink which you can package as user
13\link btplugins plugins\endlink.
14
15
69b04703 16@section intro What's this API for?
d1dab1d2
PP
17
18The goal of using this API is to create user
19\link btplugins <em>plugins</em>\endlink.
20
21A Babeltrace plugin contains one or more
22\link btcomponents <em>component classes</em>\endlink.
23
24A component class is either:
25
69b04703 26- A \b source component class: creates producers of trace
d1dab1d2 27 events.
69b04703
PP
28- A \b sink component class: creates consumers of trace events.
29- A \b filter component class: creates components which are both a
30 producers and consumers of trace events.
d1dab1d2 31
69b04703
PP
32A program or library can instantiate as many concrete \em components as
33needed from a single component class. At component instantiation time,
34the component class's registered user initialization function is called
35with custom user parameters.
d1dab1d2
PP
36
37Plugins, as of Babeltrace \btversion, are built as dynamic libraries
38(<code>.so</code> or <code>.dll</code> files) and loaded by the \c
69b04703
PP
39babeltrace converter program. You can also get plugin objects from a
40shared object file or from a directory containing shared object files
41thanks to the C API. The converter program is responsible for passing
42notifications and events from source components to filter components, if
43any, and from filter components to sink components.
44
45@image html babeltrace-cli.png
46
47@section mainpagectfir CTF IR
d1dab1d2
PP
48
49The internal representations of a trace, a stream, and an event follow
50the <a href="http://diamon.org/ctf">Common Trace Format</a> model.
51Within the Babeltrace C API, this representation is called the
52<em>Common Trace Format Intermediate Representation</em>, or
69b04703
PP
53\link ctfir CTF IR\endlink. CTF IR is flexible enough to represent
54almost any trace or logging format.
d1dab1d2
PP
55
56The CTF IR model contains the following objects, amongst others:
57
69b04703
PP
58- A \link ctfirfieldtypes field type\endlink is the type of concrete
59 \link ctfirfields fields\endlink.
60
61 For example, an integer field type contains the size (in bits) of the
62 integer fields it creates, as well as their byte order, whether or not
63 they are signed, and so on. An integer field that you create out of an
64 integer field type, however, only contains a raw integral value. You
65 can create many fields from a single field type.
66
67- An \link ctfireventclass event class\endlink is the type of
68 a concrete \link ctfirevent event\endlink.
69
70 An event class contains the field types of its various scopes, while
71 an event contains the actual fields holding their values.
72
73- A \link ctfirstreamclass stream class\endlink is the type of
74 a concrete \link ctfirstream stream\endlink.
75
76 A stream class contains the field types of its various scopes, while
77 \link ctfirpacket packets\endlink attached to a
78 \link ctfirstream stream\endlink instantiated from a
79 stream class contains the actual
80 fields holding their values. <p> A stream class is the parent of one or
81 more event classes.
82
83
84- A \link ctfirtraceclass trace class\endlink describes traces.
85
86 A trace class is the parent of one or more stream classes.
87
88- A \link ctfirclockclass clock class\endlink holds the common
89 properties of clock values that are instantiated in \link ctfirevent
90 events\endlink.
91
92@section mainpagevalues Value objects
93
94Some parts of the Babeltrace API require typical, generic scalar values
95(boolean, integer, floating point number, string) organized in compound
96objects (array, map). This is similar to the model that
97<a href="http://json.org/">JSON</a> offers.
98
99For example, the environment of a
d1dab1d2
PP
100\link ctfirtraceclass CTF IR trace class\endlink maps strings to strings
101or to integers, and the parameters passed to component instances take
69b04703
PP
102the form of a map.
103
104For this purpose, the API uses
d1dab1d2
PP
105\link values value objects\endlink.
106
69b04703
PP
107@section mainpageref Reference counting
108
d1dab1d2
PP
109All the <em>Babeltrace objects</em> have a
110<a href="https://en.wikipedia.org/wiki/Reference_counting">reference count</a>
111to make them shareable.
69b04703
PP
112When you use a Babeltrace object creation function (for example,
113bt_value_bool_create()), you get a new reference to the created
114object. When you add this object to another one, the latter takes its
115own reference using bt_get(), incrementing the shared object's reference
116count. When you are done with an object, you must call bt_put() to drop
117your reference, decrementing its reference count. When an object's
118reference count reaches 0, the object is considered \em destroyed and
119cannot be used anymore.
120
121See \ref refs for more details.
d1dab1d2
PP
122
123The postconditions of the functions and macros documented here indicate
69b04703
PP
124what you can expect from the reference counts of the Babeltrace objects
125passed as parameters to and returned from API functions.
126
127@section mainpagefreeze Frozen objects
d1dab1d2
PP
128
129The Babeltrace library can \em freeze almost all of the Babeltrace
130objects. A frozen object is considered \em immutable, although you can
131still get and put references to this object.
132
133The preconditions of the functions and macros documented here indicate
134when they expect unfrozen objects. The postconditions indicate when
135the functions and macros freeze an object.
d1dab1d2 136*/
This page took 0.054886 seconds and 4 git commands to generate.