Add `tools/format-cpp` script
[babeltrace.git] / CONTRIBUTING.adoc
1 // Render with Asciidoctor
2
3 = Babeltrace{nbsp}2 contributor's guide
4 Jérémie Galarneau, Philippe Proulx
5 1 December 2020
6 :toc: left
7 :toclevels: 3
8 :icons: font
9 :nofooter:
10 :bt2: Babeltrace{nbsp}2
11 :c-cpp: C/{cpp}
12 :cpp11: {cpp}11
13
14 This is a partial contributor's guide for the
15 https://babeltrace.org[{bt2}] project. If you have any
16 questions that are not answered by this guide, please post them on
17 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's
18 mailing list].
19
20 == {bt2} library
21
22 === Object reference counting and lifetime
23
24 This section covers the rationale behind the design of {bt2}'s
25 object lifetime management. This applies to the {bt2} library, as
26 well as to the CTF writer library (although the public reference
27 counting functions are not named the same way).
28
29 Starting from Babeltrace{nbsp}2.0, all publicly exposed objects inherit
30 a common base: `bt_object`. This base provides a number of facilities to
31 all objects, chief amongst which are lifetime management functions.
32
33 The lifetime of some public objects is managed by reference counting. In
34 this case, the API offers the `+bt_*_get_ref()+` and `+bt_*_put_ref()+`
35 functions which respectively increment and decrement an object's
36 reference count.
37
38 As far as lifetime management in concerned, {bt2} makes a clear
39 distinction between regular objects, which have a single parent, and
40 root objects, which don't.
41
42 ==== The problem
43
44 Let us consider a problematic case to illustrate the need for this
45 distinction.
46
47 A user of the {bt2} library creates a trace class, which _has_ a
48 stream class (the class of a stream) and that stream class, in turn,
49 _has_ an event class (the class of an event).
50
51 Nothing prevents this user from releasing his reference on any one of
52 these objects in any order. However, all objects in the
53 __trace--stream class--event class__ hierarchy can be retrieved
54 from any other.
55
56 For instance, the user could discard his reference on both the event
57 class and the stream class, only keeping a reference on the trace class.
58 From this trace class reference, stream classes can be enumerated,
59 providing the user with a new reference to the stream class he discarded
60 earlier. Event classes can also be enumerated from stream classes,
61 providing the user with references to the individual event classes.
62
63 Conversely, the user could also hold a reference to an event class and
64 retrieve its parent stream class. The trace class, in turn, can then be
65 retrieved from the stream class.
66
67 This example illustrates what could be interpreted as a circular
68 reference dependency existing between these objects. Of course, if the
69 objects in such a scenario were to hold references to each other (in
70 both directions), we would be in presence of a circular ownership
71 resulting in a leak of both objects as their reference counts would
72 never reach zero.
73
74 Nonetheless, the API must offer the guarantee that holding a node to any
75 node of the graph keeps all other reachable nodes alive.
76
77 ==== The solution
78
79 The scheme employed in {bt2} to break this cycle consists in the
80 "children" holding _reverse component references_ to their parents. That
81 is, in the context of the trace IR, that event classes hold a reference
82 to their parent stream class and stream classes hold a reference to
83 their parent trace class.
84
85 On the other hand, parents hold _claiming aggregation references_ to
86 their children. A claiming aggregation reference means that the object
87 being referenced should not be deleted as long as the reference still
88 exists. In this respect, it can be said that parents truly hold the
89 ownership of their children, since they control their lifetime.
90 Conversely, the reference counting mechanism is leveraged by children to
91 notify parents that no other child indirectly exposes the parent.
92
93 When a parented object's reference count reaches zero, it invokes
94 `+bt_*_put_ref()+` on its parent and does _not_ free itself. However,
95 from that point, the object depends on its parent to signal the moment
96 when it can be safely reclaimed.
97
98 The invocation of `+bt_*_put_ref()+` by the last children holding a
99 reference to its parent might trigger a cascade of `+bt_*_put_ref()+`
100 from child to parent. Eventually, a **root** object is reached. At that
101 point, if this orphaned object's reference count reaches zero, the
102 object invokes the destructor method defined by everyone of its children
103 as part of their base `struct bt_object`. The key point here is that the
104 cascade of destructor will necessarily originate from the root and
105 propagate in preorder to the children. These children will propagate the
106 destruction to their own children before reclaiming their own memory.
107 This ensures that a node's pointer to its parent is _always_ valid since
108 the parent has the responsibility of tearing-down their children before
109 cleaning themselves up.
110
111 Assuming a reference to an object is _acquired_ by calling
112 `+bt_*_get_ref()+` while its reference count is zero, the object
113 acquires, in turn, a reference on its parent using `+bt_*_get_ref()+`.
114 At that point, the child can be thought of as having converted its weak
115 reference to its parent into a regular reference. That is why this
116 reference is referred to as a _claiming_ aggregation reference.
117
118 ==== Caveats
119
120 This scheme imposes a number of strict rules defining the relation
121 between objects:
122
123 * Objects may only have one parent.
124 * Objects, beside the root, are only retrievable from their direct
125 parent or children.
126
127 ==== Example
128
129 The initial situation is rather simple: **User{nbsp}A** is holding a
130 reference to a trace class, **TC1**. As per the rules previously
131 enounced, stream classes **SC1** and **SC2** don't hold a reference to
132 **TC1** since their own reference counts are zero. The same holds true
133 for **EC1**, **EC2** and **EC3** with respect to **SC1** and **SC2**.
134
135 image::doc/contributing-images/bt-ref01.png[]
136
137 In this second step, we can see that **User{nbsp}A** has acquired a
138 reference on **SC2** through the trace class, **TC1**.
139
140 The stream class's reference count transitions from zero to one,
141 triggering the acquisition of a strong reference on **TC1** from
142 **SC2**.
143
144 Hence, at this point, the trace class's ownership is shared by
145 **User{nbsp}A** and **SC2**.
146
147 image::doc/contributing-images/bt-ref02.png[]
148
149 Next, **User{nbsp}A** acquires a reference on the **EC3** event class
150 through its parent stream class, **SC2**. Again, the transition of an
151 object's reference count from 0 to 1 triggers the acquisition of a
152 reference on its parent.
153
154 Note that SC2's reference count was incremented to 2. The trace class's
155 reference count remains unchanged.
156
157 image::doc/contributing-images/bt-ref03.png[]
158
159 **User{nbsp}A** decides to drop its reference on **SC2**. **SC2**'s
160 reference count returns back to 1, everything else remaining unchanged.
161
162 image::doc/contributing-images/bt-ref04.png[]
163
164 **User{nbsp}A** can then decide to drop its reference on the trace
165 class. This results in a reversal of the initial situation:
166 **User{nbsp}A** now owns an event, **EC3**, which is keeping everything
167 else alive and reachable.
168
169 image::doc/contributing-images/bt-ref05.png[]
170
171 If another object, **User{nbsp}B**, enters the picture and acquires a
172 reference on the **SC1** stream class, we see that **SC1**'s reference
173 count transitioned from 0 to 1, triggering the acquisition of a
174 reference on **TC1**.
175
176 image::doc/contributing-images/bt-ref06.png[]
177
178 **User{nbsp}B** hands off a reference to **EC1**, acquired through
179 **SC1**, to another object, **User{nbsp}C**. The acquisition of a
180 reference on **EC1**, which transitions from 0 to 1, triggers the
181 acquisition of a reference on its parent, **SC1**.
182
183 image::doc/contributing-images/bt-ref07.png[]
184
185 At some point, **User{nbsp}A** releases its reference on **EC3**. Since
186 **EC3**'s reference count transitions to zero, it releases its reference
187 on **SC2**. **SC2**'s reference count, in turn, reaches zero and it
188 releases its reference to **TC1**.
189
190 **TC1**'s reference count is now 1 and no further action is taken.
191
192 image::doc/contributing-images/bt-ref08.png[]
193
194 **User{nbsp}B** releases its reference on **SC1**. **User{nbsp}C**
195 becomes the sole owner of the whole hierarchy through his ownership of
196 **EC1**.
197
198 image::doc/contributing-images/bt-ref09.png[]
199
200 Finally, **User{nbsp}C** releases his ownership of **EC1**, triggering
201 the release of the whole hierarchy. Let's walk through the reclamation
202 of the whole graph.
203
204 Mirroring what happened when **User{nbsp}A** released its last reference
205 on **EC3**, the release of **EC1** by **User{nbsp}C** causes its
206 reference count to fall to zero.
207
208 This transition to zero causes **EC1** to release its reference on
209 **SC1**. **SC1**'s reference count reaching zero causes it to release
210 its reference on **TC1**.
211
212 image::doc/contributing-images/bt-ref10.png[]
213
214 Since the reference count of **TC1**, a root object, has reached zero,
215 it invokes the destructor method on its children. This method is
216 recursive and causes the stream classes to call the destructor method on
217 their event classes.
218
219 The event classes are reached and, having no children of their own, are
220 reclaimed.
221
222 image::doc/contributing-images/bt-ref11.png[]
223
224 The stream classes having destroyed their children, are then reclaimed
225 by the trace class.
226
227 image::doc/contributing-images/bt-ref12.png[]
228
229 Finally, the stream classes having been reclaimed, **TC1** is reclaimed.
230
231 image::doc/contributing-images/bt-ref13.png[]
232
233
234 == Logging
235
236 Logging is a great instrument for a developer to be able to collect
237 information about a running software.
238
239 {bt2} is a complex software with many layers. When a {bt2}
240 graph fails to run, what caused the failure? It could be caused by any
241 component, any message iterator, and any deeply nested validation of a
242 CTF IR object (within the `ctf` plugin), for example. With the
243 appropriate logging statements manually placed in the source code, we
244 can find the cause of a bug faster.
245
246 While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
247 _FATAL_ logging statements, you should liberally instrument your
248 {bt2} module with _TRACE_ logging statements to help future you
249 and other developers understand what's happening at run time.
250
251 === Logging API
252
253 The {bt2} logging API is internal: it is not exposed to the users
254 of the library; only to their developers. The only thing that a library
255 user can control is the current log level of the library itself with
256 `bt_logging_set_global_level()` and the initial library's log level with
257 the `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable.
258
259 This API is based on https://github.com/wonder-mice/zf_log[zf_log], a
260 lightweight, yet featureful, MIT-licensed core logging library for C and
261 {cpp}. The zf_log source files were modified to have the `BT_` and
262 `bt_` prefixes, and other small changes, like color support and using
263 the project's `BT_DEBUG_MODE` definition instead of the standard
264 `NDEBUG`.
265
266 The logging functions are implemented in the logging convenience
267 library (`src/logging` directory).
268
269 [[logging-headers]]
270 ==== Headers
271
272 The logging API headers are:
273
274 `<babeltrace2/logging.h>`::
275 Public header which a library user can use to set and get
276 libbabeltrace2's current log level.
277
278 `"logging/log.h"`::
279 Internal, generic logging API which you can use in any {bt2}
280 module. This is the translation of `zf_log.h`.
281 +
282 This header offers the <<gen-logging-statements,generic logging
283 statement macros>>.
284
285 `"lib/logging.h"`::
286 Specific internal header to use within the library.
287 +
288 This header defines `BT_LOG_OUTPUT_LEVEL` to a custom, library-wide
289 hidden symbol which is the library's current log level before including
290 `"logging/log.h"`.
291 +
292 This header offers the <<lib-logging-statements,library-specific logging
293 statement macros>>.
294
295 `"logging/comp-logging.h"`::
296 Specific internal header to use within a component class.
297 +
298 This header offers the <<comp-logging-statements,component-specific
299 logging statement macros>>.
300
301 [[log-levels]]
302 ==== Log levels
303
304 The internal logging API offers the following log levels, in ascending
305 order of severity:
306
307 [options="header,autowidth",cols="4"]
308 |===
309 |Log level name
310 |Log level short name
311 |Internal API enumerator
312 |Public API enumerator
313
314 |_TRACE_
315 |`T`
316 |`BT_LOG_TRACE`
317 |`BT_LOGGING_LEVEL_TRACE`
318
319 |_DEBUG_
320 |`D`
321 |`BT_LOG_DEBUG`
322 |`BT_LOGGING_LEVEL_DEBUG`
323
324 |_INFO_
325 |`I`
326 |`BT_LOG_INFO`
327 |`BT_LOGGING_LEVEL_INFO`
328
329 |_WARNING_
330 |`W`
331 |`BT_LOG_WARNING`
332 |`BT_LOGGING_LEVEL_WARNING`
333
334 |_ERROR_
335 |`E`
336 |`BT_LOG_ERROR`
337 |`BT_LOGGING_LEVEL_ERROR`
338
339 |_FATAL_
340 |`F`
341 |`BT_LOG_FATAL`
342 |`BT_LOGGING_LEVEL_FATAL`
343
344 |_NONE_
345 |`N`
346 |`BT_LOG_NONE`
347 |`BT_LOGGING_LEVEL_NONE`
348 |===
349
350 The short name is accepted by the log level environment variables and by
351 the CLI's `--log-level` options.
352
353 See <<choose-a-log-level,how to decide which one to use>> below.
354
355 There are two important log level expressions:
356
357 [[build-time-log-level]]Build-time, minimal log level::
358 The minimal log level, or build-time log level, is set at build time
359 and determines the minimal log level of the logging statements which
360 can be executed. This applies to all the modules (CLI, library,
361 plugins, bindings, etc.).
362 +
363 All the logging statements with a level below this level are **not built
364 at all**. All the logging statements with a level equal to or greater
365 than this level _can_ be executed, depending on the
366 <<run-time-log-level,run-time log level>>.
367 +
368 You can set this level at configuration time with the
369 `BABELTRACE_MINIMAL_LOG_LEVEL` environment variable, for example:
370 +
371 --
372 ----
373 $ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure
374 ----
375 --
376 +
377 The default build-time log level is `DEBUG`. For optimal performance,
378 set it to `INFO`, which effectively disables all fast path logging in
379 all the {bt2} modules. You can't set it to `WARNING`, `ERROR`,
380 `FATAL`, or `NONE` because the impact on performance is minuscule
381 starting from the _INFO_ log level anyway and we want any {bt2}
382 build to always be able to print _INFO_-level logs.
383 +
384 The library's public API provides `bt_logging_get_minimal_level()` to
385 get the configured minimal log level.
386
387 [[run-time-log-level]]Run-time, dynamic log level::
388 The dynamic log level is set at run time and determines the current,
389 _active_ log level. All the logging statements with a level below
390 this level are not executed, **but they still evaluate the
391 condition**. All the logging statements with a level equal to or
392 greater than this level are executed, provided that their level is
393 also <<build-time-log-level,enabled at build time>>.
394 +
395 `zf_log` has a concept of a global run-time log level which uses the
396 `_bt_log_global_output_lvl` symbol. In practice, we never use this
397 symbol, and always make sure that `BT_LOG_OUTPUT_LEVEL` is defined to a
398 module-wise expression before including `"logging/log.h"`.
399 +
400 In the library, `"lib/logging.h"` defines its own
401 `BT_LOG_OUTPUT_LEVEL` to the library's log level symbol before it
402 includes `"logging/log.h"` itself.
403 +
404 In libbabeltrace2, the user can set the current run-time log level with
405 the `bt_logging_set_global_level()` function, for example:
406 +
407 --
408 [source,c]
409 ----
410 bt_logging_set_global_level(BT_LOGGING_LEVEL_INFO);
411 ----
412 --
413 +
414 The library's initial run-time log level is defined by the
415 `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable, or set to _NONE_
416 if this environment variable is undefined.
417 +
418 Other modules have their own way of setting their run-time log level.
419 +
420 For example, the CLI uses the `BABELTRACE_CLI_LOG_LEVEL` environment
421 variable, as well as its global `--log-level` option:
422 +
423 ----
424 $ babeltrace2 --log-level=I ...
425 ----
426 +
427 The components use their own log level (as returned by
428 `bt_component_get_logging_level()`). With the CLI, you can set a
429 specific component's log level with its own, position-dependent
430 `--log-level` option:
431 +
432 ----
433 $ babeltrace2 /path/to/trace -c sink.ctf.fs --log-level=D
434 ----
435 +
436 Code which is common to the whole project, for example `src/common`
437 and `src/compat`, use function parameters to get its run-time log
438 level, for example:
439 +
440 [source,c]
441 ----
442 BT_HIDDEN
443 char *bt_common_get_home_plugin_path(int log_level);
444 ----
445 +
446 Typically, when a logging-enabled module calls such a function, it
447 passes its own log level expression directly (`BT_LOG_OUTPUT_LEVEL`):
448 +
449 [source,c]
450 ----
451 path = bt_common_get_home_plugin_path(BT_LOG_OUTPUT_LEVEL);
452 ----
453 +
454 Otherwise, just pass `BT_LOG_NONE`:
455 +
456 ----
457 path = bt_common_get_home_plugin_path(BT_LOG_NONE);
458 ----
459
460 [[gen-logging-statements]]
461 ==== Generic logging statement macros
462
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.
466
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.
471
472 See <<logging-instrument-c-file-gen>> and
473 <<logging-instrument-h-file-gen>> to learn how to be able to use the
474 following macros.
475
476 `+BT_LOGT("format string", ...)+`::
477 Generic trace logging statement.
478
479 `+BT_LOGD("format string", ...)+`::
480 Generic debug logging statement.
481
482 `+BT_LOGI("format string", ...)+`::
483 Generic info logging statement.
484
485 `+BT_LOGW("format string", ...)+`::
486 Generic warning logging statement.
487
488 `+BT_LOGE("format string", ...)+`::
489 Generic error logging statement.
490
491 `+BT_LOGF("format string", ...)+`::
492 Generic fatal logging statement.
493
494 `+BT_LOGT_STR("preformatted string")+`::
495 Generic preformatted string trace logging statement.
496
497 `+BT_LOGD_STR("preformatted string")+`::
498 Generic preformatted string debug logging statement.
499
500 `+BT_LOGI_STR("preformatted string")+`::
501 Generic preformatted string info logging statement.
502
503 `+BT_LOGW_STR("preformatted string")+`::
504 Generic preformatted string warning logging statement.
505
506 `+BT_LOGE_STR("preformatted string")+`::
507 Generic preformatted string error logging statement.
508
509 `+BT_LOGF_STR("preformatted string")+`::
510 Generic preformatted string fatal logging statement.
511
512 `+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
513 Generic memory trace logging statement.
514
515 `+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
516 Generic memory debug logging statement.
517
518 `+BT_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
519 Generic memory info logging statement.
520
521 `+BT_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
522 Generic memory warning logging statement.
523
524 `+BT_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
525 Generic memory error logging statement.
526
527 `+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
528 Generic memory fatal logging statement.
529
530 `+BT_LOGT_ERRNO("initial message", "format string", ...)+`::
531 Generic `errno` string trace logging statement.
532
533 `+BT_LOGD_ERRNO("initial message", "format string", ...)+`::
534 Generic `errno` string debug logging statement.
535
536 `+BT_LOGI_ERRNO("initial message", "format string", ...)+`::
537 Generic `errno` string info logging statement.
538
539 `+BT_LOGW_ERRNO("initial message", "format string", ...)+`::
540 Generic `errno` string warning logging statement.
541
542 `+BT_LOGE_ERRNO("initial message", "format string", ...)+`::
543 Generic `errno` string error logging statement.
544
545 `+BT_LOGF_ERRNO("initial message", "format string", ...)+`::
546 Generic `errno` string fatal logging statement.
547
548 [[lib-logging-statements]]
549 ==== Library-specific logging statement macros
550
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.
554
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.
558
559 The library logging statement macros are named `+BT_LIB_LOG*()+` instead
560 of `+BT_LOG*()+`:
561
562 `+BT_LIB_LOGT("format string", ...)+`::
563 Library trace logging statement.
564
565 `+BT_LIB_LOGD("format string", ...)+`::
566 Library debug logging statement.
567
568 `+BT_LIB_LOGI("format string", ...)+`::
569 Library info logging statement.
570
571 `+BT_LIB_LOGW("format string", ...)+`::
572 Library warning logging statement.
573
574 `+BT_LIB_LOGE("format string", ...)+`::
575 Library error logging statement.
576
577 `+BT_LIB_LOGF("format string", ...)+`::
578 Library fatal logging statement.
579
580 `+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
581 Library warning logging statement, and unconditional error cause
582 appending.
583
584 `+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
585 Library error logging statement, and unconditional error cause
586 appending.
587
588 `+BT_LIB_LOGF_APPEND_CAUSE("format string", ...)+`::
589 Library fatal logging statement, and unconditional error cause
590 appending.
591
592 The macros above accept the typical `printf()` conversion specifiers
593 with the following limitations:
594
595 * The `+*+` width specifier is not accepted.
596 * The `+*+` precision specifier is not accepted.
597 * The `j` and `t` length modifiers are not accepted.
598 * The `n` format specifier is not accepted.
599 * The format specifiers defined in `<inttypes.h>` are not accepted,
600 except for `PRId64`, `PRIu64`, `PRIx64`, `PRIX64`, `PRIo64`, and
601 `PRIi64`.
602
603 The {bt2} library custom conversion specifier is accepted. Its
604 syntax is either `%!u` to format a UUID (`bt_uuid` type), or:
605
606 . Introductory `%!` sequence.
607
608 . **Optional**: `[` followed by a custom prefix for the printed fields
609 of this specifier, followed by `]`. The standard form is to end this
610 prefix with `-` so that, for example, with the prefix `tc-`, the
611 complete field name becomes `tc-addr`.
612
613 . **Optional**: `pass:[+]` to print extended object members. This
614 depends on the provided format specifier.
615
616 . Format specifier (see below).
617
618 The available format specifiers are:
619
620 [options="header,autowidth",cols="3"]
621 |===
622 |Specifier
623 |Object
624 |Expected C type
625
626 |`F`
627 |Trace IR field class
628 |`+const struct bt_field_class *+`
629
630 |`f`
631 |Trace IR field
632 |`+const struct bt_field *+`
633
634 |`P`
635 |Trace IR field path
636 |`+const struct bt_field_path *+`
637
638 |`E`
639 |Trace IR event class
640 |`+const struct bt_event_class *+`
641
642 |`e`
643 |Trace IR event
644 |`+const struct bt_event *+`
645
646 |`S`
647 |Trace IR stream class.
648 |`+const struct bt_stream_class *+`
649
650 |`s`
651 |Trace IR stream
652 |`+const struct bt_stream *+`
653
654 |`a`
655 |Trace IR packet
656 |`+const struct bt_packet *+`
657
658 |`T`
659 |Trace IR trace class
660 |`+const struct bt_trace_class *+`
661
662 |`t`
663 |Trace IR trace
664 |`+const struct bt_trace *+`
665
666 |`K`
667 |Trace IR clock class
668 |`+const struct bt_clock_class *+`
669
670 |`k`
671 |Trace IR clock snapshot
672 |`+const struct bt_clock_snapshot *+`
673
674 |`v`
675 |Value object
676 |`+const struct bt_value *+`
677
678 |`R`
679 |Integer range set
680 |`const struct bt_integer_range_set *`
681
682 |`n`
683 |Message
684 |`+const struct bt_message *+`
685
686 |`I`
687 |Message iterator class
688 |`struct bt_message_iterator_class *`
689
690 |`i`
691 |Message iterator
692 |`struct bt_message_iterator *`
693
694 |`C`
695 |Component class
696 |`struct bt_component_class *`
697
698 |`c`
699 |Component
700 |`+const struct bt_component *+`
701
702 |`p`
703 |Port
704 |`+const struct bt_port *+`
705
706 |`x`
707 |Connection
708 |`+const struct bt_connection *+`
709
710 |`g`
711 |Graph
712 |`+const struct bt_graph *+`
713
714 |`z`
715 |Interrupter
716 |`+struct bt_interrupter *+`
717
718 |`l`
719 |Plugin
720 |`+const struct bt_plugin *+`
721
722 |`r`
723 |Error cause
724 |`+const struct bt_error_cause *+`
725
726 |`o`
727 |Object pool
728 |`+const struct bt_object_pool *+`
729
730 |`O`
731 |Object
732 |`+const struct bt_object *+`
733 |===
734
735 Conversion specifier examples:
736
737 * `%!f`
738 * `%![my-event-]+e`
739 * `%!t`
740 * `%!+F`
741
742 The ``, `` string (comma and space) is printed between individual
743 fields, but **not after the last one**. Therefore, you must put this
744 separator in the format string between two conversion specifiers, for
745 example:
746
747 [source,c]
748 ----
749 BT_LIB_LOGW("Message: count=%u, %!E, %!+K", count, event_class, clock_class);
750 ----
751
752 Example with a custom prefix:
753
754 [source,c]
755 ----
756 BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b);
757 ----
758
759 It is safe to pass `NULL` as any {bt2} object parameter: the macros
760 only print its null address.
761
762 WARNING: Build-time `printf()` format checks are disabled for the
763 `+BT_LIB_LOG*()+` macros because there are custom conversion specifiers,
764 so make sure to test your logging statements.
765
766 [[comp-logging-statements]]
767 ==== Component-specific logging statement macros
768
769 There are available logging macros for components. They prepend a prefix
770 including the component's name to the logging message.
771
772 See <<logging-instrument-c-file-compcls>> and
773 <<logging-instrument-h-file-compcls>> to learn how to be able to use the
774 following macros.
775
776 The component logging statement macros are named `+BT_COMP_LOG*()+`
777 instead of `+BT_LOG*()+`:
778
779 `+BT_COMP_LOGT("format string", ...)+`::
780 Component trace logging statement.
781
782 `+BT_COMP_LOGD("format string", ...)+`::
783 Component debug logging statement.
784
785 `+BT_COMP_LOGI("format string", ...)+`::
786 Component info logging statement.
787
788 `+BT_COMP_LOGW("format string", ...)+`::
789 Component warning logging statement.
790
791 `+BT_COMP_LOGE("format string", ...)+`::
792 Component error logging statement.
793
794 `+BT_COMP_LOGF("format string", ...)+`::
795 Component fatal logging statement.
796
797 `+BT_COMP_LOGT_STR("preformatted string")+`::
798 Component preformatted string trace logging statement.
799
800 `+BT_COMP_LOGD_STR("preformatted string")+`::
801 Component preformatted string debug logging statement.
802
803 `+BT_COMP_LOGI_STR("preformatted string")+`::
804 Component preformatted string info logging statement.
805
806 `+BT_COMP_LOGW_STR("preformatted string")+`::
807 Component preformatted string warning logging statement.
808
809 `+BT_COMP_LOGE_STR("preformatted string")+`::
810 Component preformatted string error logging statement.
811
812 `+BT_COMP_LOGF_STR("preformatted string")+`::
813 Component preformatted string fatal logging statement.
814
815 `+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`::
816 Component `errno` string trace logging statement.
817
818 `+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
819 Component `errno` string debug logging statement.
820
821 `+BT_COMP_LOGI_ERRNO("initial message", "format string", ...)+`::
822 Component `errno` string info logging statement.
823
824 `+BT_COMP_LOGW_ERRNO("initial message", "format string", ...)+`::
825 Component `errno` string warning logging statement.
826
827 `+BT_COMP_LOGE_ERRNO("initial message", "format string", ...)+`::
828 Component `errno` string error logging statement.
829
830 `+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
831 Component `errno` string fatal logging statement.
832
833 `+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
834 Component memory trace logging statement.
835
836 `+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
837 Component memory debug logging statement.
838
839 `+BT_COMP_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
840 Component memory info logging statement.
841
842 `+BT_COMP_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
843 Component memory warning logging statement.
844
845 `+BT_COMP_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
846 Component memory error logging statement.
847
848 `+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
849 Component memory fatal logging statement.
850
851 ==== Conditional logging
852
853 `+BT_LOG_IF(cond, statement)+`::
854 Execute `statement` only if `cond` is true.
855 +
856 Example:
857 +
858 --
859 [source,c]
860 ----
861 BT_LOG_IF(i < count / 2, BT_LOGD("Log this: i=%d", i));
862 ----
863 --
864
865 To check the <<build-time-log-level,build-time log level>>:
866
867 [source,c]
868 ----
869 #if BT_LOG_ENABLED_DEBUG
870 ...
871 #endif
872 ----
873
874 This tests if the _DEBUG_ level was enabled at build time. This means
875 that the current, <<run-time-log-level,run-time log level>> _could_ be
876 _DEBUG_, but it could also be higher. The rule of thumb is to use only
877 logging statements at the same level in a `BT_LOG_ENABLED_*` conditional
878 block.
879
880 The available definitions for build-time conditions are:
881
882 * `BT_LOG_ENABLED_TRACE`
883 * `BT_LOG_ENABLED_DEBUG`
884 * `BT_LOG_ENABLED_INFO`
885 * `BT_LOG_ENABLED_WARNING`
886 * `BT_LOG_ENABLED_ERROR`
887 * `BT_LOG_ENABLED_FATAL`
888
889 To check the current, <<run-time-log-level,run-time log level>>:
890
891 [source,c]
892 ----
893 if (BT_LOG_ON_DEBUG) {
894 ...
895 }
896 ----
897
898 This tests if the _DEBUG_ log level is dynamically turned on
899 (implies that it's also enabled at build time). This check could have a
900 noticeable impact on performance.
901
902 The available definitions for run-time conditions are:
903
904 * `BT_LOG_ON_TRACE`
905 * `BT_LOG_ON_DEBUG`
906 * `BT_LOG_ON_INFO`
907 * `BT_LOG_ON_WARNING`
908 * `BT_LOG_ON_ERROR`
909 * `BT_LOG_ON_FATAL`
910
911 Those macros check the module-specific log level symbol (defined by
912 `BT_LOG_OUTPUT_LEVEL`).
913
914 Never, ever write code which would be executed only to compute the
915 fields of a logging statement outside a conditional logging scope,
916 for example:
917
918 [source,c]
919 ----
920 int number = get_number_of_event_classes_with_property_x(...);
921 BT_LOGD("Bla bla: number=%d", number);
922 ----
923
924 Do this instead:
925
926 [source,c]
927 ----
928 if (BT_LOG_ON_DEBUG) {
929 int number = get_number_of_event_classes_with_property_x(...);
930 BT_LOGD("Bla bla: number=%d", number);
931 }
932 ----
933
934 Or even this:
935
936 [source,c]
937 ----
938 BT_LOGD("Bla bla: number=%d", get_number_of_event_classes_with_property_x(...));
939 ----
940
941 === Guides
942
943 [[logging-instrument-c-file-gen]]
944 ==== Instrument a {c-cpp} source file (generic)
945
946 To instrument a {c-cpp} source file (`.c`/`.cpp`):
947
948 . At the top of the file, before the first `#include` line (if any),
949 define your file's <<choose-a-logging-tag,logging tag>> name:
950 +
951 --
952 [source,c]
953 ----
954 #define BT_LOG_TAG "SUBSYS/MY-MODULE/MY-FILE"
955 ----
956 --
957
958 . Below the line above, define the source file's log level expression,
959 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
960 <<gen-logging-statements,logging statement>> to know the current
961 <<run-time-log-level,run-time log level>>.
962 +
963 Examples:
964 +
965 [source,c]
966 ----
967 /* Global log level variable */
968 #define BT_LOG_OUTPUT_LEVEL module_global_log_level
969 ----
970 +
971 [source,c]
972 ----
973 /* Local log level variable; must exist where you use BT_LOG*() */
974 #define BT_LOG_OUTPUT_LEVEL log_level
975 ----
976 +
977 [source,c]
978 ----
979 /* Object's log level; `obj` must exist where you use BT_LOG*() */
980 #define BT_LOG_OUTPUT_LEVEL (obj->log_level)
981 ----
982
983 . Include `"logging/log.h"`:
984 +
985 [source,c]
986 ----
987 #include "logging/log.h"
988 ----
989
990 . In the file, instrument your code with the
991 <<gen-logging-statements,generic logging statement macros>>.
992
993 [[logging-instrument-h-file-gen]]
994 ==== Instrument a {c-cpp} header file (generic)
995
996 To instrument a {c-cpp} header file (`.h`/`.hpp`), if you have
997 `static inline` functions in it:
998
999 . Do not include `"logging/log.h"`!
1000
1001 . Do one of:
1002
1003 .. In the file, instrument your code with the
1004 <<gen-logging-statements,generic logging statement macros>>, making
1005 each of them conditional to the existence of the macro you're using:
1006 +
1007 [source,c]
1008 ----
1009 static inline
1010 int some_function(int x)
1011 {
1012 /* ... */
1013
1014 #ifdef BT_LOGT
1015 BT_LOGT(...);
1016 #endif
1017
1018 /* ... */
1019
1020 #ifdef BT_LOGW_STR
1021 BT_LOGW_STR(...);
1022 #endif
1023
1024 /* ... */
1025 }
1026 ----
1027 +
1028 The {c-cpp} source files which include this header file determine if
1029 logging is enabled or not for them, and if so, what is their
1030 <<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time
1031 log level>> expression.
1032
1033 .. Require that logging be enabled:
1034 +
1035 [source,c]
1036 ----
1037 /* Protection: this file uses BT_LOG*() macros directly */
1038 #ifndef BT_LOG_SUPPORTED
1039 # error Please include "logging/log.h" before including this file.
1040 #endif
1041 ----
1042 +
1043 Then, in the file, instrument your code with the
1044 <<gen-logging-statements,generic logging statement macros>>.
1045
1046 [[logging-instrument-c-file-lib]]
1047 ==== Instrument a library {c-cpp} source file
1048
1049 To instrument a library {c-cpp} source file (`.c`/`.cpp`):
1050
1051 . At the top of the file, before the first `#include` line (if any),
1052 define your file's <<choose-a-logging-tag,logging tag>> name (this
1053 tag must start with `LIB/`):
1054 +
1055 --
1056 [source,c]
1057 ----
1058 #define BT_LOG_TAG "LIB/THE-FILE"
1059 ----
1060 --
1061
1062 . Include `"lib/logging.h"`:
1063 +
1064 [source,c]
1065 ----
1066 #include "lib/logging.h"
1067 ----
1068
1069 . In the file, instrument your code with the
1070 <<lib-logging-statements,library logging statement macros>> or with
1071 the <<gen-logging-statements,generic logging statement macros>>.
1072
1073 [[logging-instrument-h-file-lib]]
1074 ==== Instrument a library {c-cpp} header file
1075
1076 To instrument a library {c-cpp} header file (`.h`/`.hpp`), if you have
1077 `static inline` functions in it:
1078
1079 . Do not include `"lib/logging.h"`!
1080
1081 . Require that library logging be enabled:
1082 +
1083 [source,c]
1084 ----
1085 /* Protection: this file uses BT_LIB_LOG*() macros directly */
1086 #ifndef BT_LIB_LOG_SUPPORTED
1087 # error Please include "lib/logging.h" before including this file.
1088 #endif
1089 ----
1090
1091 . In the file, instrument your code with the
1092 <<lib-logging-statements,library logging statement macros>> or with
1093 the <<gen-logging-statements,generic logging statement macros>>.
1094
1095 [[logging-instrument-c-file-compcls]]
1096 ==== Instrument a component class {c-cpp} source file
1097
1098 To instrument a component class {c-cpp} source file (`.c`/`.cpp`):
1099
1100 . At the top of the file, before the first `#include` line (if any),
1101 define your file's <<choose-a-logging-tag,logging tag>> name (this tag
1102 must start with `PLUGIN/` followed by the component class identifier):
1103 +
1104 --
1105 [source,c]
1106 ----
1107 #define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC"
1108 ----
1109 --
1110
1111 . Below the line above, define the source file's log level expression,
1112 `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
1113 <<comp-logging-statements,logging statement>> to know the current
1114 <<run-time-log-level,run-time log level>>.
1115 +
1116 For a component class file, it is usually a member of a local component
1117 private structure variable:
1118 +
1119 [source,c]
1120 ----
1121 #define BT_LOG_OUTPUT_LEVEL (my_comp->log_level)
1122 ----
1123
1124 . Below the line above, define `BT_COMP_LOG_SELF_COMP` to an expression
1125 which, evaluated in the context of the
1126 <<comp-logging-statements,logging statements>>, evaluates to the self
1127 component address (`+bt_self_component *+`) of the component.
1128 +
1129 This is usually a member of a local component private structure
1130 variable:
1131 +
1132 [source,c]
1133 ----
1134 #define BT_COMP_LOG_SELF_COMP (my_comp->self_comp)
1135 ----
1136
1137 . Include `"logging/comp-logging.h"`:
1138 +
1139 [source,c]
1140 ----
1141 #include "logging/comp-logging.h"
1142 ----
1143
1144 . In the component initialization method, make sure to set the
1145 component private structure's log level member to the initial
1146 component's log level:
1147 +
1148 [source,c]
1149 ----
1150 struct my_comp {
1151 bt_logging_level log_level;
1152 /* ... */
1153 };
1154
1155 BT_HIDDEN
1156 bt_self_component_status my_comp_init(
1157 bt_self_component_source *self_comp_src,
1158 bt_value *params, void *init_method_data)
1159 {
1160 struct my_comp *my_comp = g_new0(struct my_comp, 1);
1161 bt_self_component *self_comp =
1162 bt_self_component_source_as_self_component(self_comp_src);
1163 const bt_component *comp = bt_self_component_as_component(self_comp);
1164
1165 BT_ASSERT(my_comp);
1166 my_comp->log_level = bt_component_get_logging_level(comp);
1167
1168 /* ... */
1169 }
1170 ----
1171
1172 . In the file, instrument your code with the
1173 <<comp-logging-statements,component logging statement macros>>.
1174
1175 [[logging-instrument-h-file-compcls]]
1176 ==== Instrument a component class {c-cpp} header file
1177
1178 To instrument a component class {c-cpp} header file (`.h`/`.hpp`), if
1179 you have `static inline` functions in it:
1180
1181 . Do not include `"logging/comp-logging.h"`!
1182
1183 . Require that component logging be enabled:
1184 +
1185 [source,c]
1186 ----
1187 /* Protection: this file uses BT_COMP_LOG*() macros directly */
1188 #ifndef BT_COMP_LOG_SUPPORTED
1189 # error Please include "logging/comp-logging.h" before including this file.
1190 #endif
1191 ----
1192
1193 . In the file, instrument your code with the
1194 <<comp-logging-statements,component logging statement macros>>.
1195
1196 [[choose-a-logging-tag]]
1197 ==== Choose a logging tag
1198
1199 Each logging-enabled {c-cpp} source file must define `BT_LOG_TAG` to a
1200 logging tag. A logging tag is a namespace to identify the logging
1201 messages of this specific source file.
1202
1203 In general, a logging tag name _must_ be only uppercase letters, digits,
1204 and the `-`, `.`, and `/` characters.
1205
1206 Use `/` to show the subsystem to source file hierarchy.
1207
1208 For the {bt2} library, start with `LIB/`.
1209
1210 For the CTF writer library, start with `CTF-WRITER/`.
1211
1212 For component classes, use:
1213
1214 [verse]
1215 `PLUGIN/__CCTYPE__.__PNAME__.__CCNAME__[/__FILE__]`
1216
1217 With:
1218
1219 `__CCTYPE__`::
1220 Component class's type (`SRC`, `FLT`, or `SINK`).
1221
1222 `__PNAME__`::
1223 Plugin's name.
1224
1225 `__CCNAME__`::
1226 Component class's name.
1227
1228 `__FILE__`::
1229 Additional information to specify the source file name or module.
1230
1231 For plugins (files common to many component classes), use:
1232
1233 [verse]
1234 `PLUGIN/__PNAME__[/__FILE__]`
1235
1236 With:
1237
1238 `__PNAME__`::
1239 Plugin's name.
1240
1241 `__FILE__`::
1242 Additional information to specify the source file name or module.
1243
1244 [[choose-a-log-level]]
1245 ==== Choose a log level
1246
1247 Choosing the appropriate level for your logging statement is very
1248 important.
1249
1250 [options="header,autowidth",cols="1,2,3a,4"]
1251 |===
1252 |Log level |Description |Use cases |Expected impact on performance
1253
1254 |_FATAL_
1255 |
1256 The program, library, or plugin cannot continue to work in this
1257 condition: it must be terminated immediately.
1258
1259 A _FATAL_-level logging statement should always be followed by
1260 `abort()`.
1261 |
1262 * Unexpected return values from system calls.
1263 * Logic error in internal code, for example an unexpected value in a
1264 `switch` statement.
1265 * Failed assertion (within `BT_ASSERT()`).
1266 * Unsatisfied library precondition (within `BT_ASSERT_PRE()` or
1267 `BT_ASSERT_PRE_DEV()`).
1268 * Unsatisfied library postcondition (within `BT_ASSERT_POST()` or
1269 `BT_ASSERT_POST_DEV()`).
1270 |Almost none: always enabled.
1271
1272 |_ERROR_
1273 |
1274 An important error which is somewhat not fatal, that is, the program,
1275 library, or plugin can continue to work after this, but you judge that
1276 it should be reported to the user.
1277
1278 Usually, the program cannot recover from such an error, but it can at
1279 least exit cleanly.
1280 |
1281 * Memory allocation errors.
1282 * Wrong component initialization parameters.
1283 * Corrupted, unrecoverable trace data.
1284 * Failed to perform an operation which should work considering the
1285 implementation and the satisfied preconditions. For example, the
1286 failure to create an empty object (no parameters): most probably
1287 failed internally because of an allocation error.
1288 * Almost any error in terminal elements: CLI and plugins.
1289 |Almost none: always enabled.
1290
1291 |_WARNING_
1292 |
1293 An error which still allows the execution to continue, but you judge
1294 that it should be reported to the user.
1295
1296 _WARNING_-level logging statements are for any error or weird action
1297 that is directly or indirectly caused by the user, often through some
1298 bad input data. For example, not having enough memory is considered
1299 beyond the user's control, so we always log memory errors with an
1300 _ERROR_ level (not _FATAL_ because we usually don't abort in this
1301 condition).
1302 |
1303 * Missing data within something that is expected to have it, but there's
1304 an alternative.
1305 * Invalid file, but recoverable/fixable.
1306 |Almost none: always enabled.
1307
1308 |_INFO_
1309 |
1310 Any useful information which a non-developer user would possibly
1311 understand.
1312
1313 Anything logged with this level must _not_ happen repetitively on the
1314 fast path, that is, nothing related to each message, for example. This
1315 level is used for sporadic and one-shot events.
1316 |
1317 * CLI or component configuration report.
1318 * Successful plugin, component, or message iterator initialization.
1319 * In the library: anything related to plugins, graphs, component
1320 classes, components, message iterators, connections, and ports which
1321 is not on the fast path.
1322 * Successful connection to or disconnection from another system.
1323 * An _optional_ subsystem cannot be loaded.
1324 * An _optional_ field/datum cannot be found.
1325 |
1326 Very little: always enabled.
1327
1328 |_DEBUG_
1329 |
1330 Something that only {bt2} developers would be interested into,
1331 which can occur on the fast path, but not more often than once per
1332 message.
1333
1334 The _DEBUG_ level is the default <<build-time-log-level,build-time log
1335 level>> as, since it's not _too_ verbose, the performance is similar to
1336 an _INFO_ build.
1337 |
1338 * Object construction and destruction.
1339 * Object recycling (except fields).
1340 * Object copying (except fields and values).
1341 * Object freezing (whatever the type, as freezing only occurs in
1342 developer mode).
1343 * Object interruption.
1344 * Calling user methods and logging the result.
1345 * Setting object properties (except fields and values).
1346 |
1347 Noticeable, but not as much as the _TRACE_ level: could be executed
1348 in production if you're going to need a thorough log for support
1349 tickets without having to rebuild the project.
1350
1351 |_TRACE_
1352 |
1353 Low-level debugging context information (anything that does not fit the
1354 other log levels). More appropriate for tracing in general.
1355 |
1356 * Reference count change.
1357 * Fast path, low level state machine's state change.
1358 * Get or set an object's property.
1359 * Object comparison's intermediate results.
1360 |Huge: not executed in production.
1361 |===
1362
1363 [IMPORTANT]
1364 --
1365 Make sure not to use a _WARNING_ (or higher) log level when the
1366 condition leading to the logging statement can occur under normal
1367 circumstances.
1368
1369 For example, a public function to get some object or
1370 property from an object by name or key that fails to find the value is
1371 not a warning scenario: the user could legitimately use this function to
1372 check if the name/key exists in the object. In this case, use the
1373 _TRACE_ level (or do not log at all).
1374 --
1375
1376 [[message]]
1377 ==== Write an appropriate message
1378
1379 Follow those rules when you write a logging statement's message:
1380
1381 * Use an English sentence which starts with a capital letter.
1382
1383 * Start the sentence with the appropriate verb tense depending on the
1384 context. For example:
1385 +
1386 --
1387 ** Beginning of operation (present continuous): _Creating ..._,
1388 _Copying ..._, _Serializing ..._, _Freezing ..._, _Destroying ..._
1389 ** End of operation (simple past): _Created ..._, _Successfully created ..._,
1390 _Failed to create ..._, _Set ..._ (simple past of _to set_ which is
1391 also _set_)
1392 --
1393 +
1394 For warning and error messages, you can start the message with _Cannot_
1395 or _Failed to_ followed by a verb if it's appropriate.
1396
1397 * Do not include the log level in the message itself. For example,
1398 do not start the message with _Error while_ or _Warning:_.
1399
1400 * Do not put newlines, tabs, or other special characters in the message,
1401 unless you want to log a string with such characters. Note that
1402 multiline logging messages can be hard to parse, analyze, and filter,
1403 however, so prefer multiple logging statements over a single statement
1404 with newlines.
1405
1406 * **If there are fields that your logging statement must record**,
1407 follow the message with `:` followed by a space, then with the list of
1408 fields (more about this below). If there are no fields, end the
1409 sentence with a period.
1410
1411 The statement's fields _must_ be a comma-separated list of
1412 `__name__=__value__` tokens. Keep `__name__` as simple as possible; use
1413 kebab case if possible. If `__value__` is a non-alphanumeric string, put
1414 it between double quotes (`"%s"` specifier). Always use the `PRId64` and
1415 `PRIu64` specifiers to log an `int64_t` or an `uint64_t` value. Use `%d`
1416 to log a boolean value.
1417
1418 Example:
1419
1420 "Cannot read stream data for indexing: path=\"%s\", name=\"%s\", "
1421 "stream-id=%" PRIu64 ", stream-fd=%d, "
1422 "index=%" PRIu64 ", status=%s, is-mapped=%d"
1423
1424 By following a standard format for the statement fields, it is easier to
1425 use tools like https://www.elastic.co/products/logstash[Logstash] or
1426 even https://www.splunk.com/[Splunk] to split fields and analyze logs.
1427
1428 Prefer the following suffixes in field names:
1429
1430 [options="header,autowidth"]
1431 |===
1432 |Field name suffix |Description |Format specifier
1433
1434 |`-addr` |Memory address |`%p`
1435 |`-fd` |File descriptor |`%d`
1436 |`-fp` |File stream (`+FILE *+`) |`%p`
1437 |`-id` |Object's ID |`%" PRIu64 "`
1438 |`-index` |Index |`%" PRIu64 "`
1439 |`-name` |Object's name |`\"%s\"`
1440 |===
1441
1442 === Output
1443
1444 The log is printed to the standard error stream. A log line contains the
1445 time, the process and thread IDs, the <<log-levels,log level>>, the
1446 <<choose-a-logging-tag,logging tag>>, the source's function name, file
1447 name and line number, and the <<message,message>>.
1448
1449 When {bt2} supports terminal color codes (depends on the
1450 `BABELTRACE_TERM_COLOR` environment variable's value and what the
1451 standard output and error streams are plugged into), _INFO_-level lines
1452 are blue, _WARNING_-level lines are yellow, and _ERROR_-level and
1453 _FATAL_-level lines are red.
1454
1455 Log line example:
1456
1457 ----
1458 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
1459 ----
1460
1461 You can easily filter the log with `grep` or `ag`. For example, to keep
1462 only the _DEBUG_-level logging messages that the `FIELD-CLASS` module
1463 generates:
1464
1465 ----
1466 $ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS'
1467 ----
1468
1469 == Valgrind
1470
1471 To use Valgrind on an application (for example, the CLI or a test) which
1472 loads libbabeltrace2, use:
1473
1474 ----
1475 $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
1476 LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app
1477 ----
1478
1479 `G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and
1480 `PYTHONMALLOC=malloc` is for the Python interpreter, if it is used by
1481 the Python plugin provider (Valgrind will probably show a lot of errors
1482 which originate from the Python interpreter anyway).
1483
1484 `LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
1485 libraries (plugins) which it loads. You need this to see the appropriate
1486 backtrace when Valgrind shows errors.
1487
1488 == Testing
1489
1490 [[test-env]]
1491 === Environment
1492
1493 `tests/utils/utils.sh` sets the environment variables for any {bt2}
1494 test script.
1495
1496 `utils.sh` only needs to know the path to the `tests` directory within
1497 the source and the build directories. By default, `utils.sh` assumes the
1498 build is in tree, that is, you ran `./configure` from the source's root
1499 directory, and sets the `BT_TESTS_SRCDIR` and `BT_TESTS_BUILDDIR`
1500 environment variables accordingly. You can override those variables, for
1501 example if you build out of tree.
1502
1503 All test scripts eventually do something like this to source `utils.sh`,
1504 according to where they are located relative to the `tests` directory:
1505
1506 [source,bash]
1507 ----
1508 if [ "x${BT_TESTS_SRCDIR:-}" != "x" ]; then
1509 UTILSSH="$BT_TESTS_SRCDIR/utils/utils.sh"
1510 else
1511 UTILSSH="$(dirname "$0")/../utils/utils.sh"
1512 fi
1513 ----
1514
1515 ==== Python
1516
1517 You can use the `tests/utils/run_python_bt2` script to run any command
1518 within an environment making the build's `bt2` Python package available.
1519
1520 `run_python_bt2` uses <<test-env,`utils.sh`>> which needs to know the
1521 build directory, so make sure you set the `BT_TESTS_BUILDDIR`
1522 environment variable correctly _if you build out of tree_, for example:
1523
1524 ----
1525 $ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
1526 ----
1527
1528 You can run any command which needs the `bt2` Python package through
1529 `run_python_bt2`, for example:
1530
1531 ----
1532 $ ./tests/utils/run_python_bt2 ipython3
1533 ----
1534
1535 === Report format
1536
1537 All test scripts output the test results following the
1538 https://testanything.org/[Test Anything Protocol] (TAP) format.
1539
1540 The TAP format has two mechanisms to print additional information about
1541 a test:
1542
1543 * Print a line starting with `#` to the standard output.
1544 +
1545 This is usually done with the `diag()` C function or the `diag` shell
1546 function.
1547
1548 * Print to the standard error.
1549
1550 === Python bindings
1551
1552 The `bt2` Python package tests are located in
1553 `tests/bindings/python/bt2`.
1554
1555 ==== Python test runner
1556
1557 `tests/utils/python/testrunner.py` is {bt2}'s Python test runner
1558 which loads Python files containing unit tests, finds all the test
1559 cases, and runs the tests, producing a TAP report.
1560
1561 You can see the test runner command's help with:
1562
1563 ----
1564 $ python3 ./tests/utils/python/testrunner.py --help
1565 ----
1566
1567 By default, the test runner reports failing tests (TAP's `not{nbsp}ok`
1568 line), but continues to run other tests. You can use the `--failfast`
1569 option to make the test runner fail as soon as a test fails.
1570
1571 ==== Guides
1572
1573 To run all the `bt2` Python package tests:
1574
1575 * Run:
1576 +
1577 ----
1578 $ ./tests/utils/run_python_bt2 ./tests/bindings/python/bt2/test_python_bt2
1579 ----
1580 +
1581 or:
1582 +
1583 ----
1584 $ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1585 ./tests/bindings/python/bt2/ -p '*.py'
1586 ----
1587
1588 To run **all the tests** in a test module (for example,
1589 `test_value.py`):
1590
1591 * Run:
1592 +
1593 ----
1594 $ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1595 ./tests/bindings/python/bt2 -t test_value
1596 ----
1597
1598 To run a **specific test case** (for example, `RealValueTestCase` within
1599 `test_value.py`):
1600
1601 * Run:
1602 +
1603 ----
1604 $ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1605 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
1606 ----
1607
1608 To run a **specific test** (for example,
1609 `RealValueTestCase.test_assign_pos_int` within `test_value.py`):
1610
1611 * Run:
1612 +
1613 ----
1614 $ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
1615 ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
1616 ----
1617
1618 == {cpp} usage
1619
1620 Some parts of {bt2} are written in {cpp}.
1621
1622 This section shows what's important to know about {cpp} to contribute
1623 to {bt2}.
1624
1625 [IMPORTANT]
1626 ====
1627 {bt2} only has {cpp} sources for _internal_ code.
1628
1629 In other words, libbabeltrace2 _must_ expose a pure C99 API to preserve
1630 ABI compatibility over time.
1631 ====
1632
1633 === Standard and dependencies
1634
1635 The {bt2} project is configured to use the {cpp11} standard.
1636
1637 {cpp11} makes it possible to build {bt2} with a broad range of
1638 compilers, from GCC{nbsp}4.8 and Clang{nbsp}3.3.
1639
1640 === Automake/Libtool requirements
1641
1642 To add a {cpp} source file to a part of the project, use the `.cpp`
1643 extension and add it to the list of source files in `Makefile.am` as
1644 usual.
1645
1646 If a program or a shared library has a direct {cpp} source file, then
1647 Libtool uses the {cpp} linker to create the result, dynamically
1648 linking important runtime libraries such as libstdc++ and libgcc_s.
1649
1650 Because a Libtool _convenience library_ is just an archive (`.a`), it's
1651 _not_ dynamically linked to runtime libraries, even if one of its direct
1652 sources is a {cpp} file. This means that for each program or shared
1653 library named `my_target` in `Makefile.am` which is linked to a
1654 convenience library having {cpp} sources (recursively), you _must_ do
1655 one of:
1656
1657 * Have at least one direct {cpp} source file in the
1658 `+*_my_target_SOURCES+` list.
1659
1660 * Add:
1661 +
1662 ----
1663 nodist_EXTRA_my_target_SOURCES = dummy.cpp
1664 ----
1665 +
1666 See
1667 https://www.gnu.org/software/automake/manual/automake.html#Libtool-Convenience-Libraries[Libtool
1668 Convenience Libraries] to learn more.
1669
1670 For a given program or library, you _cannot_ have a C{nbsp}file and a
1671 {cpp}{nbsp}file having the same name, for example `list.c` and
1672 `list.cpp`.
1673
1674 === Coding style
1675
1676 ==== Whitespaces, indentation, and line breaks
1677
1678 All the project's {cpp} files follow the
1679 https://clang.llvm.org/docs/ClangFormat.html[clang-format]
1680 https://clang.llvm.org/docs/ClangFormatStyleOptions.html[style] of the
1681 `.clang-format` file for whitespaces, indentation, and line breaks.
1682
1683 You _must_ format modified and new {cpp} files with clang-format before
1684 you create a contribution patch.
1685
1686 You need clang-format{nbsp}≥{nbsp}10 to use the project's `.clang-format`
1687 file.
1688
1689 To automatically format all the project's {cpp} files, run:
1690
1691 ----
1692 $ ./tools/format-cpp
1693 ----
1694
1695 Use the `FORMATTER` environment variable to override the default
1696 formatter (`clang-format{nbsp}-i`):
1697
1698 ----
1699 $ FORMATTER='clang-format-10 -i' ./tools/format-cpp
1700 ----
1701
1702 ==== Naming
1703
1704 * Use camel case with a lowercase first letter for:
1705 ** Variable names: `size`, `objSize`.
1706 ** Function/method names: `size()`, `formatAndPrint()`.
1707
1708 * Use camel case with an uppercase first letter for:
1709 ** Types: `Pistachio`, `NutManager`.
1710 ** Template parameters: `PlanetT`, `TotalSize`.
1711
1712 * Use snake case with uppercase letters for:
1713 ** Definition/macro names: `MARK_AS_UNUSED()`, `SOME_FEATURE_EXISTS`.
1714 ** Enumerators: `Type::SIGNED_INT`, `Scope::FUNCTION`.
1715
1716 * Use only lowercase letters and digits for namespaces: `mylib`, `bt2`.
1717
1718 * Use the suffix `T` for type template parameters:
1719 +
1720 [source,cpp]
1721 ----
1722 template <typename NameT, typename ItemT>
1723 ----
1724
1725 * Name a template parameter pack `Args`.
1726 +
1727 [source,cpp]
1728 ----
1729 template <typename NameT, typename... Args>
1730 ----
1731
1732 * Use an underscore prefix for private and protected methods and member
1733 type names: `_tryConnect()`, `_NodeType`.
1734
1735 * Use the prefix `_m` for private and protected member variable names:
1736 `_mLogger`, `_mSize`, `_mFieldClass`.
1737
1738 * Name setters and getters like the property name, without `set` and
1739 `get` prefixes.
1740
1741 * Use the `is` or `has` prefix, if possible, to name the functions which
1742 return `bool`.
1743
1744 === Coding convention
1745
1746 In general, the project's contributors make an effort to follow,
1747 for {cpp11} code:
1748
1749 * The
1750 https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md[{cpp} Core Guidelines].
1751
1752 * Scott Meyers's
1753 "`https://www.oreilly.com/library/view/effective-modern-c/9781491908419/[Effective Modern {cpp}]`".
1754
1755 Here are a few important reminders:
1756
1757 * Namespace your code.
1758
1759 * Create one header/source file pair per class when possible.
1760 +
1761 For a class named `MyClass`, name the corresponding files `my-class.hpp`
1762 and `my-class.cpp`.
1763
1764 * When defining a class, put constructors as the first methods, whatever
1765 their access (public/protected/private), then the destructor, and then
1766 the rest.
1767
1768 * Declare variables as close to where they are used as possible.
1769
1770 * Use `auto` when possible.
1771
1772 * Use `const` as much as possible, even for pointer
1773 (`+const char* const+`) and numeric values (`const unsigned int`)
1774 which never need to change.
1775
1776 * Implement simple setters, getters, and one-liners in header files and
1777 everything else that's not a template in source files.
1778
1779 * Make methods `const noexcept` or `const` as much as possible.
1780
1781 * Make constructors `explicit` unless you really need an implicit
1782 constructor (which is rare).
1783
1784 * Use `std::unique_ptr` to manage memory when possible.
1785 +
1786 However, use references (`+*my_unique_ptr+`) and raw pointers
1787 (`+my_unique_ptr.get()+`) when not transferring ownership.
1788
1789 * Use `nullptr`, not `NULL` nor 0.
1790
1791 * Return by value (rvalue) instead of by output parameter (non-const
1792 lvalue reference), even complex objects, unless you can prove that the
1793 performance is improved when returning by parameter.
1794
1795 * For a function parameter or a return value of which the type needs to
1796 be a reference or pointer, use:
1797 +
1798 If the value is mandatory:::
1799 A reference.
1800 If the value is optional:::
1801 A raw pointer.
1802
1803 * Don't use `+std::move()+` when you already have an rvalue, which
1804 means:
1805 ** Don't write `+return std::move(...);+` as this can interfere with
1806 RVO.
1807 ** Don't use `+std::move()+` with a function call
1808 (`+std::move(func())+`).
1809
1810 * For each possible move/copy constructor or assignment operator, do one
1811 of:
1812 ** Write a custom one.
1813 ** Mark it as defaulted (`default`)
1814 ** Mark it as deleted (`delete`).
1815
1816 * Use scoped enumerations (`+enum class+`).
1817
1818 * Mark classes known to be final with the `final` keyword.
1819
1820 * Use type aliases (`using`), not type definitions (`typedef`).
1821
1822 * Use anonymous namespaces for local functions instead of `static`.
1823
1824 * Don't pollute the global namespace:
1825 ** Don't use `using namespace xyz` anywhere.
1826 ** Use only namespace aliases in source files (`.cpp`), trying to
1827 use them in the smallest possible scope (function, or even smaller).
1828
1829 * Return a structure with named members instead of a generic container
1830 such as `std::pair` or `std::tuple`.
1831
1832 * When a class inherits a base class with virtual methods, use the
1833 `override` keyword to mark overridden virtual methods, and do not use
1834 the `virtual` keyword again.
1835
1836 * Define overloaded operators only if their meaning is obvious,
1837 unsurprising, and consistent with the corresponding built-in
1838 operators.
1839 +
1840 For example, use `+|+` as a bitwise- or logical-or, not as a shell-style
1841 pipe.
1842
1843 * Use RAII wrappers when managing system resources or interacting with
1844 C{nbsp}libraries.
1845 +
1846 In other words, don't rely on ``goto``s and error labels to clean up as
1847 you would do in{nbsp}C.
1848 +
1849 Use the RAII, Luke.
1850
1851 * Throw an exception when there's an unexpected, exceptional condition,
1852 https://isocpp.org/wiki/faq/exceptions#ctors-can-throw[including from
1853 a constructor], instead of returning a status code.
1854
1855 * Accept a by-value parameter and move it (when it's moveable) when you
1856 intend to copy it anyway.
1857 +
1858 You can do this with most STL containers.
1859 +
1860 Example:
1861 +
1862 [source,cpp]
1863 ----
1864 void Obj::doSomething(std::string str)
1865 {
1866 _mName = std::move(str);
1867 // ...
1868 }
1869 ----
1870
1871 .`baby.hpp`
1872 ====
1873 This example shows a {cpp} header which follows the {bt2} {cpp} coding
1874 convention.
1875
1876 [source,cpp]
1877 ----
1878 /*
1879 * SPDX-License-Identifier: MIT
1880 *
1881 * Copyright 2020 Harry Burnett <hburnett@reese.choco>
1882 */
1883
1884 #ifndef BABELTRACE_BABY_HPP
1885 #define BABELTRACE_BABY_HPP
1886
1887 #include <string>
1888 #include <unordered_set>
1889 #include <utility>
1890
1891 namespace life {
1892
1893 class Toy;
1894
1895 /*
1896 * A baby is a little human.
1897 */
1898 class Baby : public Human
1899 {
1900 public:
1901 using Toys = std::unordered_set<Toy>;
1902
1903 enum class Gender
1904 {
1905 MALE,
1906 FEMALE,
1907 UNKNOWN,
1908 };
1909
1910 Baby() = default;
1911 explicit Baby(const Toys& toys);
1912 Baby(const Baby&) = delete;
1913 Baby(Baby&&) = delete;
1914 Baby& operator=(const Baby&) = delete;
1915 Baby& operator=(Baby&&) = delete;
1916
1917 protected:
1918 explicit Baby(Gender initialGender = Gender::UNKNOWN);
1919
1920 public:
1921 /*
1922 * Eats `weight` grams of food.
1923 */
1924 void eat(unsigned long weight);
1925
1926 /*
1927 * Sleeps for `duration` seconds.
1928 */
1929 void sleep(double duration);
1930
1931 /*
1932 * Sets this baby's name to `name`.
1933 */
1934 void name(std::string name)
1935 {
1936 _mName = std::move(name);
1937 }
1938
1939 /*
1940 * This baby's name.
1941 */
1942 const std::string& name() const noexcept
1943 {
1944 return _mName;
1945 }
1946
1947 protected:
1948 void _addTeeth(unsigned long index);
1949 void _grow(double size) override;
1950
1951 private:
1952 std::string _mName {"Paul"};
1953 Toys _mToys;
1954 };
1955
1956 } // namespace life
1957
1958 #endif // BABELTRACE_BABY_HPP
1959 ----
1960 ====
This page took 0.068413 seconds and 4 git commands to generate.