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