1 // Render with Asciidoctor
3 = Babeltrace{nbsp}2 contributor's guide
4 Jérémie Galarneau, Philippe Proulx
10 :bt2: Babeltrace{nbsp}2
15 This is a partial contributor's guide for the
16 https://babeltrace.org[{bt2}] project. If you have any
17 questions that are not answered by this guide, please post them on
18 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's
23 === Object reference counting and lifetime
25 This section covers the rationale behind the design of {bt2}'s
26 object lifetime management. This applies to the {bt2} library, as
27 well as to the CTF writer library (although the public reference
28 counting functions are not named the same way).
30 Starting from Babeltrace{nbsp}2.0, all publicly exposed objects inherit
31 a common base: `bt_object`. This base provides a number of facilities to
32 all objects, chief amongst which are lifetime management functions.
34 The lifetime of some public objects is managed by reference counting. In
35 this case, the API offers the `+bt_*_get_ref()+` and `+bt_*_put_ref()+`
36 functions which respectively increment and decrement an object's
39 As far as lifetime management in concerned, {bt2} makes a clear
40 distinction between regular objects, which have a single parent, and
41 root objects, which don't.
45 Let us consider a problematic case to illustrate the need for this
48 A user of the {bt2} library creates a trace class, which _has_ a
49 stream class (the class of a stream) and that stream class, in turn,
50 _has_ an event class (the class of an event).
52 Nothing prevents this user from releasing his reference on any one of
53 these objects in any order. However, all objects in the
54 __trace--stream class--event class__ hierarchy can be retrieved
57 For instance, the user could discard his reference on both the event
58 class and the stream class, only keeping a reference on the trace class.
59 From this trace class reference, stream classes can be enumerated,
60 providing the user with a new reference to the stream class he discarded
61 earlier. Event classes can also be enumerated from stream classes,
62 providing the user with references to the individual event classes.
64 Conversely, the user could also hold a reference to an event class and
65 retrieve its parent stream class. The trace class, in turn, can then be
66 retrieved from the stream class.
68 This example illustrates what could be interpreted as a circular
69 reference dependency existing between these objects. Of course, if the
70 objects in such a scenario were to hold references to each other (in
71 both directions), we would be in presence of a circular ownership
72 resulting in a leak of both objects as their reference counts would
75 Nonetheless, the API must offer the guarantee that holding a node to any
76 node of the graph keeps all other reachable nodes alive.
80 The scheme employed in {bt2} to break this cycle consists in the
81 "children" holding _reverse component references_ to their parents. That
82 is, in the context of the trace IR, that event classes hold a reference
83 to their parent stream class and stream classes hold a reference to
84 their parent trace class.
86 On the other hand, parents hold _claiming aggregation references_ to
87 their children. A claiming aggregation reference means that the object
88 being referenced should not be deleted as long as the reference still
89 exists. In this respect, it can be said that parents truly hold the
90 ownership of their children, since they control their lifetime.
91 Conversely, the reference counting mechanism is leveraged by children to
92 notify parents that no other child indirectly exposes the parent.
94 When a parented object's reference count reaches zero, it invokes
95 `+bt_*_put_ref()+` on its parent and does _not_ free itself. However,
96 from that point, the object depends on its parent to signal the moment
97 when it can be safely reclaimed.
99 The invocation of `+bt_*_put_ref()+` by the last children holding a
100 reference to its parent might trigger a cascade of `+bt_*_put_ref()+`
101 from child to parent. Eventually, a **root** object is reached. At that
102 point, if this orphaned object's reference count reaches zero, the
103 object invokes the destructor method defined by everyone of its children
104 as part of their base `struct bt_object`. The key point here is that the
105 cascade of destructor will necessarily originate from the root and
106 propagate in preorder to the children. These children will propagate the
107 destruction to their own children before reclaiming their own memory.
108 This ensures that a node's pointer to its parent is _always_ valid since
109 the parent has the responsibility of tearing-down their children before
110 cleaning themselves up.
112 Assuming a reference to an object is _acquired_ by calling
113 `+bt_*_get_ref()+` while its reference count is zero, the object
114 acquires, in turn, a reference on its parent using `+bt_*_get_ref()+`.
115 At that point, the child can be thought of as having converted its weak
116 reference to its parent into a regular reference. That is why this
117 reference is referred to as a _claiming_ aggregation reference.
121 This scheme imposes a number of strict rules defining the relation
124 * Objects may only have one parent.
125 * Objects, beside the root, are only retrievable from their direct
130 The initial situation is rather simple: **User{nbsp}A** is holding a
131 reference to a trace class, **TC1**. As per the rules previously
132 enounced, stream classes **SC1** and **SC2** don't hold a reference to
133 **TC1** since their own reference counts are zero. The same holds true
134 for **EC1**, **EC2** and **EC3** with respect to **SC1** and **SC2**.
136 image::doc/contributing-images/bt-ref01.png[]
138 In this second step, we can see that **User{nbsp}A** has acquired a
139 reference on **SC2** through the trace class, **TC1**.
141 The stream class's reference count transitions from zero to one,
142 triggering the acquisition of a strong reference on **TC1** from
145 Hence, at this point, the trace class's ownership is shared by
146 **User{nbsp}A** and **SC2**.
148 image::doc/contributing-images/bt-ref02.png[]
150 Next, **User{nbsp}A** acquires a reference on the **EC3** event class
151 through its parent stream class, **SC2**. Again, the transition of an
152 object's reference count from 0 to 1 triggers the acquisition of a
153 reference on its parent.
155 Note that SC2's reference count was incremented to 2. The trace class's
156 reference count remains unchanged.
158 image::doc/contributing-images/bt-ref03.png[]
160 **User{nbsp}A** decides to drop its reference on **SC2**. **SC2**'s
161 reference count returns back to 1, everything else remaining unchanged.
163 image::doc/contributing-images/bt-ref04.png[]
165 **User{nbsp}A** can then decide to drop its reference on the trace
166 class. This results in a reversal of the initial situation:
167 **User{nbsp}A** now owns an event, **EC3**, which is keeping everything
168 else alive and reachable.
170 image::doc/contributing-images/bt-ref05.png[]
172 If another object, **User{nbsp}B**, enters the picture and acquires a
173 reference on the **SC1** stream class, we see that **SC1**'s reference
174 count transitioned from 0 to 1, triggering the acquisition of a
175 reference on **TC1**.
177 image::doc/contributing-images/bt-ref06.png[]
179 **User{nbsp}B** hands off a reference to **EC1**, acquired through
180 **SC1**, to another object, **User{nbsp}C**. The acquisition of a
181 reference on **EC1**, which transitions from 0 to 1, triggers the
182 acquisition of a reference on its parent, **SC1**.
184 image::doc/contributing-images/bt-ref07.png[]
186 At some point, **User{nbsp}A** releases its reference on **EC3**. Since
187 **EC3**'s reference count transitions to zero, it releases its reference
188 on **SC2**. **SC2**'s reference count, in turn, reaches zero and it
189 releases its reference to **TC1**.
191 **TC1**'s reference count is now 1 and no further action is taken.
193 image::doc/contributing-images/bt-ref08.png[]
195 **User{nbsp}B** releases its reference on **SC1**. **User{nbsp}C**
196 becomes the sole owner of the whole hierarchy through his ownership of
199 image::doc/contributing-images/bt-ref09.png[]
201 Finally, **User{nbsp}C** releases his ownership of **EC1**, triggering
202 the release of the whole hierarchy. Let's walk through the reclamation
205 Mirroring what happened when **User{nbsp}A** released its last reference
206 on **EC3**, the release of **EC1** by **User{nbsp}C** causes its
207 reference count to fall to zero.
209 This transition to zero causes **EC1** to release its reference on
210 **SC1**. **SC1**'s reference count reaching zero causes it to release
211 its reference on **TC1**.
213 image::doc/contributing-images/bt-ref10.png[]
215 Since the reference count of **TC1**, a root object, has reached zero,
216 it invokes the destructor method on its children. This method is
217 recursive and causes the stream classes to call the destructor method on
220 The event classes are reached and, having no children of their own, are
223 image::doc/contributing-images/bt-ref11.png[]
225 The stream classes having destroyed their children, are then reclaimed
228 image::doc/contributing-images/bt-ref12.png[]
230 Finally, the stream classes having been reclaimed, **TC1** is reclaimed.
232 image::doc/contributing-images/bt-ref13.png[]
237 Logging is a great instrument for a developer to be able to collect
238 information about a running software.
240 {bt2} is a complex software with many layers. When a {bt2}
241 graph fails to run, what caused the failure? It could be caused by any
242 component, any message iterator, and any deeply nested validation of a
243 CTF IR object (within the `ctf` plugin), for example. With the
244 appropriate logging statements manually placed in the source code, we
245 can find the cause of a bug faster.
247 While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
248 _FATAL_ logging statements, you should liberally instrument your
249 {bt2} module with _TRACE_ logging statements to help future you
250 and other developers understand what's happening at run time.
254 The {bt2} logging API is internal: it is not exposed to the users
255 of the library; only to their developers. The only thing that a library
256 user can control is the current log level of the library itself with
257 `bt_logging_set_global_level()` and the initial library's log level with
258 the `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable.
260 This API is based on https://github.com/wonder-mice/zf_log[zf_log], a
261 lightweight, yet featureful, MIT-licensed core logging library for C and
262 {cpp}. The zf_log source files were modified to have the `BT_` and
263 `bt_` prefixes, and other small changes, like color support and using
264 the project's `BT_DEBUG_MODE` definition instead of the standard
267 The logging functions are implemented in the logging convenience
268 library (`src/logging` directory).
273 The logging API headers are:
275 `<babeltrace2/logging.h>`::
276 Public header which a library user can use to set and get
277 libbabeltrace2's current log level.
280 Internal, generic logging API which you can use in any {bt2}
281 module. This is the translation of `zf_log.h`.
283 This header offers the <<gen-logging-statements,generic logging
287 Specific internal header to use within the library.
289 This header defines `BT_LOG_OUTPUT_LEVEL` to a custom, library-wide
290 hidden symbol which is the library's current log level before including
293 This header offers the <<lib-logging-statements,library-specific logging
296 `"logging/comp-logging.h"`::
297 Specific internal header to use within a component class.
299 This header offers the <<comp-logging-statements,component-specific
300 logging statement macros>>.
305 The internal logging API offers the following log levels, in ascending
308 [options="header,autowidth",cols="4"]
311 |Log level short name
312 |Internal API enumerator
313 |Public API enumerator
318 |`BT_LOGGING_LEVEL_TRACE`
323 |`BT_LOGGING_LEVEL_DEBUG`
328 |`BT_LOGGING_LEVEL_INFO`
333 |`BT_LOGGING_LEVEL_WARNING`
338 |`BT_LOGGING_LEVEL_ERROR`
343 |`BT_LOGGING_LEVEL_FATAL`
348 |`BT_LOGGING_LEVEL_NONE`
351 The short name is accepted by the log level environment variables and by
352 the CLI's `--log-level` options.
354 See <<choose-a-log-level,how to decide which one to use>> below.
356 There are two important log level expressions:
358 [[build-time-log-level]]Build-time, minimal log level::
359 The minimal log level, or build-time log level, is set at build time
360 and determines the minimal log level of the logging statements which
361 can be executed. This applies to all the modules (CLI, library,
362 plugins, bindings, etc.).
364 All the logging statements with a level below this level are **not built
365 at all**. All the logging statements with a level equal to or greater
366 than this level _can_ be executed, depending on the
367 <<run-time-log-level,run-time log level>>.
369 You can set this level at configuration time with the
370 `BABELTRACE_MINIMAL_LOG_LEVEL` environment variable, for example:
374 $ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure
378 The default build-time log level is `DEBUG`. For optimal performance,
379 set it to `INFO`, which effectively disables all fast path logging in
380 all the {bt2} modules. You can't set it to `WARNING`, `ERROR`,
381 `FATAL`, or `NONE` because the impact on performance is minuscule
382 starting from the _INFO_ log level anyway and we want any {bt2}
383 build to always be able to print _INFO_-level logs.
385 The library's public API provides `bt_logging_get_minimal_level()` to
386 get the configured minimal log level.
388 [[run-time-log-level]]Run-time, dynamic log level::
389 The dynamic log level is set at run time and determines the current,
390 _active_ log level. All the logging statements with a level below
391 this level are not executed, **but they still evaluate the
392 condition**. All the logging statements with a level equal to or
393 greater than this level are executed, provided that their level is
394 also <<build-time-log-level,enabled at build time>>.
396 `zf_log` has a concept of a global run-time log level which uses the
397 `_bt_log_global_output_lvl` symbol. In practice, we never use this
398 symbol, and always make sure that `BT_LOG_OUTPUT_LEVEL` is defined to a
399 module-wise expression before including `"logging/log.h"`.
401 In the library, `"lib/logging.h"` defines its own
402 `BT_LOG_OUTPUT_LEVEL` to the library's log level symbol before it
403 includes `"logging/log.h"` itself.
405 In libbabeltrace2, the user can set the current run-time log level with
406 the `bt_logging_set_global_level()` function, for example:
411 bt_logging_set_global_level(BT_LOGGING_LEVEL_INFO);
415 The library's initial run-time log level is defined by the
416 `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable, or set to _NONE_
417 if this environment variable is undefined.
419 Other modules have their own way of setting their run-time log level.
421 For example, the CLI uses the `BABELTRACE_CLI_LOG_LEVEL` environment
422 variable, as well as its global `--log-level` option:
425 $ babeltrace2 --log-level=I ...
428 The components use their own log level (as returned by
429 `bt_component_get_logging_level()`). With the CLI, you can set a
430 specific component's log level with its own, position-dependent
431 `--log-level` option:
434 $ babeltrace2 /path/to/trace -c sink.ctf.fs --log-level=D
437 Code which is common to the whole project, for example `src/common`
438 and `src/compat`, use function parameters to get its run-time log
443 char *bt_common_get_home_plugin_path(int log_level);
446 Typically, when a logging-enabled module calls such a function, it
447 passes its own log level expression directly (`BT_LOG_OUTPUT_LEVEL`):
451 path = bt_common_get_home_plugin_path(BT_LOG_OUTPUT_LEVEL);
454 Otherwise, just pass `BT_LOG_NONE`:
457 path = bt_common_get_home_plugin_path(BT_LOG_NONE);
460 [[gen-logging-statements]]
461 ==== Generic logging statement macros
463 The {bt2} logging statement macros work just like `printf()`
464 (except the `+BT_LOG*_STR()+` ones) and contain their <<log-levels,log
465 level>> (short name) in their name.
467 Each of the following macros evaluate the
468 <<build-time-log-level,build-time log level>> definition and
469 <<run-time-log-level,run-time log level>> expression (as defined by
470 `BT_LOG_OUTPUT_LEVEL`) to log conditionally.
472 See <<logging-instrument-c-file-gen>> and
473 <<logging-instrument-h-file-gen>> to learn how to be able to use the
476 `+BT_LOGT("format string", ...)+`::
477 Generic trace logging statement.
479 `+BT_LOGD("format string", ...)+`::
480 Generic debug logging statement.
482 `+BT_LOGI("format string", ...)+`::
483 Generic info logging statement.
485 `+BT_LOGW("format string", ...)+`::
486 Generic warning logging statement.
488 `+BT_LOGE("format string", ...)+`::
489 Generic error logging statement.
491 `+BT_LOGF("format string", ...)+`::
492 Generic fatal logging statement.
494 `+BT_LOGT_STR("preformatted string")+`::
495 Generic preformatted string trace logging statement.
497 `+BT_LOGD_STR("preformatted string")+`::
498 Generic preformatted string debug logging statement.
500 `+BT_LOGI_STR("preformatted string")+`::
501 Generic preformatted string info logging statement.
503 `+BT_LOGW_STR("preformatted string")+`::
504 Generic preformatted string warning logging statement.
506 `+BT_LOGE_STR("preformatted string")+`::
507 Generic preformatted string error logging statement.
509 `+BT_LOGF_STR("preformatted string")+`::
510 Generic preformatted string fatal logging statement.
512 `+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
513 Generic memory trace logging statement.
515 `+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
516 Generic memory debug logging statement.
518 `+BT_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
519 Generic memory info logging statement.
521 `+BT_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
522 Generic memory warning logging statement.
524 `+BT_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
525 Generic memory error logging statement.
527 `+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
528 Generic memory fatal logging statement.
530 `+BT_LOGT_ERRNO("initial message", "format string", ...)+`::
531 Generic `errno` string trace logging statement.
533 `+BT_LOGD_ERRNO("initial message", "format string", ...)+`::
534 Generic `errno` string debug logging statement.
536 `+BT_LOGI_ERRNO("initial message", "format string", ...)+`::
537 Generic `errno` string info logging statement.
539 `+BT_LOGW_ERRNO("initial message", "format string", ...)+`::
540 Generic `errno` string warning logging statement.
542 `+BT_LOGE_ERRNO("initial message", "format string", ...)+`::
543 Generic `errno` string error logging statement.
545 `+BT_LOGF_ERRNO("initial message", "format string", ...)+`::
546 Generic `errno` string fatal logging statement.
548 [[lib-logging-statements]]
549 ==== Library-specific logging statement macros
551 The {bt2} library contains an internal logging API based on the
552 generic logging framework. You can use it to log known {bt2}
553 objects without having to manually log each member.
555 See <<logging-instrument-c-file-lib>>
556 and <<logging-instrument-h-file-lib>> to
557 learn how to be able to use the following macros.
559 The library logging statement macros are named `+BT_LIB_LOG*()+` instead
562 `+BT_LIB_LOGT("format string", ...)+`::
563 Library trace logging statement.
565 `+BT_LIB_LOGD("format string", ...)+`::
566 Library debug logging statement.
568 `+BT_LIB_LOGI("format string", ...)+`::
569 Library info logging statement.
571 `+BT_LIB_LOGW("format string", ...)+`::
572 Library warning logging statement.
574 `+BT_LIB_LOGE("format string", ...)+`::
575 Library error logging statement.
577 `+BT_LIB_LOGF("format string", ...)+`::
578 Library fatal logging statement.
580 `+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
581 Library warning logging statement, and unconditional error cause
584 `+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
585 Library error logging statement, and unconditional error cause
588 The macros above accept the typical `printf()` conversion specifiers
589 with the following limitations:
591 * The `+*+` width specifier is not accepted.
592 * The `+*+` precision specifier is not accepted.
593 * The `j` and `t` length modifiers are not accepted.
594 * The `n` format specifier is not accepted.
595 * The format specifiers defined in `<inttypes.h>` are not accepted,
596 except for `PRId64`, `PRIu64`, `PRIx64`, `PRIX64`, `PRIo64`, and
599 The {bt2} library custom conversion specifier is accepted. Its
600 syntax is either `%!u` to format a UUID (`bt_uuid` type), or:
602 . Introductory `%!` sequence.
604 . **Optional**: `[` followed by a custom prefix for the printed fields
605 of this specifier, followed by `]`. The standard form is to end this
606 prefix with `-` so that, for example, with the prefix `tc-`, the
607 complete field name becomes `tc-addr`.
609 . **Optional**: `pass:[+]` to print extended object members. This
610 depends on the provided format specifier.
612 . Format specifier (see below).
614 The available format specifiers are:
616 [options="header,autowidth",cols="3"]
623 |Trace IR field class
624 |`+const struct bt_field_class *+`
628 |`+const struct bt_field *+`
632 |`+const struct bt_field_path *+`
635 |Trace IR event class
636 |`+const struct bt_event_class *+`
640 |`+const struct bt_event *+`
643 |Trace IR stream class.
644 |`+const struct bt_stream_class *+`
648 |`+const struct bt_stream *+`
652 |`+const struct bt_packet *+`
655 |Trace IR trace class
656 |`+const struct bt_trace_class *+`
660 |`+const struct bt_trace *+`
663 |Trace IR clock class
664 |`+const struct bt_clock_class *+`
667 |Trace IR clock snapshot
668 |`+const struct bt_clock_snapshot *+`
672 |`+const struct bt_value *+`
676 |`const struct bt_integer_range_set *`
680 |`+const struct bt_message *+`
683 |Message iterator class
684 |`struct bt_message_iterator_class *`
688 |`struct bt_message_iterator *`
692 |`struct bt_component_class *`
696 |`+const struct bt_component *+`
700 |`+const struct bt_port *+`
704 |`+const struct bt_connection *+`
708 |`+const struct bt_graph *+`
712 |`+struct bt_interrupter *+`
716 |`+const struct bt_plugin *+`
720 |`+const struct bt_error_cause *+`
724 |`+const struct bt_object_pool *+`
728 |`+const struct bt_object *+`
731 Conversion specifier examples:
738 The ``, `` string (comma and space) is printed between individual
739 fields, but **not after the last one**. Therefore, you must put this
740 separator in the format string between two conversion specifiers, for
745 BT_LIB_LOGW("Message: count=%u, %!E, %!+K", count, event_class, clock_class);
748 Example with a custom prefix:
752 BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b);
755 It is safe to pass `NULL` as any {bt2} object parameter: the macros
756 only print its null address.
758 WARNING: Build-time `printf()` format checks are disabled for the
759 `+BT_LIB_LOG*()+` macros because there are custom conversion specifiers,
760 so make sure to test your logging statements.
762 [[comp-logging-statements]]
763 ==== Component-specific logging statement macros
765 There are available logging macros for components. They prepend a prefix
766 including the component's name to the logging message.
768 See <<logging-instrument-c-file-compcls>> and
769 <<logging-instrument-h-file-compcls>> to learn how to be able to use the
772 The component logging statement macros are named `+BT_COMP_LOG*()+`
773 instead of `+BT_LOG*()+`:
775 `+BT_COMP_LOGT("format string", ...)+`::
776 Component trace logging statement.
778 `+BT_COMP_LOGD("format string", ...)+`::
779 Component debug logging statement.
781 `+BT_COMP_LOGI("format string", ...)+`::
782 Component info logging statement.
784 `+BT_COMP_LOGW("format string", ...)+`::
785 Component warning logging statement.
787 `+BT_COMP_LOGE("format string", ...)+`::
788 Component error logging statement.
790 `+BT_COMP_LOGF("format string", ...)+`::
791 Component fatal logging statement.
793 `+BT_COMP_LOGT_STR("preformatted string")+`::
794 Component preformatted string trace logging statement.
796 `+BT_COMP_LOGD_STR("preformatted string")+`::
797 Component preformatted string debug logging statement.
799 `+BT_COMP_LOGI_STR("preformatted string")+`::
800 Component preformatted string info logging statement.
802 `+BT_COMP_LOGW_STR("preformatted string")+`::
803 Component preformatted string warning logging statement.
805 `+BT_COMP_LOGE_STR("preformatted string")+`::
806 Component preformatted string error logging statement.
808 `+BT_COMP_LOGF_STR("preformatted string")+`::
809 Component preformatted string fatal logging statement.
811 `+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`::
812 Component `errno` string trace logging statement.
814 `+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
815 Component `errno` string debug logging statement.
817 `+BT_COMP_LOGI_ERRNO("initial message", "format string", ...)+`::
818 Component `errno` string info logging statement.
820 `+BT_COMP_LOGW_ERRNO("initial message", "format string", ...)+`::
821 Component `errno` string warning logging statement.
823 `+BT_COMP_LOGE_ERRNO("initial message", "format string", ...)+`::
824 Component `errno` string error logging statement.
826 `+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
827 Component `errno` string fatal logging statement.
829 `+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
830 Component memory trace logging statement.
832 `+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
833 Component memory debug logging statement.
835 `+BT_COMP_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
836 Component memory info logging statement.
838 `+BT_COMP_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
839 Component memory warning logging statement.
841 `+BT_COMP_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
842 Component memory error logging statement.
844 `+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
845 Component memory fatal logging statement.
847 ==== Conditional logging
849 `+BT_LOG_IF(cond, statement)+`::
850 Execute `statement` only if `cond` is true.
857 BT_LOG_IF(i < count / 2, BT_LOGD("Log this: i=%d", i));
861 To check the <<build-time-log-level,build-time log level>>:
865 #if BT_LOG_ENABLED_DEBUG
870 This tests if the _DEBUG_ level was enabled at build time. This means
871 that the current, <<run-time-log-level,run-time log level>> _could_ be
872 _DEBUG_, but it could also be higher. The rule of thumb is to use only
873 logging statements at the same level in a `BT_LOG_ENABLED_*` conditional
876 The available definitions for build-time conditions are:
878 * `BT_LOG_ENABLED_TRACE`
879 * `BT_LOG_ENABLED_DEBUG`
880 * `BT_LOG_ENABLED_INFO`
881 * `BT_LOG_ENABLED_WARNING`
882 * `BT_LOG_ENABLED_ERROR`
883 * `BT_LOG_ENABLED_FATAL`
885 To check the current, <<run-time-log-level,run-time log level>>:
889 if (BT_LOG_ON_DEBUG) {
894 This tests if the _DEBUG_ log level is dynamically turned on
895 (implies that it's also enabled at build time). This check could have a
896 noticeable impact on performance.
898 The available definitions for run-time conditions are:
903 * `BT_LOG_ON_WARNING`
907 Those macros check the module-specific log level symbol (defined by
908 `BT_LOG_OUTPUT_LEVEL`).
910 Never, ever write code which would be executed only to compute the
911 fields of a logging statement outside a conditional logging scope,
916 int number = get_number_of_event_classes_with_property_x(...);
917 BT_LOGD("Bla bla: number=%d", number);
924 if (BT_LOG_ON_DEBUG) {
925 int number = get_number_of_event_classes_with_property_x(...);
926 BT_LOGD("Bla bla: number=%d", number);
934 BT_LOGD("Bla bla: number=%d", get_number_of_event_classes_with_property_x(...));
939 [[logging-instrument-c-file-gen]]
940 ==== Instrument a {c-cpp} source file (generic)
942 To instrument a {c-cpp} source file (`.c`/`.cpp`):
944 . At the top of the file, before the first `#include` line (if any),
945 define your file's <<choose-a-logging-tag,logging tag>> name:
950 #define BT_LOG_TAG "SUBSYS/MY-MODULE/MY-FILE"
954 . Below the line above, define the source file's log level expression,
955 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
956 <<gen-logging-statements,logging statement>> to know the current
957 <<run-time-log-level,run-time log level>>.
963 /* Global log level variable */
964 #define BT_LOG_OUTPUT_LEVEL module_global_log_level
969 /* Local log level variable; must exist where you use BT_LOG*() */
970 #define BT_LOG_OUTPUT_LEVEL log_level
975 /* Object's log level; `obj` must exist where you use BT_LOG*() */
976 #define BT_LOG_OUTPUT_LEVEL (obj->log_level)
979 . Include `"logging/log.h"`:
983 #include "logging/log.h"
986 . In the file, instrument your code with the
987 <<gen-logging-statements,generic logging statement macros>>.
989 [[logging-instrument-h-file-gen]]
990 ==== Instrument a {c-cpp} header file (generic)
992 To instrument a {c-cpp} header file (`.h`/`.hpp`), if you have
993 `static inline` functions in it:
995 . Do not include `"logging/log.h"`!
999 .. In the file, instrument your code with the
1000 <<gen-logging-statements,generic logging statement macros>>, making
1001 each of them conditional to the existence of the macro you're using:
1006 int some_function(int x)
1024 The {c-cpp} source files which include this header file determine if
1025 logging is enabled or not for them, and if so, what is their
1026 <<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time
1027 log level>> expression.
1029 .. Require that logging be enabled:
1033 /* Protection: this file uses BT_LOG*() macros directly */
1034 #ifndef BT_LOG_SUPPORTED
1035 # error Please include "logging/log.h" before including this file.
1039 Then, in the file, instrument your code with the
1040 <<gen-logging-statements,generic logging statement macros>>.
1042 [[logging-instrument-c-file-lib]]
1043 ==== Instrument a library {c-cpp} source file
1045 To instrument a library {c-cpp} source file (`.c`/`.cpp`):
1047 . At the top of the file, before the first `#include` line (if any),
1048 define your file's <<choose-a-logging-tag,logging tag>> name (this
1049 tag must start with `LIB/`):
1054 #define BT_LOG_TAG "LIB/THE-FILE"
1058 . Include `"lib/logging.h"`:
1062 #include "lib/logging.h"
1065 . In the file, instrument your code with the
1066 <<lib-logging-statements,library logging statement macros>> or with
1067 the <<gen-logging-statements,generic logging statement macros>>.
1069 [[logging-instrument-h-file-lib]]
1070 ==== Instrument a library {c-cpp} header file
1072 To instrument a library {c-cpp} header file (`.h`/`.hpp`), if you have
1073 `static inline` functions in it:
1075 . Do not include `"lib/logging.h"`!
1077 . Require that library logging be enabled:
1081 /* Protection: this file uses BT_LIB_LOG*() macros directly */
1082 #ifndef BT_LIB_LOG_SUPPORTED
1083 # error Please include "lib/logging.h" before including this file.
1087 . In the file, instrument your code with the
1088 <<lib-logging-statements,library logging statement macros>> or with
1089 the <<gen-logging-statements,generic logging statement macros>>.
1091 [[logging-instrument-c-file-compcls]]
1092 ==== Instrument a component class {c-cpp} source file
1094 To instrument a component class {c-cpp} source file (`.c`/`.cpp`):
1096 . At the top of the file, before the first `#include` line (if any),
1097 define your file's <<choose-a-logging-tag,logging tag>> name (this tag
1098 must start with `PLUGIN/` followed by the component class identifier):
1103 #define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC"
1107 . Below the line above, define the source file's log level expression,
1108 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
1109 <<comp-logging-statements,logging statement>> to know the current
1110 <<run-time-log-level,run-time log level>>.
1112 For a component class file, it is usually a member of a local component
1113 private structure variable:
1117 #define BT_LOG_OUTPUT_LEVEL (my_comp->log_level)
1120 . Below the line above, define `BT_COMP_LOG_SELF_COMP` to an expression
1121 which, evaluated in the context of the
1122 <<comp-logging-statements,logging statements>>, evaluates to the self
1123 component address (`+bt_self_component *+`) of the component.
1125 This is usually a member of a local component private structure
1130 #define BT_COMP_LOG_SELF_COMP (my_comp->self_comp)
1133 . Include `"logging/comp-logging.h"`:
1137 #include "logging/comp-logging.h"
1140 . In the component initialization method, make sure to set the
1141 component private structure's log level member to the initial
1142 component's log level:
1147 bt_logging_level log_level;
1151 bt_self_component_status my_comp_init(
1152 bt_self_component_source *self_comp_src,
1153 bt_value *params, void *init_method_data)
1155 struct my_comp *my_comp = g_new0(struct my_comp, 1);
1156 bt_self_component *self_comp =
1157 bt_self_component_source_as_self_component(self_comp_src);
1158 const bt_component *comp = bt_self_component_as_component(self_comp);
1161 my_comp->log_level = bt_component_get_logging_level(comp);
1167 . In the file, instrument your code with the
1168 <<comp-logging-statements,component logging statement macros>>.
1170 [[logging-instrument-h-file-compcls]]
1171 ==== Instrument a component class {c-cpp} header file
1173 To instrument a component class {c-cpp} header file (`.h`/`.hpp`), if
1174 you have `static inline` functions in it:
1176 . Do not include `"logging/comp-logging.h"`!
1178 . Require that component logging be enabled:
1182 /* Protection: this file uses BT_COMP_LOG*() macros directly */
1183 #ifndef BT_COMP_LOG_SUPPORTED
1184 # error Please include "logging/comp-logging.h" before including this file.
1188 . In the file, instrument your code with the
1189 <<comp-logging-statements,component logging statement macros>>.
1191 [[choose-a-logging-tag]]
1192 ==== Choose a logging tag
1194 Each logging-enabled {c-cpp} source file must define `BT_LOG_TAG` to a
1195 logging tag. A logging tag is a namespace to identify the logging
1196 messages of this specific source file.
1198 In general, a logging tag name _must_ be only uppercase letters, digits,
1199 and the `-`, `.`, and `/` characters.
1201 Use `/` to show the subsystem to source file hierarchy.
1203 For the {bt2} library, start with `LIB/`.
1205 For the CTF writer library, start with `CTF-WRITER/`.
1207 For component classes, use:
1210 `PLUGIN/__CCTYPE__.__PNAME__.__CCNAME__[/__FILE__]`
1215 Component class's type (`SRC`, `FLT`, or `SINK`).
1221 Component class's name.
1224 Additional information to specify the source file name or module.
1226 For plugins (files common to many component classes), use:
1229 `PLUGIN/__PNAME__[/__FILE__]`
1237 Additional information to specify the source file name or module.
1239 [[choose-a-log-level]]
1240 ==== Choose a log level
1242 Choosing the appropriate level for your logging statement is very
1245 [options="header,autowidth",cols="1,2,3a,4"]
1247 |Log level |Description |Use cases |Expected impact on performance
1251 The program, library, or plugin cannot continue to work in this
1252 condition: it must be terminated immediately.
1254 A _FATAL_-level logging statement should always be followed by
1257 * Unexpected return values from system calls.
1258 * Logic error in internal code, for example an unexpected value in a
1260 * Failed assertion (within `BT_ASSERT()`).
1261 * Unsatisfied library precondition (within `BT_ASSERT_PRE()` or
1262 `BT_ASSERT_PRE_DEV()`).
1263 * Unsatisfied library postcondition (within `BT_ASSERT_POST()` or
1264 `BT_ASSERT_POST_DEV()`).
1265 |Almost none: always enabled.
1269 An important error which is somewhat not fatal, that is, the program,
1270 library, or plugin can continue to work after this, but you judge that
1271 it should be reported to the user.
1273 Usually, the program cannot recover from such an error, but it can at
1276 * Memory allocation errors.
1277 * Wrong component initialization parameters.
1278 * Corrupted, unrecoverable trace data.
1279 * Failed to perform an operation which should work considering the
1280 implementation and the satisfied preconditions. For example, the
1281 failure to create an empty object (no parameters): most probably
1282 failed internally because of an allocation error.
1283 * Almost any error in terminal elements: CLI and plugins.
1284 |Almost none: always enabled.
1288 An error which still allows the execution to continue, but you judge
1289 that it should be reported to the user.
1291 _WARNING_-level logging statements are for any error or weird action
1292 that is directly or indirectly caused by the user, often through some
1293 bad input data. For example, not having enough memory is considered
1294 beyond the user's control, so we always log memory errors with an
1295 _ERROR_ level (not _FATAL_ because we usually don't abort in this
1298 * Missing data within something that is expected to have it, but there's
1300 * Invalid file, but recoverable/fixable.
1301 |Almost none: always enabled.
1305 Any useful information which a non-developer user would possibly
1308 Anything logged with this level must _not_ happen repetitively on the
1309 fast path, that is, nothing related to each message, for example. This
1310 level is used for sporadic and one-shot events.
1312 * CLI or component configuration report.
1313 * Successful plugin, component, or message iterator initialization.
1314 * In the library: anything related to plugins, graphs, component
1315 classes, components, message iterators, connections, and ports which
1316 is not on the fast path.
1317 * Successful connection to or disconnection from another system.
1318 * An _optional_ subsystem cannot be loaded.
1319 * An _optional_ field/datum cannot be found.
1321 Very little: always enabled.
1325 Something that only {bt2} developers would be interested into,
1326 which can occur on the fast path, but not more often than once per
1329 The _DEBUG_ level is the default <<build-time-log-level,build-time log
1330 level>> as, since it's not _too_ verbose, the performance is similar to
1333 * Object construction and destruction.
1334 * Object recycling (except fields).
1335 * Object copying (except fields and values).
1336 * Object freezing (whatever the type, as freezing only occurs in
1338 * Object interruption.
1339 * Calling user methods and logging the result.
1340 * Setting object properties (except fields and values).
1342 Noticeable, but not as much as the _TRACE_ level: could be executed
1343 in production if you're going to need a thorough log for support
1344 tickets without having to rebuild the project.
1348 Low-level debugging context information (anything that does not fit the
1349 other log levels). More appropriate for tracing in general.
1351 * Reference count change.
1352 * Fast path, low level state machine's state change.
1353 * Get or set an object's property.
1354 * Object comparison's intermediate results.
1355 |Huge: not executed in production.
1360 Make sure not to use a _WARNING_ (or higher) log level when the
1361 condition leading to the logging statement can occur under normal
1364 For example, a public function to get some object or
1365 property from an object by name or key that fails to find the value is
1366 not a warning scenario: the user could legitimately use this function to
1367 check if the name/key exists in the object. In this case, use the
1368 _TRACE_ level (or do not log at all).
1372 ==== Write an appropriate message
1374 Follow those rules when you write a logging statement's message:
1376 * Use an English sentence which starts with a capital letter.
1378 * Start the sentence with the appropriate verb tense depending on the
1379 context. For example:
1382 ** Beginning of operation (present continuous): _Creating ..._,
1383 _Copying ..._, _Serializing ..._, _Freezing ..._, _Destroying ..._
1384 ** End of operation (simple past): _Created ..._, _Successfully created ..._,
1385 _Failed to create ..._, _Set ..._ (simple past of _to set_ which is
1389 For warning and error messages, you can start the message with _Cannot_
1390 or _Failed to_ followed by a verb if it's appropriate.
1392 * Do not include the log level in the message itself. For example,
1393 do not start the message with _Error while_ or _Warning:_.
1395 * Do not put newlines, tabs, or other special characters in the message,
1396 unless you want to log a string with such characters. Note that
1397 multiline logging messages can be hard to parse, analyze, and filter,
1398 however, so prefer multiple logging statements over a single statement
1401 * **If there are fields that your logging statement must record**,
1402 follow the message with `:` followed by a space, then with the list of
1403 fields (more about this below). If there are no fields, end the
1404 sentence with a period.
1406 The statement's fields _must_ be a comma-separated list of
1407 `__name__=__value__` tokens. Keep `__name__` as simple as possible; use
1408 kebab case if possible. If `__value__` is a non-alphanumeric string, put
1409 it between double quotes (`"%s"` specifier). Always use the `PRId64` and
1410 `PRIu64` specifiers to log an `int64_t` or an `uint64_t` value. Use `%d`
1411 to log a boolean value.
1415 "Cannot read stream data for indexing: path=\"%s\", name=\"%s\", "
1416 "stream-id=%" PRIu64 ", stream-fd=%d, "
1417 "index=%" PRIu64 ", status=%s, is-mapped=%d"
1419 By following a standard format for the statement fields, it is easier to
1420 use tools like https://www.elastic.co/products/logstash[Logstash] or
1421 even https://www.splunk.com/[Splunk] to split fields and analyze logs.
1423 Prefer the following suffixes in field names:
1425 [options="header,autowidth"]
1427 |Field name suffix |Description |Format specifier
1429 |`-addr` |Memory address |`%p`
1430 |`-fd` |File descriptor |`%d`
1431 |`-fp` |File stream (`+FILE *+`) |`%p`
1432 |`-id` |Object's ID |`%" PRIu64 "`
1433 |`-index` |Index |`%" PRIu64 "`
1434 |`-name` |Object's name |`\"%s\"`
1439 The log is printed to the standard error stream. A log line contains the
1440 time, the process and thread IDs, the <<log-levels,log level>>, the
1441 <<choose-a-logging-tag,logging tag>>, the source's function name, file
1442 name and line number, and the <<message,message>>.
1444 When {bt2} supports terminal color codes (depends on the
1445 `BABELTRACE_TERM_COLOR` environment variable's value and what the
1446 standard output and error streams are plugged into), _INFO_-level lines
1447 are blue, _WARNING_-level lines are yellow, and _ERROR_-level and
1448 _FATAL_-level lines are red.
1453 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
1456 You can easily filter the log with `grep` or `ag`. For example, to keep
1457 only the _DEBUG_-level logging messages that the `FIELD-CLASS` module
1461 $ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS'
1466 To use Valgrind on an application (for example, the CLI or a test) which
1467 loads libbabeltrace2, use:
1470 $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
1471 LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app
1474 `G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and
1475 `PYTHONMALLOC=malloc` is for the Python interpreter, if it is used by
1476 the Python plugin provider (Valgrind will probably show a lot of errors
1477 which originate from the Python interpreter anyway).
1479 `LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
1480 libraries (plugins) which it loads. You need this to see the appropriate
1481 backtrace when Valgrind shows errors.
1488 Running `make check` in the build directory (regardless of whether the build is
1489 in-tree or out-of-tree) automatically sets up the appropriate environment for
1490 tests to run in, so nothing more is needed.
1492 If building in-tree, you can run single tests from the tree directly:
1495 $ ./tests/plugins/sink.text.pretty/test-enum.sh
1498 If building out-of-tree, you can get the appropriate environment by sourcing
1499 the `tests/utils/env.sh` file residing in the build directory against which you
1503 $ source /path/to/my/build/tests/utils/env.sh
1504 $ ./tests/plugins/sink.text.pretty/test-enum.sh
1509 You can use the `tests/utils/run-in-py-env.sh` script to run any command
1510 within an environment making the build's `bt2` Python package available,
1511 as well as the testing utility Python modules.
1513 `run-in-py-env.sh` uses <<test-env,`utils.sh`>> which needs to know the
1514 build directory, so make sure you set the `BT_TESTS_BUILDDIR`
1515 environment variable correctly _if you build out of tree_, for example:
1518 $ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
1521 You can run any command which needs the `bt2` Python package through
1522 `run-in-py-env.sh`, for example:
1525 $ ./tests/utils/run-in-py-env.sh ipython3
1530 All test scripts output the test results following the
1531 https://testanything.org/[Test Anything Protocol] (TAP) format.
1533 The TAP format has two mechanisms to print additional information about
1536 * Print a line starting with `#` to the standard output.
1538 This is usually done with the `diag()` C function or the `diag` shell
1541 * Print to the standard error.
1545 The `bt2` Python package tests are located in
1546 `tests/bindings/python/bt2`.
1548 ==== Python test runner
1550 `tests/utils/python/testrunner.py` is {bt2}'s Python test runner
1551 which loads Python files containing unit tests, finds all the test
1552 cases, and runs the tests, producing a TAP report.
1554 You can see the test runner command's help with:
1557 $ python3 ./tests/utils/python/testrunner.py --help
1560 By default, the test runner reports failing tests (TAP's `not{nbsp}ok`
1561 line), but continues to run other tests. You can use the `--failfast`
1562 option to make the test runner fail as soon as a test fails.
1566 To run all the `bt2` Python package tests:
1571 $ ./tests/utils/run-in-py-env.sh ./tests/bindings/python/bt2/test-python-bt2.sh
1577 $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
1578 ./tests/bindings/python/bt2/ -p '*.py'
1581 To run **all the tests** in a test module (for example,
1587 $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
1588 ./tests/bindings/python/bt2 -t test_value
1591 To run a **specific test case** (for example, `RealValueTestCase` within
1597 $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
1598 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
1601 To run a **specific test** (for example,
1602 `RealValueTestCase.test_assign_pos_int` within `test_value.py`):
1607 $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \
1608 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
1613 A significant part and, in general, all the new code of {bt2} is written
1616 This section shows what's important to know about {cpp} to contribute
1621 {bt2} only has {cpp} sources for _internal_ code.
1623 In other words, libbabeltrace2 _must_ expose a pure C99 API to preserve
1624 ABI compatibility over time.
1629 The {bt2} project is configured to use the {cpp11} standard.
1631 {cpp11} makes it possible to build {bt2} with a broad range of
1632 compilers, from GCC{nbsp}4.8 and Clang{nbsp}3.3.
1634 === Common {cpp} code
1636 Many parts of the project need common {cpp} code. You'll find all of it
1637 under `src/cpp-common`.
1639 In general, anything under a namespace named `internal` is internal to
1640 the API containing it. For example, everything under the `bt2::internal`
1641 namespace is internal to the `bt2` namespace and therefore isn't meant
1642 to be used outside the `src/cpp-common/bt2` directory.
1644 ==== `bt2`: libbabeltrace2 {cpp} bindings
1646 `src/cpp-common/bt2` contains our internal {cpp} bindings of
1647 the libbabeltrace2 C{nbsp}API, under the `bt2` namespace.
1649 Those bindings are designed to have, as much as possible, no performance
1650 impact. Anything which inherits `bt2::BorrowedObject` contains a single
1651 libbabeltrace2 object pointer.
1653 Pass and return borrowed objects _by value_ (copy).
1655 In general, the following holds:
1657 [options="header,autowidth",cols="2"]
1660 |Equivalent C{nbsp}expression
1671 |`const bt2::ConstXyz`
1672 |`const bt_xyz * const`
1675 ==== `bt2c`: general common {cpp} code
1677 Similar to the role of `src/common` for C code.
1679 In general, everything in here is under the `bt2c` namespace.
1684 The `bt2c::align()` function template: a wrapper of
1685 `src/common/align.h`.
1687 `c-string-view.hpp`::
1688 The `bt2c::CStringView` class: a view on a constant null-terminated
1691 We have this because `bt2s::string_view` doesn't imply null termination,
1692 only a beginning and a length.
1694 A `bt2c::CStringView` instance is convertible to `const char *` and may
1695 be empty (the underlying pointer is null).
1698 The `bt2c::call()` function template: a partial implementation of
1699 https://en.cppreference.com/w/cpp/utility/functional[INVOKE].
1701 We use this mostly to assign the result of calling an immediately
1702 invoked function expression (lambda) to an `auto` variable without
1703 risking to assign the lambda itself, should we forget the calling
1708 const auto res = bt2c::call([&] {
1709 /* Complex initialization */
1714 Typed wrappers of `src/compat/endian.h`.
1717 Common exception classes.
1720 Common https://fmt.dev/[{fmt}] formatters.
1723 The `bt2c::Logger` class and helper `BT_CPPLOG*()` macros for any
1726 When possible, prefer using this over the C{nbsp}logging API.
1728 One important benefit is that this API uses {fmt} to format the logging
1729 message instead of `vsnprintf()`.
1732 The `bt2c::PrioHeap` class template: an efficient heap data
1735 `read-fixed-len-int.hpp`::
1736 The function templates `bt2c::readFixedLenInt()`,
1737 `bt2c::readFixedLenIntLe()`, and `bt2c::readFixedLenIntBe()`: read a
1738 fixed-length integer from a byte buffer.
1741 The `bt2c::safe*()` function templates: arithmetic operations which
1742 assert that there's no possible overflow.
1745 The `bt2c::StdIntT` type alias template: becomes one of the
1746 `std::*int*_t` types depending on its parameters.
1748 For example, `bt2c::StdIntT<32, true>` is `std::int32_t`.
1754 The following classes:
1757 Container of a 16-byte
1758 https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID].
1760 Provides the static `generate()` method as well as conversion to
1764 View on a UUID (not a container).
1766 Provides byte access, comparison, as well as string conversion methods.
1768 Also provides conversion to `bt2c::Uuid`.
1771 The `bt2c::vectorFastRemove()` function template: remove an element
1772 from an `std::vector` instance quickly when the order isn't
1775 ==== `bt2s`: drop-in replacements of {cpp}14 to {cpp}20 STL features
1777 Everything under the `bt2s` namespace has its equivalent under the `std`
1778 namespace, but in {cpp} versions we don't yet have access to, namely:
1781 `bt2s::make_unique()`, a drop-in replacement of `std::make_unique()`
1785 Drop-in replacement of the `std::optional` API ({cpp}17).
1788 Drop-in replacement of the `std::span` API ({cpp}20).
1791 Drop-in replacement of the `std::string_view` API ({cpp}17).
1793 ==== `vendor`: copies of {cpp} dependencies
1795 This directory contains copies of the source code of {cpp} dependencies
1796 to avoid packaging issues.
1801 https://fmt.dev/[{fmt}].
1804 https://json.nlohmann.me/[JSON for Modern C++].
1807 https://github.com/martinmoene/optional-lite[optional lite].
1809 IMPORTANT: Use the symbols of `src/cpp-common/bt2s/optional.hpp`, under
1810 the `bt2s` namespace, instead of using this directly.
1813 https://github.com/martinmoene/span-lite[span lite].
1815 IMPORTANT: Use the symbols of `src/cpp-common/bt2s/span.hpp`, under the
1816 `bt2s` namespace, instead of using this directly.
1818 `string-view-lite`::
1819 https://github.com/martinmoene/string-view-lite[string_view lite].
1821 IMPORTANT: Use the symbols of `src/cpp-common/bt2s/string-view.hpp`,
1822 under the `bt2s` namespace, instead of using this directly.
1824 === Automake/Libtool requirements
1826 To add a {cpp} source file to a part of the project, use the `.cpp`
1827 extension and add it to the list of source files in `Makefile.am` as
1830 If a program or a shared library has a direct {cpp} source file, then
1831 Libtool uses the {cpp} linker to create the result, dynamically
1832 linking important runtime libraries such as libstdc++ and libgcc_s.
1834 Because a Libtool _convenience library_ is just an archive (`.a`), it's
1835 _not_ dynamically linked to runtime libraries, even if one of its direct
1836 sources is a {cpp} file. This means that for each program or shared
1837 library named `my_target` in `Makefile.am` which is linked to a
1838 convenience library having {cpp} sources (recursively), you _must_ do
1841 * Have at least one direct {cpp} source file in the
1842 `+*_my_target_SOURCES+` list.
1847 nodist_EXTRA_my_target_SOURCES = dummy.cpp
1851 https://www.gnu.org/software/automake/manual/automake.html#Libtool-Convenience-Libraries[Libtool
1852 Convenience Libraries] to learn more.
1854 For a given program or library, you _cannot_ have a C{nbsp}file and a
1855 {cpp}{nbsp}file having the same name, for example `list.c` and
1860 ==== Whitespaces, indentation, and line breaks
1862 All the project's {cpp} files follow the
1863 https://clang.llvm.org/docs/ClangFormat.html[clang-format]
1864 https://clang.llvm.org/docs/ClangFormatStyleOptions.html[style] of the
1865 `.clang-format` file for whitespaces, indentation, and line breaks.
1867 You _must_ format modified and new {cpp} files with clang-format before
1868 you create a contribution patch.
1870 You need clang-format{nbsp}15 to use the project's `.clang-format` file.
1872 To automatically format all the project's {cpp} files, run:
1875 $ ./tools/format-cpp.sh
1878 To only format the {cpp} files of a given directory:
1881 $ ./tools/format-cpp.sh ./src/cli
1884 Use the `FORMATTER` environment variable to override the default
1885 formatter (`clang-format{nbsp}-i`):
1888 $ FORMATTER='my-clang-format-15 -i' ./tools/format-cpp.sh
1893 * Use camel case with a lowercase first letter for:
1894 ** Variable names: `size`, `objSize`.
1895 ** Function/method names: `size()`, `formatAndPrint()`.
1897 * Use camel case with an uppercase first letter for:
1898 ** Types: `Pistachio`, `NutManager`.
1899 ** Template parameters: `PlanetT`, `TotalSize`.
1901 * Use snake case with uppercase letters for:
1902 ** Definition/macro names: `MARK_AS_UNUSED()`, `SOME_FEATURE_EXISTS`.
1903 ** Enumerators: `Type::SIGNED_INT`, `Scope::FUNCTION`.
1905 * Use only lowercase letters and digits for namespaces: `mylib`, `bt2`.
1907 * Use the `T` suffix for type template parameters and the `V` suffix for
1908 non-type template parameters:
1912 template <typename NameT, typename ItemT, unsigned int SizeV = 0>
1915 * Name a template parameter pack `ArgTs`.
1919 template <typename NameT, typename... ArgTs>
1922 * Use an underscore prefix for private and protected methods and member
1923 type names: `_tryConnect()`, `_NodeType`.
1925 * Use the prefix `_m` for private and protected member variable names:
1926 `_mLogger`, `_mSize`, `_mFieldClass`.
1928 This is to avoid name clashes with private/protected getters/setters.
1930 * Name setters and getters like the property name, without the `set` and
1933 * Use the `is` or `has` prefix, if possible, to name the functions which
1936 However, try to keep the name readable. For example, prefer
1937 `colorIsBlue()` over `isColorBlue()`.
1939 === Coding convention
1941 In general, the project's contributors make an effort to follow,
1945 https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md[{cpp} Core Guidelines].
1948 "`https://www.oreilly.com/library/view/effective-modern-c/9781491908419/[Effective Modern {cpp}]`".
1950 Here are a few important reminders:
1952 * Namespace your code.
1954 * Create one header/source file pair per class when possible.
1956 For a class named `MyClass`, name the corresponding files `my-class.hpp`
1959 * Use the `inline` keyword, not `static inline`, for header-only
1960 functions that are not templates.
1962 * When defining a class, use this order:
1965 . Friends (without any preceding access specifier).
1967 . Public types and type aliases.
1969 Private/protected types may be here too if they can't be lower.
1971 . Constructors, whatever their access.
1973 . Destructor (always public).
1975 . Copy-assignment and move-assignment operators.
1979 . Protected types and type aliases.
1981 . Protected methods.
1983 . Private types and type aliases.
1987 . Protected data members.
1989 . Private data members.
1992 * Declare variables as close to where they're used as possible.
1994 * In general, try to avoid variables if it doesn't lead to more lines.
2000 const auto size = getSize(myObj, 23);
2001 auto& obj = this->_objForSize(size);
2003 abc::sendObj(obj, SendOpts::WAIT);
2010 abc::sendObj(this->_objForSize(getSize(myObj, 23)), SendOpts::WAIT);
2013 * If you really need variables, then scope them to avoid "`leaking`"
2018 doSomeStuff(123, &obj);
2021 const auto status = tryChange(obj);
2023 BT_CPPLOGD("New status: {}.", status);
2024 BT_ASSERT(status == Status::CONTINUE);
2030 This also means to either use a dedicated, named method/function or to
2031 use `bt2c::call()` with an immediately invoked function expression
2032 (lambda) to perform complex initialization of an ideally `const`
2037 const auto size = bt2c::call([this] {
2038 auto& sender = this->_curSender();
2040 if (sender.strategy() == Strategy::ACK) {
2041 return sender.strategySize();
2042 } else if (sender.strategy() == Strategy::NACK) {
2050 * Always use `bt2c::call()` to call an immediately invoked function
2051 expression (see the previous point).
2053 * If possible, initialize object members without a default value with
2054 the initializer list of a constructor, not in the constructor body.
2056 If the initialization is complex, either use a dedicated, named
2057 method/function or `bt2c::call()` with an immediately invoked function
2058 expression (lambda):
2062 MyObj::MyObj(const std::size_t size) :
2064 _mOtherObj {bt2c::call([size] {
2065 /* Complex initialization here */
2071 * Use `auto` when possible.
2073 Use `auto&` instead of `const auto&` when you know that the type is
2078 * Use `const` as much as possible, even for pointers
2079 (`+const char * const+`) and numeric values (`const unsigned int`)
2080 which never need to change.
2082 * Prefer the `pass:[MyObj myObj {...}]` initialization form over
2083 `pass:[auto myObj = MyObj {...}]`.
2085 * Implement simple setters, getters, and one-liners in header files and
2086 everything else that's not a template in source files, including
2089 * Make methods `const noexcept` or `const` as much as possible.
2091 * Make constructors `explicit` unless you really need an implicit
2092 constructor (which is rare), including default constructors:
2099 * Use `std::unique_ptr` to manage memory when possible.
2101 However, use references (`+*my_unique_ptr+`) and raw pointers
2102 (`+my_unique_ptr.get()+`) when not transferring ownership.
2104 * Use `nullptr`, not `NULL` nor 0.
2106 * Return by value (rvalue) instead of by output parameter (non-const
2107 lvalue reference), even complex objects, unless you can prove that the
2108 performance is improved when returning by parameter.
2110 * For a function parameter or a return value of which the type needs to
2111 be a reference or pointer, use:
2113 If the value is mandatory:::
2115 If the value is optional:::
2118 * Don't use `+std::move()+` when you already have an rvalue, which
2120 ** Don't write `+return std::move(...);+` as this can interfere with
2122 ** Don't use `+std::move()+` with a function call
2123 (`+std::move(func())+`).
2125 * For each possible move/copy constructor or assignment operator, do one
2127 ** Write a custom one.
2128 ** Mark it as defaulted (`default`)
2129 ** Mark it as deleted (`delete`).
2131 * Use scoped enumerations (`+enum class+`).
2133 * Mark classes known to be final with the `final` keyword.
2135 * Use type aliases (`using`), not type definitions (`typedef`).
2137 * In a `.cpp` file, use anonymous namespaces for local symbols instead
2138 of `static` or `inline`.
2140 * Prefer a function in an anonymous namespace in a `.cpp` file over a
2141 private static method if it doesn't need private access to an object.
2143 * Don't pollute the global namespace:
2144 ** Don't use `using namespace xyz` anywhere.
2145 ** Use only namespace aliases in source files (`.cpp`), trying to
2146 use them in the smallest possible scope (function, or even smaller).
2148 * Return a structure with named members instead of a generic container
2149 such as `std::pair` or `std::tuple`.
2151 * When a class inherits a base class with virtual methods, use the
2152 `override` keyword to mark overridden virtual methods, and do not use
2153 the `virtual` keyword again.
2155 * Define overloaded operators only if their meaning is obvious,
2156 unsurprising, and consistent with the corresponding built-in
2159 For example, use `+|+` as a bitwise- or logical-or, not as a shell-style
2162 * Use RAII wrappers when managing system resources or interacting with
2165 In other words, don't rely on ``goto``s and error labels to clean up as
2166 you would do in{nbsp}C.
2170 * Throw an exception when there's an unexpected, exceptional condition,
2171 https://isocpp.org/wiki/faq/exceptions#ctors-can-throw[including from
2172 a constructor], instead of returning a status code.
2174 * Accept a by-value parameter and move it (when it's moveable) when you
2175 intend to copy it anyway.
2177 You can do this with most STL containers.
2183 void Obj::doSomething(std::string str)
2185 _mName = std::move(str);
2192 This example shows a {cpp} header which follows the {bt2} {cpp} coding
2198 * SPDX-FileCopyrightText: 2020 Harry Burnett <hburnett@reese.choco>
2199 * SPDX-License-Identifier: MIT
2202 #ifndef BABELTRACE_BABY_HPP
2203 #define BABELTRACE_BABY_HPP
2206 #include <unordered_set>
2214 * A baby is a little human.
2216 class Baby : public Human
2218 friend class Parent;
2221 using Toys = std::unordered_set<Toy>;
2230 explicit Baby() = default;
2231 explicit Baby(const Toys& toys);
2232 Baby(const Baby&) = delete;
2233 Baby(Baby&&) = delete;
2236 explicit Baby(Gender initialGender = Gender::OTHER);
2240 Baby& operator=(const Baby&) = delete;
2241 Baby& operator=(Baby&&) = delete;
2244 * Eats `weight` grams of food.
2246 void eat(unsigned long weight);
2249 * Sleeps for `duration` seconds.
2251 void sleep(double duration);
2254 * Sets this baby's name to `name`.
2256 void name(std::string name)
2258 _mName = std::move(name);
2264 const std::string& name() const noexcept
2270 void _addTeeth(unsigned long index);
2271 void _grow(double size) override;
2274 std::string _mName {"Paul"};
2278 } /* namespace life */
2280 #endif /* BABELTRACE_BABY_HPP */
2288 All Python code must be formatted using the version of
2289 https://github.com/psf/black[Black] specified in `dev-requirements.txt`.
2291 All Python imports must be sorted using the version of
2292 https://pycqa.github.io/isort/[isort] indicated in `dev-requirements.txt`.