| 1 | // Render with Asciidoctor |
| 2 | |
| 3 | = Babeltrace{nbsp}2 contributor's guide |
| 4 | Jérémie Galarneau, Philippe Proulx |
| 5 | 22 February 2024 |
| 6 | :toc: left |
| 7 | :toclevels: 3 |
| 8 | :icons: font |
| 9 | :nofooter: |
| 10 | :bt2: Babeltrace{nbsp}2 |
| 11 | :c-cpp: C/{cpp} |
| 12 | :cpp11: {cpp}11 |
| 13 | :fmt: pass:[{fmt}] |
| 14 | |
| 15 | This is a partial contributor's guide for the |
| 16 | https://babeltrace.org[{bt2}] project. If you have any |
| 17 | questions that are not answered by this guide, please post them on |
| 18 | https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's |
| 19 | mailing list]. |
| 20 | |
| 21 | == {bt2} library |
| 22 | |
| 23 | === Object reference counting and lifetime |
| 24 | |
| 25 | This section covers the rationale behind the design of {bt2}'s |
| 26 | object lifetime management. This applies to the {bt2} library, as |
| 27 | well as to the CTF writer library (although the public reference |
| 28 | counting functions are not named the same way). |
| 29 | |
| 30 | Starting from Babeltrace{nbsp}2.0, all publicly exposed objects inherit |
| 31 | a common base: `bt_object`. This base provides a number of facilities to |
| 32 | all objects, chief amongst which are lifetime management functions. |
| 33 | |
| 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. |
| 38 | |
| 39 | As far as lifetime management in concerned, {bt2} makes a clear |
| 40 | distinction between regular objects, which have a single parent, and |
| 41 | root objects, which don't. |
| 42 | |
| 43 | ==== The problem |
| 44 | |
| 45 | Let us consider a problematic case to illustrate the need for this |
| 46 | distinction. |
| 47 | |
| 48 | A user of the {bt2} library creates a trace class, which _has_ a |
| 49 | stream class (the class of a stream) and that stream class, in turn, |
| 50 | _has_ an event class (the class of an event). |
| 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 |
| 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. |
| 63 | |
| 64 | Conversely, the user could also hold a reference to an event class and |
| 65 | retrieve its parent stream class. The trace class, in turn, can then be |
| 66 | retrieved from the stream class. |
| 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 | |
| 78 | ==== The solution |
| 79 | |
| 80 | The scheme employed in {bt2} to break this cycle consists in the |
| 81 | "children" holding _reverse component references_ to their parents. That |
| 82 | is, in the context of the trace IR, that event classes hold a reference |
| 83 | to their parent stream class and stream classes hold a reference to |
| 84 | their parent trace class. |
| 85 | |
| 86 | On the other hand, parents hold _claiming aggregation references_ to |
| 87 | their children. A claiming aggregation reference means that the object |
| 88 | being referenced should not be deleted as long as the reference still |
| 89 | exists. In this respect, it can be said that parents truly hold the |
| 90 | ownership of their children, since they control their lifetime. |
| 91 | Conversely, the reference counting mechanism is leveraged by children to |
| 92 | notify parents that no other child indirectly exposes the parent. |
| 93 | |
| 94 | When a parented object's reference count reaches zero, it invokes |
| 95 | `+bt_*_put_ref()+` on its parent and does _not_ free itself. However, |
| 96 | from that point, the object depends on its parent to signal the moment |
| 97 | when it can be safely reclaimed. |
| 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 | |
| 119 | ==== Caveats |
| 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 | |
| 128 | ==== Example |
| 129 | |
| 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**. |
| 135 | |
| 136 | image::doc/contributing-images/bt-ref01.png[] |
| 137 | |
| 138 | In this second step, we can see that **User{nbsp}A** has acquired a |
| 139 | reference on **SC2** through the trace class, **TC1**. |
| 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 | |
| 145 | Hence, at this point, the trace class's ownership is shared by |
| 146 | **User{nbsp}A** and **SC2**. |
| 147 | |
| 148 | image::doc/contributing-images/bt-ref02.png[] |
| 149 | |
| 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. |
| 154 | |
| 155 | Note that SC2's reference count was incremented to 2. The trace class's |
| 156 | reference count remains unchanged. |
| 157 | |
| 158 | image::doc/contributing-images/bt-ref03.png[] |
| 159 | |
| 160 | **User{nbsp}A** decides to drop its reference on **SC2**. **SC2**'s |
| 161 | reference count returns back to 1, everything else remaining unchanged. |
| 162 | |
| 163 | image::doc/contributing-images/bt-ref04.png[] |
| 164 | |
| 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. |
| 169 | |
| 170 | image::doc/contributing-images/bt-ref05.png[] |
| 171 | |
| 172 | If another object, **User{nbsp}B**, enters the picture and acquires a |
| 173 | reference on the **SC1** stream class, we see that **SC1**'s reference |
| 174 | count transitioned from 0 to 1, triggering the acquisition of a |
| 175 | reference on **TC1**. |
| 176 | |
| 177 | image::doc/contributing-images/bt-ref06.png[] |
| 178 | |
| 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**. |
| 183 | |
| 184 | image::doc/contributing-images/bt-ref07.png[] |
| 185 | |
| 186 | At some point, **User{nbsp}A** releases its reference on **EC3**. Since |
| 187 | **EC3**'s reference count transitions to zero, it releases its reference |
| 188 | on **SC2**. **SC2**'s reference count, in turn, reaches zero and it |
| 189 | releases its reference to **TC1**. |
| 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 | |
| 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**. |
| 198 | |
| 199 | image::doc/contributing-images/bt-ref09.png[] |
| 200 | |
| 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. |
| 204 | |
| 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. |
| 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 |
| 226 | by the trace class. |
| 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 | |
| 235 | == Logging |
| 236 | |
| 237 | Logging is a great instrument for a developer to be able to collect |
| 238 | information about a running software. |
| 239 | |
| 240 | {bt2} is a complex software with many layers. When a {bt2} |
| 241 | graph fails to run, what caused the failure? It could be caused by any |
| 242 | component, any message iterator, and any deeply nested validation of a |
| 243 | CTF IR object (within the `ctf` plugin), for example. With the |
| 244 | appropriate logging statements manually placed in the source code, we |
| 245 | can find the cause of a bug faster. |
| 246 | |
| 247 | While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to |
| 248 | _FATAL_ logging statements, you should liberally instrument your |
| 249 | {bt2} module with _TRACE_ logging statements to help future you |
| 250 | and other developers understand what's happening at run time. |
| 251 | |
| 252 | === Logging API |
| 253 | |
| 254 | The {bt2} logging API is internal: it is not exposed to the users |
| 255 | of the library; only to their developers. The only thing that a library |
| 256 | user can control is the current log level of the library itself with |
| 257 | `bt_logging_set_global_level()` and the initial library's log level with |
| 258 | the `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable. |
| 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 |
| 262 | {cpp}. The zf_log source files were modified to have the `BT_` and |
| 263 | `bt_` prefixes, and other small changes, like color support and using |
| 264 | the project's `BT_DEBUG_MODE` definition instead of the standard |
| 265 | `NDEBUG`. |
| 266 | |
| 267 | The logging functions are implemented in the logging convenience |
| 268 | library (`src/logging` directory). |
| 269 | |
| 270 | [[logging-headers]] |
| 271 | ==== Headers |
| 272 | |
| 273 | The logging API headers are: |
| 274 | |
| 275 | `<babeltrace2/logging.h>`:: |
| 276 | Public header which a library user can use to set and get |
| 277 | libbabeltrace2's current log level. |
| 278 | |
| 279 | `"logging/log.h"`:: |
| 280 | Internal, generic logging API which you can use in any {bt2} |
| 281 | module. This is the translation of `zf_log.h`. |
| 282 | + |
| 283 | This header offers the <<gen-logging-statements,generic logging |
| 284 | statement macros>>. |
| 285 | |
| 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>>. |
| 295 | |
| 296 | `"logging/comp-logging.h"`:: |
| 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>>. |
| 301 | |
| 302 | [[log-levels]] |
| 303 | ==== Log levels |
| 304 | |
| 305 | The internal logging API offers the following log levels, in ascending |
| 306 | order of severity: |
| 307 | |
| 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 | |
| 315 | |_TRACE_ |
| 316 | |`T` |
| 317 | |`BT_LOG_TRACE` |
| 318 | |`BT_LOGGING_LEVEL_TRACE` |
| 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 | |
| 330 | |_WARNING_ |
| 331 | |`W` |
| 332 | |`BT_LOG_WARNING` |
| 333 | |`BT_LOGGING_LEVEL_WARNING` |
| 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. |
| 353 | |
| 354 | See <<choose-a-log-level,how to decide which one to use>> below. |
| 355 | |
| 356 | There are two important log level expressions: |
| 357 | |
| 358 | [[build-time-log-level]]Build-time, minimal log level:: |
| 359 | The minimal log level, or build-time log level, is set at build time |
| 360 | and determines the minimal log level of the logging statements which |
| 361 | can be executed. This applies to all the modules (CLI, library, |
| 362 | plugins, bindings, etc.). |
| 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 |
| 366 | than this level _can_ be executed, depending on the |
| 367 | <<run-time-log-level,run-time log level>>. |
| 368 | + |
| 369 | You can set this level at configuration time with the |
| 370 | `BABELTRACE_MINIMAL_LOG_LEVEL` environment variable, for example: |
| 371 | + |
| 372 | -- |
| 373 | ---- |
| 374 | $ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure |
| 375 | ---- |
| 376 | -- |
| 377 | + |
| 378 | The default build-time log level is `DEBUG`. For optimal performance, |
| 379 | set it to `INFO`, which effectively disables all fast path logging in |
| 380 | all the {bt2} modules. You can't set it to `WARNING`, `ERROR`, |
| 381 | `FATAL`, or `NONE` because the impact on performance is minuscule |
| 382 | starting from the _INFO_ log level anyway and we want any {bt2} |
| 383 | build to always be able to print _INFO_-level logs. |
| 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:: |
| 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>>. |
| 395 | + |
| 396 | `zf_log` has a concept of a global run-time log level which uses the |
| 397 | `_bt_log_global_output_lvl` symbol. In practice, we never use this |
| 398 | symbol, and always make sure that `BT_LOG_OUTPUT_LEVEL` is defined to a |
| 399 | module-wise expression before including `"logging/log.h"`. |
| 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. |
| 404 | + |
| 405 | In libbabeltrace2, the user can set the current run-time log level with |
| 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 |
| 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 | ---- |
| 443 | char *bt_common_get_home_plugin_path(int log_level); |
| 444 | ---- |
| 445 | + |
| 446 | Typically, when a logging-enabled module calls such a function, it |
| 447 | passes its own log level expression directly (`BT_LOG_OUTPUT_LEVEL`): |
| 448 | + |
| 449 | [source,c] |
| 450 | ---- |
| 451 | path = bt_common_get_home_plugin_path(BT_LOG_OUTPUT_LEVEL); |
| 452 | ---- |
| 453 | + |
| 454 | Otherwise, just pass `BT_LOG_NONE`: |
| 455 | + |
| 456 | ---- |
| 457 | path = bt_common_get_home_plugin_path(BT_LOG_NONE); |
| 458 | ---- |
| 459 | |
| 460 | [[gen-logging-statements]] |
| 461 | ==== Generic logging statement macros |
| 462 | |
| 463 | The {bt2} logging statement macros work just like `printf()` |
| 464 | (except the `+BT_LOG*_STR()+` ones) and contain their <<log-levels,log |
| 465 | level>> (short name) in their name. |
| 466 | |
| 467 | Each of the following macros evaluate the |
| 468 | <<build-time-log-level,build-time log level>> definition and |
| 469 | <<run-time-log-level,run-time log level>> expression (as defined by |
| 470 | `BT_LOG_OUTPUT_LEVEL`) to log conditionally. |
| 471 | |
| 472 | See <<logging-instrument-c-file-gen>> and |
| 473 | <<logging-instrument-h-file-gen>> to learn how to be able to use the |
| 474 | following macros. |
| 475 | |
| 476 | `+BT_LOGT("format string", ...)+`:: |
| 477 | Generic trace logging statement. |
| 478 | |
| 479 | `+BT_LOGD("format string", ...)+`:: |
| 480 | Generic debug logging statement. |
| 481 | |
| 482 | `+BT_LOGI("format string", ...)+`:: |
| 483 | Generic info logging statement. |
| 484 | |
| 485 | `+BT_LOGW("format string", ...)+`:: |
| 486 | Generic warning logging statement. |
| 487 | |
| 488 | `+BT_LOGE("format string", ...)+`:: |
| 489 | Generic error logging statement. |
| 490 | |
| 491 | `+BT_LOGF("format string", ...)+`:: |
| 492 | Generic fatal logging statement. |
| 493 | |
| 494 | `+BT_LOGT_STR("preformatted string")+`:: |
| 495 | Generic preformatted string trace logging statement. |
| 496 | |
| 497 | `+BT_LOGD_STR("preformatted string")+`:: |
| 498 | Generic preformatted string debug logging statement. |
| 499 | |
| 500 | `+BT_LOGI_STR("preformatted string")+`:: |
| 501 | Generic preformatted string info logging statement. |
| 502 | |
| 503 | `+BT_LOGW_STR("preformatted string")+`:: |
| 504 | Generic preformatted string warning logging statement. |
| 505 | |
| 506 | `+BT_LOGE_STR("preformatted string")+`:: |
| 507 | Generic preformatted string error logging statement. |
| 508 | |
| 509 | `+BT_LOGF_STR("preformatted string")+`:: |
| 510 | Generic preformatted string fatal logging statement. |
| 511 | |
| 512 | `+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`:: |
| 513 | Generic memory trace logging statement. |
| 514 | |
| 515 | `+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`:: |
| 516 | Generic memory debug logging statement. |
| 517 | |
| 518 | `+BT_LOGI_MEM(data_ptr, data_size, "format string", ...)+`:: |
| 519 | Generic memory info logging statement. |
| 520 | |
| 521 | `+BT_LOGW_MEM(data_ptr, data_size, "format string", ...)+`:: |
| 522 | Generic memory warning logging statement. |
| 523 | |
| 524 | `+BT_LOGE_MEM(data_ptr, data_size, "format string", ...)+`:: |
| 525 | Generic memory error logging statement. |
| 526 | |
| 527 | `+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`:: |
| 528 | Generic memory fatal logging statement. |
| 529 | |
| 530 | `+BT_LOGT_ERRNO("initial message", "format string", ...)+`:: |
| 531 | Generic `errno` string trace logging statement. |
| 532 | |
| 533 | `+BT_LOGD_ERRNO("initial message", "format string", ...)+`:: |
| 534 | Generic `errno` string debug logging statement. |
| 535 | |
| 536 | `+BT_LOGI_ERRNO("initial message", "format string", ...)+`:: |
| 537 | Generic `errno` string info logging statement. |
| 538 | |
| 539 | `+BT_LOGW_ERRNO("initial message", "format string", ...)+`:: |
| 540 | Generic `errno` string warning logging statement. |
| 541 | |
| 542 | `+BT_LOGE_ERRNO("initial message", "format string", ...)+`:: |
| 543 | Generic `errno` string error logging statement. |
| 544 | |
| 545 | `+BT_LOGF_ERRNO("initial message", "format string", ...)+`:: |
| 546 | Generic `errno` string fatal logging statement. |
| 547 | |
| 548 | [[lib-logging-statements]] |
| 549 | ==== Library-specific logging statement macros |
| 550 | |
| 551 | The {bt2} library contains an internal logging API based on the |
| 552 | generic logging framework. You can use it to log known {bt2} |
| 553 | objects without having to manually log each member. |
| 554 | |
| 555 | See <<logging-instrument-c-file-lib>> |
| 556 | and <<logging-instrument-h-file-lib>> to |
| 557 | learn how to be able to use the following macros. |
| 558 | |
| 559 | The library logging statement macros are named `+BT_LIB_LOG*()+` instead |
| 560 | of `+BT_LOG*()+`: |
| 561 | |
| 562 | `+BT_LIB_LOGT("format string", ...)+`:: |
| 563 | Library trace logging statement. |
| 564 | |
| 565 | `+BT_LIB_LOGD("format string", ...)+`:: |
| 566 | Library debug logging statement. |
| 567 | |
| 568 | `+BT_LIB_LOGI("format string", ...)+`:: |
| 569 | Library info logging statement. |
| 570 | |
| 571 | `+BT_LIB_LOGW("format string", ...)+`:: |
| 572 | Library warning logging statement. |
| 573 | |
| 574 | `+BT_LIB_LOGE("format string", ...)+`:: |
| 575 | Library error logging statement. |
| 576 | |
| 577 | `+BT_LIB_LOGF("format string", ...)+`:: |
| 578 | Library fatal logging statement. |
| 579 | |
| 580 | `+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`:: |
| 581 | Library warning logging statement, and unconditional error cause |
| 582 | appending. |
| 583 | |
| 584 | `+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`:: |
| 585 | Library error logging statement, and unconditional error cause |
| 586 | appending. |
| 587 | |
| 588 | 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 | |
| 599 | The {bt2} library custom conversion specifier is accepted. Its |
| 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 |
| 624 | |`+const struct bt_field_class *+` |
| 625 | |
| 626 | |`f` |
| 627 | |Trace IR field |
| 628 | |`+const struct bt_field *+` |
| 629 | |
| 630 | |`P` |
| 631 | |Trace IR field path |
| 632 | |`+const struct bt_field_path *+` |
| 633 | |
| 634 | |`E` |
| 635 | |Trace IR event class |
| 636 | |`+const struct bt_event_class *+` |
| 637 | |
| 638 | |`e` |
| 639 | |Trace IR event |
| 640 | |`+const struct bt_event *+` |
| 641 | |
| 642 | |`S` |
| 643 | |Trace IR stream class. |
| 644 | |`+const struct bt_stream_class *+` |
| 645 | |
| 646 | |`s` |
| 647 | |Trace IR stream |
| 648 | |`+const struct bt_stream *+` |
| 649 | |
| 650 | |`a` |
| 651 | |Trace IR packet |
| 652 | |`+const struct bt_packet *+` |
| 653 | |
| 654 | |`T` |
| 655 | |Trace IR trace class |
| 656 | |`+const struct bt_trace_class *+` |
| 657 | |
| 658 | |`t` |
| 659 | |Trace IR trace |
| 660 | |`+const struct bt_trace *+` |
| 661 | |
| 662 | |`K` |
| 663 | |Trace IR clock class |
| 664 | |`+const struct bt_clock_class *+` |
| 665 | |
| 666 | |`k` |
| 667 | |Trace IR clock snapshot |
| 668 | |`+const struct bt_clock_snapshot *+` |
| 669 | |
| 670 | |`v` |
| 671 | |Value object |
| 672 | |`+const struct bt_value *+` |
| 673 | |
| 674 | |`R` |
| 675 | |Integer range set |
| 676 | |`const struct bt_integer_range_set *` |
| 677 | |
| 678 | |`n` |
| 679 | |Message |
| 680 | |`+const struct bt_message *+` |
| 681 | |
| 682 | |`I` |
| 683 | |Message iterator class |
| 684 | |`struct bt_message_iterator_class *` |
| 685 | |
| 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 |
| 696 | |`+const struct bt_component *+` |
| 697 | |
| 698 | |`p` |
| 699 | |Port |
| 700 | |`+const struct bt_port *+` |
| 701 | |
| 702 | |`x` |
| 703 | |Connection |
| 704 | |`+const struct bt_connection *+` |
| 705 | |
| 706 | |`g` |
| 707 | |Graph |
| 708 | |`+const struct bt_graph *+` |
| 709 | |
| 710 | |`z` |
| 711 | |Interrupter |
| 712 | |`+struct bt_interrupter *+` |
| 713 | |
| 714 | |`l` |
| 715 | |Plugin |
| 716 | |`+const struct bt_plugin *+` |
| 717 | |
| 718 | |`r` |
| 719 | |Error cause |
| 720 | |`+const struct bt_error_cause *+` |
| 721 | |
| 722 | |`o` |
| 723 | |Object pool |
| 724 | |`+const struct bt_object_pool *+` |
| 725 | |
| 726 | |`O` |
| 727 | |Object |
| 728 | |`+const struct bt_object *+` |
| 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 | |
| 755 | It is safe to pass `NULL` as any {bt2} object parameter: the macros |
| 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 | |
| 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 | |
| 768 | See <<logging-instrument-c-file-compcls>> and |
| 769 | <<logging-instrument-h-file-compcls>> to learn how to be able to use the |
| 770 | following macros. |
| 771 | |
| 772 | The component logging statement macros are named `+BT_COMP_LOG*()+` |
| 773 | instead of `+BT_LOG*()+`: |
| 774 | |
| 775 | `+BT_COMP_LOGT("format string", ...)+`:: |
| 776 | Component trace logging statement. |
| 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 | |
| 793 | `+BT_COMP_LOGT_STR("preformatted string")+`:: |
| 794 | Component preformatted string trace logging statement. |
| 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 | |
| 811 | `+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`:: |
| 812 | Component `errno` string trace logging statement. |
| 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 | |
| 829 | `+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`:: |
| 830 | Component memory trace logging statement. |
| 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. |
| 846 | |
| 847 | ==== Conditional logging |
| 848 | |
| 849 | `+BT_LOG_IF(cond, statement)+`:: |
| 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 | |
| 870 | This tests if the _DEBUG_ level was enabled at build time. This means |
| 871 | that the current, <<run-time-log-level,run-time log level>> _could_ be |
| 872 | _DEBUG_, but it could also be higher. The rule of thumb is to use only |
| 873 | logging statements at the same level in a `BT_LOG_ENABLED_*` conditional |
| 874 | block. |
| 875 | |
| 876 | The available definitions for build-time conditions are: |
| 877 | |
| 878 | * `BT_LOG_ENABLED_TRACE` |
| 879 | * `BT_LOG_ENABLED_DEBUG` |
| 880 | * `BT_LOG_ENABLED_INFO` |
| 881 | * `BT_LOG_ENABLED_WARNING` |
| 882 | * `BT_LOG_ENABLED_ERROR` |
| 883 | * `BT_LOG_ENABLED_FATAL` |
| 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 |
| 895 | (implies that it's also enabled at build time). This check could have a |
| 896 | noticeable impact on performance. |
| 897 | |
| 898 | The available definitions for run-time conditions are: |
| 899 | |
| 900 | * `BT_LOG_ON_TRACE` |
| 901 | * `BT_LOG_ON_DEBUG` |
| 902 | * `BT_LOG_ON_INFO` |
| 903 | * `BT_LOG_ON_WARNING` |
| 904 | * `BT_LOG_ON_ERROR` |
| 905 | * `BT_LOG_ON_FATAL` |
| 906 | |
| 907 | Those macros check the module-specific log level symbol (defined by |
| 908 | `BT_LOG_OUTPUT_LEVEL`). |
| 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 | |
| 937 | === Guides |
| 938 | |
| 939 | [[logging-instrument-c-file-gen]] |
| 940 | ==== Instrument a {c-cpp} source file (generic) |
| 941 | |
| 942 | To instrument a {c-cpp} source file (`.c`/`.cpp`): |
| 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: |
| 946 | + |
| 947 | -- |
| 948 | [source,c] |
| 949 | ---- |
| 950 | #define BT_LOG_TAG "SUBSYS/MY-MODULE/MY-FILE" |
| 951 | ---- |
| 952 | -- |
| 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 | ---- |
| 966 | + |
| 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 | ---- |
| 978 | |
| 979 | . Include `"logging/log.h"`: |
| 980 | + |
| 981 | [source,c] |
| 982 | ---- |
| 983 | #include "logging/log.h" |
| 984 | ---- |
| 985 | |
| 986 | . In the file, instrument your code with the |
| 987 | <<gen-logging-statements,generic logging statement macros>>. |
| 988 | |
| 989 | [[logging-instrument-h-file-gen]] |
| 990 | ==== Instrument a {c-cpp} header file (generic) |
| 991 | |
| 992 | To instrument a {c-cpp} header file (`.h`/`.hpp`), if you have |
| 993 | `static inline` functions in it: |
| 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: |
| 1002 | + |
| 1003 | [source,c] |
| 1004 | ---- |
| 1005 | static inline |
| 1006 | int some_function(int x) |
| 1007 | { |
| 1008 | /* ... */ |
| 1009 | |
| 1010 | #ifdef BT_LOGT |
| 1011 | BT_LOGT(...); |
| 1012 | #endif |
| 1013 | |
| 1014 | /* ... */ |
| 1015 | |
| 1016 | #ifdef BT_LOGW_STR |
| 1017 | BT_LOGW_STR(...); |
| 1018 | #endif |
| 1019 | |
| 1020 | /* ... */ |
| 1021 | } |
| 1022 | ---- |
| 1023 | + |
| 1024 | The {c-cpp} source files which include this header file determine if |
| 1025 | logging is enabled or not for them, and if so, what is their |
| 1026 | <<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time |
| 1027 | log level>> expression. |
| 1028 | |
| 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 | |
| 1042 | [[logging-instrument-c-file-lib]] |
| 1043 | ==== Instrument a library {c-cpp} source file |
| 1044 | |
| 1045 | To instrument a library {c-cpp} source file (`.c`/`.cpp`): |
| 1046 | |
| 1047 | . At the top of the file, before the first `#include` line (if any), |
| 1048 | define your file's <<choose-a-logging-tag,logging tag>> name (this |
| 1049 | tag must start with `LIB/`): |
| 1050 | + |
| 1051 | -- |
| 1052 | [source,c] |
| 1053 | ---- |
| 1054 | #define BT_LOG_TAG "LIB/THE-FILE" |
| 1055 | ---- |
| 1056 | -- |
| 1057 | |
| 1058 | . Include `"lib/logging.h"`: |
| 1059 | + |
| 1060 | [source,c] |
| 1061 | ---- |
| 1062 | #include "lib/logging.h" |
| 1063 | ---- |
| 1064 | |
| 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>>. |
| 1068 | |
| 1069 | [[logging-instrument-h-file-lib]] |
| 1070 | ==== Instrument a library {c-cpp} header file |
| 1071 | |
| 1072 | To instrument a library {c-cpp} header file (`.h`/`.hpp`), if you have |
| 1073 | `static inline` functions in it: |
| 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>>. |
| 1090 | |
| 1091 | [[logging-instrument-c-file-compcls]] |
| 1092 | ==== Instrument a component class {c-cpp} source file |
| 1093 | |
| 1094 | To instrument a component class {c-cpp} source file (`.c`/`.cpp`): |
| 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): |
| 1099 | + |
| 1100 | -- |
| 1101 | [source,c] |
| 1102 | ---- |
| 1103 | #define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC" |
| 1104 | ---- |
| 1105 | -- |
| 1106 | |
| 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 | ---- |
| 1119 | |
| 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 | |
| 1133 | . Include `"logging/comp-logging.h"`: |
| 1134 | + |
| 1135 | [source,c] |
| 1136 | ---- |
| 1137 | #include "logging/comp-logging.h" |
| 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; |
| 1148 | /* ... */ |
| 1149 | }; |
| 1150 | |
| 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); |
| 1162 | |
| 1163 | /* ... */ |
| 1164 | } |
| 1165 | ---- |
| 1166 | |
| 1167 | . In the file, instrument your code with the |
| 1168 | <<comp-logging-statements,component logging statement macros>>. |
| 1169 | |
| 1170 | [[logging-instrument-h-file-compcls]] |
| 1171 | ==== Instrument a component class {c-cpp} header file |
| 1172 | |
| 1173 | To instrument a component class {c-cpp} header file (`.h`/`.hpp`), if |
| 1174 | you have `static inline` functions in it: |
| 1175 | |
| 1176 | . Do not include `"logging/comp-logging.h"`! |
| 1177 | |
| 1178 | . Require that component logging be enabled: |
| 1179 | + |
| 1180 | [source,c] |
| 1181 | ---- |
| 1182 | /* Protection: this file uses BT_COMP_LOG*() macros directly */ |
| 1183 | #ifndef BT_COMP_LOG_SUPPORTED |
| 1184 | # error Please include "logging/comp-logging.h" before including this file. |
| 1185 | #endif |
| 1186 | ---- |
| 1187 | |
| 1188 | . In the file, instrument your code with the |
| 1189 | <<comp-logging-statements,component logging statement macros>>. |
| 1190 | |
| 1191 | [[choose-a-logging-tag]] |
| 1192 | ==== Choose a logging tag |
| 1193 | |
| 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. |
| 1197 | |
| 1198 | In general, a logging tag name _must_ be only uppercase letters, digits, |
| 1199 | and the `-`, `.`, and `/` characters. |
| 1200 | |
| 1201 | Use `/` to show the subsystem to source file hierarchy. |
| 1202 | |
| 1203 | For the {bt2} library, start with `LIB/`. |
| 1204 | |
| 1205 | For the CTF writer library, start with `CTF-WRITER/`. |
| 1206 | |
| 1207 | For component classes, use: |
| 1208 | |
| 1209 | [verse] |
| 1210 | `PLUGIN/__CCTYPE__.__PNAME__.__CCNAME__[/__FILE__]` |
| 1211 | |
| 1212 | With: |
| 1213 | |
| 1214 | `__CCTYPE__`:: |
| 1215 | Component class's type (`SRC`, `FLT`, or `SINK`). |
| 1216 | |
| 1217 | `__PNAME__`:: |
| 1218 | Plugin's name. |
| 1219 | |
| 1220 | `__CCNAME__`:: |
| 1221 | Component class's name. |
| 1222 | |
| 1223 | `__FILE__`:: |
| 1224 | Additional information to specify the source file name or module. |
| 1225 | |
| 1226 | For plugins (files common to many component classes), use: |
| 1227 | |
| 1228 | [verse] |
| 1229 | `PLUGIN/__PNAME__[/__FILE__]` |
| 1230 | |
| 1231 | With: |
| 1232 | |
| 1233 | `__PNAME__`:: |
| 1234 | Plugin's name. |
| 1235 | |
| 1236 | `__FILE__`:: |
| 1237 | Additional information to specify the source file name or module. |
| 1238 | |
| 1239 | [[choose-a-log-level]] |
| 1240 | ==== Choose a log level |
| 1241 | |
| 1242 | Choosing the appropriate level for your logging statement is very |
| 1243 | important. |
| 1244 | |
| 1245 | [options="header,autowidth",cols="1,2,3a,4"] |
| 1246 | |=== |
| 1247 | |Log level |Description |Use cases |Expected impact on performance |
| 1248 | |
| 1249 | |_FATAL_ |
| 1250 | | |
| 1251 | The program, library, or plugin cannot continue to work in this |
| 1252 | condition: it must be terminated immediately. |
| 1253 | |
| 1254 | A _FATAL_-level logging statement should always be followed by |
| 1255 | `abort()`. |
| 1256 | | |
| 1257 | * Unexpected return values from system calls. |
| 1258 | * Logic error in internal code, for example an unexpected value in a |
| 1259 | `switch` statement. |
| 1260 | * Failed assertion (within `BT_ASSERT()`). |
| 1261 | * Unsatisfied library precondition (within `BT_ASSERT_PRE()` or |
| 1262 | `BT_ASSERT_PRE_DEV()`). |
| 1263 | * Unsatisfied library postcondition (within `BT_ASSERT_POST()` or |
| 1264 | `BT_ASSERT_POST_DEV()`). |
| 1265 | |Almost none: always enabled. |
| 1266 | |
| 1267 | |_ERROR_ |
| 1268 | | |
| 1269 | An important error which is somewhat not fatal, that is, the program, |
| 1270 | library, or plugin can continue to work after this, but you judge that |
| 1271 | it should be reported to the user. |
| 1272 | |
| 1273 | Usually, the program cannot recover from such an error, but it can at |
| 1274 | least exit cleanly. |
| 1275 | | |
| 1276 | * Memory allocation errors. |
| 1277 | * Wrong component initialization parameters. |
| 1278 | * Corrupted, unrecoverable trace data. |
| 1279 | * Failed to perform an operation which should work considering the |
| 1280 | implementation and the satisfied preconditions. For example, the |
| 1281 | failure to create an empty object (no parameters): most probably |
| 1282 | failed internally because of an allocation error. |
| 1283 | * Almost any error in terminal elements: CLI and plugins. |
| 1284 | |Almost none: always enabled. |
| 1285 | |
| 1286 | |_WARNING_ |
| 1287 | | |
| 1288 | An error which still allows the execution to continue, but you judge |
| 1289 | that it should be reported to the user. |
| 1290 | |
| 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). |
| 1297 | | |
| 1298 | * Missing data within something that is expected to have it, but there's |
| 1299 | an alternative. |
| 1300 | * Invalid file, but recoverable/fixable. |
| 1301 | |Almost none: always enabled. |
| 1302 | |
| 1303 | |_INFO_ |
| 1304 | | |
| 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. |
| 1317 | * Successful connection to or disconnection from another system. |
| 1318 | * An _optional_ subsystem cannot be loaded. |
| 1319 | * An _optional_ field/datum cannot be found. |
| 1320 | | |
| 1321 | Very little: always enabled. |
| 1322 | |
| 1323 | |_DEBUG_ |
| 1324 | | |
| 1325 | Something that only {bt2} developers would be interested into, |
| 1326 | which can occur on the fast path, but not more often than once per |
| 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). |
| 1338 | * Object interruption. |
| 1339 | * Calling user methods and logging the result. |
| 1340 | * Setting object properties (except fields and values). |
| 1341 | | |
| 1342 | Noticeable, but not as much as the _TRACE_ level: could be executed |
| 1343 | in production if you're going to need a thorough log for support |
| 1344 | tickets without having to rebuild the project. |
| 1345 | |
| 1346 | |_TRACE_ |
| 1347 | | |
| 1348 | Low-level debugging context information (anything that does not fit the |
| 1349 | other log levels). More appropriate for tracing in general. |
| 1350 | | |
| 1351 | * Reference count change. |
| 1352 | * Fast path, low level state machine's state change. |
| 1353 | * Get or set an object's property. |
| 1354 | * Object comparison's intermediate results. |
| 1355 | |Huge: not executed in production. |
| 1356 | |=== |
| 1357 | |
| 1358 | [IMPORTANT] |
| 1359 | -- |
| 1360 | Make sure not to use a _WARNING_ (or higher) log level when the |
| 1361 | condition leading to the logging statement can occur under normal |
| 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 |
| 1368 | _TRACE_ level (or do not log at all). |
| 1369 | -- |
| 1370 | |
| 1371 | [[message]] |
| 1372 | ==== Write an appropriate message |
| 1373 | |
| 1374 | Follow those rules when you write a logging statement's message: |
| 1375 | |
| 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: |
| 1380 | + |
| 1381 | -- |
| 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_) |
| 1387 | -- |
| 1388 | + |
| 1389 | For warning and error messages, you can start the message with _Cannot_ |
| 1390 | or _Failed to_ followed by a verb if it's appropriate. |
| 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 | |
| 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. |
| 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 |
| 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. |
| 1412 | |
| 1413 | Example: |
| 1414 | |
| 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" |
| 1418 | |
| 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. |
| 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` |
| 1431 | |`-fp` |File stream (`+FILE *+`) |`%p` |
| 1432 | |`-id` |Object's ID |`%" PRIu64 "` |
| 1433 | |`-index` |Index |`%" PRIu64 "` |
| 1434 | |`-name` |Object's name |`\"%s\"` |
| 1435 | |=== |
| 1436 | |
| 1437 | === Output |
| 1438 | |
| 1439 | The log is printed to the standard error stream. A log line contains the |
| 1440 | time, the process and thread IDs, the <<log-levels,log level>>, the |
| 1441 | <<choose-a-logging-tag,logging tag>>, the source's function name, file |
| 1442 | name and line number, and the <<message,message>>. |
| 1443 | |
| 1444 | When {bt2} supports terminal color codes (depends on the |
| 1445 | `BABELTRACE_TERM_COLOR` environment variable's value and what the |
| 1446 | standard output and error streams are plugged into), _INFO_-level lines |
| 1447 | are blue, _WARNING_-level lines are yellow, and _ERROR_-level and |
| 1448 | _FATAL_-level lines are red. |
| 1449 | |
| 1450 | Log line example: |
| 1451 | |
| 1452 | ---- |
| 1453 | 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0 |
| 1454 | ---- |
| 1455 | |
| 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 |
| 1458 | generates: |
| 1459 | |
| 1460 | ---- |
| 1461 | $ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS' |
| 1462 | ---- |
| 1463 | |
| 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 \ |
| 1471 | LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app |
| 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 | |
| 1479 | `LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared |
| 1480 | libraries (plugins) which it loads. You need this to see the appropriate |
| 1481 | backtrace when Valgrind shows errors. |
| 1482 | |
| 1483 | == Testing |
| 1484 | |
| 1485 | [[test-env]] |
| 1486 | === Environment |
| 1487 | |
| 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 | ---- |
| 1495 | $ ./tests/plugins/sink.text.pretty/test-enum.sh |
| 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 |
| 1504 | $ ./tests/plugins/sink.text.pretty/test-enum.sh |
| 1505 | ---- |
| 1506 | |
| 1507 | ==== Python |
| 1508 | |
| 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. |
| 1512 | |
| 1513 | `run-in-py-env.sh` uses <<test-env,`utils.sh`>> which needs to know the |
| 1514 | build directory, so make sure you set the `BT_TESTS_BUILDDIR` |
| 1515 | environment variable correctly _if you build out of tree_, for example: |
| 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 |
| 1522 | `run-in-py-env.sh`, for example: |
| 1523 | |
| 1524 | ---- |
| 1525 | $ ./tests/utils/run-in-py-env.sh ipython3 |
| 1526 | ---- |
| 1527 | |
| 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 | |
| 1543 | === Python bindings |
| 1544 | |
| 1545 | The `bt2` Python package tests are located in |
| 1546 | `tests/bindings/python/bt2`. |
| 1547 | |
| 1548 | ==== Python test runner |
| 1549 | |
| 1550 | `tests/utils/python/testrunner.py` is {bt2}'s Python test runner |
| 1551 | which loads Python files containing unit tests, finds all the test |
| 1552 | cases, and runs the tests, producing a TAP report. |
| 1553 | |
| 1554 | You can see the test runner command's help with: |
| 1555 | |
| 1556 | ---- |
| 1557 | $ python3 ./tests/utils/python/testrunner.py --help |
| 1558 | ---- |
| 1559 | |
| 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. |
| 1563 | |
| 1564 | ==== Guides |
| 1565 | |
| 1566 | To run all the `bt2` Python package tests: |
| 1567 | |
| 1568 | * Run: |
| 1569 | + |
| 1570 | ---- |
| 1571 | $ ./tests/utils/run-in-py-env.sh ./tests/bindings/python/bt2/test-python-bt2.sh |
| 1572 | ---- |
| 1573 | + |
| 1574 | or: |
| 1575 | + |
| 1576 | ---- |
| 1577 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
| 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 | ---- |
| 1587 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
| 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 | ---- |
| 1597 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
| 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 | + |
| 1606 | ---- |
| 1607 | $ ./tests/utils/run-in-py-env.sh python3 ./tests/utils/python/testrunner.py \ |
| 1608 | ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int |
| 1609 | ---- |
| 1610 | |
| 1611 | == {cpp} usage |
| 1612 | |
| 1613 | A significant part and, in general, all the new code of {bt2} is written |
| 1614 | in {cpp}. |
| 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 | |
| 1627 | === Standard |
| 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 | |
| 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 | |
| 1818 | `string-view-lite`:: |
| 1819 | https://github.com/martinmoene/string-view-lite[string_view lite]. |
| 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 | |
| 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 | |
| 1870 | You need clang-format{nbsp}15 to use the project's `.clang-format` file. |
| 1871 | |
| 1872 | To automatically format all the project's {cpp} files, run: |
| 1873 | |
| 1874 | ---- |
| 1875 | $ ./tools/format-cpp.sh |
| 1876 | ---- |
| 1877 | |
| 1878 | To only format the {cpp} files of a given directory: |
| 1879 | |
| 1880 | ---- |
| 1881 | $ ./tools/format-cpp.sh ./src/cli |
| 1882 | ---- |
| 1883 | |
| 1884 | Use the `FORMATTER` environment variable to override the default |
| 1885 | formatter (`clang-format{nbsp}-i`): |
| 1886 | |
| 1887 | ---- |
| 1888 | $ FORMATTER='my-clang-format-15 -i' ./tools/format-cpp.sh |
| 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 | ** Enumerators: `Type::SignedInt`, `Scope::Function`. |
| 1901 | |
| 1902 | * Use snake case with uppercase letters for: |
| 1903 | ** Definition/macro names: `MARK_AS_UNUSED()`, `SOME_FEATURE_EXISTS`. |
| 1904 | |
| 1905 | * Use only lowercase letters and digits for namespaces: `mylib`, `bt2`. |
| 1906 | |
| 1907 | * Use the `T` suffix for type template parameters and the `V` suffix for |
| 1908 | non-type template parameters: |
| 1909 | + |
| 1910 | [source,cpp] |
| 1911 | ---- |
| 1912 | template <typename NameT, typename ItemT, unsigned int SizeV = 0> |
| 1913 | ---- |
| 1914 | |
| 1915 | * Name a template parameter pack `ArgTs`. |
| 1916 | + |
| 1917 | [source,cpp] |
| 1918 | ---- |
| 1919 | template <typename NameT, typename... ArgTs> |
| 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`. |
| 1927 | + |
| 1928 | This is to avoid name clashes with private/protected getters/setters. |
| 1929 | |
| 1930 | * Name setters and getters like the property name, without the `set` and |
| 1931 | `get` prefixes. |
| 1932 | |
| 1933 | * Use the `is` or `has` prefix, if possible, to name the functions which |
| 1934 | return `bool`. |
| 1935 | + |
| 1936 | However, try to keep the name readable. For example, prefer |
| 1937 | `colorIsBlue()` over `isColorBlue()`. |
| 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 | |
| 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. |
| 1982 | |
| 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 | ---- |
| 2070 | |
| 2071 | * Use `auto` when possible. |
| 2072 | + |
| 2073 | Use `auto&` instead of `const auto&` when you know that the type is |
| 2074 | `const` anyway. |
| 2075 | + |
| 2076 | Don't use `auto *`. |
| 2077 | |
| 2078 | * Use `const` as much as possible, even for pointers |
| 2079 | (`+const char * const+`) and numeric values (`const unsigned int`) |
| 2080 | which never need to change. |
| 2081 | |
| 2082 | * Prefer the `pass:[MyObj myObj {...}]` initialization form over |
| 2083 | `pass:[auto myObj = MyObj {...}]`. |
| 2084 | |
| 2085 | * Implement simple setters, getters, and one-liners in header files and |
| 2086 | everything else that's not a template in source files, including |
| 2087 | constructors. |
| 2088 | |
| 2089 | * Make methods `const noexcept` or `const` as much as possible. |
| 2090 | |
| 2091 | * Make constructors `explicit` unless you really need an implicit |
| 2092 | constructor (which is rare), including default constructors: |
| 2093 | + |
| 2094 | [source,cpp] |
| 2095 | ---- |
| 2096 | explicit Meow(); |
| 2097 | ---- |
| 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 | |
| 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. |
| 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); |
| 2186 | /* ... */ |
| 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 | /* |
| 2198 | * SPDX-FileCopyrightText: 2020 Harry Burnett <hburnett@reese.choco> |
| 2199 | * SPDX-License-Identifier: MIT |
| 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 | { |
| 2218 | friend class Parent; |
| 2219 | |
| 2220 | public: |
| 2221 | using Toys = std::unordered_set<Toy>; |
| 2222 | |
| 2223 | enum class Gender |
| 2224 | { |
| 2225 | Male, |
| 2226 | Female, |
| 2227 | Other, |
| 2228 | }; |
| 2229 | |
| 2230 | explicit Baby() = default; |
| 2231 | explicit Baby(const Toys& toys); |
| 2232 | Baby(const Baby&) = delete; |
| 2233 | Baby(Baby&&) = delete; |
| 2234 | |
| 2235 | protected: |
| 2236 | explicit Baby(Gender initialGender = Gender::OTHER); |
| 2237 | |
| 2238 | public: |
| 2239 | ~Baby(); |
| 2240 | Baby& operator=(const Baby&) = delete; |
| 2241 | Baby& operator=(Baby&&) = delete; |
| 2242 | |
| 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 | |
| 2278 | } /* namespace life */ |
| 2279 | |
| 2280 | #endif /* BABELTRACE_BABY_HPP */ |
| 2281 | ---- |
| 2282 | ==== |
| 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`. |
| 2290 | |
| 2291 | All Python imports must be sorted using the version of |
| 2292 | https://pycqa.github.io/isort/[isort] indicated in `dev-requirements.txt`. |