Commit | Line | Data |
---|---|---|
8bf65fbd JG |
1 | #ifndef BABELTRACE_CTF_IR_VISITOR_H |
2 | #define BABELTRACE_CTF_IR_VISITOR_H | |
3 | ||
4 | /* | |
5 | * BabelTrace - CTF IR: Visitor | |
6 | * | |
7 | * Copyright 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
8 | * | |
9 | * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com> | |
10 | * | |
11 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
12 | * of this software and associated documentation files (the "Software"), to deal | |
13 | * in the Software without restriction, including without limitation the rights | |
14 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
15 | * copies of the Software, and to permit persons to whom the Software is | |
16 | * furnished to do so, subject to the following conditions: | |
17 | * | |
18 | * The above copyright notice and this permission notice shall be included in | |
19 | * all copies or substantial portions of the Software. | |
20 | * | |
21 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
22 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
23 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
24 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
25 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
26 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
27 | * SOFTWARE. | |
28 | * | |
29 | * The Common Trace Format (CTF) Specification is available at | |
30 | * http://www.efficios.com/ctf | |
31 | */ | |
32 | ||
33 | #ifdef __cplusplus | |
34 | extern "C" { | |
35 | #endif | |
36 | ||
304b3717 PP |
37 | /** |
38 | @defgroup ctfirvisitor CTF IR visitor | |
39 | @ingroup ctfir | |
40 | @brief CTF IR visitor. | |
41 | ||
6dd2bd0c PP |
42 | @code |
43 | #include <babeltrace/ctf-ir/visitor.h> | |
44 | @endcode | |
45 | ||
304b3717 PP |
46 | A CTF IR <strong><em>visitor</em></strong> is a function that you |
47 | can use to visit the hierarchy of a | |
48 | \link ctfirtraceclass CTF IR trace class\endlink with | |
50842bdc | 49 | bt_trace_visit() or of a |
304b3717 | 50 | \link ctfirstreamclass CTF IR stream class\endlink with |
50842bdc | 51 | bt_stream_class_visit(). |
304b3717 PP |
52 | |
53 | The traversal of the object's hierarchy is always done in a | |
54 | pre-order fashion. | |
55 | ||
56 | @sa ctfirstreamclass | |
57 | @sa ctfirtraceclass | |
58 | ||
59 | @file | |
60 | @brief CTF IR visitor types and functions. | |
61 | @sa ctfirvisitor | |
62 | ||
63 | @addtogroup ctfirvisitor | |
64 | @{ | |
65 | */ | |
66 | ||
67 | /** | |
50842bdc | 68 | @struct bt_object |
304b3717 PP |
69 | @brief A CTF IR object wrapper. |
70 | ||
71 | This structure wraps both a CTF IR object and its type | |
50842bdc | 72 | (see #bt_object_type). It is used in the visiting function. |
304b3717 | 73 | |
50842bdc PP |
74 | You can use the bt_object_get_type() and |
75 | bt_object_get_object() accessors to get the type and wrapped | |
304b3717 PP |
76 | CTF IR object of a CTF IR object wrapper. |
77 | ||
78 | A CTF IR object wrapper has <strong>no reference count</strong>: do \em | |
79 | not use bt_put() or bt_get() on it. | |
80 | ||
81 | @sa ctfirvisitor | |
82 | */ | |
50842bdc | 83 | struct bt_visitor_object; |
8bf65fbd | 84 | |
304b3717 PP |
85 | /** |
86 | @brief CTF IR object wrapper type. | |
87 | */ | |
50842bdc | 88 | enum bt_visitor_object_type { |
304b3717 | 89 | /// Unknown (used for errors). |
50842bdc | 90 | BT_VISITOR_OBJECT_TYPE_UNKNOWN = -1, |
304b3717 PP |
91 | |
92 | /// \ref ctfirtraceclass. | |
50842bdc | 93 | BT_VISITOR_OBJECT_TYPE_TRACE = 0, |
304b3717 PP |
94 | |
95 | /// \ref ctfirstreamclass. | |
50842bdc | 96 | BT_VISITOR_OBJECT_TYPE_STREAM_CLASS = 1, |
304b3717 PP |
97 | |
98 | /// \ref ctfirstream. | |
50842bdc | 99 | BT_VISITOR_OBJECT_TYPE_STREAM = 2, |
304b3717 PP |
100 | |
101 | /// \ref ctfireventclass. | |
50842bdc | 102 | BT_VISITOR_OBJECT_TYPE_EVENT_CLASS = 3, |
304b3717 PP |
103 | |
104 | /// \ref ctfirevent. | |
50842bdc | 105 | BT_VISITOR_OBJECT_TYPE_EVENT = 4, |
304b3717 PP |
106 | |
107 | /// Number of entries in this enumeration. | |
50842bdc | 108 | BT_VISITOR_OBJECT_TYPE_NR, |
8bf65fbd JG |
109 | }; |
110 | ||
304b3717 PP |
111 | /** |
112 | @brief Visting function type. | |
113 | ||
50842bdc PP |
114 | A function of this type is called by bt_trace_visit() or |
115 | bt_stream_class_visit() when visiting the CTF IR object wrapper | |
304b3717 PP |
116 | \p object. |
117 | ||
118 | \p object has <strong>no reference count</strong>: do \em not use | |
119 | bt_put() or bt_get() on it. | |
120 | ||
121 | @param[in] object Currently visited CTF IR object wrapper. | |
122 | @param[in] data User data. | |
123 | @returns 0 on success, or a negative value on error. | |
124 | ||
125 | @prenotnull{object} | |
126 | ||
50842bdc PP |
127 | @sa bt_trace_visit(): Accepts a visitor to visit a trace class. |
128 | @sa bt_stream_class_visit(): Accepts a visitor to visit a stream | |
304b3717 PP |
129 | class. |
130 | */ | |
50842bdc | 131 | typedef int (*bt_visitor)(struct bt_visitor_object *object, |
8bf65fbd JG |
132 | void *data); |
133 | ||
304b3717 PP |
134 | /** |
135 | @brief Returns the type of the CTF IR object wrapped by the CTF IR | |
136 | object wrapper \p object. | |
8bf65fbd | 137 | |
304b3717 PP |
138 | @param[in] object Object wrapper of which to get the type. |
139 | @returns Type of \p object. | |
140 | ||
141 | @prenotnull{object} | |
142 | ||
50842bdc | 143 | @sa bt_visitor_object_get_object(): Returns the object wrapped by a given |
304b3717 PP |
144 | CTF IR object wrapper. |
145 | */ | |
50842bdc PP |
146 | enum bt_visitor_object_type bt_visitor_object_get_type( |
147 | struct bt_visitor_object *object); | |
304b3717 PP |
148 | |
149 | /** | |
150 | @brief Returns the CTF IR object wrapped by the CTF IR object | |
151 | wrapper \p object. | |
152 | ||
c2f29fb9 PP |
153 | The reference count of \p object is \em not incremented by this |
154 | function. On success, you must call bt_get() on the return value to | |
155 | have your own reference. | |
156 | ||
304b3717 PP |
157 | @param[in] object Object wrapper of which to get the wrapped |
158 | CTF IR object. | |
159 | @returns CTF IR object wrapped by \p object. | |
160 | ||
161 | @prenotnull{object} | |
c2f29fb9 | 162 | @post The reference count of the returned object is not modified. |
304b3717 | 163 | |
50842bdc | 164 | @sa bt_visitor_object_get_type(): Returns the type of a given |
304b3717 PP |
165 | CTF IR object wrapper. |
166 | */ | |
50842bdc | 167 | void *bt_visitor_object_get_object(struct bt_visitor_object *object); |
8bf65fbd | 168 | |
304b3717 PP |
169 | /** @} */ |
170 | ||
8bf65fbd JG |
171 | #ifdef __cplusplus |
172 | } | |
173 | #endif | |
174 | ||
175 | #endif /* BABELTRACE_CTF_IR_VISITOR_H */ |