Commit | Line | Data |
---|---|---|
cd4aac1e PP |
1 | // Render with Asciidoctor |
2 | ||
28b765ac | 3 | = Babeltrace{nbsp}2 contributor's guide |
f9ded0e0 | 4 | Jérémie Galarneau, Philippe Proulx |
a1ac73cf | 5 | 22 February 2024 |
28b765ac PP |
6 | :toc: left |
7 | :toclevels: 3 | |
fb7ff115 PP |
8 | :icons: font |
9 | :nofooter: | |
28b765ac | 10 | :bt2: Babeltrace{nbsp}2 |
fb7ff115 PP |
11 | :c-cpp: C/{cpp} |
12 | :cpp11: {cpp}11 | |
a1ac73cf | 13 | :fmt: pass:[{fmt}] |
beb0fb75 | 14 | |
f9ded0e0 | 15 | This is a partial contributor's guide for the |
28b765ac | 16 | https://babeltrace.org[{bt2}] project. If you have any |
cd4aac1e PP |
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 | |
19 | mailing list]. | |
20 | ||
28b765ac | 21 | == {bt2} library |
f9ded0e0 | 22 | |
cd4aac1e | 23 | === Object reference counting and lifetime |
f9ded0e0 | 24 | |
28b765ac PP |
25 | This section covers the rationale behind the design of {bt2}'s |
26 | object lifetime management. This applies to the {bt2} library, as | |
cd4aac1e PP |
27 | well as to the CTF writer library (although the public reference |
28 | counting functions are not named the same way). | |
f9ded0e0 | 29 | |
28b765ac PP |
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 | |
f9ded0e0 PP |
32 | all objects, chief amongst which are lifetime management functions. |
33 | ||
cd4aac1e PP |
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 | |
37 | reference count. | |
f9ded0e0 | 38 | |
28b765ac | 39 | As far as lifetime management in concerned, {bt2} makes a clear |
f9ded0e0 PP |
40 | distinction between regular objects, which have a single parent, and |
41 | root objects, which don't. | |
42 | ||
cd4aac1e | 43 | ==== The problem |
f9ded0e0 PP |
44 | |
45 | Let us consider a problematic case to illustrate the need for this | |
46 | distinction. | |
47 | ||
28b765ac | 48 | A user of the {bt2} library creates a trace class, which _has_ a |
cd4aac1e PP |
49 | stream class (the class of a stream) and that stream class, in turn, |
50 | _has_ an event class (the class of an event). | |
f9ded0e0 PP |
51 | |
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 | |
55 | from any other. | |
56 | ||
57 | For instance, the user could discard his reference on both the event | |
cd4aac1e PP |
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. | |
f9ded0e0 PP |
63 | |
64 | Conversely, the user could also hold a reference to an event class and | |
cd4aac1e | 65 | retrieve its parent stream class. The trace class, in turn, can then be |
f9ded0e0 PP |
66 | retrieved from the stream class. |
67 | ||
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 | |
73 | never reach zero. | |
74 | ||
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. | |
77 | ||
cd4aac1e | 78 | ==== The solution |
f9ded0e0 | 79 | |
28b765ac | 80 | The scheme employed in {bt2} to break this cycle consists in the |
cd4aac1e | 81 | "children" holding _reverse component references_ to their parents. That |
56e18c4c PP |
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 | |
cd4aac1e | 84 | their parent trace class. |
f9ded0e0 | 85 | |
cd4aac1e | 86 | On the other hand, parents hold _claiming aggregation references_ to |
f9ded0e0 PP |
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. | |
93 | ||
94 | When a parented object's reference count reaches zero, it invokes | |
cd4aac1e PP |
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. | |
98 | ||
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. | |
111 | ||
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. | |
118 | ||
cd4aac1e | 119 | ==== Caveats |
f9ded0e0 PP |
120 | |
121 | This scheme imposes a number of strict rules defining the relation | |
122 | between objects: | |
123 | ||
124 | * Objects may only have one parent. | |
125 | * Objects, beside the root, are only retrievable from their direct | |
126 | parent or children. | |
127 | ||
cd4aac1e | 128 | ==== Example |
f9ded0e0 | 129 | |
cd4aac1e PP |
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**. | |
f9ded0e0 PP |
135 | |
136 | image::doc/contributing-images/bt-ref01.png[] | |
137 | ||
cd4aac1e PP |
138 | In this second step, we can see that **User{nbsp}A** has acquired a |
139 | reference on **SC2** through the trace class, **TC1**. | |
f9ded0e0 PP |
140 | |
141 | The stream class's reference count transitions from zero to one, | |
142 | triggering the acquisition of a strong reference on **TC1** from | |
143 | **SC2**. | |
144 | ||
cd4aac1e PP |
145 | Hence, at this point, the trace class's ownership is shared by |
146 | **User{nbsp}A** and **SC2**. | |
f9ded0e0 PP |
147 | |
148 | image::doc/contributing-images/bt-ref02.png[] | |
149 | ||
cd4aac1e PP |
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. | |
f9ded0e0 | 154 | |
cd4aac1e | 155 | Note that SC2's reference count was incremented to 2. The trace class's |
f9ded0e0 PP |
156 | reference count remains unchanged. |
157 | ||
158 | image::doc/contributing-images/bt-ref03.png[] | |
159 | ||
cd4aac1e PP |
160 | **User{nbsp}A** decides to drop its reference on **SC2**. **SC2**'s |
161 | reference count returns back to 1, everything else remaining unchanged. | |
f9ded0e0 PP |
162 | |
163 | image::doc/contributing-images/bt-ref04.png[] | |
164 | ||
cd4aac1e PP |
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. | |
f9ded0e0 PP |
169 | |
170 | image::doc/contributing-images/bt-ref05.png[] | |
171 | ||
cd4aac1e | 172 | If another object, **User{nbsp}B**, enters the picture and acquires a |
f9ded0e0 PP |
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**. | |
176 | ||
177 | image::doc/contributing-images/bt-ref06.png[] | |
178 | ||
cd4aac1e PP |
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**. | |
f9ded0e0 PP |
183 | |
184 | image::doc/contributing-images/bt-ref07.png[] | |
185 | ||
cd4aac1e | 186 | At some point, **User{nbsp}A** releases its reference on **EC3**. Since |
f9ded0e0 PP |
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**. | |
190 | ||
191 | **TC1**'s reference count is now 1 and no further action is taken. | |
192 | ||
193 | image::doc/contributing-images/bt-ref08.png[] | |
194 | ||
cd4aac1e PP |
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 | |
197 | **EC1**. | |
f9ded0e0 PP |
198 | |
199 | image::doc/contributing-images/bt-ref09.png[] | |
200 | ||
cd4aac1e PP |
201 | Finally, **User{nbsp}C** releases his ownership of **EC1**, triggering |
202 | the release of the whole hierarchy. Let's walk through the reclamation | |
203 | of the whole graph. | |
f9ded0e0 | 204 | |
cd4aac1e PP |
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. | |
f9ded0e0 PP |
208 | |
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**. | |
212 | ||
213 | image::doc/contributing-images/bt-ref10.png[] | |
214 | ||
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 | |
218 | their event classes. | |
219 | ||
220 | The event classes are reached and, having no children of their own, are | |
221 | reclaimed. | |
222 | ||
223 | image::doc/contributing-images/bt-ref11.png[] | |
224 | ||
225 | The stream classes having destroyed their children, are then reclaimed | |
cd4aac1e | 226 | by the trace class. |
f9ded0e0 PP |
227 | |
228 | image::doc/contributing-images/bt-ref12.png[] | |
229 | ||
230 | Finally, the stream classes having been reclaimed, **TC1** is reclaimed. | |
231 | ||
232 | image::doc/contributing-images/bt-ref13.png[] | |
233 | ||
234 | ||
f9ded0e0 | 235 | == Logging |
beb0fb75 PP |
236 | |
237 | Logging is a great instrument for a developer to be able to collect | |
238 | information about a running software. | |
239 | ||
28b765ac | 240 | {bt2} is a complex software with many layers. When a {bt2} |
beb0fb75 | 241 | graph fails to run, what caused the failure? It could be caused by any |
cd4aac1e PP |
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. | |
beb0fb75 | 246 | |
cd4aac1e PP |
247 | While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to |
248 | _FATAL_ logging statements, you should liberally instrument your | |
28b765ac | 249 | {bt2} module with _TRACE_ logging statements to help future you |
cd4aac1e | 250 | and other developers understand what's happening at run time. |
beb0fb75 | 251 | |
f9ded0e0 | 252 | === Logging API |
beb0fb75 | 253 | |
28b765ac | 254 | The {bt2} logging API is internal: it is not exposed to the users |
cd4aac1e | 255 | of the library; only to their developers. The only thing that a library |
4a41523d | 256 | user can control is the current log level of the library itself with |
beb0fb75 | 257 | `bt_logging_set_global_level()` and the initial library's log level with |
cd4aac1e | 258 | the `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable. |
beb0fb75 PP |
259 | |
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 | |
fb7ff115 | 262 | {cpp}. The zf_log source files were modified to have the `BT_` and |
cd4aac1e PP |
263 | `bt_` prefixes, and other small changes, like color support and using |
264 | the project's `BT_DEBUG_MODE` definition instead of the standard | |
265 | `NDEBUG`. | |
beb0fb75 PP |
266 | |
267 | The logging functions are implemented in the logging convenience | |
cd4aac1e | 268 | library (`src/logging` directory). |
beb0fb75 | 269 | |
cd4aac1e | 270 | [[logging-headers]] |
f9ded0e0 | 271 | ==== Headers |
beb0fb75 PP |
272 | |
273 | The logging API headers are: | |
274 | ||
3fadfbc0 | 275 | `<babeltrace2/logging.h>`:: |
cd4aac1e | 276 | Public header which a library user can use to set and get |
a12f3d62 | 277 | libbabeltrace2's current log level. |
beb0fb75 | 278 | |
cd4aac1e | 279 | `"logging/log.h"`:: |
28b765ac | 280 | Internal, generic logging API which you can use in any {bt2} |
cd4aac1e PP |
281 | module. This is the translation of `zf_log.h`. |
282 | + | |
283 | This header offers the <<gen-logging-statements,generic logging | |
284 | statement macros>>. | |
beb0fb75 | 285 | |
cd4aac1e PP |
286 | `"lib/logging.h"`:: |
287 | Specific internal header to use within the library. | |
288 | + | |
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 | |
291 | `"logging/log.h"`. | |
292 | + | |
293 | This header offers the <<lib-logging-statements,library-specific logging | |
294 | statement macros>>. | |
beb0fb75 | 295 | |
d9c39b0a | 296 | `"logging/comp-logging.h"`:: |
cd4aac1e PP |
297 | Specific internal header to use within a component class. |
298 | + | |
299 | This header offers the <<comp-logging-statements,component-specific | |
300 | logging statement macros>>. | |
beb0fb75 | 301 | |
cd4aac1e | 302 | [[log-levels]] |
f9ded0e0 | 303 | ==== Log levels |
beb0fb75 | 304 | |
cd4aac1e PP |
305 | The internal logging API offers the following log levels, in ascending |
306 | order of severity: | |
beb0fb75 | 307 | |
cd4aac1e PP |
308 | [options="header,autowidth",cols="4"] |
309 | |=== | |
310 | |Log level name | |
311 | |Log level short name | |
312 | |Internal API enumerator | |
313 | |Public API enumerator | |
314 | ||
ef267d12 PP |
315 | |_TRACE_ |
316 | |`T` | |
317 | |`BT_LOG_TRACE` | |
318 | |`BT_LOGGING_LEVEL_TRACE` | |
cd4aac1e PP |
319 | |
320 | |_DEBUG_ | |
321 | |`D` | |
322 | |`BT_LOG_DEBUG` | |
323 | |`BT_LOGGING_LEVEL_DEBUG` | |
324 | ||
325 | |_INFO_ | |
326 | |`I` | |
327 | |`BT_LOG_INFO` | |
328 | |`BT_LOGGING_LEVEL_INFO` | |
329 | ||
770538dd | 330 | |_WARNING_ |
cd4aac1e | 331 | |`W` |
770538dd PP |
332 | |`BT_LOG_WARNING` |
333 | |`BT_LOGGING_LEVEL_WARNING` | |
cd4aac1e PP |
334 | |
335 | |_ERROR_ | |
336 | |`E` | |
337 | |`BT_LOG_ERROR` | |
338 | |`BT_LOGGING_LEVEL_ERROR` | |
339 | ||
340 | |_FATAL_ | |
341 | |`F` | |
342 | |`BT_LOG_FATAL` | |
343 | |`BT_LOGGING_LEVEL_FATAL` | |
344 | ||
345 | |_NONE_ | |
346 | |`N` | |
347 | |`BT_LOG_NONE` | |
348 | |`BT_LOGGING_LEVEL_NONE` | |
349 | |=== | |
350 | ||
351 | The short name is accepted by the log level environment variables and by | |
352 | the CLI's `--log-level` options. | |
beb0fb75 | 353 | |
cd4aac1e | 354 | See <<choose-a-log-level,how to decide which one to use>> below. |
beb0fb75 | 355 | |
cd4aac1e | 356 | There are two important log level expressions: |
beb0fb75 PP |
357 | |
358 | [[build-time-log-level]]Build-time, minimal log level:: | |
cd4aac1e PP |
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.). | |
beb0fb75 PP |
363 | + |
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 | |
f9ded0e0 PP |
366 | than this level _can_ be executed, depending on the |
367 | <<run-time-log-level,run-time log level>>. | |
beb0fb75 PP |
368 | + |
369 | You can set this level at configuration time with the | |
370 | `BABELTRACE_MINIMAL_LOG_LEVEL` environment variable, for example: | |
371 | + | |
372 | -- | |
373 | ---- | |
770538dd | 374 | $ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure |
beb0fb75 PP |
375 | ---- |
376 | -- | |
377 | + | |
cd4aac1e PP |
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 | |
28b765ac | 380 | all the {bt2} modules. You can't set it to `WARNING`, `ERROR`, |
dd22a91f | 381 | `FATAL`, or `NONE` because the impact on performance is minuscule |
28b765ac | 382 | starting from the _INFO_ log level anyway and we want any {bt2} |
dd22a91f | 383 | build to always be able to print _INFO_-level logs. |
beb0fb75 PP |
384 | + |
385 | The library's public API provides `bt_logging_get_minimal_level()` to | |
386 | get the configured minimal log level. | |
387 | ||
388 | [[run-time-log-level]]Run-time, dynamic log level:: | |
cd4aac1e PP |
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>>. | |
beb0fb75 | 395 | + |
f9ded0e0 PP |
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 | |
cd4aac1e PP |
399 | module-wise expression before including `"logging/log.h"`. |
400 | + | |
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. | |
beb0fb75 | 404 | + |
a12f3d62 | 405 | In libbabeltrace2, the user can set the current run-time log level with |
beb0fb75 PP |
406 | the `bt_logging_set_global_level()` function, for example: |
407 | + | |
408 | -- | |
409 | [source,c] | |
410 | ---- | |
411 | bt_logging_set_global_level(BT_LOGGING_LEVEL_INFO); | |
412 | ---- | |
413 | -- | |
414 | + | |
415 | The library's initial run-time log level is defined by the | |
cd4aac1e PP |
416 | `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable, or set to _NONE_ |
417 | if this environment variable is undefined. | |
418 | + | |
419 | Other modules have their own way of setting their run-time log level. | |
420 | + | |
421 | For example, the CLI uses the `BABELTRACE_CLI_LOG_LEVEL` environment | |
422 | variable, as well as its global `--log-level` option: | |
423 | + | |
424 | ---- | |
425 | $ babeltrace2 --log-level=I ... | |
426 | ---- | |
427 | + | |
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: | |
432 | + | |
433 | ---- | |
434 | $ babeltrace2 /path/to/trace -c sink.ctf.fs --log-level=D | |
435 | ---- | |
436 | + | |
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 | |
439 | level, for example: | |
440 | + | |
441 | [source,c] | |
442 | ---- | |
cd4aac1e PP |
443 | char *bt_common_get_home_plugin_path(int log_level); |
444 | ---- | |
beb0fb75 | 445 | + |
cd4aac1e PP |
446 | Typically, when a logging-enabled module calls such a function, it |
447 | passes its own log level expression directly (`BT_LOG_OUTPUT_LEVEL`): | |
beb0fb75 | 448 | + |
cd4aac1e PP |
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 | ||
cd4aac1e PP |
460 | [[gen-logging-statements]] |
461 | ==== Generic logging statement macros | |
462 | ||
28b765ac | 463 | The {bt2} logging statement macros work just like `printf()` |
cd4aac1e PP |
464 | (except the `+BT_LOG*_STR()+` ones) and contain their <<log-levels,log |
465 | level>> (short name) in their name. | |
beb0fb75 | 466 | |
cd4aac1e PP |
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. | |
beb0fb75 | 471 | |
28b765ac PP |
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. | |
beb0fb75 | 475 | |
ef267d12 PP |
476 | `+BT_LOGT("format string", ...)+`:: |
477 | Generic trace logging statement. | |
beb0fb75 | 478 | |
cd4aac1e PP |
479 | `+BT_LOGD("format string", ...)+`:: |
480 | Generic debug logging statement. | |
beb0fb75 | 481 | |
cd4aac1e PP |
482 | `+BT_LOGI("format string", ...)+`:: |
483 | Generic info logging statement. | |
beb0fb75 | 484 | |
cd4aac1e PP |
485 | `+BT_LOGW("format string", ...)+`:: |
486 | Generic warning logging statement. | |
beb0fb75 | 487 | |
cd4aac1e PP |
488 | `+BT_LOGE("format string", ...)+`:: |
489 | Generic error logging statement. | |
beb0fb75 | 490 | |
cd4aac1e PP |
491 | `+BT_LOGF("format string", ...)+`:: |
492 | Generic fatal logging statement. | |
beb0fb75 | 493 | |
ef267d12 PP |
494 | `+BT_LOGT_STR("preformatted string")+`:: |
495 | Generic preformatted string trace logging statement. | |
beb0fb75 | 496 | |
cd4aac1e PP |
497 | `+BT_LOGD_STR("preformatted string")+`:: |
498 | Generic preformatted string debug logging statement. | |
beb0fb75 | 499 | |
cd4aac1e PP |
500 | `+BT_LOGI_STR("preformatted string")+`:: |
501 | Generic preformatted string info logging statement. | |
beb0fb75 | 502 | |
cd4aac1e PP |
503 | `+BT_LOGW_STR("preformatted string")+`:: |
504 | Generic preformatted string warning logging statement. | |
beb0fb75 | 505 | |
cd4aac1e PP |
506 | `+BT_LOGE_STR("preformatted string")+`:: |
507 | Generic preformatted string error logging statement. | |
beb0fb75 | 508 | |
cd4aac1e PP |
509 | `+BT_LOGF_STR("preformatted string")+`:: |
510 | Generic preformatted string fatal logging statement. | |
beb0fb75 | 511 | |
ef267d12 PP |
512 | `+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`:: |
513 | Generic memory trace logging statement. | |
beb0fb75 | 514 | |
cd4aac1e PP |
515 | `+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`:: |
516 | Generic memory debug logging statement. | |
b81626f9 | 517 | |
cd4aac1e PP |
518 | `+BT_LOGI_MEM(data_ptr, data_size, "format string", ...)+`:: |
519 | Generic memory info logging statement. | |
b81626f9 | 520 | |
cd4aac1e PP |
521 | `+BT_LOGW_MEM(data_ptr, data_size, "format string", ...)+`:: |
522 | Generic memory warning logging statement. | |
b81626f9 | 523 | |
cd4aac1e PP |
524 | `+BT_LOGE_MEM(data_ptr, data_size, "format string", ...)+`:: |
525 | Generic memory error logging statement. | |
b81626f9 | 526 | |
cd4aac1e PP |
527 | `+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`:: |
528 | Generic memory fatal logging statement. | |
b81626f9 | 529 | |
ef267d12 PP |
530 | `+BT_LOGT_ERRNO("initial message", "format string", ...)+`:: |
531 | Generic `errno` string trace logging statement. | |
b81626f9 | 532 | |
cd4aac1e PP |
533 | `+BT_LOGD_ERRNO("initial message", "format string", ...)+`:: |
534 | Generic `errno` string debug logging statement. | |
beb0fb75 | 535 | |
cd4aac1e PP |
536 | `+BT_LOGI_ERRNO("initial message", "format string", ...)+`:: |
537 | Generic `errno` string info logging statement. | |
beb0fb75 | 538 | |
cd4aac1e PP |
539 | `+BT_LOGW_ERRNO("initial message", "format string", ...)+`:: |
540 | Generic `errno` string warning logging statement. | |
beb0fb75 | 541 | |
cd4aac1e PP |
542 | `+BT_LOGE_ERRNO("initial message", "format string", ...)+`:: |
543 | Generic `errno` string error logging statement. | |
beb0fb75 | 544 | |
cd4aac1e PP |
545 | `+BT_LOGF_ERRNO("initial message", "format string", ...)+`:: |
546 | Generic `errno` string fatal logging statement. | |
beb0fb75 | 547 | |
cd4aac1e PP |
548 | [[lib-logging-statements]] |
549 | ==== Library-specific logging statement macros | |
550 | ||
28b765ac PP |
551 | The {bt2} library contains an internal logging API based on the |
552 | generic logging framework. You can use it to log known {bt2} | |
cd4aac1e PP |
553 | objects without having to manually log each member. |
554 | ||
28b765ac PP |
555 | See <<logging-instrument-c-file-lib>> |
556 | and <<logging-instrument-h-file-lib>> to | |
cd4aac1e PP |
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 | ||
ef267d12 PP |
562 | `+BT_LIB_LOGT("format string", ...)+`:: |
563 | Library trace logging statement. | |
cd4aac1e PP |
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 | ||
3cd4c495 PP |
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 | |
3cd4c495 PP |
586 | appending. |
587 | ||
cd4aac1e PP |
588 | The macros above accept the typical `printf()` conversion specifiers |
589 | with the following limitations: | |
590 | ||
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 | |
597 | `PRIi64`. | |
598 | ||
28b765ac | 599 | The {bt2} library custom conversion specifier is accepted. Its |
cd4aac1e PP |
600 | syntax is either `%!u` to format a UUID (`bt_uuid` type), or: |
601 | ||
602 | . Introductory `%!` sequence. | |
603 | ||
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`. | |
608 | ||
609 | . **Optional**: `pass:[+]` to print extended object members. This | |
610 | depends on the provided format specifier. | |
611 | ||
612 | . Format specifier (see below). | |
613 | ||
614 | The available format specifiers are: | |
615 | ||
616 | [options="header,autowidth",cols="3"] | |
617 | |=== | |
618 | |Specifier | |
619 | |Object | |
620 | |Expected C type | |
621 | ||
622 | |`F` | |
623 | |Trace IR field class | |
6769570a | 624 | |`+const struct bt_field_class *+` |
cd4aac1e PP |
625 | |
626 | |`f` | |
627 | |Trace IR field | |
6769570a | 628 | |`+const struct bt_field *+` |
cd4aac1e PP |
629 | |
630 | |`P` | |
631 | |Trace IR field path | |
6769570a | 632 | |`+const struct bt_field_path *+` |
cd4aac1e PP |
633 | |
634 | |`E` | |
635 | |Trace IR event class | |
6769570a | 636 | |`+const struct bt_event_class *+` |
cd4aac1e PP |
637 | |
638 | |`e` | |
639 | |Trace IR event | |
6769570a | 640 | |`+const struct bt_event *+` |
cd4aac1e PP |
641 | |
642 | |`S` | |
643 | |Trace IR stream class. | |
6769570a | 644 | |`+const struct bt_stream_class *+` |
cd4aac1e PP |
645 | |
646 | |`s` | |
647 | |Trace IR stream | |
6769570a | 648 | |`+const struct bt_stream *+` |
cd4aac1e PP |
649 | |
650 | |`a` | |
651 | |Trace IR packet | |
6769570a | 652 | |`+const struct bt_packet *+` |
cd4aac1e PP |
653 | |
654 | |`T` | |
655 | |Trace IR trace class | |
6769570a | 656 | |`+const struct bt_trace_class *+` |
cd4aac1e PP |
657 | |
658 | |`t` | |
659 | |Trace IR trace | |
6769570a | 660 | |`+const struct bt_trace *+` |
cd4aac1e PP |
661 | |
662 | |`K` | |
663 | |Trace IR clock class | |
6769570a | 664 | |`+const struct bt_clock_class *+` |
cd4aac1e PP |
665 | |
666 | |`k` | |
667 | |Trace IR clock snapshot | |
6769570a | 668 | |`+const struct bt_clock_snapshot *+` |
cd4aac1e PP |
669 | |
670 | |`v` | |
671 | |Value object | |
6769570a PP |
672 | |`+const struct bt_value *+` |
673 | ||
674 | |`R` | |
675 | |Integer range set | |
676 | |`const struct bt_integer_range_set *` | |
cd4aac1e PP |
677 | |
678 | |`n` | |
679 | |Message | |
6769570a | 680 | |`+const struct bt_message *+` |
cd4aac1e | 681 | |
a3f0c7db SM |
682 | |`I` |
683 | |Message iterator class | |
684 | |`struct bt_message_iterator_class *` | |
685 | ||
cd4aac1e PP |
686 | |`i` |
687 | |Message iterator | |
688 | |`struct bt_message_iterator *` | |
689 | ||
690 | |`C` | |
691 | |Component class | |
692 | |`struct bt_component_class *` | |
693 | ||
694 | |`c` | |
695 | |Component | |
6769570a | 696 | |`+const struct bt_component *+` |
cd4aac1e PP |
697 | |
698 | |`p` | |
699 | |Port | |
6769570a | 700 | |`+const struct bt_port *+` |
cd4aac1e PP |
701 | |
702 | |`x` | |
703 | |Connection | |
6769570a | 704 | |`+const struct bt_connection *+` |
cd4aac1e PP |
705 | |
706 | |`g` | |
707 | |Graph | |
6769570a | 708 | |`+const struct bt_graph *+` |
cd4aac1e | 709 | |
b70d57a1 PP |
710 | |`z` |
711 | |Interrupter | |
712 | |`+struct bt_interrupter *+` | |
713 | ||
cd4aac1e PP |
714 | |`l` |
715 | |Plugin | |
6769570a | 716 | |`+const struct bt_plugin *+` |
cd4aac1e | 717 | |
553c4bab PP |
718 | |`r` |
719 | |Error cause | |
6769570a | 720 | |`+const struct bt_error_cause *+` |
553c4bab | 721 | |
cd4aac1e PP |
722 | |`o` |
723 | |Object pool | |
6769570a | 724 | |`+const struct bt_object_pool *+` |
cd4aac1e PP |
725 | |
726 | |`O` | |
727 | |Object | |
6769570a | 728 | |`+const struct bt_object *+` |
cd4aac1e PP |
729 | |=== |
730 | ||
731 | Conversion specifier examples: | |
732 | ||
733 | * `%!f` | |
734 | * `%![my-event-]+e` | |
735 | * `%!t` | |
736 | * `%!+F` | |
737 | ||
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 | |
741 | example: | |
742 | ||
743 | [source,c] | |
744 | ---- | |
745 | BT_LIB_LOGW("Message: count=%u, %!E, %!+K", count, event_class, clock_class); | |
746 | ---- | |
747 | ||
748 | Example with a custom prefix: | |
749 | ||
750 | [source,c] | |
751 | ---- | |
752 | BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b); | |
753 | ---- | |
754 | ||
28b765ac | 755 | It is safe to pass `NULL` as any {bt2} object parameter: the macros |
cd4aac1e PP |
756 | only print its null address. |
757 | ||
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. | |
761 | ||
cd4aac1e PP |
762 | [[comp-logging-statements]] |
763 | ==== Component-specific logging statement macros | |
764 | ||
765 | There are available logging macros for components. They prepend a prefix | |
766 | including the component's name to the logging message. | |
767 | ||
28b765ac PP |
768 | See <<logging-instrument-c-file-compcls>> and |
769 | <<logging-instrument-h-file-compcls>> to learn how to be able to use the | |
cd4aac1e PP |
770 | following macros. |
771 | ||
772 | The component logging statement macros are named `+BT_COMP_LOG*()+` | |
773 | instead of `+BT_LOG*()+`: | |
774 | ||
ef267d12 PP |
775 | `+BT_COMP_LOGT("format string", ...)+`:: |
776 | Component trace logging statement. | |
cd4aac1e PP |
777 | |
778 | `+BT_COMP_LOGD("format string", ...)+`:: | |
779 | Component debug logging statement. | |
780 | ||
781 | `+BT_COMP_LOGI("format string", ...)+`:: | |
782 | Component info logging statement. | |
783 | ||
784 | `+BT_COMP_LOGW("format string", ...)+`:: | |
785 | Component warning logging statement. | |
786 | ||
787 | `+BT_COMP_LOGE("format string", ...)+`:: | |
788 | Component error logging statement. | |
789 | ||
790 | `+BT_COMP_LOGF("format string", ...)+`:: | |
791 | Component fatal logging statement. | |
792 | ||
ef267d12 PP |
793 | `+BT_COMP_LOGT_STR("preformatted string")+`:: |
794 | Component preformatted string trace logging statement. | |
cd4aac1e PP |
795 | |
796 | `+BT_COMP_LOGD_STR("preformatted string")+`:: | |
797 | Component preformatted string debug logging statement. | |
798 | ||
799 | `+BT_COMP_LOGI_STR("preformatted string")+`:: | |
800 | Component preformatted string info logging statement. | |
801 | ||
802 | `+BT_COMP_LOGW_STR("preformatted string")+`:: | |
803 | Component preformatted string warning logging statement. | |
804 | ||
805 | `+BT_COMP_LOGE_STR("preformatted string")+`:: | |
806 | Component preformatted string error logging statement. | |
807 | ||
808 | `+BT_COMP_LOGF_STR("preformatted string")+`:: | |
809 | Component preformatted string fatal logging statement. | |
810 | ||
ef267d12 PP |
811 | `+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`:: |
812 | Component `errno` string trace logging statement. | |
cd4aac1e PP |
813 | |
814 | `+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`:: | |
815 | Component `errno` string debug logging statement. | |
816 | ||
817 | `+BT_COMP_LOGI_ERRNO("initial message", "format string", ...)+`:: | |
818 | Component `errno` string info logging statement. | |
819 | ||
820 | `+BT_COMP_LOGW_ERRNO("initial message", "format string", ...)+`:: | |
821 | Component `errno` string warning logging statement. | |
822 | ||
823 | `+BT_COMP_LOGE_ERRNO("initial message", "format string", ...)+`:: | |
824 | Component `errno` string error logging statement. | |
825 | ||
826 | `+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`:: | |
827 | Component `errno` string fatal logging statement. | |
828 | ||
ef267d12 PP |
829 | `+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`:: |
830 | Component memory trace logging statement. | |
cd4aac1e PP |
831 | |
832 | `+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`:: | |
833 | Component memory debug logging statement. | |
834 | ||
835 | `+BT_COMP_LOGI_MEM(data_ptr, data_size, "format string", ...)+`:: | |
836 | Component memory info logging statement. | |
837 | ||
838 | `+BT_COMP_LOGW_MEM(data_ptr, data_size, "format string", ...)+`:: | |
839 | Component memory warning logging statement. | |
840 | ||
841 | `+BT_COMP_LOGE_MEM(data_ptr, data_size, "format string", ...)+`:: | |
842 | Component memory error logging statement. | |
843 | ||
844 | `+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`:: | |
845 | Component memory fatal logging statement. | |
beb0fb75 | 846 | |
f9ded0e0 | 847 | ==== Conditional logging |
beb0fb75 | 848 | |
cd4aac1e | 849 | `+BT_LOG_IF(cond, statement)+`:: |
beb0fb75 PP |
850 | Execute `statement` only if `cond` is true. |
851 | + | |
852 | Example: | |
853 | + | |
854 | -- | |
855 | [source,c] | |
856 | ---- | |
857 | BT_LOG_IF(i < count / 2, BT_LOGD("Log this: i=%d", i)); | |
858 | ---- | |
859 | -- | |
860 | ||
861 | To check the <<build-time-log-level,build-time log level>>: | |
862 | ||
863 | [source,c] | |
864 | ---- | |
865 | #if BT_LOG_ENABLED_DEBUG | |
866 | ... | |
867 | #endif | |
868 | ---- | |
869 | ||
cd4aac1e PP |
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 | |
f9ded0e0 PP |
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 | |
874 | block. | |
beb0fb75 PP |
875 | |
876 | The available definitions for build-time conditions are: | |
877 | ||
ef267d12 | 878 | * `BT_LOG_ENABLED_TRACE` |
beb0fb75 PP |
879 | * `BT_LOG_ENABLED_DEBUG` |
880 | * `BT_LOG_ENABLED_INFO` | |
770538dd | 881 | * `BT_LOG_ENABLED_WARNING` |
beb0fb75 PP |
882 | * `BT_LOG_ENABLED_ERROR` |
883 | * `BT_LOG_ENABLED_FATAL` | |
884 | ||
885 | To check the current, <<run-time-log-level,run-time log level>>: | |
886 | ||
887 | [source,c] | |
888 | ---- | |
889 | if (BT_LOG_ON_DEBUG) { | |
890 | ... | |
891 | } | |
892 | ---- | |
893 | ||
894 | This tests if the _DEBUG_ log level is dynamically turned on | |
cd4aac1e | 895 | (implies that it's also enabled at build time). This check could have a |
beb0fb75 PP |
896 | noticeable impact on performance. |
897 | ||
898 | The available definitions for run-time conditions are: | |
899 | ||
ef267d12 | 900 | * `BT_LOG_ON_TRACE` |
beb0fb75 PP |
901 | * `BT_LOG_ON_DEBUG` |
902 | * `BT_LOG_ON_INFO` | |
770538dd | 903 | * `BT_LOG_ON_WARNING` |
beb0fb75 PP |
904 | * `BT_LOG_ON_ERROR` |
905 | * `BT_LOG_ON_FATAL` | |
906 | ||
cd4aac1e PP |
907 | Those macros check the module-specific log level symbol (defined by |
908 | `BT_LOG_OUTPUT_LEVEL`). | |
beb0fb75 PP |
909 | |
910 | Never, ever write code which would be executed only to compute the | |
911 | fields of a logging statement outside a conditional logging scope, | |
912 | for example: | |
913 | ||
914 | [source,c] | |
915 | ---- | |
916 | int number = get_number_of_event_classes_with_property_x(...); | |
917 | BT_LOGD("Bla bla: number=%d", number); | |
918 | ---- | |
919 | ||
920 | Do this instead: | |
921 | ||
922 | [source,c] | |
923 | ---- | |
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); | |
927 | } | |
928 | ---- | |
929 | ||
930 | Or even this: | |
931 | ||
932 | [source,c] | |
933 | ---- | |
934 | BT_LOGD("Bla bla: number=%d", get_number_of_event_classes_with_property_x(...)); | |
935 | ---- | |
936 | ||
cd4aac1e | 937 | === Guides |
beb0fb75 | 938 | |
cd4aac1e | 939 | [[logging-instrument-c-file-gen]] |
fb7ff115 | 940 | ==== Instrument a {c-cpp} source file (generic) |
beb0fb75 | 941 | |
fb7ff115 | 942 | To instrument a {c-cpp} source file (`.c`/`.cpp`): |
cd4aac1e PP |
943 | |
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: | |
4a41523d PP |
946 | + |
947 | -- | |
948 | [source,c] | |
949 | ---- | |
cd4aac1e | 950 | #define BT_LOG_TAG "SUBSYS/MY-MODULE/MY-FILE" |
4a41523d PP |
951 | ---- |
952 | -- | |
cd4aac1e PP |
953 | |
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>>. | |
958 | + | |
959 | Examples: | |
960 | + | |
961 | [source,c] | |
962 | ---- | |
963 | /* Global log level variable */ | |
964 | #define BT_LOG_OUTPUT_LEVEL module_global_log_level | |
965 | ---- | |
4a41523d | 966 | + |
cd4aac1e PP |
967 | [source,c] |
968 | ---- | |
969 | /* Local log level variable; must exist where you use BT_LOG*() */ | |
970 | #define BT_LOG_OUTPUT_LEVEL log_level | |
971 | ---- | |
972 | + | |
973 | [source,c] | |
974 | ---- | |
975 | /* Object's log level; `obj` must exist where you use BT_LOG*() */ | |
976 | #define BT_LOG_OUTPUT_LEVEL (obj->log_level) | |
977 | ---- | |
4a41523d | 978 | |
cd4aac1e | 979 | . Include `"logging/log.h"`: |
4a41523d | 980 | + |
beb0fb75 PP |
981 | [source,c] |
982 | ---- | |
578e048b | 983 | #include "logging/log.h" |
cd4aac1e | 984 | ---- |
4a41523d | 985 | |
cd4aac1e PP |
986 | . In the file, instrument your code with the |
987 | <<gen-logging-statements,generic logging statement macros>>. | |
4a41523d | 988 | |
cd4aac1e | 989 | [[logging-instrument-h-file-gen]] |
fb7ff115 | 990 | ==== Instrument a {c-cpp} header file (generic) |
cd4aac1e | 991 | |
fb7ff115 PP |
992 | To instrument a {c-cpp} header file (`.h`/`.hpp`), if you have |
993 | `static inline` functions in it: | |
cd4aac1e PP |
994 | |
995 | . Do not include `"logging/log.h"`! | |
996 | ||
997 | . Do one of: | |
998 | ||
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: | |
4a41523d | 1002 | + |
cd4aac1e PP |
1003 | [source,c] |
1004 | ---- | |
1005 | static inline | |
1006 | int some_function(int x) | |
1007 | { | |
1008 | /* ... */ | |
4a41523d | 1009 | |
ef267d12 PP |
1010 | #ifdef BT_LOGT |
1011 | BT_LOGT(...); | |
cd4aac1e | 1012 | #endif |
beb0fb75 | 1013 | |
cd4aac1e | 1014 | /* ... */ |
6470c171 | 1015 | |
cd4aac1e PP |
1016 | #ifdef BT_LOGW_STR |
1017 | BT_LOGW_STR(...); | |
1018 | #endif | |
f9ded0e0 | 1019 | |
cd4aac1e PP |
1020 | /* ... */ |
1021 | } | |
1022 | ---- | |
1023 | + | |
fb7ff115 PP |
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 | |
cd4aac1e PP |
1026 | <<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time |
1027 | log level>> expression. | |
f9ded0e0 | 1028 | |
cd4aac1e PP |
1029 | .. Require that logging be enabled: |
1030 | + | |
1031 | [source,c] | |
1032 | ---- | |
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. | |
1036 | #endif | |
1037 | ---- | |
1038 | + | |
1039 | Then, in the file, instrument your code with the | |
1040 | <<gen-logging-statements,generic logging statement macros>>. | |
1041 | ||
cd4aac1e | 1042 | [[logging-instrument-c-file-lib]] |
fb7ff115 | 1043 | ==== Instrument a library {c-cpp} source file |
cd4aac1e | 1044 | |
fb7ff115 | 1045 | To instrument a library {c-cpp} source file (`.c`/`.cpp`): |
4a41523d PP |
1046 | |
1047 | . At the top of the file, before the first `#include` line (if any), | |
cd4aac1e PP |
1048 | define your file's <<choose-a-logging-tag,logging tag>> name (this |
1049 | tag must start with `LIB/`): | |
4a41523d PP |
1050 | + |
1051 | -- | |
1052 | [source,c] | |
1053 | ---- | |
cd4aac1e | 1054 | #define BT_LOG_TAG "LIB/THE-FILE" |
4a41523d PP |
1055 | ---- |
1056 | -- | |
cd4aac1e PP |
1057 | |
1058 | . Include `"lib/logging.h"`: | |
4a41523d | 1059 | + |
cd4aac1e PP |
1060 | [source,c] |
1061 | ---- | |
1062 | #include "lib/logging.h" | |
1063 | ---- | |
4a41523d | 1064 | |
cd4aac1e PP |
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>>. | |
4a41523d | 1068 | |
cd4aac1e | 1069 | [[logging-instrument-h-file-lib]] |
fb7ff115 | 1070 | ==== Instrument a library {c-cpp} header file |
cd4aac1e | 1071 | |
fb7ff115 PP |
1072 | To instrument a library {c-cpp} header file (`.h`/`.hpp`), if you have |
1073 | `static inline` functions in it: | |
cd4aac1e PP |
1074 | |
1075 | . Do not include `"lib/logging.h"`! | |
1076 | ||
1077 | . Require that library logging be enabled: | |
1078 | + | |
1079 | [source,c] | |
1080 | ---- | |
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. | |
1084 | #endif | |
1085 | ---- | |
1086 | ||
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>>. | |
f9ded0e0 | 1090 | |
cd4aac1e | 1091 | [[logging-instrument-c-file-compcls]] |
fb7ff115 | 1092 | ==== Instrument a component class {c-cpp} source file |
cd4aac1e | 1093 | |
fb7ff115 | 1094 | To instrument a component class {c-cpp} source file (`.c`/`.cpp`): |
cd4aac1e PP |
1095 | |
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): | |
4a41523d PP |
1099 | + |
1100 | -- | |
1101 | [source,c] | |
1102 | ---- | |
cd4aac1e PP |
1103 | #define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC" |
1104 | ---- | |
1105 | -- | |
4a41523d | 1106 | |
cd4aac1e PP |
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>>. | |
1111 | + | |
1112 | For a component class file, it is usually a member of a local component | |
1113 | private structure variable: | |
1114 | + | |
1115 | [source,c] | |
1116 | ---- | |
1117 | #define BT_LOG_OUTPUT_LEVEL (my_comp->log_level) | |
1118 | ---- | |
4a41523d | 1119 | |
cd4aac1e PP |
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. | |
1124 | + | |
1125 | This is usually a member of a local component private structure | |
1126 | variable: | |
1127 | + | |
1128 | [source,c] | |
1129 | ---- | |
1130 | #define BT_COMP_LOG_SELF_COMP (my_comp->self_comp) | |
1131 | ---- | |
1132 | ||
d9c39b0a | 1133 | . Include `"logging/comp-logging.h"`: |
cd4aac1e PP |
1134 | + |
1135 | [source,c] | |
1136 | ---- | |
d9c39b0a | 1137 | #include "logging/comp-logging.h" |
cd4aac1e PP |
1138 | ---- |
1139 | ||
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: | |
1143 | + | |
1144 | [source,c] | |
1145 | ---- | |
1146 | struct my_comp { | |
1147 | bt_logging_level log_level; | |
4a41523d | 1148 | /* ... */ |
cd4aac1e | 1149 | }; |
4a41523d | 1150 | |
cd4aac1e PP |
1151 | bt_self_component_status my_comp_init( |
1152 | bt_self_component_source *self_comp_src, | |
1153 | bt_value *params, void *init_method_data) | |
1154 | { | |
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); | |
1159 | ||
1160 | BT_ASSERT(my_comp); | |
1161 | my_comp->log_level = bt_component_get_logging_level(comp); | |
4a41523d PP |
1162 | |
1163 | /* ... */ | |
1164 | } | |
1165 | ---- | |
cd4aac1e PP |
1166 | |
1167 | . In the file, instrument your code with the | |
1168 | <<comp-logging-statements,component logging statement macros>>. | |
1169 | ||
cd4aac1e | 1170 | [[logging-instrument-h-file-compcls]] |
fb7ff115 | 1171 | ==== Instrument a component class {c-cpp} header file |
cd4aac1e | 1172 | |
fb7ff115 PP |
1173 | To instrument a component class {c-cpp} header file (`.h`/`.hpp`), if |
1174 | you have `static inline` functions in it: | |
cd4aac1e | 1175 | |
d9c39b0a | 1176 | . Do not include `"logging/comp-logging.h"`! |
cd4aac1e PP |
1177 | |
1178 | . Require that component logging be enabled: | |
4a41523d | 1179 | + |
cd4aac1e PP |
1180 | [source,c] |
1181 | ---- | |
1182 | /* Protection: this file uses BT_COMP_LOG*() macros directly */ | |
1183 | #ifndef BT_COMP_LOG_SUPPORTED | |
d9c39b0a | 1184 | # error Please include "logging/comp-logging.h" before including this file. |
cd4aac1e PP |
1185 | #endif |
1186 | ---- | |
1187 | ||
1188 | . In the file, instrument your code with the | |
1189 | <<comp-logging-statements,component logging statement macros>>. | |
1190 | ||
cd4aac1e PP |
1191 | [[choose-a-logging-tag]] |
1192 | ==== Choose a logging tag | |
beb0fb75 | 1193 | |
fb7ff115 PP |
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. | |
beb0fb75 | 1197 | |
cd4aac1e PP |
1198 | In general, a logging tag name _must_ be only uppercase letters, digits, |
1199 | and the `-`, `.`, and `/` characters. | |
beb0fb75 | 1200 | |
cd4aac1e PP |
1201 | Use `/` to show the subsystem to source file hierarchy. |
1202 | ||
28b765ac | 1203 | For the {bt2} library, start with `LIB/`. |
cd4aac1e PP |
1204 | |
1205 | For the CTF writer library, start with `CTF-WRITER/`. | |
1206 | ||
1207 | For component classes, use: | |
beb0fb75 | 1208 | |
93841983 | 1209 | [verse] |
cd4aac1e PP |
1210 | `PLUGIN/__CCTYPE__.__PNAME__.__CCNAME__[/__FILE__]` |
1211 | ||
1212 | With: | |
1213 | ||
1214 | `__CCTYPE__`:: | |
1215 | Component class's type (`SRC`, `FLT`, or `SINK`). | |
beb0fb75 | 1216 | |
cd4aac1e | 1217 | `__PNAME__`:: |
93841983 | 1218 | Plugin's name. |
beb0fb75 | 1219 | |
cd4aac1e | 1220 | `__CCNAME__`:: |
93841983 | 1221 | Component class's name. |
beb0fb75 | 1222 | |
cd4aac1e | 1223 | `__FILE__`:: |
93841983 | 1224 | Additional information to specify the source file name or module. |
beb0fb75 | 1225 | |
cd4aac1e | 1226 | For plugins (files common to many component classes), use: |
beb0fb75 | 1227 | |
cd4aac1e PP |
1228 | [verse] |
1229 | `PLUGIN/__PNAME__[/__FILE__]` | |
beb0fb75 | 1230 | |
cd4aac1e | 1231 | With: |
beb0fb75 | 1232 | |
cd4aac1e PP |
1233 | `__PNAME__`:: |
1234 | Plugin's name. | |
1235 | ||
1236 | `__FILE__`:: | |
1237 | Additional information to specify the source file name or module. | |
1238 | ||
cd4aac1e PP |
1239 | [[choose-a-log-level]] |
1240 | ==== Choose a log level | |
beb0fb75 PP |
1241 | |
1242 | Choosing the appropriate level for your logging statement is very | |
1243 | important. | |
1244 | ||
cd4aac1e | 1245 | [options="header,autowidth",cols="1,2,3a,4"] |
beb0fb75 | 1246 | |=== |
cd4aac1e | 1247 | |Log level |Description |Use cases |Expected impact on performance |
beb0fb75 PP |
1248 | |
1249 | |_FATAL_ | |
cd4aac1e PP |
1250 | | |
1251 | The program, library, or plugin cannot continue to work in this | |
beb0fb75 PP |
1252 | condition: it must be terminated immediately. |
1253 | ||
b4b9064d | 1254 | A _FATAL_-level logging statement should always be followed by |
4a41523d | 1255 | `abort()`. |
beb0fb75 PP |
1256 | | |
1257 | * Unexpected return values from system calls. | |
4a41523d PP |
1258 | * Logic error in internal code, for example an unexpected value in a |
1259 | `switch` statement. | |
cd4aac1e | 1260 | * Failed assertion (within `BT_ASSERT()`). |
bdb288b3 PP |
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()`). | |
dd22a91f | 1265 | |Almost none: always enabled. |
beb0fb75 PP |
1266 | |
1267 | |_ERROR_ | |
cd4aac1e PP |
1268 | | |
1269 | An important error which is somewhat not fatal, that is, the program, | |
beb0fb75 PP |
1270 | library, or plugin can continue to work after this, but you judge that |
1271 | it should be reported to the user. | |
1272 | ||
1273 | Usually, the program cannot recover from such an error, but it can at | |
1274 | least exit cleanly. | |
1275 | | | |
1276 | * Memory allocation errors. | |
cd4aac1e PP |
1277 | * Wrong component initialization parameters. |
1278 | * Corrupted, unrecoverable trace data. | |
beb0fb75 PP |
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. | |
93841983 | 1283 | * Almost any error in terminal elements: CLI and plugins. |
dd22a91f | 1284 | |Almost none: always enabled. |
beb0fb75 | 1285 | |
770538dd | 1286 | |_WARNING_ |
cd4aac1e PP |
1287 | | |
1288 | An error which still allows the execution to continue, but you judge | |
1289 | that it should be reported to the user. | |
6c1b33a8 | 1290 | |
770538dd PP |
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 | |
1296 | condition). | |
beb0fb75 | 1297 | | |
cd4aac1e PP |
1298 | * Missing data within something that is expected to have it, but there's |
1299 | an alternative. | |
1300 | * Invalid file, but recoverable/fixable. | |
dd22a91f | 1301 | |Almost none: always enabled. |
beb0fb75 PP |
1302 | |
1303 | |_INFO_ | |
beb0fb75 | 1304 | | |
cd4aac1e PP |
1305 | Any useful information which a non-developer user would possibly |
1306 | understand. | |
1307 | ||
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. | |
1311 | | | |
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. | |
beb0fb75 | 1317 | * Successful connection to or disconnection from another system. |
4a41523d | 1318 | * An _optional_ subsystem cannot be loaded. |
cd4aac1e PP |
1319 | * An _optional_ field/datum cannot be found. |
1320 | | | |
dd22a91f | 1321 | Very little: always enabled. |
beb0fb75 PP |
1322 | |
1323 | |_DEBUG_ | |
beb0fb75 | 1324 | | |
28b765ac | 1325 | Something that only {bt2} developers would be interested into, |
cd4aac1e PP |
1326 | which can occur on the fast path, but not more often than once per |
1327 | message. | |
1328 | ||
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 | |
1331 | an _INFO_ build. | |
1332 | | | |
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 | |
1337 | developer mode). | |
9b4f9b42 | 1338 | * Object interruption. |
cd4aac1e PP |
1339 | * Calling user methods and logging the result. |
1340 | * Setting object properties (except fields and values). | |
1341 | | | |
ef267d12 | 1342 | Noticeable, but not as much as the _TRACE_ level: could be executed |
cd4aac1e PP |
1343 | in production if you're going to need a thorough log for support |
1344 | tickets without having to rebuild the project. | |
beb0fb75 | 1345 | |
ef267d12 | 1346 | |_TRACE_ |
cd4aac1e PP |
1347 | | |
1348 | Low-level debugging context information (anything that does not fit the | |
1349 | other log levels). More appropriate for tracing in general. | |
beb0fb75 PP |
1350 | | |
1351 | * Reference count change. | |
cd4aac1e | 1352 | * Fast path, low level state machine's state change. |
beb0fb75 PP |
1353 | * Get or set an object's property. |
1354 | * Object comparison's intermediate results. | |
1355 | |Huge: not executed in production. | |
1356 | |=== | |
1357 | ||
cd4aac1e PP |
1358 | [IMPORTANT] |
1359 | -- | |
770538dd | 1360 | Make sure not to use a _WARNING_ (or higher) log level when the |
cd4aac1e PP |
1361 | condition leading to the logging statement can occur under normal |
1362 | circumstances. | |
1363 | ||
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 | |
ef267d12 | 1368 | _TRACE_ level (or do not log at all). |
cd4aac1e | 1369 | -- |
b4b9064d | 1370 | |
b4b9064d | 1371 | [[message]] |
cd4aac1e | 1372 | ==== Write an appropriate message |
beb0fb75 PP |
1373 | |
1374 | Follow those rules when you write a logging statement's message: | |
1375 | ||
cd4aac1e PP |
1376 | * Use an English sentence which starts with a capital letter. |
1377 | ||
1378 | * Start the sentence with the appropriate verb tense depending on the | |
1379 | context. For example: | |
beb0fb75 PP |
1380 | + |
1381 | -- | |
b4b9064d PP |
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 | |
1386 | also _set_) | |
beb0fb75 PP |
1387 | -- |
1388 | + | |
1389 | For warning and error messages, you can start the message with _Cannot_ | |
b4b9064d | 1390 | or _Failed to_ followed by a verb if it's appropriate. |
beb0fb75 PP |
1391 | |
1392 | * Do not include the log level in the message itself. For example, | |
1393 | do not start the message with _Error while_ or _Warning:_. | |
1394 | ||
cd4aac1e PP |
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 | |
1399 | with newlines. | |
beb0fb75 PP |
1400 | |
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. | |
1405 | ||
1406 | The statement's fields _must_ be a comma-separated list of | |
cd4aac1e PP |
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. | |
beb0fb75 PP |
1412 | |
1413 | Example: | |
1414 | ||
cd4aac1e PP |
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" | |
beb0fb75 | 1418 | |
cd4aac1e PP |
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. | |
beb0fb75 PP |
1422 | |
1423 | Prefer the following suffixes in field names: | |
1424 | ||
1425 | [options="header,autowidth"] | |
1426 | |=== | |
1427 | |Field name suffix |Description |Format specifier | |
1428 | ||
1429 | |`-addr` |Memory address |`%p` | |
1430 | |`-fd` |File descriptor |`%d` | |
cd4aac1e PP |
1431 | |`-fp` |File stream (`+FILE *+`) |`%p` |
1432 | |`-id` |Object's ID |`%" PRIu64 "` | |
1433 | |`-index` |Index |`%" PRIu64 "` | |
beb0fb75 | 1434 | |`-name` |Object's name |`\"%s\"` |
beb0fb75 PP |
1435 | |=== |
1436 | ||
f9ded0e0 | 1437 | === Output |
beb0fb75 PP |
1438 | |
1439 | The log is printed to the standard error stream. A log line contains the | |
cd4aac1e PP |
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>>. | |
beb0fb75 | 1443 | |
28b765ac | 1444 | When {bt2} supports terminal color codes (depends on the |
f9ded0e0 PP |
1445 | `BABELTRACE_TERM_COLOR` environment variable's value and what the |
1446 | standard output and error streams are plugged into), _INFO_-level lines | |
770538dd | 1447 | are blue, _WARNING_-level lines are yellow, and _ERROR_-level and |
f9ded0e0 PP |
1448 | _FATAL_-level lines are red. |
1449 | ||
1450 | Log line example: | |
beb0fb75 | 1451 | |
cd4aac1e PP |
1452 | ---- |
1453 | 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0 | |
1454 | ---- | |
beb0fb75 | 1455 | |
cd4aac1e PP |
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 | |
beb0fb75 PP |
1458 | generates: |
1459 | ||
cd4aac1e PP |
1460 | ---- |
1461 | $ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS' | |
1462 | ---- | |
1463 | ||
cd4aac1e PP |
1464 | == Valgrind |
1465 | ||
1466 | To use Valgrind on an application (for example, the CLI or a test) which | |
1467 | loads libbabeltrace2, use: | |
1468 | ||
1469 | ---- | |
1470 | $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \ | |
916d0d91 | 1471 | LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app |
cd4aac1e PP |
1472 | ---- |
1473 | ||
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). | |
1478 | ||
16b7b5e7 | 1479 | `LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared |
cd4aac1e PP |
1480 | libraries (plugins) which it loads. You need this to see the appropriate |
1481 | backtrace when Valgrind shows errors. | |
c637d729 FD |
1482 | |
1483 | == Testing | |
1484 | ||
800400d8 PP |
1485 | [[test-env]] |
1486 | === Environment | |
c637d729 | 1487 | |
8aed890c SM |
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. | |
1491 | ||
1492 | If building in-tree, you can run single tests from the tree directly: | |
1493 | ||
1494 | ---- | |
7132b838 | 1495 | $ ./tests/plugins/sink.text.pretty/test-enum.sh |
8aed890c SM |
1496 | ---- |
1497 | ||
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 | |
1500 | want to run tests. | |
1501 | ||
1502 | ---- | |
1503 | $ source /path/to/my/build/tests/utils/env.sh | |
7132b838 | 1504 | $ ./tests/plugins/sink.text.pretty/test-enum.sh |
800400d8 PP |
1505 | ---- |
1506 | ||
1507 | ==== Python | |
1508 | ||
31d2049b PP |
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. | |
800400d8 | 1512 | |
31d2049b | 1513 | `run-in-py-env.sh` uses <<test-env,`utils.sh`>> which needs to know the |
800400d8 PP |
1514 | build directory, so make sure you set the `BT_TESTS_BUILDDIR` |
1515 | environment variable correctly _if you build out of tree_, for example: | |
1516 | ||
1517 | ---- | |
1518 | $ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests | |
1519 | ---- | |
1520 | ||
1521 | You can run any command which needs the `bt2` Python package through | |
31d2049b | 1522 | `run-in-py-env.sh`, for example: |
c637d729 FD |
1523 | |
1524 | ---- | |
31d2049b | 1525 | $ ./tests/utils/run-in-py-env.sh ipython3 |
c637d729 FD |
1526 | ---- |
1527 | ||
800400d8 PP |
1528 | === Report format |
1529 | ||
1530 | All test scripts output the test results following the | |
1531 | https://testanything.org/[Test Anything Protocol] (TAP) format. | |
1532 | ||
1533 | The TAP format has two mechanisms to print additional information about | |
1534 | a test: | |
1535 | ||
1536 | * Print a line starting with `#` to the standard output. | |
1537 | + | |
1538 | This is usually done with the `diag()` C function or the `diag` shell | |
1539 | function. | |
1540 | ||
1541 | * Print to the standard error. | |
1542 | ||
800400d8 PP |
1543 | === Python bindings |
1544 | ||
1545 | The `bt2` Python package tests are located in | |
1546 | `tests/bindings/python/bt2`. | |
1547 | ||
800400d8 PP |
1548 | ==== Python test runner |
1549 | ||
28b765ac | 1550 | `tests/utils/python/testrunner.py` is {bt2}'s Python test runner |
800400d8 PP |
1551 | which loads Python files containing unit tests, finds all the test |
1552 | cases, and runs the tests, producing a TAP report. | |
1553 | ||
1554 | You can see the test runner command's help with: | |
c637d729 FD |
1555 | |
1556 | ---- | |
800400d8 | 1557 | $ python3 ./tests/utils/python/testrunner.py --help |
c637d729 FD |
1558 | ---- |
1559 | ||
800400d8 PP |
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. | |
c637d729 | 1563 | |
800400d8 PP |
1564 | ==== Guides |
1565 | ||
1566 | To run all the `bt2` Python package tests: | |
1567 | ||
1568 | * Run: | |
1569 | + | |
1570 | ---- | |
31d2049b | 1571 | $ ./tests/utils/run-in-py-env.sh ./tests/bindings/python/bt2/test-python-bt2.sh |
800400d8 PP |
1572 | ---- |
1573 | + | |
1574 | or: | |
1575 | + | |
1576 | ---- | |
31d2049b | 1577 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
800400d8 PP |
1578 | ./tests/bindings/python/bt2/ -p '*.py' |
1579 | ---- | |
1580 | ||
1581 | To run **all the tests** in a test module (for example, | |
1582 | `test_value.py`): | |
1583 | ||
1584 | * Run: | |
1585 | + | |
1586 | ---- | |
31d2049b | 1587 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
800400d8 PP |
1588 | ./tests/bindings/python/bt2 -t test_value |
1589 | ---- | |
1590 | ||
1591 | To run a **specific test case** (for example, `RealValueTestCase` within | |
1592 | `test_value.py`): | |
1593 | ||
1594 | * Run: | |
1595 | + | |
1596 | ---- | |
31d2049b | 1597 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
800400d8 PP |
1598 | ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase |
1599 | ---- | |
1600 | ||
1601 | To run a **specific test** (for example, | |
1602 | `RealValueTestCase.test_assign_pos_int` within `test_value.py`): | |
1603 | ||
1604 | * Run: | |
1605 | + | |
c637d729 | 1606 | ---- |
31d2049b | 1607 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
800400d8 | 1608 | ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int |
c637d729 | 1609 | ---- |
fb7ff115 PP |
1610 | |
1611 | == {cpp} usage | |
1612 | ||
a1ac73cf PP |
1613 | A significant part and, in general, all the new code of {bt2} is written |
1614 | in {cpp}. | |
fb7ff115 PP |
1615 | |
1616 | This section shows what's important to know about {cpp} to contribute | |
1617 | to {bt2}. | |
1618 | ||
1619 | [IMPORTANT] | |
1620 | ==== | |
1621 | {bt2} only has {cpp} sources for _internal_ code. | |
1622 | ||
1623 | In other words, libbabeltrace2 _must_ expose a pure C99 API to preserve | |
1624 | ABI compatibility over time. | |
1625 | ==== | |
1626 | ||
a1ac73cf | 1627 | === Standard |
fb7ff115 PP |
1628 | |
1629 | The {bt2} project is configured to use the {cpp11} standard. | |
1630 | ||
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. | |
1633 | ||
a1ac73cf PP |
1634 | === Common {cpp} code |
1635 | ||
1636 | Many parts of the project need common {cpp} code. You'll find all of it | |
1637 | under `src/cpp-common`. | |
1638 | ||
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. | |
1643 | ||
1644 | ==== `bt2`: libbabeltrace2 {cpp} bindings | |
1645 | ||
1646 | `src/cpp-common/bt2` contains our internal {cpp} bindings of | |
1647 | the libbabeltrace2 C{nbsp}API, under the `bt2` namespace. | |
1648 | ||
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. | |
1652 | ||
1653 | Pass and return borrowed objects _by value_ (copy). | |
1654 | ||
1655 | In general, the following holds: | |
1656 | ||
1657 | [options="header,autowidth",cols="2"] | |
1658 | |=== | |
1659 | |{cpp} expression | |
1660 | |Equivalent C{nbsp}expression | |
1661 | ||
1662 | |`bt2::Xyz` | |
1663 | |`bt_xyz *` | |
1664 | ||
1665 | |`const bt2::Xyz` | |
1666 | |`bt_xyz * const` | |
1667 | ||
1668 | |`bt2::ConstXyz` | |
1669 | |`const bt_xyz *` | |
1670 | ||
1671 | |`const bt2::ConstXyz` | |
1672 | |`const bt_xyz * const` | |
1673 | |=== | |
1674 | ||
1675 | ==== `bt2c`: general common {cpp} code | |
1676 | ||
1677 | Similar to the role of `src/common` for C code. | |
1678 | ||
1679 | In general, everything in here is under the `bt2c` namespace. | |
1680 | ||
1681 | Notable files are: | |
1682 | ||
1683 | `align.hpp`:: | |
1684 | The `bt2c::align()` function template: a wrapper of | |
1685 | `src/common/align.h`. | |
1686 | ||
1687 | `c-string-view.hpp`:: | |
1688 | The `bt2c::CStringView` class: a view on a constant null-terminated | |
1689 | C{nbsp}string. | |
1690 | + | |
1691 | We have this because `bt2s::string_view` doesn't imply null termination, | |
1692 | only a beginning and a length. | |
1693 | + | |
1694 | A `bt2c::CStringView` instance is convertible to `const char *` and may | |
1695 | be empty (the underlying pointer is null). | |
1696 | ||
1697 | `call.hpp`:: | |
1698 | The `bt2c::call()` function template: a partial implementation of | |
1699 | https://en.cppreference.com/w/cpp/utility/functional[INVOKE]. | |
1700 | + | |
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 | |
1704 | parentheses: | |
1705 | + | |
1706 | [source,cpp] | |
1707 | ---- | |
1708 | const auto res = bt2c::call([&] { | |
1709 | /* Complex initialization */ | |
1710 | }); | |
1711 | ---- | |
1712 | ||
1713 | `endian.hpp`:: | |
1714 | Typed wrappers of `src/compat/endian.h`. | |
1715 | ||
1716 | `exc.hpp`:: | |
1717 | Common exception classes. | |
1718 | ||
1719 | `fmt.hpp`:: | |
1720 | Common https://fmt.dev/[{fmt}] formatters. | |
1721 | ||
1722 | `logging.hpp`:: | |
1723 | The `bt2c::Logger` class and helper `BT_CPPLOG*()` macros for any | |
1724 | {cpp} logging. | |
1725 | + | |
1726 | When possible, prefer using this over the C{nbsp}logging API. | |
1727 | + | |
1728 | One important benefit is that this API uses {fmt} to format the logging | |
1729 | message instead of `vsnprintf()`. | |
1730 | ||
1731 | `prio-heap.hpp`:: | |
1732 | The `bt2c::PrioHeap` class template: an efficient heap data | |
1733 | structure. | |
1734 | ||
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. | |
1739 | ||
1740 | `safe-ops.hpp`:: | |
1741 | The `bt2c::safe*()` function templates: arithmetic operations which | |
1742 | assert that there's no possible overflow. | |
1743 | ||
1744 | `std-int.hpp`:: | |
1745 | The `bt2c::StdIntT` type alias template: becomes one of the | |
1746 | `std::*int*_t` types depending on its parameters. | |
1747 | + | |
1748 | For example, `bt2c::StdIntT<32, true>` is `std::int32_t`. | |
1749 | ||
1750 | `type-traits.hpp`:: | |
1751 | Common type traits. | |
1752 | ||
1753 | `uuid.hpp`:: | |
1754 | The following classes: | |
1755 | ||
1756 | `bt2c::Uuid`::: | |
1757 | Container of a 16-byte | |
1758 | https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID]. | |
1759 | + | |
1760 | Provides the static `generate()` method as well as conversion to | |
1761 | `bt2c::UuidView`. | |
1762 | ||
1763 | `bt2c::UuidView`::: | |
1764 | View on a UUID (not a container). | |
1765 | + | |
1766 | Provides byte access, comparison, as well as string conversion methods. | |
1767 | + | |
1768 | Also provides conversion to `bt2c::Uuid`. | |
1769 | ||
1770 | `vector.hpp`:: | |
1771 | The `bt2c::vectorFastRemove()` function template: remove an element | |
1772 | from an `std::vector` instance quickly when the order isn't | |
1773 | important. | |
1774 | ||
1775 | ==== `bt2s`: drop-in replacements of {cpp}14 to {cpp}20 STL features | |
1776 | ||
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: | |
1779 | ||
1780 | `make_unique.hpp`:: | |
1781 | `bt2s::make_unique()`, a drop-in replacement of `std::make_unique()` | |
1782 | ({cpp}14). | |
1783 | ||
1784 | `optional.hpp`:: | |
1785 | Drop-in replacement of the `std::optional` API ({cpp}17). | |
1786 | ||
1787 | `span.hpp`:: | |
1788 | Drop-in replacement of the `std::span` API ({cpp}20). | |
1789 | ||
1790 | `string-view.hpp`:: | |
1791 | Drop-in replacement of the `std::string_view` API ({cpp}17). | |
1792 | ||
1793 | ==== `vendor`: copies of {cpp} dependencies | |
1794 | ||
1795 | This directory contains copies of the source code of {cpp} dependencies | |
1796 | to avoid packaging issues. | |
1797 | ||
1798 | They are: | |
1799 | ||
1800 | `fmt`:: | |
1801 | https://fmt.dev/[{fmt}]. | |
1802 | ||
1803 | `nlohmann`:: | |
1804 | https://json.nlohmann.me/[JSON for Modern C++]. | |
1805 | ||
1806 | `optional-lite`:: | |
1807 | https://github.com/martinmoene/optional-lite[optional lite]. | |
1808 | + | |
1809 | IMPORTANT: Use the symbols of `src/cpp-common/bt2s/optional.hpp`, under | |
1810 | the `bt2s` namespace, instead of using this directly. | |
1811 | ||
1812 | `span-lite`:: | |
1813 | https://github.com/martinmoene/span-lite[span lite]. | |
1814 | + | |
1815 | IMPORTANT: Use the symbols of `src/cpp-common/bt2s/span.hpp`, under the | |
1816 | `bt2s` namespace, instead of using this directly. | |
1817 | ||
a19a1879 MJ |
1818 | `string-view-lite`:: |
1819 | https://github.com/martinmoene/string-view-lite[string_view lite]. | |
a1ac73cf PP |
1820 | + |
1821 | IMPORTANT: Use the symbols of `src/cpp-common/bt2s/string-view.hpp`, | |
1822 | under the `bt2s` namespace, instead of using this directly. | |
1823 | ||
fb7ff115 PP |
1824 | === Automake/Libtool requirements |
1825 | ||
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 | |
1828 | usual. | |
1829 | ||
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. | |
1833 | ||
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 | |
1839 | one of: | |
1840 | ||
1841 | * Have at least one direct {cpp} source file in the | |
1842 | `+*_my_target_SOURCES+` list. | |
1843 | ||
1844 | * Add: | |
1845 | + | |
1846 | ---- | |
1847 | nodist_EXTRA_my_target_SOURCES = dummy.cpp | |
1848 | ---- | |
1849 | + | |
1850 | See | |
1851 | https://www.gnu.org/software/automake/manual/automake.html#Libtool-Convenience-Libraries[Libtool | |
1852 | Convenience Libraries] to learn more. | |
1853 | ||
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 | |
1856 | `list.cpp`. | |
1857 | ||
1858 | === Coding style | |
1859 | ||
1860 | ==== Whitespaces, indentation, and line breaks | |
1861 | ||
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. | |
1866 | ||
1867 | You _must_ format modified and new {cpp} files with clang-format before | |
1868 | you create a contribution patch. | |
1869 | ||
1d323849 | 1870 | You need clang-format{nbsp}15 to use the project's `.clang-format` file. |
fb7ff115 PP |
1871 | |
1872 | To automatically format all the project's {cpp} files, run: | |
1873 | ||
1874 | ---- | |
ac4d5cf0 | 1875 | $ ./tools/format-cpp.sh |
b61d5465 PP |
1876 | ---- |
1877 | ||
a1ac73cf | 1878 | To only format the {cpp} files of a given directory: |
3e674024 PP |
1879 | |
1880 | ---- | |
ac4d5cf0 | 1881 | $ ./tools/format-cpp.sh ./src/cli |
3e674024 PP |
1882 | ---- |
1883 | ||
b61d5465 PP |
1884 | Use the `FORMATTER` environment variable to override the default |
1885 | formatter (`clang-format{nbsp}-i`): | |
1886 | ||
1887 | ---- | |
ac4d5cf0 | 1888 | $ FORMATTER='my-clang-format-15 -i' ./tools/format-cpp.sh |
fb7ff115 PP |
1889 | ---- |
1890 | ||
1891 | ==== Naming | |
1892 | ||
1893 | * Use camel case with a lowercase first letter for: | |
1894 | ** Variable names: `size`, `objSize`. | |
1895 | ** Function/method names: `size()`, `formatAndPrint()`. | |
1896 | ||
1897 | * Use camel case with an uppercase first letter for: | |
1898 | ** Types: `Pistachio`, `NutManager`. | |
1899 | ** Template parameters: `PlanetT`, `TotalSize`. | |
1900 | ||
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`. | |
1904 | ||
1905 | * Use only lowercase letters and digits for namespaces: `mylib`, `bt2`. | |
1906 | ||
a1ac73cf PP |
1907 | * Use the `T` suffix for type template parameters and the `V` suffix for |
1908 | non-type template parameters: | |
fb7ff115 PP |
1909 | + |
1910 | [source,cpp] | |
1911 | ---- | |
a1ac73cf | 1912 | template <typename NameT, typename ItemT, unsigned int SizeV = 0> |
fb7ff115 PP |
1913 | ---- |
1914 | ||
a1ac73cf | 1915 | * Name a template parameter pack `ArgTs`. |
fb7ff115 PP |
1916 | + |
1917 | [source,cpp] | |
1918 | ---- | |
a1ac73cf | 1919 | template <typename NameT, typename... ArgTs> |
fb7ff115 PP |
1920 | ---- |
1921 | ||
1922 | * Use an underscore prefix for private and protected methods and member | |
1923 | type names: `_tryConnect()`, `_NodeType`. | |
1924 | ||
1925 | * Use the prefix `_m` for private and protected member variable names: | |
1926 | `_mLogger`, `_mSize`, `_mFieldClass`. | |
a1ac73cf PP |
1927 | + |
1928 | This is to avoid name clashes with private/protected getters/setters. | |
fb7ff115 | 1929 | |
a1ac73cf | 1930 | * Name setters and getters like the property name, without the `set` and |
fb7ff115 PP |
1931 | `get` prefixes. |
1932 | ||
1933 | * Use the `is` or `has` prefix, if possible, to name the functions which | |
1934 | return `bool`. | |
a1ac73cf PP |
1935 | + |
1936 | However, try to keep the name readable. For example, prefer | |
1937 | `colorIsBlue()` over `isColorBlue()`. | |
fb7ff115 PP |
1938 | |
1939 | === Coding convention | |
1940 | ||
1941 | In general, the project's contributors make an effort to follow, | |
1942 | for {cpp11} code: | |
1943 | ||
1944 | * The | |
1945 | https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md[{cpp} Core Guidelines]. | |
1946 | ||
1947 | * Scott Meyers's | |
1948 | "`https://www.oreilly.com/library/view/effective-modern-c/9781491908419/[Effective Modern {cpp}]`". | |
1949 | ||
1950 | Here are a few important reminders: | |
1951 | ||
1952 | * Namespace your code. | |
1953 | ||
1954 | * Create one header/source file pair per class when possible. | |
1955 | + | |
1956 | For a class named `MyClass`, name the corresponding files `my-class.hpp` | |
1957 | and `my-class.cpp`. | |
1958 | ||
a1ac73cf PP |
1959 | * Use the `inline` keyword, not `static inline`, for header-only |
1960 | functions that are not templates. | |
1961 | ||
1962 | * When defining a class, use this order: | |
1963 | + | |
1964 | -- | |
1965 | . Friends (without any preceding access specifier). | |
1966 | ||
1967 | . Public types and type aliases. | |
1968 | + | |
1969 | Private/protected types may be here too if they can't be lower. | |
1970 | ||
1971 | . Constructors, whatever their access. | |
1972 | ||
1973 | . Destructor (always public). | |
1974 | ||
1975 | . Copy-assignment and move-assignment operators. | |
1976 | ||
1977 | . Public methods. | |
1978 | ||
1979 | . Protected types and type aliases. | |
1980 | ||
1981 | . Protected methods. | |
fb7ff115 | 1982 | |
a1ac73cf PP |
1983 | . Private types and type aliases. |
1984 | ||
1985 | . Private methods. | |
1986 | ||
1987 | . Protected data members. | |
1988 | ||
1989 | . Private data members. | |
1990 | -- | |
1991 | ||
1992 | * Declare variables as close to where they're used as possible. | |
1993 | ||
1994 | * In general, try to avoid variables if it doesn't lead to more lines. | |
1995 | + | |
1996 | For example, given: | |
1997 | + | |
1998 | [source,cpp] | |
1999 | ---- | |
2000 | const auto size = getSize(myObj, 23); | |
2001 | auto& obj = this->_objForSize(size); | |
2002 | ||
2003 | abc::sendObj(obj, SendOpts::WAIT); | |
2004 | ---- | |
2005 | + | |
2006 | Prefer this: | |
2007 | + | |
2008 | [source,cpp] | |
2009 | ---- | |
2010 | abc::sendObj(this->_objForSize(getSize(myObj, 23)), SendOpts::WAIT); | |
2011 | ---- | |
2012 | ||
2013 | * If you really need variables, then scope them to avoid "`leaking`" | |
2014 | them: | |
2015 | + | |
2016 | [source,cpp] | |
2017 | ---- | |
2018 | doSomeStuff(123, &obj); | |
2019 | ||
2020 | { | |
2021 | const auto status = tryChange(obj); | |
2022 | ||
2023 | BT_CPPLOGD("New status: {}.", status); | |
2024 | BT_ASSERT(status == Status::CONTINUE); | |
2025 | } | |
2026 | ||
2027 | doMoreStuff(&obj); | |
2028 | ---- | |
2029 | + | |
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` | |
2033 | variable: | |
2034 | + | |
2035 | [source,cpp] | |
2036 | ---- | |
2037 | const auto size = bt2c::call([this] { | |
2038 | auto& sender = this->_curSender(); | |
2039 | ||
2040 | if (sender.strategy() == Strategy::ACK) { | |
2041 | return sender.strategySize(); | |
2042 | } else if (sender.strategy() == Strategy::NACK) { | |
2043 | return 0; | |
2044 | } | |
2045 | ||
2046 | return _mDefSize; | |
2047 | }); | |
2048 | ---- | |
2049 | ||
2050 | * Always use `bt2c::call()` to call an immediately invoked function | |
2051 | expression (see the previous point). | |
2052 | ||
2053 | * If possible, initialize object members without a default value with | |
2054 | the initializer list of a constructor, not in the constructor body. | |
2055 | + | |
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): | |
2059 | + | |
2060 | [source,cpp] | |
2061 | ---- | |
2062 | MyObj::MyObj(const std::size_t size) : | |
2063 | _mSize {size}, | |
2064 | _mOtherObj {bt2c::call([size] { | |
2065 | /* Complex initialization here */ | |
2066 | })} | |
2067 | { | |
2068 | } | |
2069 | ---- | |
fb7ff115 PP |
2070 | |
2071 | * Use `auto` when possible. | |
a1ac73cf PP |
2072 | + |
2073 | Use `auto&` instead of `const auto&` when you know that the type is | |
2074 | `const` anyway. | |
2075 | + | |
2076 | Don't use `auto *`. | |
fb7ff115 | 2077 | |
a1ac73cf PP |
2078 | * Use `const` as much as possible, even for pointers |
2079 | (`+const char * const+`) and numeric values (`const unsigned int`) | |
fb7ff115 PP |
2080 | which never need to change. |
2081 | ||
a1ac73cf PP |
2082 | * Prefer the `pass:[MyObj myObj {...}]` initialization form over |
2083 | `pass:[auto myObj = MyObj {...}]`. | |
2084 | ||
fb7ff115 | 2085 | * Implement simple setters, getters, and one-liners in header files and |
a1ac73cf PP |
2086 | everything else that's not a template in source files, including |
2087 | constructors. | |
fb7ff115 PP |
2088 | |
2089 | * Make methods `const noexcept` or `const` as much as possible. | |
2090 | ||
2091 | * Make constructors `explicit` unless you really need an implicit | |
a1ac73cf PP |
2092 | constructor (which is rare), including default constructors: |
2093 | + | |
2094 | [source,cpp] | |
2095 | ---- | |
2096 | explicit Meow(); | |
2097 | ---- | |
fb7ff115 PP |
2098 | |
2099 | * Use `std::unique_ptr` to manage memory when possible. | |
2100 | + | |
2101 | However, use references (`+*my_unique_ptr+`) and raw pointers | |
2102 | (`+my_unique_ptr.get()+`) when not transferring ownership. | |
2103 | ||
2104 | * Use `nullptr`, not `NULL` nor 0. | |
2105 | ||
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. | |
2109 | ||
2110 | * For a function parameter or a return value of which the type needs to | |
2111 | be a reference or pointer, use: | |
2112 | + | |
2113 | If the value is mandatory::: | |
2114 | A reference. | |
2115 | If the value is optional::: | |
2116 | A raw pointer. | |
2117 | ||
2118 | * Don't use `+std::move()+` when you already have an rvalue, which | |
2119 | means: | |
2120 | ** Don't write `+return std::move(...);+` as this can interfere with | |
2121 | RVO. | |
2122 | ** Don't use `+std::move()+` with a function call | |
2123 | (`+std::move(func())+`). | |
2124 | ||
2125 | * For each possible move/copy constructor or assignment operator, do one | |
2126 | of: | |
2127 | ** Write a custom one. | |
2128 | ** Mark it as defaulted (`default`) | |
2129 | ** Mark it as deleted (`delete`). | |
2130 | ||
2131 | * Use scoped enumerations (`+enum class+`). | |
2132 | ||
2133 | * Mark classes known to be final with the `final` keyword. | |
2134 | ||
2135 | * Use type aliases (`using`), not type definitions (`typedef`). | |
2136 | ||
a1ac73cf PP |
2137 | * In a `.cpp` file, use anonymous namespaces for local symbols instead |
2138 | of `static` or `inline`. | |
2139 | ||
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. | |
fb7ff115 PP |
2142 | |
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). | |
2147 | ||
2148 | * Return a structure with named members instead of a generic container | |
2149 | such as `std::pair` or `std::tuple`. | |
2150 | ||
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. | |
2154 | ||
2155 | * Define overloaded operators only if their meaning is obvious, | |
2156 | unsurprising, and consistent with the corresponding built-in | |
2157 | operators. | |
2158 | + | |
2159 | For example, use `+|+` as a bitwise- or logical-or, not as a shell-style | |
2160 | pipe. | |
2161 | ||
2162 | * Use RAII wrappers when managing system resources or interacting with | |
2163 | C{nbsp}libraries. | |
2164 | + | |
2165 | In other words, don't rely on ``goto``s and error labels to clean up as | |
2166 | you would do in{nbsp}C. | |
2167 | + | |
2168 | Use the RAII, Luke. | |
2169 | ||
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. | |
2173 | ||
2174 | * Accept a by-value parameter and move it (when it's moveable) when you | |
2175 | intend to copy it anyway. | |
2176 | + | |
2177 | You can do this with most STL containers. | |
2178 | + | |
2179 | Example: | |
2180 | + | |
2181 | [source,cpp] | |
2182 | ---- | |
2183 | void Obj::doSomething(std::string str) | |
2184 | { | |
2185 | _mName = std::move(str); | |
a1ac73cf | 2186 | /* ... */ |
fb7ff115 PP |
2187 | } |
2188 | ---- | |
2189 | ||
2190 | .`baby.hpp` | |
2191 | ==== | |
2192 | This example shows a {cpp} header which follows the {bt2} {cpp} coding | |
2193 | convention. | |
2194 | ||
2195 | [source,cpp] | |
2196 | ---- | |
2197 | /* | |
a1ac73cf | 2198 | * SPDX-FileCopyrightText: 2020 Harry Burnett <hburnett@reese.choco> |
fb7ff115 | 2199 | * SPDX-License-Identifier: MIT |
fb7ff115 PP |
2200 | */ |
2201 | ||
2202 | #ifndef BABELTRACE_BABY_HPP | |
2203 | #define BABELTRACE_BABY_HPP | |
2204 | ||
2205 | #include <string> | |
2206 | #include <unordered_set> | |
2207 | #include <utility> | |
2208 | ||
2209 | namespace life { | |
2210 | ||
2211 | class Toy; | |
2212 | ||
2213 | /* | |
2214 | * A baby is a little human. | |
2215 | */ | |
2216 | class Baby : public Human | |
2217 | { | |
a1ac73cf PP |
2218 | friend class Parent; |
2219 | ||
fb7ff115 PP |
2220 | public: |
2221 | using Toys = std::unordered_set<Toy>; | |
2222 | ||
2223 | enum class Gender | |
2224 | { | |
2225 | MALE, | |
2226 | FEMALE, | |
a1ac73cf | 2227 | OTHER, |
fb7ff115 PP |
2228 | }; |
2229 | ||
a1ac73cf | 2230 | explicit Baby() = default; |
fb7ff115 PP |
2231 | explicit Baby(const Toys& toys); |
2232 | Baby(const Baby&) = delete; | |
2233 | Baby(Baby&&) = delete; | |
fb7ff115 PP |
2234 | |
2235 | protected: | |
a1ac73cf | 2236 | explicit Baby(Gender initialGender = Gender::OTHER); |
fb7ff115 PP |
2237 | |
2238 | public: | |
a1ac73cf PP |
2239 | ~Baby(); |
2240 | Baby& operator=(const Baby&) = delete; | |
2241 | Baby& operator=(Baby&&) = delete; | |
2242 | ||
fb7ff115 PP |
2243 | /* |
2244 | * Eats `weight` grams of food. | |
2245 | */ | |
2246 | void eat(unsigned long weight); | |
2247 | ||
2248 | /* | |
2249 | * Sleeps for `duration` seconds. | |
2250 | */ | |
2251 | void sleep(double duration); | |
2252 | ||
2253 | /* | |
2254 | * Sets this baby's name to `name`. | |
2255 | */ | |
2256 | void name(std::string name) | |
2257 | { | |
2258 | _mName = std::move(name); | |
2259 | } | |
2260 | ||
2261 | /* | |
2262 | * This baby's name. | |
2263 | */ | |
2264 | const std::string& name() const noexcept | |
2265 | { | |
2266 | return _mName; | |
2267 | } | |
2268 | ||
2269 | protected: | |
2270 | void _addTeeth(unsigned long index); | |
2271 | void _grow(double size) override; | |
2272 | ||
2273 | private: | |
2274 | std::string _mName {"Paul"}; | |
2275 | Toys _mToys; | |
2276 | }; | |
2277 | ||
a1ac73cf | 2278 | } /* namespace life */ |
fb7ff115 | 2279 | |
a1ac73cf | 2280 | #endif /* BABELTRACE_BABY_HPP */ |
fb7ff115 PP |
2281 | ---- |
2282 | ==== | |
7554731e SM |
2283 | |
2284 | == Python Usage | |
2285 | ||
2286 | === Formatting | |
2287 | ||
2288 | All Python code must be formatted using the version of | |
2289 | https://github.com/psf/black[Black] specified in `dev-requirements.txt`. | |
5995b304 SM |
2290 | |
2291 | All Python imports must be sorted using the version of | |
2292 | https://pycqa.github.io/isort/[isort] indicated in `dev-requirements.txt`. |