lib: use object pool for event and packet notifications
[babeltrace.git] / plugins / ctf / common / notif-iter / notif-iter.h
CommitLineData
e98a2d6e
PP
1#ifndef CTF_NOTIF_ITER_H
2#define CTF_NOTIF_ITER_H
3
4/*
5 * Babeltrace - CTF notification iterator
6 * ¯¯¯¯¯ ¯¯¯¯
7 * Copyright (c) 2015-2016 EfficiOS Inc. and Linux Foundation
8 * Copyright (c) 2015-2016 Philippe Proulx <pproulx@efficios.com>
9 *
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of this software and associated documentation files (the "Software"), to deal
12 * in the Software without restriction, including without limitation the rights
13 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14 * copies of the Software, and to permit persons to whom the Software is
15 * furnished to do so, subject to the following conditions:
16 *
17 * The above copyright notice and this permission notice shall be included in
18 * all copies or substantial portions of the Software.
19 *
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26 * SOFTWARE.
27 */
28
29#include <stdint.h>
30#include <stdio.h>
31#include <stddef.h>
9d408fca 32#include <babeltrace/babeltrace.h>
e98a2d6e
PP
33#include <babeltrace/babeltrace-internal.h>
34
35/**
36 * @file ctf-notif-iter.h
37 *
38 * CTF notification iterator
39 * ¯¯¯¯¯ ¯¯¯¯
40 * This is a common internal API used by CTF source plugins. It allows
41 * one to get notifications from a user-provided medium.
42 */
43
44/**
45 * Medium operations status codes.
46 */
50842bdc 47enum bt_notif_iter_medium_status {
e98a2d6e
PP
48 /**
49 * End of file.
50 *
51 * The medium function called by the notification iterator
52 * function reached the end of the file.
53 */
50842bdc 54 BT_NOTIF_ITER_MEDIUM_STATUS_EOF = 1,
e98a2d6e
PP
55
56 /**
57 * There is no data available right now, try again later.
58 */
50842bdc 59 BT_NOTIF_ITER_MEDIUM_STATUS_AGAIN = 11,
9e0c8dbb
JG
60
61 /** Unsupported operation. */
50842bdc 62 BT_NOTIF_ITER_MEDIUM_STATUS_UNSUPPORTED = -3,
e98a2d6e
PP
63
64 /** Invalid argument. */
50842bdc 65 BT_NOTIF_ITER_MEDIUM_STATUS_INVAL = -2,
e98a2d6e
PP
66
67 /** General error. */
50842bdc 68 BT_NOTIF_ITER_MEDIUM_STATUS_ERROR = -1,
e98a2d6e
PP
69
70 /** Everything okay. */
50842bdc 71 BT_NOTIF_ITER_MEDIUM_STATUS_OK = 0,
e98a2d6e
PP
72};
73
74/**
75 * CTF notification iterator API status code.
76 */
50842bdc 77enum bt_notif_iter_status {
e98a2d6e
PP
78 /**
79 * End of file.
80 *
81 * The medium function called by the notification iterator
82 * function reached the end of the file.
83 */
50842bdc 84 BT_NOTIF_ITER_STATUS_EOF = BT_NOTIF_ITER_MEDIUM_STATUS_EOF,
e98a2d6e
PP
85
86 /**
87 * There is no data available right now, try again later.
88 *
89 * Some condition resulted in the
50842bdc 90 * bt_notif_iter_medium_ops::request_bytes() user function not
e98a2d6e
PP
91 * having access to any data now. You should retry calling the
92 * last called notification iterator function once the situation
93 * is resolved.
94 */
50842bdc 95 BT_NOTIF_ITER_STATUS_AGAIN = BT_NOTIF_ITER_MEDIUM_STATUS_AGAIN,
e98a2d6e
PP
96
97 /** Invalid argument. */
50842bdc 98 BT_NOTIF_ITER_STATUS_INVAL = BT_NOTIF_ITER_MEDIUM_STATUS_INVAL,
e98a2d6e 99
9e0c8dbb 100 /** Unsupported operation. */
50842bdc 101 BT_NOTIF_ITER_STATUS_UNSUPPORTED = BT_NOTIF_ITER_MEDIUM_STATUS_UNSUPPORTED,
9e0c8dbb 102
e98a2d6e 103 /** General error. */
50842bdc 104 BT_NOTIF_ITER_STATUS_ERROR = BT_NOTIF_ITER_MEDIUM_STATUS_ERROR,
e98a2d6e
PP
105
106 /** Everything okay. */
50842bdc 107 BT_NOTIF_ITER_STATUS_OK = 0,
e98a2d6e
PP
108};
109
9e0c8dbb
JG
110/**
111 * CTF notification iterator seek operation directives.
112 */
50842bdc 113enum bt_notif_iter_seek_whence {
9e0c8dbb
JG
114 /**
115 * Set the iterator's position to an absolute offset in the underlying
116 * medium.
117 */
50842bdc 118 BT_NOTIF_ITER_SEEK_WHENCE_SET,
9e0c8dbb
JG
119};
120
e98a2d6e
PP
121/**
122 * Medium operations.
123 *
124 * Those user functions are called by the notification iterator
125 * functions to request medium actions.
126 */
50842bdc 127struct bt_notif_iter_medium_ops {
e98a2d6e
PP
128 /**
129 * Returns the next byte buffer to be used by the binary file
130 * reader to deserialize binary data.
131 *
132 * This function \em must be defined.
133 *
134 * The purpose of this function is to return a buffer of bytes
135 * to the notification iterator, of a maximum of \p request_sz
136 * bytes. If this function cannot return a buffer of at least
137 * \p request_sz bytes, it may return a smaller buffer. In
138 * either cases, \p buffer_sz must be set to the returned buffer
139 * size (in bytes).
140 *
141 * The returned buffer's ownership remains the medium, in that
142 * it won't be freed by the notification iterator functions. The
143 * returned buffer won't be modified by the notification
144 * iterator functions either.
145 *
146 * When this function is called for the first time for a given
147 * file, the offset within the file is considered to be 0. The
148 * next times this function is called, the returned buffer's
149 * byte offset within the complete file must be the previous
150 * offset plus the last returned value of \p buffer_sz by this
151 * medium.
152 *
153 * This function must return one of the following statuses:
154 *
50842bdc 155 * - <b>#BT_NOTIF_ITER_MEDIUM_STATUS_OK</b>: Everything
e98a2d6e
PP
156 * is okay, i.e. \p buffer_sz is set to a positive value
157 * reflecting the number of available bytes in the buffer
158 * starting at the address written in \p buffer_addr.
50842bdc 159 * - <b>#BT_NOTIF_ITER_MEDIUM_STATUS_AGAIN</b>: No data is
e98a2d6e
PP
160 * available right now. In this case, the notification
161 * iterator function called by the user returns
50842bdc 162 * #BT_NOTIF_ITER_STATUS_AGAIN, and it is the user's
e98a2d6e
PP
163 * responsibility to make sure enough data becomes available
164 * before calling the \em same notification iterator
165 * function again to continue the decoding process.
50842bdc 166 * - <b>#BT_NOTIF_ITER_MEDIUM_STATUS_EOF</b>: The end of
e98a2d6e
PP
167 * the file was reached, and no more data will ever be
168 * available for this file. In this case, the notification
169 * iterator function called by the user returns
50842bdc 170 * #BT_NOTIF_ITER_STATUS_EOF. This must \em not be
e98a2d6e
PP
171 * returned when returning at least one byte of data to the
172 * caller, i.e. this must be returned when there's
173 * absolutely nothing left; should the request size be
174 * larger than what's left in the file, this function must
175 * return what's left, setting \p buffer_sz to the number of
176 * remaining bytes, and return
50842bdc 177 * #BT_NOTIF_ITER_MEDIUM_STATUS_EOF on the \em following
e98a2d6e 178 * call.
50842bdc 179 * - <b>#BT_NOTIF_ITER_MEDIUM_STATUS_ERROR</b>: A fatal
e98a2d6e
PP
180 * error occured during this operation. In this case, the
181 * notification iterator function called by the user returns
50842bdc 182 * #BT_NOTIF_ITER_STATUS_ERROR.
e98a2d6e 183 *
50842bdc 184 * If #BT_NOTIF_ITER_MEDIUM_STATUS_OK is not returned, the
e98a2d6e
PP
185 * values of \p buffer_sz and \p buffer_addr are \em ignored by
186 * the caller.
187 *
188 * @param request_sz Requested buffer size (bytes)
189 * @param buffer_addr Returned buffer address
190 * @param buffer_sz Returned buffer's size (bytes)
191 * @param data User data
192 * @returns Status code (see description above)
193 */
50842bdc 194 enum bt_notif_iter_medium_status (* request_bytes)(
e98a2d6e
PP
195 size_t request_sz, uint8_t **buffer_addr,
196 size_t *buffer_sz, void *data);
197
9e0c8dbb
JG
198 /**
199 * Repositions the underlying stream's position.
200 *
201 * This *optional* method repositions the underlying stream
202 * to a given absolute or relative position, as indicated by
203 * the whence directive.
204 *
50842bdc 205 * @param whence One of #bt_notif_iter_seek_whence values
9e0c8dbb
JG
206 * @param offset Offset to use for the given directive
207 * @param data User data
50842bdc 208 * @returns One of #bt_notif_iter_medium_status values
9e0c8dbb 209 */
50842bdc
PP
210 enum bt_notif_iter_medium_status (* seek)(
211 enum bt_notif_iter_seek_whence whence,
9e0c8dbb
JG
212 off_t offset, void *data);
213
e98a2d6e
PP
214 /**
215 * Returns a stream instance (weak reference) for the given
216 * stream class.
217 *
218 * This is called after a packet header is read, and the
219 * corresponding stream class is found by the notification
220 * iterator.
221 *
b92735af
PP
222 * @param stream_class Stream class of the stream to get
223 * @param stream_id Stream (instance) ID of the stream
224 * to get (-1ULL if not available)
e98a2d6e
PP
225 * @param data User data
226 * @returns Stream instance (weak reference) or
227 * \c NULL on error
228 */
312c056a 229 struct bt_stream * (* borrow_stream)(
50842bdc 230 struct bt_stream_class *stream_class,
b92735af 231 uint64_t stream_id, void *data);
e98a2d6e
PP
232};
233
234/** CTF notification iterator. */
50842bdc 235struct bt_notif_iter;
e98a2d6e
PP
236
237// TODO: Replace by the real thing
50842bdc
PP
238enum bt_notif_iter_notif_type {
239 BT_NOTIF_ITER_NOTIF_NEW_PACKET,
240 BT_NOTIF_ITER_NOTIF_END_OF_PACKET,
241 BT_NOTIF_ITER_NOTIF_EVENT,
e98a2d6e
PP
242};
243
50842bdc
PP
244struct bt_notif_iter_notif {
245 enum bt_notif_iter_notif_type type;
e98a2d6e
PP
246};
247
50842bdc
PP
248struct bt_notif_iter_notif_new_packet {
249 struct bt_notif_iter_notif base;
250 struct bt_packet *packet;
e98a2d6e
PP
251};
252
50842bdc
PP
253struct bt_notif_iter_notif_end_of_packet {
254 struct bt_notif_iter_notif base;
255 struct bt_packet *packet;
e98a2d6e
PP
256};
257
50842bdc
PP
258struct bt_notif_iter_notif_event {
259 struct bt_notif_iter_notif base;
260 struct bt_event *event;
e98a2d6e
PP
261};
262
e98a2d6e
PP
263/**
264 * Creates a CTF notification iterator.
265 *
266 * Upon successful completion, the reference count of \p trace is
267 * incremented.
268 *
269 * @param trace Trace to read
270 * @param max_request_sz Maximum buffer size, in bytes, to
271 * request to
50842bdc 272 * bt_notif_iter_medium_ops::request_bytes()
e98a2d6e
PP
273 * at a time
274 * @param medops Medium operations
275 * @param medops_data User data (passed to medium operations)
e98a2d6e
PP
276 * @returns New CTF notification iterator on
277 * success, or \c NULL on error
278 */
2cf1d51e 279BT_HIDDEN
50842bdc
PP
280struct bt_notif_iter *bt_notif_iter_create(struct bt_trace *trace,
281 size_t max_request_sz, struct bt_notif_iter_medium_ops medops,
55314f2a 282 void *medops_data);
e98a2d6e
PP
283
284/**
285 * Destroys a CTF notification iterator, freeing all internal resources.
286 *
287 * The registered trace's reference count is decremented.
288 *
289 * @param notif_iter CTF notification iterator
290 */
2cf1d51e 291BT_HIDDEN
50842bdc 292void bt_notif_iter_destroy(struct bt_notif_iter *notif_iter);
e98a2d6e 293
e98a2d6e
PP
294/**
295 * Returns the next notification from a CTF notification iterator.
296 *
50842bdc 297 * Upon successful completion, #BT_NOTIF_ITER_STATUS_OK is
e98a2d6e
PP
298 * returned, and the next notification is written to \p notif.
299 * In this case, the caller is responsible for calling
300 * bt_notification_put() on the returned notification.
301 *
50842bdc 302 * If this function returns #BT_NOTIF_ITER_STATUS_AGAIN, the caller
e98a2d6e
PP
303 * should make sure that data becomes available to its medium, and
304 * call this function again, until another status is returned.
305 *
306 * @param notif_iter CTF notification iterator
0982a26d
PP
307 * @param cc_prio_map Clock class priority map to use when
308 * creating an event notification
e98a2d6e 309 * @param notification Returned notification if the function's
50842bdc
PP
310 * return value is #BT_NOTIF_ITER_STATUS_OK
311 * @returns One of #bt_notif_iter_status values
e98a2d6e 312 */
2cf1d51e 313BT_HIDDEN
50842bdc
PP
314enum bt_notif_iter_status bt_notif_iter_get_next_notification(
315 struct bt_notif_iter *notit,
0982a26d 316 struct bt_clock_class_priority_map *cc_prio_map,
5c563278 317 struct bt_graph *graph,
78586d8a 318 struct bt_notification **notification);
e98a2d6e 319
87187cbf
PP
320/**
321 * Returns the first packet header and context fields. This function
312c056a 322 * never needs to call the `borrow_stream()` medium operation because
87187cbf
PP
323 * it does not create packet or event objects.
324 *
325 * @param notif_iter CTF notification iterator
326 * @param packet_header_field Packet header field (\c NULL if there's
327 * no packet header field)
328 * @param packet_context_field Packet context field (\c NULL if there's
329 * no packet context field)
50842bdc 330 * @returns One of #bt_notif_iter_status values
87187cbf
PP
331 */
332BT_HIDDEN
312c056a 333enum bt_notif_iter_status bt_notif_iter_borrow_packet_header_context_fields(
50842bdc
PP
334 struct bt_notif_iter *notit,
335 struct bt_field **packet_header_field,
336 struct bt_field **packet_context_field);
87187cbf 337
6de92955 338BT_HIDDEN
50842bdc 339void bt_notif_iter_set_medops_data(struct bt_notif_iter *notit,
6de92955
PP
340 void *medops_data);
341
9e0c8dbb 342BT_HIDDEN
50842bdc
PP
343enum bt_notif_iter_status bt_notif_iter_seek(
344 struct bt_notif_iter *notit, off_t offset);
9e0c8dbb
JG
345
346/*
347 * Get the current packet's offset in bytes relative to the media's initial
348 * position.
349 */
350BT_HIDDEN
50842bdc
PP
351off_t bt_notif_iter_get_current_packet_offset(
352 struct bt_notif_iter *notit);
9e0c8dbb
JG
353
354/* Get the current packet's size (in bits). */
355BT_HIDDEN
50842bdc
PP
356off_t bt_notif_iter_get_current_packet_size(
357 struct bt_notif_iter *notit);
9e0c8dbb 358
f42867e2
PP
359/*
360 * Resets the iterator so that the next requested medium bytes are
361 * assumed to be the first bytes of a new stream. The first notification
362 * which this iterator emits after calling bt_notif_iter_reset() is a
363 * BT_NOTIFICATION_TYPE_STREAM_BEGIN one.
364 */
365BT_HIDDEN
366void bt_notif_iter_reset(struct bt_notif_iter *notit);
367
fdf0e7a0 368static inline
50842bdc
PP
369const char *bt_notif_iter_medium_status_string(
370 enum bt_notif_iter_medium_status status)
fdf0e7a0
PP
371{
372 switch (status) {
50842bdc
PP
373 case BT_NOTIF_ITER_MEDIUM_STATUS_EOF:
374 return "BT_NOTIF_ITER_MEDIUM_STATUS_EOF";
375 case BT_NOTIF_ITER_MEDIUM_STATUS_AGAIN:
376 return "BT_NOTIF_ITER_MEDIUM_STATUS_AGAIN";
377 case BT_NOTIF_ITER_MEDIUM_STATUS_INVAL:
378 return "BT_NOTIF_ITER_MEDIUM_STATUS_INVAL";
379 case BT_NOTIF_ITER_MEDIUM_STATUS_ERROR:
380 return "BT_NOTIF_ITER_MEDIUM_STATUS_ERROR";
381 case BT_NOTIF_ITER_MEDIUM_STATUS_OK:
382 return "BT_NOTIF_ITER_MEDIUM_STATUS_OK";
fdf0e7a0
PP
383 default:
384 return "(unknown)";
385 }
386}
387
388static inline
50842bdc
PP
389const char *bt_notif_iter_status_string(
390 enum bt_notif_iter_status status)
fdf0e7a0
PP
391{
392 switch (status) {
50842bdc
PP
393 case BT_NOTIF_ITER_STATUS_EOF:
394 return "BT_NOTIF_ITER_STATUS_EOF";
395 case BT_NOTIF_ITER_STATUS_AGAIN:
396 return "BT_NOTIF_ITER_STATUS_AGAIN";
397 case BT_NOTIF_ITER_STATUS_INVAL:
398 return "BT_NOTIF_ITER_STATUS_INVAL";
399 case BT_NOTIF_ITER_STATUS_ERROR:
400 return "BT_NOTIF_ITER_STATUS_ERROR";
401 case BT_NOTIF_ITER_STATUS_OK:
402 return "BT_NOTIF_ITER_STATUS_OK";
fdf0e7a0
PP
403 default:
404 return "(unknown)";
405 }
406}
407
e98a2d6e 408#endif /* CTF_NOTIF_ITER_H */
This page took 0.060922 seconds and 4 git commands to generate.