[babeltrace.git] / include / babeltrace / ctf-ir / event.h

#ifndef BABELTRACE_CTF_IR_EVENT_H
#define BABELTRACE_CTF_IR_EVENT_H

/*
 * BabelTrace - CTF IR: Event
 *
 * Copyright 2013, 2014 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
 */

/* For bt_get() */
#include <babeltrace/ref.h>

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

struct bt_value;
struct bt_clock_class;

/**
@defgroup ctfirevent CTF IR event
@ingroup ctfir
@brief CTF IR event.

@code
#include <babeltrace/ctf-ir/event.h>
@endcode

A CTF IR <strong><em>event</em></strong> is a container of event
fields:

- <strong>Stream event header</strong> field, described by the
  <em>stream event header field type</em> of a
  \link ctfirstreamclass CTF IR stream class\endlink.
- <strong>Stream event context</strong> field, described by the
  <em>stream event context field type</em> of a stream class.
- <strong>Event context</strong> field, described by the
  <em>event context field type</em> of a
  \link ctfireventclass CTF IR event class\endlink.
- <strong>Event payload</strong>, described by the
  <em>event payload field type</em> of an event class.

As a reminder, here's the structure of a CTF packet:

@imgpacketstructure

You can create a CTF IR event \em from a
\link ctfireventclass CTF IR event class\endlink with
bt_event_create(). The event class you use to create an event
object becomes its parent.

If the \link ctfirtraceclass CTF IR trace class\endlink of an event
object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
which is the parent of its event class) was created by a
\link ctfwriter CTF writer\endlink object, then the only possible
action you can do with this event object is to append it to a
\link ctfirstream CTF IR stream\endlink with
bt_stream_append_event(). Otherwise, you can create an event
notification with bt_notification_event_create(). The event you pass
to this function \em must have an attached packet object first.

You can attach a \link ctfirpacket CTF IR packet object\endlink to an
event object with bt_event_set_packet().

A CTF IR event has a mapping of
\link ctfirclockvalue CTF IR clock values\endlink. A clock value is
an instance of a specific
\link ctfirclockclass CTF IR clock class\endlink when the event is
emitted. You can set an event object's clock value with
bt_event_set_clock_value().

As with any Babeltrace object, CTF IR event objects have
<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
counts</a>. See \ref refs to learn more about the reference counting
management of Babeltrace objects.

bt_notification_event_create() \em freezes its event parameter on
success. You cannot modify a frozen event object: it is considered
immutable, except for \link refs reference counting\endlink.

@sa ctfireventclass
@sa ctfirpacket

@file
@brief CTF IR event type and functions.
@sa ctfirevent

@addtogroup ctfirevent
@{
*/

/**
@struct bt_event
@brief A CTF IR event.
@sa ctfirevent
*/
struct bt_event;
struct bt_event_header_field;
struct bt_clock;
struct bt_clock_value;
struct bt_event_class;
struct bt_field;
struct bt_field_type;
struct bt_stream_class;
struct bt_packet;

/**
@name Creation and parent access functions
@{
*/

/**
@brief  Creates a default CTF IR event from the CTF IR event class
	\p event_class.

\p event_class \em must have a parent
\link ctfirstreamclass CTF IR stream class\endlink.

On success, the four fields of the created event object are not set. You
can set them with bt_event_set_header(),
bt_event_set_stream_event_context(),
bt_event_set_context(), and bt_event_set_payload().

This function tries to resolve the needed
\link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
types that are found anywhere in the context or payload field
types of \p event_class and in the root field types of the
parent stream class of \p event_class. If any automatic resolving fails,
this function fails. This means that, if any dynamic field type need
a field type which should be found in the trace packet header root
field type, and if the parent stream class of \p event_class was not
added to a \link ctfirtraceclass CTF IR trace class\endlink yet
with bt_trace_add_stream_class(), then this function fails.

@param[in] event_class	CTF IR event class to use to create the
			CTF IR event.
@returns		Created event object, or \c NULL on error.

@prenotnull{event_class}
@pre \p event_class has a parent stream class.
@postsuccessrefcountret1
*/
extern struct bt_event_class *bt_event_borrow_class(struct bt_event *event);

/**
@brief	Returns the parent CTF IR event class of the CTF IR event
	\p event.

This function returns a reference to the event class which was used to
create the event object in the first place with bt_event_create().

@param[in] event	Event of which to get the parent event class.
@returns		Parent event class of \p event,
			or \c NULL on error.

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc
*/
static inline
struct bt_event_class *bt_event_get_class(struct bt_event *event)
{
	return bt_get(bt_event_borrow_class(event));
}

extern struct bt_packet *bt_event_borrow_packet(struct bt_event *event);

/**
@brief	Returns the CTF IR packet associated to the CTF IR event
	\p event.

This function returns a reference to the event class which was set to
\p event in the first place with bt_event_set_packet().

@param[in] event	Event of which to get the associated packet.
@returns		Packet associated to \p event,
			or \c NULL if no packet is associated to
			\p event or on error.

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc

@sa bt_event_set_packet(): Associates a given event to a given
	packet.
*/
static inline
struct bt_packet *bt_event_get_packet(struct bt_event *event)
{
	return bt_get(bt_event_borrow_packet(event));
}

