python: define _BaseObject._ptr property
[babeltrace.git] / doc / api / libbabeltrace2 / dox / group-trace-ir.dox
... / ...
CommitLineData
1/*!
2@defgroup api-tir Trace IR
3@ingroup api-msg
4
5@brief
6 Intermediate representation of
7 <a href="https://en.wikipedia.org/wiki/Tracing_(software)">tracing</a>
8 domain objects and concepts (contents of \bt_p_msg).
9
10The \bt_name
11<strong><em>trace IR</em></strong> (intermediate representation) modules
12contain everything you need to represent tracing domain concepts and
13objects so that many \bt_p_comp, written by different authors, can
14exchange trace metadata and data.
15
16The trace IR objects are divided into two main categories:
17
18<dl>
19 <dt>Metadata</dt>
20 <dd>
21 Classes of data objects.
22
23 A metadata object describes many data objects.
24
25 For example, an \bt_ev_cls describes the numeric ID, name, logging
26 level, and \ref api-tir-fc "classes" of payload \bt_p_field of all
27 the \bt_p_ev you create from it.
28
29 Metadata objects are one of the most valuable concepts of
30 \bt_name: because they describe the structures of many
31 data objects at once, they enable great space and time
32 optimizations.
33
34 For example, a \bt_sink_comp which writes a trace following a
35 metadata-supporting format, such as the
36 <a href="https://diamon.org/ctf/">Common Trace Format</a>, can
37 serialize the metadata objects once so that the data objects are
38 more compact and take less time to write.
39
40 The metadata objects are:
41
42 - \bt_c_clock_cls
43 - \bt_c_ev_cls
44 - \bt_cp_fc
45 - \bt_c_field_path
46 - \bt_c_stream_cls
47 - \bt_c_trace_cls
48 </dd>
49
50 <dt>Data</dt>
51 <dd>
52 Instances of metadata objects.
53
54 For example, a \bt_stream is an instance of a \bt_stream_cls.
55
56 The data objects are:
57
58 - \bt_c_cs
59 - \bt_c_ev
60 - \bt_cp_field
61 - \bt_c_pkt
62 - \bt_c_stream
63 - \bt_c_trace
64 </dd>
65</dl>
66
67The trace IR metadata to data object association is:
68
69<table>
70 <tr>
71 <th>Metadata object
72 <th>Data object
73 <tr>
74 <td>\bt_c_clock_cls
75 <td>Stream clock (see \ref api-tir-cs)
76 <tr>
77 <td>\bt_c_ev_cls
78 <td>\bt_c_ev
79 <tr>
80 <td>\bt_c_fc
81 <td>\bt_c_field
82 <tr>
83 <td>\bt_c_stream_cls
84 <td>\bt_c_stream
85 <tr>
86 <td>\bt_c_trace_cls
87 <td>\bt_c_trace
88</table>
89
90Within a trace processing \bt_graph, \bt_p_msg carry data objects from
91\bt_comp to component.
92
93You need to create metadata objects \em before you create data objects.
94You can then use the data objects to create messages.
95
96For example, you need a \bt_stream_cls to create a \bt_stream. With
97a \bt_stream, you can create a \bt_p_sb_msg, \bt_p_se_msg, \bt_p_ev_msg,
98and other types of messages.
99
100Usually, when you create a data object from a metadata object, the
101metadata object becomes \ref api-fund-freezing "frozen": you cannot
102modify it for the rest of its lifetime.
103
104All metadata objects and some data objects have an optional <em>user
105attributes</em> property (a \bt_map_val): you can use it to attach
106custom attributes, without any semantics specified by the \bt_name
107project, to those objects.
108*/
This page took 0.043809 seconds and 4 git commands to generate.