include/babeltrace/ctf-ir/event.h

   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 */