extern struct bt_stream *bt_event_borrow_stream(struct bt_event *event);

/**
@brief	Returns the parent CTF IR stream associated to the CTF IR event
	\p event.

@param[in] event	Event of which to get the parent stream.
@returns		Parent stream of \p event, or \c NULL on error.

@prenotnull{event}
@postrefcountsame{event}
@postsuccessrefcountretinc
*/
static inline
struct bt_stream *bt_event_get_stream(struct bt_event *event)
{
	return bt_get(bt_event_borrow_stream(event));
}

/** @} */

/**
@name Contained fields functions
@{
*/

extern struct bt_field *bt_event_borrow_header(struct bt_event *event);

extern int bt_event_move_header(struct bt_event *event,
		struct bt_event_header_field *header);

extern struct bt_field *bt_event_borrow_stream_event_context(
		struct bt_event *event);

extern struct bt_field *bt_event_borrow_context(struct bt_event *event);

extern struct bt_field *bt_event_borrow_payload(struct bt_event *event);

/** @} */

/**
@name Clock value functions
@{
*/

extern struct bt_clock_value *bt_event_borrow_clock_value(
		struct bt_event *event,
		struct bt_clock_class *clock_class);

/** @} */

/** @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_EVENT_H */
Commit	Line	Data
	1	#ifndef BABELTRACE_CTF_IR_EVENT_H
	2	#define BABELTRACE_CTF_IR_EVENT_H
	3
	4	/*
	5	* BabelTrace - CTF IR: Event
	6	*
	7	* Copyright 2013, 2014 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	/* For bt_get() */
	34	#include <babeltrace/ref.h>
	35
	36	#include <stdint.h>
	37	#include <stddef.h>
	38
	39	#ifdef __cplusplus
	40	extern "C" {
	41	#endif
	42
	43	struct bt_value;
	44	struct bt_clock_class;
	45
	46	/**
	47	@defgroup ctfirevent CTF IR event
	48	@ingroup ctfir
	49	@brief CTF IR event.
	50
	51	@code
	52	#include <babeltrace/ctf-ir/event.h>
	53	@endcode
	54
	55	A CTF IR <strong><em>event</em></strong> is a container of event
	56	fields:
	57
	58	- <strong>Stream event header</strong> field, described by the
	59	<em>stream event header field type</em> of a
	60	\link ctfirstreamclass CTF IR stream class\endlink.
	61	- <strong>Stream event context</strong> field, described by the
	62	<em>stream event context field type</em> of a stream class.
	63	- <strong>Event context</strong> field, described by the
	64	<em>event context field type</em> of a
	65	\link ctfireventclass CTF IR event class\endlink.
	66	- <strong>Event payload</strong>, described by the
	67	<em>event payload field type</em> of an event class.
	68
	69	As a reminder, here's the structure of a CTF packet:
	70
	71	@imgpacketstructure
	72
	73	You can create a CTF IR event \em from a
	74	\link ctfireventclass CTF IR event class\endlink with
	75	bt_event_create(). The event class you use to create an event
	76	object becomes its parent.
	77
	78	If the \link ctfirtraceclass CTF IR trace class\endlink of an event
	79	object (parent of its \link ctfirstreamclass CTF IR stream class\endlink,
	80	which is the parent of its event class) was created by a
	81	\link ctfwriter CTF writer\endlink object, then the only possible
	82	action you can do with this event object is to append it to a
	83	\link ctfirstream CTF IR stream\endlink with
	84	bt_stream_append_event(). Otherwise, you can create an event
	85	notification with bt_notification_event_create(). The event you pass
	86	to this function \em must have an attached packet object first.
	87
	88	You can attach a \link ctfirpacket CTF IR packet object\endlink to an
	89	event object with bt_event_set_packet().
	90
	91	A CTF IR event has a mapping of
	92	\link ctfirclockvalue CTF IR clock values\endlink. A clock value is
	93	an instance of a specific
	94	\link ctfirclockclass CTF IR clock class\endlink when the event is
	95	emitted. You can set an event object's clock value with
	96	bt_event_set_clock_value().
	97
	98	As with any Babeltrace object, CTF IR event objects have
	99	<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
	100	counts</a>. See \ref refs to learn more about the reference counting
	101	management of Babeltrace objects.
	102
	103	bt_notification_event_create() \em freezes its event parameter on
	104	success. You cannot modify a frozen event object: it is considered
	105	immutable, except for \link refs reference counting\endlink.
	106
	107	@sa ctfireventclass
	108	@sa ctfirpacket
	109
	110	@file
	111	@brief CTF IR event type and functions.
	112	@sa ctfirevent
	113
	114	@addtogroup ctfirevent
	115	@{
	116	*/
	117
	118	/**
	119	@struct bt_event
	120	@brief A CTF IR event.
	121	@sa ctfirevent
	122	*/
	123	struct bt_event;
	124	struct bt_event_header_field;
	125	struct bt_clock;
	126	struct bt_clock_value;
	127	struct bt_event_class;
	128	struct bt_field;
	129	struct bt_field_type;
	130	struct bt_stream_class;
	131	struct bt_packet;
	132
	133	/**
	134	@name Creation and parent access functions
	135	@{
	136	*/
	137
	138	/**
	139	@brief Creates a default CTF IR event from the CTF IR event class
	140	\p event_class.
	141
	142	\p event_class \em must have a parent
	143	\link ctfirstreamclass CTF IR stream class\endlink.
	144
	145	On success, the four fields of the created event object are not set. You
	146	can set them with bt_event_set_header(),
	147	bt_event_set_stream_event_context(),
	148	bt_event_set_context(), and bt_event_set_payload().
	149
	150	This function tries to resolve the needed
	151	\link ctfirfieldtypes CTF IR field type\endlink of the dynamic field
	152	types that are found anywhere in the context or payload field
	153	types of \p event_class and in the root field types of the
	154	parent stream class of \p event_class. If any automatic resolving fails,
	155	this function fails. This means that, if any dynamic field type need
	156	a field type which should be found in the trace packet header root
	157	field type, and if the parent stream class of \p event_class was not
	158	added to a \link ctfirtraceclass CTF IR trace class\endlink yet
	159	with bt_trace_add_stream_class(), then this function fails.
	160
	161	@param[in] event_class CTF IR event class to use to create the
	162	CTF IR event.
	163	@returns Created event object, or \c NULL on error.
	164
	165	@prenotnull{event_class}
	166	@pre \p event_class has a parent stream class.
	167	@postsuccessrefcountret1
	168	*/
	169	extern struct bt_event_class bt_event_borrow_class(struct bt_event event);
	170
	171	/**
	172	@brief Returns the parent CTF IR event class of the CTF IR event
	173	\p event.
	174
	175	This function returns a reference to the event class which was used to
	176	create the event object in the first place with bt_event_create().
	177
	178	@param[in] event Event of which to get the parent event class.
	179	@returns Parent event class of \p event,
	180	or \c NULL on error.
	181
	182	@prenotnull{event}
	183	@postrefcountsame{event}
	184	@postsuccessrefcountretinc
	185	*/
	186	static inline
	187	struct bt_event_class bt_event_get_class(struct bt_event event)
	188	{
	189	return bt_get(bt_event_borrow_class(event));
	190	}
	191
	192	extern struct bt_packet bt_event_borrow_packet(struct bt_event event);
	193
	194	/**
	195	@brief Returns the CTF IR packet associated to the CTF IR event
	196	\p event.
	197
	198	This function returns a reference to the event class which was set to
	199	\p event in the first place with bt_event_set_packet().
	200
	201	@param[in] event Event of which to get the associated packet.
	202	@returns Packet associated to \p event,
	203	or \c NULL if no packet is associated to
	204	\p event or on error.
	205
	206	@prenotnull{event}
	207	@postrefcountsame{event}
	208	@postsuccessrefcountretinc
	209
	210	@sa bt_event_set_packet(): Associates a given event to a given
	211	packet.
	212	*/
	213	static inline
	214	struct bt_packet bt_event_get_packet(struct bt_event event)
	215	{
	216	return bt_get(bt_event_borrow_packet(event));
	217	}
	218
	219	extern struct bt_stream bt_event_borrow_stream(struct bt_event event);
	220
	221	/**
	222	@brief Returns the parent CTF IR stream associated to the CTF IR event
	223	\p event.
	224
	225	@param[in] event Event of which to get the parent stream.
	226	@returns Parent stream of \p event, or \c NULL on error.
	227
	228	@prenotnull{event}
	229	@postrefcountsame{event}
	230	@postsuccessrefcountretinc
	231	*/
	232	static inline
	233	struct bt_stream bt_event_get_stream(struct bt_event event)
	234	{
	235	return bt_get(bt_event_borrow_stream(event));
	236	}
	237
	238	/** @} */
	239
	240	/**
	241	@name Contained fields functions
	242	@{
	243	*/
	244
	245	extern struct bt_field bt_event_borrow_header(struct bt_event event);
	246
	247	extern int bt_event_move_header(struct bt_event *event,
	248	struct bt_event_header_field *header);
	249
	250	extern struct bt_field *bt_event_borrow_stream_event_context(
	251	struct bt_event *event);
	252
	253	extern struct bt_field bt_event_borrow_context(struct bt_event event);
	254
	255	extern struct bt_field bt_event_borrow_payload(struct bt_event event);
	256
	257	/** @} */
	258
	259	/**
	260	@name Clock value functions
	261	@{
	262	*/
	263
	264	extern struct bt_clock_value *bt_event_borrow_clock_value(
	265	struct bt_event *event,
	266	struct bt_clock_class *clock_class);
	267
	268	/** @} */
	269
	270	/** @} */
	271
	272	#ifdef __cplusplus
	273	}
	274	#endif
	275
	276	#endif /* BABELTRACE_CTF_IR_EVENT_H */