2 @defgroup api-tir Trace IR
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).
11 <strong><em>trace IR</em></strong> (intermediate representation) modules
12 contain everything you need to represent tracing domain concepts and
13 objects so that many \bt_p_comp, written by different authors, can
14 exchange trace metadata and data.
16 The trace IR objects are divided into two main categories:
21 Classes of data objects.
23 A metadata object describes many data objects.
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.
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
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.
40 The metadata objects are:
52 Instances of metadata objects.
54 For example, a \bt_stream is an instance of a \bt_stream_cls.
67 The trace IR metadata to data object association is:
75 <td>Stream clock (see \ref api-tir-cs)
90 Within a trace processing \bt_graph, \bt_p_msg carry data objects from
91 \bt_comp to component.
93 You need to create metadata objects \em before you create data objects.
94 You can then use the data objects to create messages.
96 For example, you need a \bt_stream_cls to create a \bt_stream. With
97 a \bt_stream, you can create a \bt_p_sb_msg, \bt_p_se_msg, \bt_p_ev_msg,
98 and other types of messages.
100 Usually, when you create a data object from a metadata object, the
101 metadata object becomes \ref api-fund-freezing "frozen": you cannot
102 modify it for the rest of its lifetime.
104 All metadata objects and some data objects have an optional <em>user
105 attributes</em> property (a \bt_map_val): you can use it to attach
106 custom attributes, without any semantics specified by the \bt_name
107 project, to those objects.