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 /* For bt_bool */
  37 #include <babeltrace/types.h>
  38
  39 #include <stdint.h>
  40 #include <stddef.h>
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 struct bt_value;
  47 struct bt_clock_class;
  48
  49 /**
  50 @defgroup ctfirevent CTF IR event
  51 @ingroup ctfir
  52 @brief CTF IR event.
  53
  54 @code
  55 #include <babeltrace/ctf-ir/event.h>
  56 @endcode
  57
  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
  78 bt_event_create(). The event class you use to create an event
  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
  84 \link ctfwriter CTF writer\endlink object, then the only possible
  85 action you can do with this event object is to append it to a
  86 \link ctfirstream CTF IR stream\endlink with
  87 bt_stream_append_event(). Otherwise, you can create an event
  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
  92 event object with bt_event_set_packet().
  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
  99 bt_event_set_clock_value().
 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 /**
 122 @struct bt_event
 123 @brief A CTF IR event.
 124 @sa ctfirevent
 125 */
 126 struct bt_event;
 127 struct bt_event_header_field;
 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;
 135
 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
 149 can set them with bt_event_set_header(),
 150 bt_event_set_stream_event_context(),
 151 bt_event_set_context(), and bt_event_set_payload().
 152
 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
 162 with bt_trace_add_stream_class(), then this function fails.
 163
 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 */
 172 extern struct bt_event_class *bt_event_borrow_class(struct bt_event *event);
 173
 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
 179 create the event object in the first place with bt_event_create().
 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}
 186 @postrefcountsame{event}
 187 @postsuccessrefcountretinc
 188 */
 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);
 196
 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
 202 \p event in the first place with bt_event_set_packet().
 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}
 210 @postrefcountsame{event}
 211 @postsuccessrefcountretinc
 212
 213 @sa bt_event_set_packet(): Associates a given event to a given
 214         packet.
 215 */
 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 }
 221
 222 extern struct bt_stream *bt_event_borrow_stream(struct bt_event *event);
 223
 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}
 232 @postrefcountsame{event}
 233 @postsuccessrefcountretinc
 234 */
 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 }
 240
 241 /** @} */
 242
 243 /**
 244 @name Contained fields functions
 245 @{
 246 */
 247
 248 extern struct bt_field *bt_event_borrow_header(struct bt_event *event);
 249
 250 extern int bt_event_move_header(struct bt_event *event,
 251                 struct bt_event_header_field *header);
 252
 253 extern struct bt_field *bt_event_borrow_stream_event_context(
 254                 struct bt_event *event);
 255
 256 extern struct bt_field *bt_event_borrow_context(struct bt_event *event);
 257
 258 extern struct bt_field *bt_event_borrow_payload(struct bt_event *event);
 259
 260 /** @} */
 261
 262 /**
 263 @name Clock value functions
 264 @{
 265 */
 266
 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);
 273
 274 /** @} */
 275
 276 /** @} */
 277
 278 #ifdef __cplusplus
 279 }
 280 #endif
 281
 282 #endif /* BABELTRACE_CTF_IR_EVENT_H */