Commit | Line | Data |
---|---|---|
16ca5ff0 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
16ca5ff0 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
16ca5ff0 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_CTF_WRITER_VISITOR_H |
8 | #define BABELTRACE2_CTF_WRITER_VISITOR_H | |
9 | ||
16ca5ff0 PP |
10 | #ifdef __cplusplus |
11 | extern "C" { | |
12 | #endif | |
13 | ||
14 | /** | |
15 | @defgroup ctfirvisitor CTF IR visitor | |
16 | @ingroup ctfir | |
17 | @brief CTF IR visitor. | |
18 | ||
19 | @code | |
3fadfbc0 | 20 | #include <babeltrace2/trace-ir/visitor.h> |
16ca5ff0 PP |
21 | @endcode |
22 | ||
23 | A CTF IR <strong><em>visitor</em></strong> is a function that you | |
24 | can use to visit the hierarchy of a | |
25 | \link ctfirtraceclass CTF IR trace class\endlink with | |
26 | bt_ctf_trace_visit() or of a | |
27 | \link ctfirstreamclass CTF IR stream class\endlink with | |
28 | bt_ctf_stream_class_visit(). | |
29 | ||
30 | The traversal of the object's hierarchy is always done in a | |
31 | pre-order fashion. | |
32 | ||
33 | @sa ctfirstreamclass | |
34 | @sa ctfirtraceclass | |
35 | ||
36 | @file | |
37 | @brief CTF IR visitor types and functions. | |
38 | @sa ctfirvisitor | |
39 | ||
40 | @addtogroup ctfirvisitor | |
41 | @{ | |
42 | */ | |
43 | ||
44 | /** | |
e1e02a22 | 45 | @struct bt_ctf_object |
16ca5ff0 PP |
46 | @brief A CTF IR object wrapper. |
47 | ||
48 | This structure wraps both a CTF IR object and its type | |
e1e02a22 | 49 | (see #bt_ctf_object_type). It is used in the visiting function. |
16ca5ff0 | 50 | |
e1e02a22 PP |
51 | You can use the bt_ctf_object_get_type() and |
52 | bt_ctf_object_get_object() accessors to get the type and wrapped | |
16ca5ff0 PP |
53 | CTF IR object of a CTF IR object wrapper. |
54 | ||
55 | A CTF IR object wrapper has <strong>no reference count</strong>: do \em | |
e1e02a22 | 56 | not use bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it. |
16ca5ff0 PP |
57 | |
58 | @sa ctfirvisitor | |
59 | */ | |
60 | struct bt_ctf_visitor_object; | |
61 | ||
62 | /** | |
63 | @brief CTF IR object wrapper type. | |
64 | */ | |
65 | enum bt_ctf_visitor_object_type { | |
66 | /// Unknown (used for errors). | |
67 | BT_CTF_VISITOR_OBJECT_TYPE_UNKNOWN = -1, | |
68 | ||
69 | /// \ref ctfirtraceclass. | |
70 | BT_CTF_VISITOR_OBJECT_TYPE_TRACE = 0, | |
71 | ||
72 | /// \ref ctfirstreamclass. | |
73 | BT_CTF_VISITOR_OBJECT_TYPE_STREAM_CLASS = 1, | |
74 | ||
75 | /// \ref ctfirstream. | |
76 | BT_CTF_VISITOR_OBJECT_TYPE_STREAM = 2, | |
77 | ||
78 | /// \ref ctfireventclass. | |
79 | BT_CTF_VISITOR_OBJECT_TYPE_EVENT_CLASS = 3, | |
80 | ||
81 | /// \ref ctfirevent. | |
82 | BT_CTF_VISITOR_OBJECT_TYPE_EVENT = 4, | |
83 | ||
84 | /// Number of entries in this enumeration. | |
85 | BT_CTF_VISITOR_OBJECT_TYPE_NR, | |
86 | }; | |
87 | ||
88 | /** | |
89 | @brief Visting function type. | |
90 | ||
91 | A function of this type is called by bt_ctf_trace_visit() or | |
92 | bt_ctf_stream_class_visit() when visiting the CTF IR object wrapper | |
93 | \p object. | |
94 | ||
95 | \p object has <strong>no reference count</strong>: do \em not use | |
e1e02a22 | 96 | bt_ctf_object_put_ref() or bt_ctf_object_get_ref() on it. |
16ca5ff0 PP |
97 | |
98 | @param[in] object Currently visited CTF IR object wrapper. | |
99 | @param[in] data User data. | |
100 | @returns 0 on success, or a negative value on error. | |
101 | ||
102 | @prenotnull{object} | |
103 | ||
104 | @sa bt_ctf_trace_visit(): Accepts a visitor to visit a trace class. | |
105 | @sa bt_ctf_stream_class_visit(): Accepts a visitor to visit a stream | |
106 | class. | |
107 | */ | |
108 | typedef int (*bt_ctf_visitor)(struct bt_ctf_visitor_object *object, | |
109 | void *data); | |
110 | ||
111 | /** | |
112 | @brief Returns the type of the CTF IR object wrapped by the CTF IR | |
113 | object wrapper \p object. | |
114 | ||
115 | @param[in] object Object wrapper of which to get the type. | |
116 | @returns Type of \p object. | |
117 | ||
118 | @prenotnull{object} | |
119 | ||
120 | @sa bt_ctf_visitor_object_get_object(): Returns the object wrapped by a given | |
121 | CTF IR object wrapper. | |
122 | */ | |
123 | enum bt_ctf_visitor_object_type bt_ctf_visitor_object_get_type( | |
124 | struct bt_ctf_visitor_object *object); | |
125 | ||
126 | /** | |
127 | @brief Returns the CTF IR object wrapped by the CTF IR object | |
128 | wrapper \p object. | |
129 | ||
130 | The reference count of \p object is \em not incremented by this | |
e1e02a22 | 131 | function. On success, you must call bt_ctf_object_get_ref() on the return value to |
16ca5ff0 PP |
132 | have your own reference. |
133 | ||
134 | @param[in] object Object wrapper of which to get the wrapped | |
135 | CTF IR object. | |
136 | @returns CTF IR object wrapped by \p object. | |
137 | ||
138 | @prenotnull{object} | |
139 | @post The reference count of the returned object is not modified. | |
140 | ||
141 | @sa bt_ctf_visitor_object_get_type(): Returns the type of a given | |
142 | CTF IR object wrapper. | |
143 | */ | |
144 | void *bt_ctf_visitor_object_get_object(struct bt_ctf_visitor_object *object); | |
145 | ||
146 | /** @} */ | |
147 | ||
148 | #ifdef __cplusplus | |
149 | } | |
150 | #endif | |
151 | ||
924dc299 | 152 | #endif /* BABELTRACE2_CTF_WRITER_VISITOR_H */ |