| 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 What's this API for? |
| 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 component class: creates producers of trace |
| 27 | events. |
| 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. |
| 31 | |
| 32 | A program or library can instantiate as many concrete \em components as |
| 33 | needed from a single component class. At component instantiation time, |
| 34 | the component class's registered user initialization function is called |
| 35 | with custom user parameters. |
| 36 | |
| 37 | Plugins, as of Babeltrace \btversion, are built as dynamic libraries |
| 38 | (<code>.so</code> or <code>.dll</code> files) and loaded by the \c |
| 39 | babeltrace converter program. You can also get plugin objects from a |
| 40 | shared object file or from a directory containing shared object files |
| 41 | thanks to the C API. The converter program is responsible for passing |
| 42 | notifications and events from source components to filter components, if |
| 43 | any, and from filter components to sink components. |
| 44 | |
| 45 | @image html babeltrace-cli.png |
| 46 | |
| 47 | @section mainpagectfir CTF IR |
| 48 | |
| 49 | The internal representations of a trace, a stream, and an event follow |
| 50 | the <a href="http://diamon.org/ctf">Common Trace Format</a> model. |
| 51 | Within the Babeltrace C API, this representation is called the |
| 52 | <em>Common Trace Format Intermediate Representation</em>, or |
| 53 | \link ctfir CTF IR\endlink. CTF IR is flexible enough to represent |
| 54 | almost any trace or logging format. |
| 55 | |
| 56 | The CTF IR model contains the following objects, amongst others: |
| 57 | |
| 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 | |
| 94 | Some parts of the Babeltrace API require typical, generic scalar values |
| 95 | (boolean, integer, floating point number, string) organized in compound |
| 96 | objects (array, map). This is similar to the model that |
| 97 | <a href="http://json.org/">JSON</a> offers. |
| 98 | |
| 99 | For example, the environment of a |
| 100 | \link ctfirtraceclass CTF IR trace class\endlink maps strings to strings |
| 101 | or to integers, and the parameters passed to component instances take |
| 102 | the form of a map. |
| 103 | |
| 104 | For this purpose, the API uses |
| 105 | \link values value objects\endlink. |
| 106 | |
| 107 | @section mainpageref Reference counting |
| 108 | |
| 109 | All the <em>Babeltrace objects</em> have a |
| 110 | <a href="https://en.wikipedia.org/wiki/Reference_counting">reference count</a> |
| 111 | to make them shareable. |
| 112 | When you use a Babeltrace object creation function (for example, |
| 113 | bt_value_bool_create()), you get a new reference to the created |
| 114 | object. When you add this object to another one, the latter takes its |
| 115 | own reference using bt_get(), incrementing the shared object's reference |
| 116 | count. When you are done with an object, you must call bt_put() to drop |
| 117 | your reference, decrementing its reference count. When an object's |
| 118 | reference count reaches 0, the object is considered \em destroyed and |
| 119 | cannot be used anymore. |
| 120 | |
| 121 | See \ref refs for more details. |
| 122 | |
| 123 | The postconditions of the functions and macros documented here indicate |
| 124 | what you can expect from the reference counts of the Babeltrace objects |
| 125 | passed as parameters to and returned from API functions. |
| 126 | |
| 127 | @section mainpagefreeze Frozen objects |
| 128 | |
| 129 | The Babeltrace library can \em freeze almost all of the Babeltrace |
| 130 | objects. A frozen object is considered \em immutable, although you can |
| 131 | still get and put references to this object. |
| 132 | |
| 133 | The preconditions of the functions and macros documented here indicate |
| 134 | when they expect unfrozen objects. The postconditions indicate when |
| 135 | the functions and macros freeze an object. |
| 136 | */ |