[babeltrace.git] / include / babeltrace / ctf-writer / visitor.h

#ifndef BABELTRACE_CTF_WRITER_VISITOR_H
#define BABELTRACE_CTF_WRITER_VISITOR_H

/*
 * BabelTrace - CTF writer: Visitor
 *
 * Copyright 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * The Common Trace Format (CTF) Specification is available at
 * http://www.efficios.com/ctf
 */

#ifdef __cplusplus
extern "C" {
#endif

/**
@defgroup ctfirvisitor CTF IR visitor
@ingroup ctfir
@brief CTF IR visitor.

@code
#include <babeltrace/trace-ir/visitor.h>
@endcode

A CTF IR <strong><em>visitor</em></strong> is a function that you
can use to visit the hierarchy of a
\link ctfirtraceclass CTF IR trace class\endlink with
bt_ctf_trace_visit() or of a
\link ctfirstreamclass CTF IR stream class\endlink with
bt_ctf_stream_class_visit().

The traversal of the object's hierarchy is always done in a
pre-order fashion.

@sa ctfirstreamclass
@sa ctfirtraceclass

@file
@brief CTF IR visitor types and functions.
@sa ctfirvisitor

@addtogroup ctfirvisitor
@{
*/

/**
@struct bt_object
@brief A CTF IR object wrapper.

This structure wraps both a CTF IR object and its type
(see #bt_object_type). It is used in the visiting function.

You can use the bt_object_get_type() and
bt_object_get_object() accessors to get the type and wrapped
CTF IR object of a CTF IR object wrapper.

A CTF IR object wrapper has <strong>no reference count</strong>: do \em
not use bt_put() or bt_get() on it.

@sa ctfirvisitor
*/
struct bt_ctf_visitor_object;

/**
@brief	CTF IR object wrapper type.
*/
enum bt_ctf_visitor_object_type {
	/// Unknown (used for errors).
	BT_CTF_VISITOR_OBJECT_TYPE_UNKNOWN = -1,

	/// \ref ctfirtraceclass.
	BT_CTF_VISITOR_OBJECT_TYPE_TRACE = 0,

	/// \ref ctfirstreamclass.
	BT_CTF_VISITOR_OBJECT_TYPE_STREAM_CLASS = 1,

	/// \ref ctfirstream.
	BT_CTF_VISITOR_OBJECT_TYPE_STREAM = 2,

	/// \ref ctfireventclass.
	BT_CTF_VISITOR_OBJECT_TYPE_EVENT_CLASS = 3,

	/// \ref ctfirevent.
	BT_CTF_VISITOR_OBJECT_TYPE_EVENT = 4,

	/// Number of entries in this enumeration.
	BT_CTF_VISITOR_OBJECT_TYPE_NR,
};

/**
@brief	Visting function type.

A function of this type is called by bt_ctf_trace_visit() or
bt_ctf_stream_class_visit() when visiting the CTF IR object wrapper
\p object.

\p object has <strong>no reference count</strong>: do \em not use
bt_put() or bt_get() on it.

@param[in] object	Currently visited CTF IR object wrapper.
@param[in] data		User data.
@returns		0 on success, or a negative value on error.

@prenotnull{object}

@sa bt_ctf_trace_visit(): Accepts a visitor to visit a trace class.
@sa bt_ctf_stream_class_visit(): Accepts a visitor to visit a stream
	class.
*/
typedef int (*bt_ctf_visitor)(struct bt_ctf_visitor_object *object,
		void *data);

/**
@brief	Returns the type of the CTF IR object wrapped by the CTF IR
	object wrapper \p object.

@param[in] object	Object wrapper of which to get the type.
@returns		Type of \p object.

@prenotnull{object}

@sa bt_ctf_visitor_object_get_object(): Returns the object wrapped by a given
	CTF IR object wrapper.
*/
enum bt_ctf_visitor_object_type bt_ctf_visitor_object_get_type(
		struct bt_ctf_visitor_object *object);

/**
@brief	Returns the CTF IR object wrapped by the CTF IR object
	wrapper \p object.

The reference count of \p object is \em not incremented by this
function. On success, you must call bt_get() on the return value to
have your own reference.

@param[in] object	Object wrapper of which to get the wrapped
			CTF IR object.
@returns		CTF IR object wrapped by \p object.

@prenotnull{object}
@post The reference count of the returned object is not modified.

@sa bt_ctf_visitor_object_get_type(): Returns the type of a given
	CTF IR object wrapper.
*/
void *bt_ctf_visitor_object_get_object(struct bt_ctf_visitor_object *object);

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_WRITER_VISITOR_H */
Commit	Line	Data
16ca5ff0 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
56e18c4c	43	#include <babeltrace/trace-ir/visitor.h>
16ca5ff0 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
	79	not use bt_put() or bt_get() on it.
	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
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
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
154	function. On success, you must call bt_get() on the return value to
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 */