df6053d52788af3fa88466738f129a806bdd7b15
[babeltrace.git] / include / babeltrace2 / graph / message-iterator-class.h
1 #ifndef BABELTRACE2_GRAPH_MESSAGE_ITERATOR_CLASS_H
2 #define BABELTRACE2_GRAPH_MESSAGE_ITERATOR_CLASS_H
3
4 /*
5 * Copyright (c) 2019 EfficiOS Inc.
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy
8 * of this software and associated documentation files (the "Software"), to deal
9 * in the Software without restriction, including without limitation the rights
10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11 * copies of the Software, and to permit persons to whom the Software is
12 * furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23 * SOFTWARE.
24 */
25
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
28 #endif
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34
35 /*!
36 @defgroup api-msg-iter-cls Message iterator class
37 @ingroup api-comp-cls-dev
38
39 @brief
40 \bt_c_msg_iter class.
41
42 A <strong><em>message iterator class</em></strong> is the class of a
43 \bt_msg_iter.
44
45 @image html msg-iter-cls.png
46
47 \bt_cp_src_comp_cls and \bt_p_flt_comp_cls contain a message iterator
48 class. For such a component class, its message iterator class is the
49 class of any message iterator created for any \bt_oport of the
50 component class's instances (\bt_p_comp).
51
52 Therefore, the only thing you can do with a message iterator class is to
53 pass it to bt_component_class_source_create() or
54 bt_component_class_filter_create() to set it as the created component
55 class's message iterator class.
56
57 A message iterator class has <em>methods</em>. This module essentially
58 offers:
59
60 - Message iterator class method type definitions.
61
62 - A message iterator class creation function, to which you must pass
63 the mandatory \link api-msg-iter-cls-meth-next "next" method\endlink.
64
65 - Functions to set optional message iterator class methods.
66
67 A message iterator class method is a user function. All message iterator
68 class methods operate on an instance (a \bt_msg_iter). The type of the
69 method's first parameter is #bt_self_message_iterator. This is similar
70 to an instance method in Python (where the instance object name is
71 generally <code>self</code>) or a member function in C++ (where the
72 instance pointer is named <code>this</code>), for example.
73
74 See \ref api-msg-iter-cls-methods "Methods" to learn more about the
75 different types of message iterator class methods.
76
77 A message iterator class is a
78 \ref api-fund-shared-object "shared object": get a new reference with
79 bt_message_iterator_class_get_ref() and put an existing reference with
80 bt_message_iterator_class_put_ref().
81
82 Some library functions \ref api-fund-freezing "freeze" message iterator
83 classes on success. The documentation of those functions indicate this
84 postcondition.
85
86 The type of a message iterator class is #bt_message_iterator_class.
87
88 Create a message iterator class with bt_message_iterator_class_create().
89 When you call this function, you must pass the message iterator
90 class's mandatory
91 \link api-msg-iter-cls-meth-next "next" method\endlink.
92
93 <h1>\anchor api-msg-iter-cls-methods Methods</h1>
94
95 To learn when exactly the methods below are called, see
96 \ref api-graph-lc "Trace processing graph life cycle" and
97 \ref api-msg-iter.
98
99 The available message iterator class methods to implement are:
100
101 <table>
102 <tr>
103 <th>Name
104 <th>Requirement
105 <th>C type
106 <tr>
107 <td>Can seek beginning?
108 <td>Optional
109 <td>#bt_message_iterator_class_can_seek_beginning_method
110 <tr>
111 <td>Can seek ns from origin?
112 <td>Optional
113 <td>#bt_message_iterator_class_can_seek_ns_from_origin_method
114 <tr>
115 <td>Finalize
116 <td>Optional
117 <td>#bt_message_iterator_class_finalize_method
118 <tr>
119 <td>Initialize
120 <td>Optional
121 <td>#bt_message_iterator_class_initialize_method
122 <tr>
123 <td>Next
124 <td>Mandatory
125 <td>#bt_message_iterator_class_next_method
126 <tr>
127 <td>Seek beginning
128 <td>Optional
129 <td>#bt_message_iterator_class_seek_beginning_method
130 <tr>
131 <td>Seek ns from origin
132 <td>Optional
133 <td>#bt_message_iterator_class_seek_ns_from_origin_method
134 </table>
135
136 <dl>
137 <dt>
138 \anchor api-msg-iter-cls-meth-can-seek-beg
139 Can seek beginning?
140 </dt>
141 <dd>
142 Called to check whether or not your \bt_msg_iter can currently
143 seek its beginning (the very first message of its
144 \ref api-msg-seq "sequence").
145
146 There are some use cases in which a message iterator cannot always
147 seek its beginning, depending on its state.
148
149 If you don't implement this method, then, if you implement the
150 \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method, the
151 library assumes that your message iterator can always seek its
152 beginning.
153
154 The message iterator of a \bt_flt_comp will typically consider
155 the beginning seeking capability of its own upstream message
156 iterator(s) (with bt_message_iterator_can_seek_beginning()) in this
157 method's implementation.
158
159 If you need to block the thread to compute whether or not your
160 message iterator can seek its beginning, you can instead report to
161 try again later to the caller by returning
162 #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
163
164 Set this optional method with the \bt_p{can_seek_method} parameter
165 of bt_message_iterator_class_set_seek_beginning_methods().
166 </dd>
167
168 <dt>
169 \anchor api-msg-iter-cls-meth-can-seek-ns
170 Can seek ns from origin?
171 </dt>
172 <dd>
173 Called to check whether or not your \bt_msg_iter can currently
174 seek a message occurring at or after a specific time given in
175 nanoseconds from its
176 \ref api-tir-clock-cls-origin "clock class origin".
177
178 There are some use cases in which a message iterator cannot always
179 seek some specific time, depending on its state.
180
181 Within this method, your receive the specific time to seek as the
182 \bt_p{ns_from_origin} parameter. You don't receive any
183 \bt_clock_cls: the method operates at the nanosecond from some
184 origin level and it is left to the implementation to decide whether
185 or not the message iterator can seek this point in time.
186
187 If you don't implement this method, then, if you implement the
188 \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method, the
189 library assumes that your message iterator can always seek any
190 message occurring at or after any time.
191
192 The message iterator of a \bt_flt_comp will typically consider
193 the time seeking capability of its own upstream message
194 iterator(s) (with bt_message_iterator_can_seek_ns_from_origin()) in
195 this method's implementation.
196
197 If you need to block the thread to compute whether or not your
198 message iterator can seek a message occurring at or after a given
199 time, you can instead report to try again later to the caller by
200 returning
201 #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
202
203 Set this optional method with the \bt_p{can_seek_method} parameter
204 of bt_message_iterator_class_set_seek_ns_from_origin_methods().
205 </dd>
206
207 <dt>
208 \anchor api-msg-iter-cls-meth-fini
209 Finalize
210 </dt>
211 <dd>
212 Called to finalize your \bt_msg_iter, that is, to let you
213 destroy/free/finalize any user data you have (retrieved with
214 bt_self_message_iterator_get_data()).
215
216 The \bt_name library does not specify exactly when this method is
217 called, but guarantees that it's called before the message iterator
218 is destroyed.
219
220 The library guarantees that all message iterators are destroyed
221 before their component is destroyed.
222
223 This method is \em not called if the message iterator's
224 \ref api-msg-iter-cls-meth-init "initialization method"
225 previously returned an error status code.
226
227 Set this optional method with
228 bt_message_iterator_class_set_finalize_method().
229 </dd>
230
231 <dt>
232 \anchor api-msg-iter-cls-meth-init
233 Initialize
234 </dt>
235 <dd>
236 Called within bt_message_iterator_create_from_message_iterator()
237 or bt_message_iterator_create_from_sink_component() to initialize
238 your \bt_msg_iter.
239
240 Within this method, you can access your \bt_comp's user data
241 by first borrowing it with
242 bt_self_message_iterator_borrow_component() and then using
243 bt_self_component_get_data().
244
245 For the message iterator of a \bt_flt_comp, this method is
246 typically where you create an upstream \bt_msg_iter
247 with bt_message_iterator_create_from_message_iterator().
248
249 You can create user data and set it as the \bt_self_msg_iter's user
250 data with bt_self_message_iterator_set_data().
251
252 If you return #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
253 from this method, then your message iterator's
254 \ref api-msg-iter-cls-meth-fini "finalization method" will be
255 called, if it exists, when your message iterator is finalized.
256
257 This method receives a message iterator configuration object
258 (#bt_self_message_iterator_configuration type). As of
259 \bt_name_version_min_maj, you can use
260 bt_self_message_iterator_configuration_set_can_seek_forward()
261 during, and only during, this method's execution to set whether or
262 not your message iterator can <em>seek forward</em>.
263
264 For a message iterator to be able to seek forward, all the \bt_p_msg
265 of its message sequence must have some \bt_cs.
266 bt_message_iterator_seek_ns_from_origin() uses this configuration
267 option and the beginning seeking capability of a message iterator
268 (bt_message_iterator_can_seek_beginning())
269 to make it seek a message occurring at or after a specific time even
270 when the message iterator does not implement the
271 \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
272
273 Set this optional method with
274 bt_message_iterator_class_set_initialize_method().
275 </dd>
276
277 <dt>
278 \anchor api-msg-iter-cls-meth-next
279 "Next" (get next messages)
280 </dt>
281 <dd>
282 Called within bt_message_iterator_next()
283 to "advance" your \bt_msg_iter, that is, to get its next
284 messages.
285
286 Within this method, you receive:
287
288 - An array of \bt_p_msg to fill (\bt_p{messages} parameter)
289 with your message iterator's next messages, if any.
290
291 Note that this array needs its own message
292 \ref api-fund-shared-object "references". In other
293 words, if you have a message reference and you put this message
294 into the array without calling bt_message_get_ref(), then you just
295 \em moved the message reference to the array (the array owns the
296 message now).
297
298 - The capacity of the message array (\bt_p{capacity} parameter),
299 that is, the maximum number of messages you can put in it.
300
301 - A message count output parameter (\bt_p{count}) which, on success,
302 you must set to the number of messages you put in the message
303 array.
304
305 If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
306 from this method, then you must put at least one message in the
307 message array. In other words, \bt_p{*count} must be greater than
308 zero.
309
310 You must honour the \ref api-msg-seq "message sequence rules" when
311 you put new or existing messages in the message array.
312
313 If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
314 then all the messages of the message array become
315 \ref api-fund-freezing "frozen".
316
317 This method typically:
318
319 <dl>
320 <dt>For a \bt_src_comp's message iterator</dt>
321 <dd>
322 Creates brand new \bt_p_msg to represent one or more input
323 traces.
324 </dd>
325
326 <dt>For a \bt_flt_comp's message iterator</dt>
327 <dd>
328 Gets \em one message batch from one (or more) upstream
329 \bt_msg_iter and filters them.
330 </dd>
331 </dl>
332
333 For a source component's message iterator, you are free to create
334 as many as \bt_p{capacity} messages. For a filter component's
335 message iterator, you are free to get more than one batch of
336 messages from upstream message iterators if needed. However, in both
337 cases, keep in mind that the \bt_name project recommends that this
338 method executes fast enough so as not to block an interactive
339 application running on the same thread.
340
341 During what you consider to be a long, blocking operation, the
342 project recommends that you periodically check whether or not you
343 are interrupted with bt_self_message_iterator_is_interrupted(). When
344 you are, you can return either
345 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN or
346 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR, depending on
347 your capability to continue the current operation later.
348
349 If you need to block the thread to insert messages into the message
350 array, you can instead report to try again later to the caller by
351 returning #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN.
352 When you return this status code, you must \em not put any message
353 into the message array.
354
355 If your message iterator's iteration process is done (you have no
356 more messages to emit), then return
357 #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END. When you return
358 this status code, you must \em not put any message into the message
359 array.
360
361 Set this mandatory method at message iterator class creation time
362 with bt_message_iterator_class_create().
363 </dd>
364
365 <dt>
366 \anchor api-msg-iter-cls-meth-seek-beg
367 Seek beginning
368 </dt>
369 <dd>
370 Called within bt_message_iterator_seek_beginning() to make
371 your message iterator seek its beginning, that is, the very first
372 message of its \ref api-msg-seq "sequence".
373
374 The sequence of messages of a given message iterator must always be
375 the same, in that, if your message iterator emitted the messages A,
376 B, C, D, and E, and then this "seek beginning" method is called
377 successfully
378 (it returns
379 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK),
380 then your message iterator's next messages (the next time your
381 \link api-msg-iter-cls-meth-next "next" method\endlink
382 is called) must be A, B, C, D, and E.
383
384 The \bt_name project recommends that this method executes fast
385 enough so as not to block an interactive application running on the
386 same thread.
387
388 During what you consider to be a long, blocking operation, the
389 project recommends that you periodically check whether or not you
390 are interrupted with bt_self_message_iterator_is_interrupted(). When
391 you are, you can return either
392 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN or
393 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR,
394 depending on your capability to continue the current operation
395 later.
396
397 If you need to block the thread to make your message iterator seek
398 its beginning, you can instead report to try again later to the
399 caller by returning
400 #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
401
402 The optional
403 \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
404 method can indicate whether or not your message iterator can
405 currently seek its beginning. If you implement it, the library
406 guarantees that it is called and returns #BT_TRUE before this "seek
407 beginning" is called, without any other message iterator methods
408 being called in between.
409
410 Set this optional method with the \bt_p{seek_method} parameter
411 of bt_message_iterator_class_set_seek_beginning_methods().
412 </dd>
413
414 <dt>
415 \anchor api-msg-iter-cls-meth-seek-ns
416 Seek ns from origin
417 </dt>
418 <dd>
419 Called within bt_message_iterator_seek_ns_from_origin() to make
420 your message iterator seek a message occurring at or after a specific
421 time given in nanoseconds from its
422 \ref api-tir-clock-cls-origin "clock class origin".
423
424 Within this method, your receive the specific time to seek as the
425 \bt_p{ns_from_origin} parameter. You don't receive any
426 \bt_clock_cls: the method operates at the nanosecond from some
427 origin level and it is left to the implementation to seek a message
428 having at least this time while still honouring the
429 \ref api-msg-seq "message sequence rules" the next time your
430 \link api-msg-iter-cls-meth-next "next" method\endlink is called.
431
432 If you return
433 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK from
434 this method, then the next time your
435 \link api-msg-iter-cls-meth-next "next" method\endlink is called:
436
437 - For each "active" \bt_stream at the seeked time point, you must
438 emit a \bt_sb_msg for this stream before you emit any other
439 message for this stream.
440
441 The stream beginning message must have a
442 \ref api-msg-sb-prop-cs "default clock snapshot" which corresponds
443 to the seeked time point.
444
445 - For each "active" \bt_pkt at the seeked time point, you must
446 emit a \bt_pb_msg for this packet before you emit any other
447 message for this packet.
448
449 The packet beginning message must have a
450 \ref api-msg-pb-prop-cs "default clock snapshot" which corresponds
451 to the seeked time point.
452
453 The \bt_name project recommends that this method executes fast
454 enough so as not to block an interactive application running on the
455 same thread.
456
457 During what you consider to be a long, blocking operation, the
458 project recommends that you periodically check whether or not you
459 are interrupted with bt_self_message_iterator_is_interrupted(). When
460 you are, you can return either
461 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
462 or
463 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR,
464 depending on your capability to continue the current operation
465 later.
466
467 If you need to block the thread to make your message iterator seek a
468 message occurring at or after a given time, you can instead report to
469 try again later to the caller by returning
470 #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
471
472 The optional
473 \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
474 method can indicate whether or not your message iterator can
475 currently seek a specific time. If you implement it, the library
476 guarantees that it is called and returns #BT_TRUE before this "seek
477 ns from origin" is called, without any other message iterator
478 methods being called in between.
479
480 Set this optional method with the \bt_p{seek_method} parameter
481 of bt_message_iterator_class_set_seek_ns_from_origin_methods().
482 </dd>
483 </dl>
484
485 Within any method, you can access the \bt_msg_iter's \bt_comp's
486 configured \ref #bt_logging_level "logging level" by first upcasting the
487 \bt_self_comp to the #bt_component type with
488 bt_self_component_as_component(), and then with
489 bt_component_get_logging_level().
490 */
491
492 /*! @{ */
493
494 /*!
495 @name Type
496 @{
497
498 @typedef struct bt_message_iterator_class bt_message_iterator_class;
499
500 @brief
501 Message iterator class.
502
503 @}
504 */
505
506 /*!
507 @name Method types
508 @{
509 */
510
511 /*!
512 @brief
513 Status codes for #bt_message_iterator_class_can_seek_beginning_method.
514 */
515 typedef enum bt_message_iterator_class_can_seek_beginning_method_status {
516 /*!
517 @brief
518 Success.
519 */
520 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
521
522 /*!
523 @brief
524 Try again.
525 */
526 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
527
528 /*!
529 @brief
530 Out of memory.
531 */
532 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
533
534 /*!
535 @brief
536 User error.
537 */
538 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
539 } bt_message_iterator_class_can_seek_beginning_method_status;
540
541 /*!
542 @brief
543 \bt_c_msg_iter "can seek beginning?" method.
544
545 See the \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
546 method.
547
548 @param[in] self_message_iterator
549 Message iterator instance.
550 @param[out] can_seek_beginning
551 <strong>On success</strong>, \bt_p{*can_seek_beginning} is
552 #BT_TRUE if \bt_p{self_message_iterator} can currently seek its
553 beginning.
554
555 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK
556 Success.
557 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN
558 Try again.
559 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
560 Out of memory.
561 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR
562 User error.
563
564 @bt_pre_not_null{self_message_iterator}
565 @bt_pre_not_null{can_seek_beginning}
566
567 @post
568 <strong>On success</strong>, \bt_p{*can_seek_beginning} is set.
569
570 @sa bt_message_iterator_class_set_seek_beginning_methods() &mdash;
571 Sets the "seek beginning" and "can seek beginning?" methods of a
572 message iterator class.
573 */
574 typedef bt_message_iterator_class_can_seek_beginning_method_status
575 (*bt_message_iterator_class_can_seek_beginning_method)(
576 bt_self_message_iterator *self_message_iterator,
577 bt_bool *can_seek_beginning);
578
579 /*!
580 @brief
581 Status codes for #bt_message_iterator_class_can_seek_ns_from_origin_method.
582 */
583 typedef enum bt_message_iterator_class_can_seek_ns_from_origin_method_status {
584 /*!
585 @brief
586 Success.
587 */
588 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
589
590 /*!
591 @brief
592 Try again.
593 */
594 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
595
596 /*!
597 @brief
598 Out of memory.
599 */
600 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
601
602 /*!
603 @brief
604 User error.
605 */
606 BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
607 } bt_message_iterator_class_can_seek_ns_from_origin_method_status;
608
609 /*!
610 @brief
611 \bt_c_msg_iter "can seek ns from origin?" method.
612
613 See the \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
614 method.
615
616 @param[in] self_message_iterator
617 Message iterator instance.
618 @param[in] ns_from_origin
619 Requested time point to seek.
620 @param[out] can_seek_ns_from_origin
621 <strong>On success</strong>, set \bt_p{*can_seek_ns_from_origin} to
622 #BT_TRUE if \bt_p{self_message_iterator} can currently seek a
623 message occurring at or after \bt_p{ns_from_origin} nanoseconds from
624 its \ref api-tir-clock-cls-origin "clock class origin".
625
626 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
627 Success.
628 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
629 Try again.
630 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
631 Out of memory.
632 @retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
633 User error.
634
635 @bt_pre_not_null{self_message_iterator}
636 @bt_pre_not_null{can_seek_ns_from_origin}
637
638 @post
639 <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is set.
640
641 @sa bt_message_iterator_class_set_seek_ns_from_origin_methods() &mdash;
642 Sets the "seek ns from origin" and "can seek ns from origin?"
643 methods of a message iterator class.
644 */
645 typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status
646 (*bt_message_iterator_class_can_seek_ns_from_origin_method)(
647 bt_self_message_iterator *self_message_iterator,
648 int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
649
650 /*!
651 @brief
652 \bt_c_msg_iter finalization method.
653
654 See the \ref api-msg-iter-cls-meth-fini "finalize" method.
655
656 @param[in] self_message_iterator
657 Message iterator instance.
658
659 @bt_pre_not_null{self_message_iterator}
660
661 @bt_post_no_error
662
663 @sa bt_message_iterator_class_set_finalize_method() &mdash;
664 Sets the finalization method of a message iterator class.
665 */
666 typedef void
667 (*bt_message_iterator_class_finalize_method)(
668 bt_self_message_iterator *self_message_iterator);
669
670 /*!
671 @brief
672 Status codes for #bt_message_iterator_class_initialize_method.
673 */
674 typedef enum bt_message_iterator_class_initialize_method_status {
675 /*!
676 @brief
677 Success.
678 */
679 BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
680
681 /*!
682 @brief
683 Out of memory.
684 */
685 BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
686
687 /*!
688 @brief
689 User error.
690 */
691 BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
692 } bt_message_iterator_class_initialize_method_status;
693
694 /*!
695 @brief
696 \bt_c_msg_iter initialization method.
697
698 See the \ref api-msg-iter-cls-meth-init "initialize" method.
699
700 @param[in] self_message_iterator
701 Message iterator instance.
702 @param[in] configuration
703 Message iterator's configuration.
704 @param[in] port
705 \bt_c_oport for which \bt_p{self_message_iterator} was created.
706
707 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
708 Success.
709 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
710 Out of memory.
711 @retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR
712 User error.
713
714 @bt_pre_not_null{self_message_iterator}
715 @bt_pre_not_null{configuration}
716 @bt_pre_not_null{port}
717
718 @sa bt_message_iterator_class_set_initialize_method() &mdash;
719 Sets the initialization method of a message iterator class.
720 */
721 typedef bt_message_iterator_class_initialize_method_status
722 (*bt_message_iterator_class_initialize_method)(
723 bt_self_message_iterator *self_message_iterator,
724 bt_self_message_iterator_configuration *configuration,
725 bt_self_component_port_output *port);
726
727 /*!
728 @brief
729 Status codes for #bt_message_iterator_class_next_method.
730 */
731 typedef enum bt_message_iterator_class_next_method_status {
732 /*!
733 @brief
734 Success.
735 */
736 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
737
738 /*!
739 @brief
740 End of iteration.
741 */
742 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END = __BT_FUNC_STATUS_END,
743
744 /*!
745 @brief
746 Try again.
747 */
748 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
749
750 /*!
751 @brief
752 Out of memory.
753 */
754 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
755
756 /*!
757 @brief
758 User error.
759 */
760 BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
761 } bt_message_iterator_class_next_method_status;
762
763 /*!
764 @brief
765 \bt_c_msg_iter "next" (get next messages) method.
766
767 See the \link api-msg-iter-cls-meth-next "next"\endlink method.
768
769 If this method returns #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
770 then all the messages of the message array become
771 \ref api-fund-freezing "frozen".
772
773 @param[in] self_message_iterator
774 Message iterator instance.
775 @param[out] messages
776 @parblock
777 Message array to fill, on success, with the \bt_p_msg to emit.
778
779 This array needs its own message
780 \ref api-fund-shared-object "references". In other
781 words, if you have a message reference and you put this message
782 into the array without calling bt_message_get_ref(), then you just
783 \em moved the message reference to the array (the array owns the
784 message now).
785
786 The capacity of this array (maximum number of messages you can put
787 in it) is \bt_p{capacity}.
788 @endparblock
789 @param[in] capacity
790 Capacity of the \bt_p{messages} array (maximum number of messages
791 you can put in it).
792 @param[out] count
793 <strong>On success</strong>, \bt_p{*count} is the number of messages
794 you put in \bt_p{messages}.
795
796 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
797 Success.
798 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END
799 End of iteration.
800 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN
801 Try again.
802 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR
803 Out of memory.
804 @retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR
805 User error.
806
807 @bt_pre_not_null{self_message_iterator}
808 @bt_pre_not_null{messages}
809 @pre
810 \bt_p{capacity} ≥ 1.
811 @bt_pre_not_null{count}
812
813 @post
814 <strong>On success</strong>, \bt_p{messages} contains \bt_p{*count}
815 message references as its first \bt_p{*count} elements.
816 @post
817 <strong>On success</strong>, the \bt_p_msg in \bt_p{messages} honour
818 the \ref api-msg-seq "message sequence rules".
819 @post
820 <strong>On success</strong>, for any \bt_ev_msg in
821 \bt_p{messages}, its
822 \ref api-tir-ev-prop-payload "payload field",
823 \ref api-tir-ev-prop-spec-ctx "specific context field",
824 \ref api-tir-ev-prop-common-ctx "common context field", and all
825 their inner \bt_p_field, recursively, are set.
826 @post
827 <strong>On success</strong>, \bt_p{*count}&nbsp;≥&nbsp;1.
828 @post
829 <strong>On success</strong>,
830 \bt_p{*count}&nbsp;≤&nbsp;\bt_p{capacity}.
831
832 @sa bt_message_iterator_class_create() &mdash;
833 Creates a message iterator class.
834 */
835 typedef bt_message_iterator_class_next_method_status
836 (*bt_message_iterator_class_next_method)(
837 bt_self_message_iterator *self_message_iterator,
838 bt_message_array_const messages, uint64_t capacity,
839 uint64_t *count);
840
841 /*!
842 @brief
843 Status codes for #bt_message_iterator_class_seek_beginning_method.
844 */
845 typedef enum bt_message_iterator_class_seek_beginning_method_status {
846 /*!
847 @brief
848 Success.
849 */
850 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
851
852 /*!
853 @brief
854 Try again.
855 */
856 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
857
858 /*!
859 @brief
860 Out of memory.
861 */
862 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
863
864 /*!
865 @brief
866 User error.
867 */
868 BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
869 } bt_message_iterator_class_seek_beginning_method_status;
870
871 /*!
872 @brief
873 \bt_c_msg_iter "seek beginning" method.
874
875 See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method.
876
877 @param[in] self_message_iterator
878 Message iterator instance.
879
880 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK
881 Success.
882 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN
883 Try again.
884 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
885 Out of memory.
886 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR
887 User error.
888
889 @bt_pre_not_null{self_message_iterator}
890 @pre
891 <strong>If \bt_p{self_message_iterator} has a
892 \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
893 method</strong>, then it was called and returned #BT_TRUE before
894 this "seek beginning" method is called, without any other method of
895 \bt_p{self_message_iterator} called in between.
896
897 @sa bt_message_iterator_class_set_seek_beginning_methods() &mdash;
898 Sets the "seek beginning" and "can seek beginning?" methods of a
899 message iterator class.
900 */
901 typedef bt_message_iterator_class_seek_beginning_method_status
902 (*bt_message_iterator_class_seek_beginning_method)(
903 bt_self_message_iterator *self_message_iterator);
904
905 /*!
906 @brief
907 Status codes for #bt_message_iterator_class_seek_ns_from_origin_method.
908 */
909 typedef enum bt_message_iterator_class_seek_ns_from_origin_method_status {
910 /*!
911 @brief
912 Success.
913 */
914 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
915
916 /*!
917 @brief
918 Try again.
919 */
920 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
921
922 /*!
923 @brief
924 Out of memory.
925 */
926 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
927
928 /*!
929 @brief
930 User error.
931 */
932 BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
933 } bt_message_iterator_class_seek_ns_from_origin_method_status;
934
935 /*!
936 @brief
937 \bt_c_msg_iter "seek ns from origin" method.
938
939 See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
940
941 @param[in] self_message_iterator
942 Message iterator instance.
943 @param[in] ns_from_origin
944 Time point to seek.
945
946 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
947 Success.
948 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
949 Try again.
950 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
951 Out of memory.
952 @retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
953 User error.
954
955 @bt_pre_not_null{self_message_iterator}
956 @pre
957 <strong>If \bt_p{self_message_iterator} has a
958 \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
959 method</strong>, then it was called and returned #BT_TRUE before
960 this "seek ns from origin" method is called, without any other
961 method of \bt_p{self_message_iterator} called in between.
962
963 @sa bt_message_iterator_class_set_seek_ns_from_origin_methods() &mdash;
964 Sets the "seek ns from origin" and "can seek ns from origin?"
965 methods of a message iterator class.
966 */
967 typedef bt_message_iterator_class_seek_ns_from_origin_method_status
968 (*bt_message_iterator_class_seek_ns_from_origin_method)(
969 bt_self_message_iterator *self_message_iterator,
970 int64_t ns_from_origin);
971
972 /*! @} */
973
974 /*!
975 @name Creation
976 @{
977 */
978
979 /*!
980 @brief
981 Creates a message iterator class having the
982 \link api-msg-iter-cls-meth-next "next" method\endlink method
983 \bt_p{next_method}.
984
985 @param[in] next_method
986 "Next" method of the message iterator class to create.
987
988 @returns
989 New message iterator class reference, or \c NULL on memory error.
990
991 @bt_pre_not_null{next_method}
992 */
993 extern bt_message_iterator_class *
994 bt_message_iterator_class_create(
995 bt_message_iterator_class_next_method next_method);
996
997 /*! @} */
998
999 /*!
1000 @name Method setting
1001 @{
1002 */
1003
1004 /*!
1005 @brief
1006 Status code for the
1007 <code>bt_message_iterator_class_set_*_method()</code> functions.
1008 */
1009 typedef enum bt_message_iterator_class_set_method_status {
1010 /*!
1011 @brief
1012 Success.
1013 */
1014 BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK,
1015 } bt_message_iterator_class_set_method_status;
1016
1017 /*!
1018 @brief
1019 Sets the optional finalization method of the message iterator class
1020 \bt_p{message_iterator_class} to \bt_p{method}.
1021
1022 See the \ref api-msg-iter-cls-meth-fini "finalize" method.
1023
1024 @param[in] message_iterator_class
1025 Message iterator class of which to set the finalization method to
1026 \bt_p{method}.
1027 @param[in] method
1028 New finalization method of \bt_p{message_iterator_class}.
1029
1030 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1031 Success.
1032
1033 @bt_pre_not_null{message_iterator_class}
1034 @bt_pre_hot{message_iterator_class}
1035 @bt_pre_not_null{method}
1036 */
1037 extern bt_message_iterator_class_set_method_status
1038 bt_message_iterator_class_set_finalize_method(
1039 bt_message_iterator_class *message_iterator_class,
1040 bt_message_iterator_class_finalize_method method);
1041
1042 /*!
1043 @brief
1044 Sets the optional initialization method of the message iterator
1045 class \bt_p{message_iterator_class} to \bt_p{method}.
1046
1047 See the \ref api-msg-iter-cls-meth-init "initialize" method.
1048
1049 @param[in] message_iterator_class
1050 Message iterator class of which to set the initialization method to
1051 \bt_p{method}.
1052 @param[in] method
1053 New initialization method of \bt_p{message_iterator_class}.
1054
1055 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1056 Success.
1057
1058 @bt_pre_not_null{message_iterator_class}
1059 @bt_pre_hot{message_iterator_class}
1060 @bt_pre_not_null{method}
1061 */
1062 extern bt_message_iterator_class_set_method_status
1063 bt_message_iterator_class_set_initialize_method(
1064 bt_message_iterator_class *message_iterator_class,
1065 bt_message_iterator_class_initialize_method method);
1066
1067 /*!
1068 @brief
1069 Sets the optional "seek beginning" and
1070 "can seek beginning?" methods of the message iterator class
1071 \bt_p{message_iterator_class} to \bt_p{seek_method} and
1072 \bt_p{can_seek_method}.
1073
1074 See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning"
1075 and \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
1076 methods.
1077
1078 @param[in] message_iterator_class
1079 Message iterator class of which to set the "seek beginning"
1080 and "can seek beginning?" methods.
1081 @param[in] seek_method
1082 New "seek beginning" method of \bt_p{message_iterator_class}.
1083 @param[in] can_seek_method
1084 @parblock
1085 New "can seek beginning?" method of \bt_p{message_iterator_class}.
1086
1087 Can be \c NULL, in which case it is equivalent to setting a method
1088 which always returns #BT_TRUE.
1089 @endparblock
1090
1091 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1092 Success.
1093
1094 @bt_pre_not_null{message_iterator_class}
1095 @bt_pre_hot{message_iterator_class}
1096 @bt_pre_not_null{seek_method}
1097 */
1098 extern bt_message_iterator_class_set_method_status
1099 bt_message_iterator_class_set_seek_beginning_methods(
1100 bt_message_iterator_class *message_iterator_class,
1101 bt_message_iterator_class_seek_beginning_method seek_method,
1102 bt_message_iterator_class_can_seek_beginning_method can_seek_method);
1103
1104 /*!
1105 @brief
1106 Sets the optional "seek ns from origin" and
1107 "can seek ns from origin?" methods of the message iterator class
1108 \bt_p{message_iterator_class} to \bt_p{seek_method} and
1109 \bt_p{can_seek_method}.
1110
1111 See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin"
1112 and
1113 \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
1114 methods.
1115
1116 @param[in] message_iterator_class
1117 Message iterator class of which to set the "seek ns from origin"
1118 and "can seek ns from origin?" methods.
1119 @param[in] seek_method
1120 New "seek ns from origin" method of \bt_p{message_iterator_class}.
1121 @param[in] can_seek_method
1122 @parblock
1123 New "can seek ns from origin?" method of
1124 \bt_p{message_iterator_class}.
1125
1126 Can be \c NULL, in which case it is equivalent to setting a method
1127 which always returns #BT_TRUE.
1128 @endparblock
1129
1130 @retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
1131 Success.
1132
1133 @bt_pre_not_null{message_iterator_class}
1134 @bt_pre_hot{message_iterator_class}
1135 @bt_pre_not_null{seek_method}
1136 */
1137 extern bt_message_iterator_class_set_method_status
1138 bt_message_iterator_class_set_seek_ns_from_origin_methods(
1139 bt_message_iterator_class *message_iterator_class,
1140 bt_message_iterator_class_seek_ns_from_origin_method seek_method,
1141 bt_message_iterator_class_can_seek_ns_from_origin_method can_seek_method);
1142
1143 /*! @} */
1144
1145 /*!
1146 @name Reference count
1147 @{
1148 */
1149
1150 /*!
1151 @brief
1152 Increments the \ref api-fund-shared-object "reference count" of
1153 the message iterator class \bt_p{message_iterator_class}.
1154
1155 @param[in] message_iterator_class
1156 @parblock
1157 Message iterator class of which to increment the reference count.
1158
1159 Can be \c NULL.
1160 @endparblock
1161
1162 @sa bt_component_put_ref() &mdash;
1163 Decrements the reference count of a message iterator class.
1164 */
1165 extern void bt_message_iterator_class_get_ref(
1166 const bt_message_iterator_class *message_iterator_class);
1167
1168 /*!
1169 @brief
1170 Decrements the \ref api-fund-shared-object "reference count" of
1171 the message iterator class \bt_p{message_iterator_class}.
1172
1173 @param[in] message_iterator_class
1174 @parblock
1175 Message iterator class of which to decrement the reference count.
1176
1177 Can be \c NULL.
1178 @endparblock
1179
1180 @sa bt_component_get_ref() &mdash;
1181 Increments the reference count of a message iterator class.
1182 */
1183 extern void bt_message_iterator_class_put_ref(
1184 const bt_message_iterator_class *message_iterator_class);
1185
1186 /*!
1187 @brief
1188 Decrements the reference count of the message iterator class
1189 \bt_p{_message_iterator_class}, and then sets
1190 \bt_p{_message_iterator_class} to \c NULL.
1191
1192 @param _message_iterator_class
1193 @parblock
1194 Message iterator class of which to decrement the reference count.
1195
1196 Can contain \c NULL.
1197 @endparblock
1198
1199 @bt_pre_assign_expr{_message_iterator_class}
1200 */
1201 #define BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET(_message_iterator_class) \
1202 do { \
1203 bt_message_iterator_class_put_ref(_message_iterator_class); \
1204 (_message_iterator_class) = NULL; \
1205 } while (0)
1206
1207 /*!
1208 @brief
1209 Decrements the reference count of the message iterator class \bt_p{_dst},
1210 sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src}
1211 to \c NULL.
1212
1213 This macro effectively moves a message iterator class reference from the
1214 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
1215 existing \bt_p{_dst} reference.
1216
1217 @param _dst
1218 @parblock
1219 Destination expression.
1220
1221 Can contain \c NULL.
1222 @endparblock
1223 @param _src
1224 @parblock
1225 Source expression.
1226
1227 Can contain \c NULL.
1228 @endparblock
1229
1230 @bt_pre_assign_expr{_dst}
1231 @bt_pre_assign_expr{_src}
1232 */
1233 #define BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF(_dst, _src) \
1234 do { \
1235 bt_message_iterator_class_put_ref(_dst); \
1236 (_dst) = (_src); \
1237 (_src) = NULL; \
1238 } while (0)
1239
1240 /*! @} */
1241
1242 /*! @} */
1243
1244 #ifdef __cplusplus
1245 }
1246 #endif
1247
1248 #endif /* BABELTRACE2_GRAPH_MESSAGE_ITERATOR_CLASS_H */
This page took 0.054081 seconds and 3 git commands to generate.