Rename: bt_put(), bt_get() -> bt_object_put_ref(), bt_object_get_ref()
[babeltrace.git] / include / babeltrace / ctf-writer / visitor.h
CommitLineData
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
34extern "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
46A CTF IR <strong><em>visitor</em></strong> is a function that you
47can use to visit the hierarchy of a
48\link ctfirtraceclass CTF IR trace class\endlink with
49bt_ctf_trace_visit() or of a
50\link ctfirstreamclass CTF IR stream class\endlink with
51bt_ctf_stream_class_visit().
52
53The traversal of the object's hierarchy is always done in a
54pre-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
71This structure wraps both a CTF IR object and its type
72(see #bt_object_type). It is used in the visiting function.
73
74You can use the bt_object_get_type() and
75bt_object_get_object() accessors to get the type and wrapped
76CTF IR object of a CTF IR object wrapper.
77
78A CTF IR object wrapper has <strong>no reference count</strong>: do \em
8138bfe1 79not use bt_object_put_ref() or bt_object_get_ref() on it.
086dc475
PP
80
81@sa ctfirvisitor
82*/
83struct bt_ctf_visitor_object;
84
85/**
86@brief CTF IR object wrapper type.
87*/
88enum 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
114A function of this type is called by bt_ctf_trace_visit() or
115bt_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 119bt_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*/
131typedef 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*/
146enum 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
153The reference count of \p object is \em not incremented by this
8138bfe1 154function. On success, you must call bt_object_get_ref() on the return value to
086dc475
PP
155have 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*/
167void *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 */
This page took 0.029417 seconds and 4 git commands to generate.