[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>

/* For bt_bool */
#include <babeltrace/types.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 int bt_event_set_clock_value(struct bt_event *event,
		struct bt_clock_class *clock_class, uint64_t raw_value,
		bt_bool is_default);

extern struct bt_clock_value *bt_event_borrow_default_clock_value(
		struct bt_event *event);

/** @} */

/** @} */

#ifdef __cplusplus
}
#endif

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