doc/api/dox/main-page.dox

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