Commit | Line | Data |
---|---|---|
086dc475 PP |
1 | #ifndef BABELTRACE_CTF_WRITER_VISITOR_H |
2 | #define BABELTRACE_CTF_WRITER_VISITOR_H | |
3 | ||
4 | /* | |
5 | * BabelTrace - CTF writer: 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 | ||
37 | /** | |
38 | @defgroup ctfirvisitor CTF IR visitor | |
39 | @ingroup ctfir | |
40 | @brief CTF IR visitor. | |
41 | ||
42 | @code | |
108b91d0 | 43 | #include <babeltrace/trace-ir/visitor.h> |
086dc475 PP |
44 | @endcode |
45 | ||
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 | |
49 | bt_ctf_trace_visit() or of a | |
50 | \link ctfirstreamclass CTF IR stream class\endlink with | |
51 | bt_ctf_stream_class_visit(). | |
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 | /** | |
68 | @struct bt_object | |
69 | @brief A CTF IR object wrapper. | |
70 | ||
71 | This structure wraps both a CTF IR object and its type | |
72 | (see #bt_object_type). It is used in the visiting function. | |
73 | ||
74 | You can use the bt_object_get_type() and | |
75 | bt_object_get_object() accessors to get the type and wrapped | |
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 | |
8138bfe1 | 79 | not use bt_object_put_ref() or bt_object_get_ref() on it. |
086dc475 PP |
80 | |
81 | @sa ctfirvisitor | |
82 | */ | |
83 | struct bt_ctf_visitor_object; | |
84 | ||
85 | /** | |
86 | @brief CTF IR object wrapper type. | |
87 | */ | |
88 | enum bt_ctf_visitor_object_type { | |
89 | /// Unknown (used for errors). | |
90 | BT_CTF_VISITOR_OBJECT_TYPE_UNKNOWN = -1, | |
91 | ||
92 | /// \ref ctfirtraceclass. | |
93 | BT_CTF_VISITOR_OBJECT_TYPE_TRACE = 0, | |
94 | ||
95 | /// \ref ctfirstreamclass. | |
96 | BT_CTF_VISITOR_OBJECT_TYPE_STREAM_CLASS = 1, | |
97 | ||
98 | /// \ref ctfirstream. | |
99 | BT_CTF_VISITOR_OBJECT_TYPE_STREAM = 2, | |
100 | ||
101 | /// \ref ctfireventclass. | |
102 | BT_CTF_VISITOR_OBJECT_TYPE_EVENT_CLASS = 3, | |
103 | ||
104 | /// \ref ctfirevent. | |
105 | BT_CTF_VISITOR_OBJECT_TYPE_EVENT = 4, | |
106 | ||
107 | /// Number of entries in this enumeration. | |
108 | BT_CTF_VISITOR_OBJECT_TYPE_NR, | |
109 | }; | |
110 | ||
111 | /** | |
112 | @brief Visting function type. | |
113 | ||
114 | A function of this type is called by bt_ctf_trace_visit() or | |
115 | bt_ctf_stream_class_visit() when visiting the CTF IR object wrapper | |
116 | \p object. | |
117 | ||
118 | \p object has <strong>no reference count</strong>: do \em not use | |
8138bfe1 | 119 | bt_object_put_ref() or bt_object_get_ref() on it. |
086dc475 PP |
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 | ||
127 | @sa bt_ctf_trace_visit(): Accepts a visitor to visit a trace class. | |
128 | @sa bt_ctf_stream_class_visit(): Accepts a visitor to visit a stream | |
129 | class. | |
130 | */ | |
131 | typedef int (*bt_ctf_visitor)(struct bt_ctf_visitor_object *object, | |
132 | void *data); | |
133 | ||
134 | /** | |
135 | @brief Returns the type of the CTF IR object wrapped by the CTF IR | |
136 | object wrapper \p object. | |
137 | ||
138 | @param[in] object Object wrapper of which to get the type. | |
139 | @returns Type of \p object. | |
140 | ||
141 | @prenotnull{object} | |
142 | ||
143 | @sa bt_ctf_visitor_object_get_object(): Returns the object wrapped by a given | |
144 | CTF IR object wrapper. | |
145 | */ | |
146 | enum bt_ctf_visitor_object_type bt_ctf_visitor_object_get_type( | |
147 | struct bt_ctf_visitor_object *object); | |
148 | ||
149 | /** | |
150 | @brief Returns the CTF IR object wrapped by the CTF IR object | |
151 | wrapper \p object. | |
152 | ||
153 | The reference count of \p object is \em not incremented by this | |
8138bfe1 | 154 | function. On success, you must call bt_object_get_ref() on the return value to |
086dc475 PP |
155 | have your own reference. |
156 | ||
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} | |
162 | @post The reference count of the returned object is not modified. | |
163 | ||
164 | @sa bt_ctf_visitor_object_get_type(): Returns the type of a given | |
165 | CTF IR object wrapper. | |
166 | */ | |
167 | void *bt_ctf_visitor_object_get_object(struct bt_ctf_visitor_object *object); | |
168 | ||
169 | /** @} */ | |
170 | ||
171 | #ifdef __cplusplus | |
172 | } | |
173 | #endif | |
174 | ||
175 | #endif /* BABELTRACE_CTF_WRITER_VISITOR_H */ |