Commit | Line | Data |
---|---|---|
d1dab1d2 PP |
1 | /** |
2 | @mainpage Welcome! | |
3 | ||
4 | Welcome 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 | |
8 | source converter of | |
9 | <a href="https://en.wikipedia.org/wiki/Tracing_(software)">trace</a> | |
10 | formats. You can use its C API to | |
11 | write custom source, sink, and filter | |
12 | \link btcomponents component classes\endlink which you can package as user | |
13 | \link btplugins plugins\endlink. | |
14 | ||
15 | ||
16 | @section intro Introduction | |
17 | ||
18 | The goal of using this API is to create user | |
19 | \link btplugins <em>plugins</em>\endlink. | |
20 | ||
21 | A Babeltrace plugin contains one or more | |
22 | \link btcomponents <em>component classes</em>\endlink. | |
23 | ||
24 | A component class is either: | |
25 | ||
26 | - A \b source, or producer of trace events. | |
27 | - A \b sink, or consumer of trace events. | |
28 | - A \b filter, that is, both a producer and a consumer of trace | |
29 | events. | |
30 | ||
31 | A program or library can instantiate a component class as many times as | |
32 | needed as concrete \em components. At component instantiation time, the | |
33 | constructor function receives custom parameters. | |
34 | ||
35 | Plugins, as of Babeltrace \btversion, are built as dynamic libraries | |
36 | (<code>.so</code> or <code>.dll</code> files) and loaded by the \c | |
37 | babeltrace converter program. The converter program is responsible for | |
38 | passing notifications and events from source components to filter | |
39 | components, if any, and from filter components to sink components. | |
40 | ||
41 | The internal representations of a trace, a stream, and an event follow | |
42 | the <a href="http://diamon.org/ctf">Common Trace Format</a> model. | |
43 | Within the Babeltrace C API, this representation is called the | |
44 | <em>Common Trace Format Intermediate Representation</em>, or | |
45 | \link ctfir CTF IR\endlink. | |
46 | ||
47 | The CTF IR model contains the following objects, amongst others: | |
48 | ||
49 | <ul> | |
50 | <li> | |
51 | A \link ctfirfieldtypes field type\endlink is a template for creating | |
52 | a concrete \link ctfirfields field\endlink. | |
53 | <p> | |
54 | For example, an integer field type contains the size (in bits) of the | |
55 | integer fields it describes, as well as their byte order, whether or not | |
56 | they are signed, and so on. An integer field created out of an integer | |
57 | field type, however, only contains a raw integer value. You can create | |
58 | many fields from a single field type template. | |
59 | ||
60 | <li> | |
61 | An \link ctfireventclass event class\endlink is a template for | |
62 | creating a concrete \link ctfirevent event\endlink. | |
63 | <p> | |
64 | An event class contains the field types of its various scopes, while an | |
65 | event contains the actual fields holding their values. | |
66 | ||
67 | <li> | |
68 | A \link ctfirstreamclass stream class\endlink is a template for | |
69 | creating a concrete \link ctfirstream stream\endlink. | |
70 | <p> | |
71 | A stream class contains the field types of its various scopes, while | |
72 | \link ctfirpacket packets\endlink attached to a | |
73 | \link ctfirstream stream\endlink instantiated from a | |
74 | stream class contains the actual | |
75 | fields holding their values. <p> A stream class is the parent of one or | |
76 | more event classes. | |
77 | ||
78 | <li> | |
79 | A \link ctfirtraceclass trace class\endlink describes traces. | |
80 | <p> | |
81 | A trace class is the parent of one or more stream classes. | |
82 | ||
83 | <li> | |
84 | A \link ctfirclockclass clock class\endlink holds the common properties | |
85 | of clock values that are instantiated in \link ctfirevent events\endlink. | |
86 | </ul> | |
87 | ||
88 | Some parts of the API require typical scalar value objects (boolean, | |
89 | integer, floating point number, string) and compound value objects | |
90 | (array, map). For example, the environment of a | |
91 | \link ctfirtraceclass CTF IR trace class\endlink maps strings to strings | |
92 | or to integers, and the parameters passed to component instances take | |
93 | the form of a map. For this purpose, the API uses | |
94 | \link values value objects\endlink. | |
95 | ||
96 | All the <em>Babeltrace objects</em> have a | |
97 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference count</a> | |
98 | to make them shareable. | |
99 | When you create a Babeltrace object, its reference count is | |
100 | initialized to 1: you are its sole owner. When you add this object to | |
101 | another one, the latter takes its own reference using bt_get(), | |
102 | incrementing the shared object's reference count. When you are done | |
103 | with an object, you must call bt_put() to drop your reference, | |
104 | decrementing its reference count. When an object's reference count | |
105 | reaches 0, the object is considered \em destroyed and cannot be | |
106 | used anymore. See \ref refs for more details. | |
107 | ||
108 | The postconditions of the functions and macros documented here indicate | |
109 | what you can expect of the reference counts of the Babeltrace objects | |
110 | passed as parameters and returned. | |
111 | ||
112 | The Babeltrace library can \em freeze almost all of the Babeltrace | |
113 | objects. A frozen object is considered \em immutable, although you can | |
114 | still get and put references to this object. | |
115 | ||
116 | The preconditions of the functions and macros documented here indicate | |
117 | when they expect unfrozen objects. The postconditions indicate when | |
118 | the functions and macros freeze an object. | |
119 | ||
120 | Have a look at \ref quickstart to learn more about the available | |
121 | modules of the Babeltrace C API. | |
122 | */ |