-= Babeltrace's contributor's guide
-Jérémie Galarneau, Philippe Proulx
-v0.1, 6 September 2017
-:toc:
-:toclevels: 5
+// Render with Asciidoctor
+= Babeltrace{nbsp}2 contributor's guide
+Jérémie Galarneau, Philippe Proulx
+1 December 2020
+:toc: left
+:toclevels: 3
+:icons: font
+:nofooter:
+:bt2: Babeltrace{nbsp}2
+:c-cpp: C/{cpp}
+:cpp11: {cpp}11
This is a partial contributor's guide for the
-http://diamon.org/babeltrace[Babeltrace] project. If you have any
-questions that are not answered in this guide, please post them
-on https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's mailing list].
+https://babeltrace.org[{bt2}] project. If you have any
+questions that are not answered by this guide, please post them on
+https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[Babeltrace's
+mailing list].
+== {bt2} library
-== Object reference counting and lifetime
+=== Object reference counting and lifetime
-This section covers the rationale behind the design of Babeltrace's
-object lifetime management.
+This section covers the rationale behind the design of {bt2}'s
+object lifetime management. This applies to the {bt2} library, as
+well as to the CTF writer library (although the public reference
+counting functions are not named the same way).
-Starting from Babeltrace 2.x, all publicly exposed objects inherit a
-common base: `bt_object`. This base provides a number of facilities to
+Starting from Babeltrace{nbsp}2.0, all publicly exposed objects inherit
+a common base: `bt_object`. This base provides a number of facilities to
all objects, chief amongst which are lifetime management functions.
-The reference count of all public objects is controlled by invoking the
-`bt_get()` and `bt_put()` functions which respectively increment and
-decrement an object's reference count.
+The lifetime of some public objects is managed by reference counting. In
+this case, the API offers the `+bt_*_get_ref()+` and `+bt_*_put_ref()+`
+functions which respectively increment and decrement an object's
+reference count.
-As far as lifetime management in concerned, Babeltrace makes a clear
+As far as lifetime management in concerned, {bt2} makes a clear
distinction between regular objects, which have a single parent, and
root objects, which don't.
-
-=== The problem
+==== The problem
Let us consider a problematic case to illustrate the need for this
distinction.
-A user of the CTF Writer library declares a trace, which *has* a
-stream class (the declaration of a stream) and that stream class, in
-turn, *has* an event class (the declaration of an event).
+A user of the {bt2} library creates a trace class, which _has_ a
+stream class (the class of a stream) and that stream class, in turn,
+_has_ an event class (the class of an event).
Nothing prevents this user from releasing his reference on any one of
these objects in any order. However, all objects in the
from any other.
For instance, the user could discard his reference on both the event
-class and the stream class, only keeping a reference on the trace. From
-this trace reference, stream classes can be enumerated, providing the
-user with a new reference to the stream class he discarded earlier.
-event classes can also be enumerated from stream classes, providing the
-user with references to the individual event classes.
+class and the stream class, only keeping a reference on the trace class.
+From this trace class reference, stream classes can be enumerated,
+providing the user with a new reference to the stream class he discarded
+earlier. Event classes can also be enumerated from stream classes,
+providing the user with references to the individual event classes.
Conversely, the user could also hold a reference to an event class and
-retrieve its parent stream class. The trace, in turn, can then be
+retrieve its parent stream class. The trace class, in turn, can then be
retrieved from the stream class.
This example illustrates what could be interpreted as a circular
Nonetheless, the API must offer the guarantee that holding a node to any
node of the graph keeps all other reachable nodes alive.
+==== The solution
-=== The solution
-
-The scheme employed in Babeltrace to break this cycle consists in the
-"children" holding *reverse component references* to their parents. That
+The scheme employed in {bt2} to break this cycle consists in the
+"children" holding _reverse component references_ to their parents. That
is, in the context of the trace IR, that event classes hold a reference
to their parent stream class and stream classes hold a reference to
-their parent trace.
+their parent trace class.
-On the other hand, parents hold *claiming aggregation references* to
+On the other hand, parents hold _claiming aggregation references_ to
their children. A claiming aggregation reference means that the object
being referenced should not be deleted as long as the reference still
exists. In this respect, it can be said that parents truly hold the
notify parents that no other child indirectly exposes the parent.
When a parented object's reference count reaches zero, it invokes
-`bt_put()` on its parent and does **not** free itself. However, from
-that point, the object depends on its parent to signal the moment when
-it can be safely reclaimed.
-
-The invocation of `bt_put()` by the last children holding a reference to
-its parent might trigger a cascade of `bt_put()` from child to parent.
-Eventually, a **root** object is reached. At that point, if this
-orphaned object's reference count reaches zero, the object invokes the
-destructor method defined by everyone of its children as part of their
-base `struct bt_object`. The key point here is that the cascade of
-destructor will necessarily originate from the root and propagate in
-preorder to the children. These children will propagate the destruction
-to their own children before reclaiming their own memory. This ensures
-that a node's pointer to its parent is *always* valid since the parent
-has the responsibility of tearing-down their children before cleaning
-themselves up.
-
-Assuming a reference to an object is *acquired* by calling `bt_get()`
-while its reference count is zero, the object acquires, in turn, a
-reference on its parent using `bt_get()`. At that point, the child can
-be thought of as having converted its weak reference to its parent into
-a regular reference. That is why this reference is referred to as a
-*claiming* aggregation reference.
-
-
-=== Caveats
+`+bt_*_put_ref()+` on its parent and does _not_ free itself. However,
+from that point, the object depends on its parent to signal the moment
+when it can be safely reclaimed.
+
+The invocation of `+bt_*_put_ref()+` by the last children holding a
+reference to its parent might trigger a cascade of `+bt_*_put_ref()+`
+from child to parent. Eventually, a **root** object is reached. At that
+point, if this orphaned object's reference count reaches zero, the
+object invokes the destructor method defined by everyone of its children
+as part of their base `struct bt_object`. The key point here is that the
+cascade of destructor will necessarily originate from the root and
+propagate in preorder to the children. These children will propagate the
+destruction to their own children before reclaiming their own memory.
+This ensures that a node's pointer to its parent is _always_ valid since
+the parent has the responsibility of tearing-down their children before
+cleaning themselves up.
+
+Assuming a reference to an object is _acquired_ by calling
+`+bt_*_get_ref()+` while its reference count is zero, the object
+acquires, in turn, a reference on its parent using `+bt_*_get_ref()+`.
+At that point, the child can be thought of as having converted its weak
+reference to its parent into a regular reference. That is why this
+reference is referred to as a _claiming_ aggregation reference.
+
+==== Caveats
This scheme imposes a number of strict rules defining the relation
between objects:
* Objects, beside the root, are only retrievable from their direct
parent or children.
+==== Example
-=== Example
-
-The initial situation is rather simple: **User A** is holding a
-reference to a trace, **TC1**. As per the rules previously enounced,
-stream classes **SC1** and **SC2** don't hold a reference to **TC1**
-since their own reference counts are zero. The same holds true for
-**EC1**, **EC2** and **EC3** with respect to **SC1** and **SC2**.
+The initial situation is rather simple: **User{nbsp}A** is holding a
+reference to a trace class, **TC1**. As per the rules previously
+enounced, stream classes **SC1** and **SC2** don't hold a reference to
+**TC1** since their own reference counts are zero. The same holds true
+for **EC1**, **EC2** and **EC3** with respect to **SC1** and **SC2**.
image::doc/contributing-images/bt-ref01.png[]
-In this second step, we can see that **User A** has acquired a reference
-on **SC2** through the trace, **TC1**.
+In this second step, we can see that **User{nbsp}A** has acquired a
+reference on **SC2** through the trace class, **TC1**.
The stream class's reference count transitions from zero to one,
triggering the acquisition of a strong reference on **TC1** from
**SC2**.
-Hence, at this point, the trace's ownership is shared by **User A** and
-**SC2**.
+Hence, at this point, the trace class's ownership is shared by
+**User{nbsp}A** and **SC2**.
image::doc/contributing-images/bt-ref02.png[]
-Next, **User A** acquires a reference on the **EC3** event class through
-its parent stream class, **SC2**. Again, the transition of an object's
-reference count from 0 to 1 triggers the acquisition of a reference on
-its parent.
+Next, **User{nbsp}A** acquires a reference on the **EC3** event class
+through its parent stream class, **SC2**. Again, the transition of an
+object's reference count from 0 to 1 triggers the acquisition of a
+reference on its parent.
-Note that SC2's reference count was incremented to 2. The trace's
+Note that SC2's reference count was incremented to 2. The trace class's
reference count remains unchanged.
image::doc/contributing-images/bt-ref03.png[]
-**User A** decides to drop its reference on **SC2**. **SC2**'s reference
-count returns back to 1, everything else remaining unchanged.
+**User{nbsp}A** decides to drop its reference on **SC2**. **SC2**'s
+reference count returns back to 1, everything else remaining unchanged.
image::doc/contributing-images/bt-ref04.png[]
-**User A** can then decide to drop its reference on the trace. This
-results in a reversal of the initial situation: **User A** now owns an
-event, **EC3**, which is keeping everything else alive and reachable.
+**User{nbsp}A** can then decide to drop its reference on the trace
+class. This results in a reversal of the initial situation:
+**User{nbsp}A** now owns an event, **EC3**, which is keeping everything
+else alive and reachable.
image::doc/contributing-images/bt-ref05.png[]
-If another object, **User B**, enters the picture and acquires a
+If another object, **User{nbsp}B**, enters the picture and acquires a
reference on the **SC1** stream class, we see that **SC1**'s reference
count transitioned from 0 to 1, triggering the acquisition of a
reference on **TC1**.
image::doc/contributing-images/bt-ref06.png[]
-**User B** hands off a reference to **EC1**, acquired through **SC1**,
-to another object, **User C**. The acquisition of a reference on
-**EC1**, which transitions from 0 to 1, triggers the acquisition of a
-reference on its parent, **SC1**.
+**User{nbsp}B** hands off a reference to **EC1**, acquired through
+**SC1**, to another object, **User{nbsp}C**. The acquisition of a
+reference on **EC1**, which transitions from 0 to 1, triggers the
+acquisition of a reference on its parent, **SC1**.
image::doc/contributing-images/bt-ref07.png[]
-At some point, **User A** releases its reference on **EC3**. Since
+At some point, **User{nbsp}A** releases its reference on **EC3**. Since
**EC3**'s reference count transitions to zero, it releases its reference
on **SC2**. **SC2**'s reference count, in turn, reaches zero and it
releases its reference to **TC1**.
image::doc/contributing-images/bt-ref08.png[]
-**User B** releases its reference on **SC1**. **User C** becomes the
-sole owner of the whole hierarchy through his ownership of **EC1**.
+**User{nbsp}B** releases its reference on **SC1**. **User{nbsp}C**
+becomes the sole owner of the whole hierarchy through his ownership of
+**EC1**.
image::doc/contributing-images/bt-ref09.png[]
-Finally, **User C** releases his ownership of **EC1**, triggering the
-release of the whole hierarchy. Let's walk through the reclamation of
-the whole graph.
+Finally, **User{nbsp}C** releases his ownership of **EC1**, triggering
+the release of the whole hierarchy. Let's walk through the reclamation
+of the whole graph.
-Mirroring what happened when **User A** released its last reference on
-**EC3**, the release of **EC1** by **User C** causes its reference count
-to fall to zero.
+Mirroring what happened when **User{nbsp}A** released its last reference
+on **EC3**, the release of **EC1** by **User{nbsp}C** causes its
+reference count to fall to zero.
This transition to zero causes **EC1** to release its reference on
**SC1**. **SC1**'s reference count reaching zero causes it to release
image::doc/contributing-images/bt-ref11.png[]
The stream classes having destroyed their children, are then reclaimed
-by the trace.
+by the trace class.
image::doc/contributing-images/bt-ref12.png[]
image::doc/contributing-images/bt-ref13.png[]
-== Valgrind
-
-To use Valgrind on an application (for example, the CLI or a test) which
-loads libbabeltrace2, use:
-
- $ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
- BABELTRACE_NO_DLCLOSE=1 valgrind --leak-check=full \
- --suppressions=/path/to/babeltrace/extras/valgrind/popt.supp app
-
-`G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and
-`PYTHONMALLOC=malloc` is for the Python interpreter, if it is used by
-the Python plugin provider (Valgrind will probably show a lot of errors
-which originate from Python interpreter anyway).
-
-`BABELTRACE_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
-libraries (plugins) which it loads. This is needed to see the
-appropriate backtrace when Valgrind shows errors.
-
-
== Logging
Logging is a great instrument for a developer to be able to collect
information about a running software.
-Babeltrace is a complex software with many layers. When a Babeltrace
+{bt2} is a complex software with many layers. When a {bt2}
graph fails to run, what caused the failure? It could be caused by any
-component, any notification iterator, and any deeply nested validation
-of a CTR IR object, for example. With the appropriate logging statements
-manually placed in the source code, we can find the cause of a bug
-faster.
-
-While <<log-level,care must be taken>> when placing _INFO_ to _FATAL_
-logging statements, you should liberally instrument your Babeltrace
-module with _DEBUG_ and _VERBOSE_ logging statements to help future you
-and other developers understand what's happening at run-time.
+component, any message iterator, and any deeply nested validation of a
+CTF IR object (within the `ctf` plugin), for example. With the
+appropriate logging statements manually placed in the source code, we
+can find the cause of a bug faster.
+While <<choose-a-log-level,care must be taken>> when placing _DEBUG_ to
+_FATAL_ logging statements, you should liberally instrument your
+{bt2} module with _TRACE_ logging statements to help future you
+and other developers understand what's happening at run time.
=== Logging API
-The Babeltrace logging API is internal: it is not exposed to the users
-of the library, only to their developers. The only thing that a library
+The {bt2} logging API is internal: it is not exposed to the users
+of the library; only to their developers. The only thing that a library
user can control is the current log level of the library itself with
`bt_logging_set_global_level()` and the initial library's log level with
-the `BABELTRACE_LOGGING_GLOBAL_LEVEL` environment variable.
+the `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable.
This API is based on https://github.com/wonder-mice/zf_log[zf_log], a
lightweight, yet featureful, MIT-licensed core logging library for C and
-$$C++$$. The zf_log source files were modified to have the `BT_` and
-`bt_` prefixes, and other small changes, like color support.
+{cpp}. The zf_log source files were modified to have the `BT_` and
+`bt_` prefixes, and other small changes, like color support and using
+the project's `BT_DEBUG_MODE` definition instead of the standard
+`NDEBUG`.
The logging functions are implemented in the logging convenience
-library (`logging` directory).
-
+library (`src/logging` directory).
+[[logging-headers]]
==== Headers
The logging API headers are:
-`<babeltrace/logging.h>`::
- Public header which a library user can use to control and read
+`<babeltrace2/logging.h>`::
+ Public header which a library user can use to set and get
libbabeltrace2's current log level.
-`<babeltrace/logging-internal.h>`::
- Internal, generic logging API which you can use in any Babeltrace
- subproject. This is the translation of `zf_log.h`.
-
-`<babeltrace/lib-logging-internal.h>`::
- Specific internal header to use within the library. This header
- defines `BT_LOG_OUTPUT_LEVEL` to a custom, library-wide hidden
- symbol which is the library's current log level before including
- `<babeltrace/logging-internal.h>`.
+`"logging/log.h"`::
+ Internal, generic logging API which you can use in any {bt2}
+ module. This is the translation of `zf_log.h`.
++
+This header offers the <<gen-logging-statements,generic logging
+statement macros>>.
-Do not include `<babeltrace/logging-internal.h>` or
-`<babeltrace/lib-logging-internal.h>` in a header which contains logging
-statements: this header could be included in source files which define a
-different <<choose-a-tag,tag>>, for example. See
-<<logging-instrument-header, Instrument a C header file>>.
+`"lib/logging.h"`::
+ Specific internal header to use within the library.
++
+This header defines `BT_LOG_OUTPUT_LEVEL` to a custom, library-wide
+hidden symbol which is the library's current log level before including
+`"logging/log.h"`.
++
+This header offers the <<lib-logging-statements,library-specific logging
+statement macros>>.
+`"logging/comp-logging.h"`::
+ Specific internal header to use within a component class.
++
+This header offers the <<comp-logging-statements,component-specific
+logging statement macros>>.
+[[log-levels]]
==== Log levels
-The API offers the following log levels:
+The internal logging API offers the following log levels, in ascending
+order of severity:
-* _VERBOSE_
-* _DEBUG_
-* _INFO_
-* _WARN_
-* _ERROR_
-* _FATAL_
+[options="header,autowidth",cols="4"]
+|===
+|Log level name
+|Log level short name
+|Internal API enumerator
+|Public API enumerator
-See <<log-level,how to decide which one to use>> below.
+|_TRACE_
+|`T`
+|`BT_LOG_TRACE`
+|`BT_LOGGING_LEVEL_TRACE`
-There are two important log level variables:
+|_DEBUG_
+|`D`
+|`BT_LOG_DEBUG`
+|`BT_LOGGING_LEVEL_DEBUG`
+
+|_INFO_
+|`I`
+|`BT_LOG_INFO`
+|`BT_LOGGING_LEVEL_INFO`
+
+|_WARNING_
+|`W`
+|`BT_LOG_WARNING`
+|`BT_LOGGING_LEVEL_WARNING`
+
+|_ERROR_
+|`E`
+|`BT_LOG_ERROR`
+|`BT_LOGGING_LEVEL_ERROR`
+
+|_FATAL_
+|`F`
+|`BT_LOG_FATAL`
+|`BT_LOGGING_LEVEL_FATAL`
+
+|_NONE_
+|`N`
+|`BT_LOG_NONE`
+|`BT_LOGGING_LEVEL_NONE`
+|===
+
+The short name is accepted by the log level environment variables and by
+the CLI's `--log-level` options.
+
+See <<choose-a-log-level,how to decide which one to use>> below.
+
+There are two important log level expressions:
[[build-time-log-level]]Build-time, minimal log level::
- The minimal log level, or build-time log level, is set at build
- time and determines the minimal log level which can be executed.
- This applies to all the subprojects and modules (CLI, library,
- plugins, etc.).
+ The minimal log level, or build-time log level, is set at build time
+ and determines the minimal log level of the logging statements which
+ can be executed. This applies to all the modules (CLI, library,
+ plugins, bindings, etc.).
+
All the logging statements with a level below this level are **not built
at all**. All the logging statements with a level equal to or greater
+
--
----
-$ BABELTRACE_MINIMAL_LOG_LEVEL=WARN ./configure
+$ BABELTRACE_MINIMAL_LOG_LEVEL=INFO ./configure
----
--
+
-The default build-time log level is `VERBOSE`. For optimal performance,
-set it to `NONE`, which effectively disables all logging in all the
-Babeltrace subprojects.
+The default build-time log level is `DEBUG`. For optimal performance,
+set it to `INFO`, which effectively disables all fast path logging in
+all the {bt2} modules. You can't set it to `WARNING`, `ERROR`,
+`FATAL`, or `NONE` because the impact on performance is minuscule
+starting from the _INFO_ log level anyway and we want any {bt2}
+build to always be able to print _INFO_-level logs.
+
The library's public API provides `bt_logging_get_minimal_level()` to
get the configured minimal log level.
[[run-time-log-level]]Run-time, dynamic log level::
- The dynamic log level is set at run-time and determines the current,
- active log level. All the logging statements with a level below this
- level are not executed, but they evaluate the condition. All the
- logging statements with a level equal to or greater than this level
- are executed, provided that their level is also
- <<build-time-log-level,enabled at build time>>.
+ The dynamic log level is set at run time and determines the current,
+ _active_ log level. All the logging statements with a level below
+ this level are not executed, **but they still evaluate the
+ condition**. All the logging statements with a level equal to or
+ greater than this level are executed, provided that their level is
+ also <<build-time-log-level,enabled at build time>>.
+
`zf_log` has a concept of a global run-time log level which uses the
`_bt_log_global_output_lvl` symbol. In practice, we never use this
symbol, and always make sure that `BT_LOG_OUTPUT_LEVEL` is defined to a
-module-wise or subproject-wise hidden symbol before including
-`<babeltrace/logging-internal.h>`. In the library,
-`<babeltrace/lib-logging-internal.h>` does this job: just include this
-header which defines `BT_LOG_OUTPUT_LEVEL` to the appropriate symbol
-before it includes `<babeltrace/logging-internal.h>`. In plugins, for
-example, there is one log level per component class, which makes log
-filtering easier during execution.
+module-wise expression before including `"logging/log.h"`.
++
+In the library, `"lib/logging.h"` defines its own
+`BT_LOG_OUTPUT_LEVEL` to the library's log level symbol before it
+includes `"logging/log.h"` itself.
+
In libbabeltrace2, the user can set the current run-time log level with
the `bt_logging_set_global_level()` function, for example:
--
+
The library's initial run-time log level is defined by the
-`BABELTRACE_LOGGING_GLOBAL_LEVEL` environment variable (`VERBOSE`, `DEBUG`,
-`INFO`, `WARN`, `ERROR`, `FATAL`, or `NONE`), or set to _NONE_ if this
-environment variable is undefined.
+`LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable, or set to _NONE_
+if this environment variable is undefined.
++
+Other modules have their own way of setting their run-time log level.
++
+For example, the CLI uses the `BABELTRACE_CLI_LOG_LEVEL` environment
+variable, as well as its global `--log-level` option:
++
+----
+$ babeltrace2 --log-level=I ...
+----
++
+The components use their own log level (as returned by
+`bt_component_get_logging_level()`). With the CLI, you can set a
+specific component's log level with its own, position-dependent
+`--log-level` option:
++
+----
+$ babeltrace2 /path/to/trace -c sink.ctf.fs --log-level=D
+----
++
+Code which is common to the whole project, for example `src/common`
+and `src/compat`, use function parameters to get its run-time log
+level, for example:
++
+[source,c]
+----
+BT_HIDDEN
+char *bt_common_get_home_plugin_path(int log_level);
+----
+
-Other subprojects have their own way of setting their run-time log
-level. For example, the CLI uses the `BABELTRACE_CLI_LOG_LEVEL`
-environment variable, and the `filter.utils.muxer` component class
-initializes its log level thanks to the
-`BABELTRACE_PLUGIN_UTILS_MUXER_FLT_LOG_LEVEL` environment variable
-(also _NONE_ by default).
+Typically, when a logging-enabled module calls such a function, it
+passes its own log level expression directly (`BT_LOG_OUTPUT_LEVEL`):
+
-Make sure that there is a documented way to initialize or modify the
-log level of your subproject or module, and that it's set to _NONE_
-by default.
+[source,c]
+----
+path = bt_common_get_home_plugin_path(BT_LOG_OUTPUT_LEVEL);
+----
++
+Otherwise, just pass `BT_LOG_NONE`:
++
+----
+path = bt_common_get_home_plugin_path(BT_LOG_NONE);
+----
+
+[[gen-logging-statements]]
+==== Generic logging statement macros
+
+The {bt2} logging statement macros work just like `printf()`
+(except the `+BT_LOG*_STR()+` ones) and contain their <<log-levels,log
+level>> (short name) in their name.
+
+Each of the following macros evaluate the
+<<build-time-log-level,build-time log level>> definition and
+<<run-time-log-level,run-time log level>> expression (as defined by
+`BT_LOG_OUTPUT_LEVEL`) to log conditionally.
+
+See <<logging-instrument-c-file-gen>> and
+<<logging-instrument-h-file-gen>> to learn how to be able to use the
+following macros.
+
+`+BT_LOGT("format string", ...)+`::
+ Generic trace logging statement.
+
+`+BT_LOGD("format string", ...)+`::
+ Generic debug logging statement.
+
+`+BT_LOGI("format string", ...)+`::
+ Generic info logging statement.
+
+`+BT_LOGW("format string", ...)+`::
+ Generic warning logging statement.
+
+`+BT_LOGE("format string", ...)+`::
+ Generic error logging statement.
+
+`+BT_LOGF("format string", ...)+`::
+ Generic fatal logging statement.
+
+`+BT_LOGT_STR("preformatted string")+`::
+ Generic preformatted string trace logging statement.
+
+`+BT_LOGD_STR("preformatted string")+`::
+ Generic preformatted string debug logging statement.
+
+`+BT_LOGI_STR("preformatted string")+`::
+ Generic preformatted string info logging statement.
+
+`+BT_LOGW_STR("preformatted string")+`::
+ Generic preformatted string warning logging statement.
+
+`+BT_LOGE_STR("preformatted string")+`::
+ Generic preformatted string error logging statement.
+
+`+BT_LOGF_STR("preformatted string")+`::
+ Generic preformatted string fatal logging statement.
+
+`+BT_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
+ Generic memory trace logging statement.
+
+`+BT_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
+ Generic memory debug logging statement.
+
+`+BT_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
+ Generic memory info logging statement.
+
+`+BT_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
+ Generic memory warning logging statement.
+
+`+BT_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
+ Generic memory error logging statement.
+
+`+BT_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
+ Generic memory fatal logging statement.
+
+`+BT_LOGT_ERRNO("initial message", "format string", ...)+`::
+ Generic `errno` string trace logging statement.
+
+`+BT_LOGD_ERRNO("initial message", "format string", ...)+`::
+ Generic `errno` string debug logging statement.
+
+`+BT_LOGI_ERRNO("initial message", "format string", ...)+`::
+ Generic `errno` string info logging statement.
+
+`+BT_LOGW_ERRNO("initial message", "format string", ...)+`::
+ Generic `errno` string warning logging statement.
+
+`+BT_LOGE_ERRNO("initial message", "format string", ...)+`::
+ Generic `errno` string error logging statement.
+
+`+BT_LOGF_ERRNO("initial message", "format string", ...)+`::
+ Generic `errno` string fatal logging statement.
+
+[[lib-logging-statements]]
+==== Library-specific logging statement macros
+
+The {bt2} library contains an internal logging API based on the
+generic logging framework. You can use it to log known {bt2}
+objects without having to manually log each member.
+
+See <<logging-instrument-c-file-lib>>
+and <<logging-instrument-h-file-lib>> to
+learn how to be able to use the following macros.
+
+The library logging statement macros are named `+BT_LIB_LOG*()+` instead
+of `+BT_LOG*()+`:
+
+`+BT_LIB_LOGT("format string", ...)+`::
+ Library trace logging statement.
+
+`+BT_LIB_LOGD("format string", ...)+`::
+ Library debug logging statement.
+
+`+BT_LIB_LOGI("format string", ...)+`::
+ Library info logging statement.
+
+`+BT_LIB_LOGW("format string", ...)+`::
+ Library warning logging statement.
+
+`+BT_LIB_LOGE("format string", ...)+`::
+ Library error logging statement.
+
+`+BT_LIB_LOGF("format string", ...)+`::
+ Library fatal logging statement.
+
+`+BT_LIB_LOGW_APPEND_CAUSE("format string", ...)+`::
+ Library warning logging statement, and unconditional error cause
+ appending.
+
+`+BT_LIB_LOGE_APPEND_CAUSE("format string", ...)+`::
+ Library error logging statement, and unconditional error cause
+ appending.
+
+`+BT_LIB_LOGF_APPEND_CAUSE("format string", ...)+`::
+ Library fatal logging statement, and unconditional error cause
+ appending.
+
+The macros above accept the typical `printf()` conversion specifiers
+with the following limitations:
+
+* The `+*+` width specifier is not accepted.
+* The `+*+` precision specifier is not accepted.
+* The `j` and `t` length modifiers are not accepted.
+* The `n` format specifier is not accepted.
+* The format specifiers defined in `<inttypes.h>` are not accepted,
+ except for `PRId64`, `PRIu64`, `PRIx64`, `PRIX64`, `PRIo64`, and
+ `PRIi64`.
+
+The {bt2} library custom conversion specifier is accepted. Its
+syntax is either `%!u` to format a UUID (`bt_uuid` type), or:
+
+. Introductory `%!` sequence.
+
+. **Optional**: `[` followed by a custom prefix for the printed fields
+ of this specifier, followed by `]`. The standard form is to end this
+ prefix with `-` so that, for example, with the prefix `tc-`, the
+ complete field name becomes `tc-addr`.
+
+. **Optional**: `pass:[+]` to print extended object members. This
+ depends on the provided format specifier.
+
+. Format specifier (see below).
+
+The available format specifiers are:
+
+[options="header,autowidth",cols="3"]
+|===
+|Specifier
+|Object
+|Expected C type
+
+|`F`
+|Trace IR field class
+|`+const struct bt_field_class *+`
+
+|`f`
+|Trace IR field
+|`+const struct bt_field *+`
+
+|`P`
+|Trace IR field path
+|`+const struct bt_field_path *+`
+
+|`E`
+|Trace IR event class
+|`+const struct bt_event_class *+`
+
+|`e`
+|Trace IR event
+|`+const struct bt_event *+`
+
+|`S`
+|Trace IR stream class.
+|`+const struct bt_stream_class *+`
+
+|`s`
+|Trace IR stream
+|`+const struct bt_stream *+`
+
+|`a`
+|Trace IR packet
+|`+const struct bt_packet *+`
+
+|`T`
+|Trace IR trace class
+|`+const struct bt_trace_class *+`
+
+|`t`
+|Trace IR trace
+|`+const struct bt_trace *+`
+|`K`
+|Trace IR clock class
+|`+const struct bt_clock_class *+`
-[[logging-statements]]
-==== Logging statement macros
+|`k`
+|Trace IR clock snapshot
+|`+const struct bt_clock_snapshot *+`
-The Babeltrace logging statement macros work just like `printf()` and
-contain their log level in their name:
+|`v`
+|Value object
+|`+const struct bt_value *+`
-`BT_LOGV("format string", ...)`::
- Standard verbose logging statement.
+|`R`
+|Integer range set
+|`const struct bt_integer_range_set *`
-`BT_LOGD("format string", ...)`::
- Standard debug logging statement.
+|`n`
+|Message
+|`+const struct bt_message *+`
-`BT_LOGI("format string", ...)`::
- Standard info logging statement.
+|`I`
+|Message iterator class
+|`struct bt_message_iterator_class *`
-`BT_LOGW("format string", ...)`::
- Standard warning logging statement.
+|`i`
+|Message iterator
+|`struct bt_message_iterator *`
-`BT_LOGE("format string", ...)`::
- Standard error logging statement.
+|`C`
+|Component class
+|`struct bt_component_class *`
-`BT_LOGF("format string", ...)`::
- Standard fatal logging statement.
+|`c`
+|Component
+|`+const struct bt_component *+`
-`BT_LOGV_MEM(data_ptr, data_size, "format string", ...)`::
- Memory verbose logging statement.
+|`p`
+|Port
+|`+const struct bt_port *+`
-`BT_LOGD_MEM(data_ptr, data_size, "format string", ...)`::
- Memory debug logging statement.
+|`x`
+|Connection
+|`+const struct bt_connection *+`
-`BT_LOGI_MEM(data_ptr, data_size, "format string", ...)`::
- Memory info logging statement.
+|`g`
+|Graph
+|`+const struct bt_graph *+`
-`BT_LOGW_MEM(data_ptr, data_size, "format string", ...)`::
- Memory warning logging statement.
+|`z`
+|Interrupter
+|`+struct bt_interrupter *+`
-`BT_LOGE_MEM(data_ptr, data_size, "format string", ...)`::
- Memory error logging statement.
+|`l`
+|Plugin
+|`+const struct bt_plugin *+`
-`BT_LOGF_MEM(data_ptr, data_size, "format string", ...)`::
- Memory fatal logging statement.
+|`r`
+|Error cause
+|`+const struct bt_error_cause *+`
-`BT_LOGV_ERRNO("initial message", "format string", ...)`::
- `errno` string verbose logging statement.
+|`o`
+|Object pool
+|`+const struct bt_object_pool *+`
-`BT_LOGD_ERRNO("initial message", "format string", ...)`::
- `errno` string debug logging statement.
+|`O`
+|Object
+|`+const struct bt_object *+`
+|===
+
+Conversion specifier examples:
+
+* `%!f`
+* `%![my-event-]+e`
+* `%!t`
+* `%!+F`
+
+The ``, `` string (comma and space) is printed between individual
+fields, but **not after the last one**. Therefore, you must put this
+separator in the format string between two conversion specifiers, for
+example:
+
+[source,c]
+----
+BT_LIB_LOGW("Message: count=%u, %!E, %!+K", count, event_class, clock_class);
+----
+
+Example with a custom prefix:
+
+[source,c]
+----
+BT_LIB_LOGI("Some message: %![ec-a-]e, %![ec-b-]+e", ec_a, ec_b);
+----
+
+It is safe to pass `NULL` as any {bt2} object parameter: the macros
+only print its null address.
+
+WARNING: Build-time `printf()` format checks are disabled for the
+`+BT_LIB_LOG*()+` macros because there are custom conversion specifiers,
+so make sure to test your logging statements.
+
+[[comp-logging-statements]]
+==== Component-specific logging statement macros
+
+There are available logging macros for components. They prepend a prefix
+including the component's name to the logging message.
+
+See <<logging-instrument-c-file-compcls>> and
+<<logging-instrument-h-file-compcls>> to learn how to be able to use the
+following macros.
+
+The component logging statement macros are named `+BT_COMP_LOG*()+`
+instead of `+BT_LOG*()+`:
+
+`+BT_COMP_LOGT("format string", ...)+`::
+ Component trace logging statement.
+
+`+BT_COMP_LOGD("format string", ...)+`::
+ Component debug logging statement.
+
+`+BT_COMP_LOGI("format string", ...)+`::
+ Component info logging statement.
+
+`+BT_COMP_LOGW("format string", ...)+`::
+ Component warning logging statement.
+
+`+BT_COMP_LOGE("format string", ...)+`::
+ Component error logging statement.
+
+`+BT_COMP_LOGF("format string", ...)+`::
+ Component fatal logging statement.
+
+`+BT_COMP_LOGT_STR("preformatted string")+`::
+ Component preformatted string trace logging statement.
+
+`+BT_COMP_LOGD_STR("preformatted string")+`::
+ Component preformatted string debug logging statement.
+
+`+BT_COMP_LOGI_STR("preformatted string")+`::
+ Component preformatted string info logging statement.
+
+`+BT_COMP_LOGW_STR("preformatted string")+`::
+ Component preformatted string warning logging statement.
+
+`+BT_COMP_LOGE_STR("preformatted string")+`::
+ Component preformatted string error logging statement.
+
+`+BT_COMP_LOGF_STR("preformatted string")+`::
+ Component preformatted string fatal logging statement.
-`BT_LOGI_ERRNO("initial message", "format string", ...)`::
- `errno` string info logging statement.
+`+BT_COMP_LOGT_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string trace logging statement.
-`BT_LOGW_ERRNO("initial message", "format string", ...)`::
- `errno` string warning logging statement.
+`+BT_COMP_LOGD_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string debug logging statement.
-`BT_LOGE_ERRNO("initial message", "format string", ...)`::
- `errno` string error logging statement.
+`+BT_COMP_LOGI_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string info logging statement.
-`BT_LOGF_ERRNO("initial message", "format string", ...)`::
- `errno` string fatal logging statement.
+`+BT_COMP_LOGW_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string warning logging statement.
-`BT_LOGV_STR("preformatted string")`::
- Preformatted string verbose logging statement.
+`+BT_COMP_LOGE_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string error logging statement.
-`BT_LOGD_STR("preformatted string")`::
- Preformatted string debug logging statement.
+`+BT_COMP_LOGF_ERRNO("initial message", "format string", ...)+`::
+ Component `errno` string fatal logging statement.
-`BT_LOGI_STR("preformatted string")`::
- Preformatted string info logging statement.
+`+BT_COMP_LOGT_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory trace logging statement.
-`BT_LOGW_STR("preformatted string")`::
- Preformatted string warning logging statement.
+`+BT_COMP_LOGD_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory debug logging statement.
-`BT_LOGE_STR("preformatted string")`::
- Preformatted string error logging statement.
+`+BT_COMP_LOGI_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory info logging statement.
-`BT_LOGF_STR("preformatted string")`::
- Preformatted string fatal logging statement.
+`+BT_COMP_LOGW_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory warning logging statement.
+`+BT_COMP_LOGE_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory error logging statement.
+
+`+BT_COMP_LOGF_MEM(data_ptr, data_size, "format string", ...)+`::
+ Component memory fatal logging statement.
==== Conditional logging
-`BT_LOG_IF(cond, statement)`::
+`+BT_LOG_IF(cond, statement)+`::
Execute `statement` only if `cond` is true.
+
Example:
#endif
----
-This tests if the _DEBUG_ level was enabled at build-time. This means
-that the current, <<run-time-log-level,dynamic log level>> _could_ be
+This tests if the _DEBUG_ level was enabled at build time. This means
+that the current, <<run-time-log-level,run-time log level>> _could_ be
_DEBUG_, but it could also be higher. The rule of thumb is to use only
logging statements at the same level in a `BT_LOG_ENABLED_*` conditional
block.
The available definitions for build-time conditions are:
-* `BT_LOG_ENABLED_VERBOSE`
+* `BT_LOG_ENABLED_TRACE`
* `BT_LOG_ENABLED_DEBUG`
* `BT_LOG_ENABLED_INFO`
-* `BT_LOG_ENABLED_WARN`
+* `BT_LOG_ENABLED_WARNING`
* `BT_LOG_ENABLED_ERROR`
* `BT_LOG_ENABLED_FATAL`
----
This tests if the _DEBUG_ log level is dynamically turned on
-(implies that it's also enabled at build-time). This check could have a
+(implies that it's also enabled at build time). This check could have a
noticeable impact on performance.
The available definitions for run-time conditions are:
-* `BT_LOG_ON_VERBOSE`
+* `BT_LOG_ON_TRACE`
* `BT_LOG_ON_DEBUG`
* `BT_LOG_ON_INFO`
-* `BT_LOG_ON_WARN`
+* `BT_LOG_ON_WARNING`
* `BT_LOG_ON_ERROR`
* `BT_LOG_ON_FATAL`
-Those macros check the subproject-specific or module-specific log level
-symbol (defined by `BT_LOG_OUTPUT_LEVEL`).
+Those macros check the module-specific log level symbol (defined by
+`BT_LOG_OUTPUT_LEVEL`).
Never, ever write code which would be executed only to compute the
fields of a logging statement outside a conditional logging scope,
BT_LOGD("Bla bla: number=%d", get_number_of_event_classes_with_property_x(...));
----
+=== Guides
-[[how-to]]
-=== Instrument a module
+[[logging-instrument-c-file-gen]]
+==== Instrument a {c-cpp} source file (generic)
-Follow those steps to make your module loggable:
+To instrument a {c-cpp} source file (`.c`/`.cpp`):
-. In your module's root directory, create a `logging.c` file with
- this content:
+. At the top of the file, before the first `#include` line (if any),
+ define your file's <<choose-a-logging-tag,logging tag>> name:
+
--
[source,c]
----
-/*
- * Copyright (c) 2017 EfficiOS Inc. <http://efficios.com/>
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
-#define BT_LOG_OUTPUT_LEVEL my_module_log_level
-#include <babeltrace/logging-internal.h>
-
-BT_LOG_INIT_LOG_LEVEL(my_module_log_level, "BABELTRACE_MY_MODULE_LOG_LEVEL");
+#define BT_LOG_TAG "SUBSYS/MY-MODULE/MY-FILE"
----
--
+
+. Below the line above, define the source file's log level expression,
+ `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
+ <<gen-logging-statements,logging statement>> to know the current
+ <<run-time-log-level,run-time log level>>.
++
+Examples:
++
+[source,c]
+----
+/* Global log level variable */
+#define BT_LOG_OUTPUT_LEVEL module_global_log_level
+----
++
+[source,c]
+----
+/* Local log level variable; must exist where you use BT_LOG*() */
+#define BT_LOG_OUTPUT_LEVEL log_level
+----
+
-Replace `my_module_log_level` with the name of the symbol which holds
-the log level for your module (should be unique amongst all the log level
-symbols of the project). Replace `BABELTRACE_MY_MODULE_LOG_LEVEL` with
-the name of the environment variable from which to initialize your
-module's log level at construction time. `BT_LOG_INIT_LOG_LEVEL()`
-defines both the hidden log level symbol and a constructor which reads
-the environment variable and sets the log level symbol accordingly.
+[source,c]
+----
+/* Object's log level; `obj` must exist where you use BT_LOG*() */
+#define BT_LOG_OUTPUT_LEVEL (obj->log_level)
+----
-. In your module's root directory, create a `logging.h` file with
- this content:
+. Include `"logging/log.h"`:
+
---
[source,c]
----
-#ifndef BABELTRACE_MY_MODULE_LOGGING_H
-#define BABELTRACE_MY_MODULE_LOGGING_H
+#include "logging/log.h"
+----
-/*
- * Copyright (c) 2017 EfficiOS Inc. <http://efficios.com/>
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
+. In the file, instrument your code with the
+ <<gen-logging-statements,generic logging statement macros>>.
-#define BT_LOG_OUTPUT_LEVEL my_module_log_level
-#include <babeltrace/logging-internal.h>
+[[logging-instrument-h-file-gen]]
+==== Instrument a {c-cpp} header file (generic)
-BT_LOG_LEVEL_EXTERN_SYMBOL(my_module_log_level);
+To instrument a {c-cpp} header file (`.h`/`.hpp`), if you have
+`static inline` functions in it:
-#endif /* BABELTRACE_MY_MODULE_LOGGING_H */
-----
---
+. Do not include `"logging/log.h"`!
+
+. Do one of:
+
+.. In the file, instrument your code with the
+ <<gen-logging-statements,generic logging statement macros>>, making
+ each of them conditional to the existence of the macro you're using:
+
-Replace `my_module_log_level` with the name of your module's
-log level symbol.
+[source,c]
+----
+static inline
+int some_function(int x)
+{
+ /* ... */
+
+#ifdef BT_LOGT
+ BT_LOGT(...);
+#endif
-. Include the `logging.c` and `logging.h` in the `_SOURCES` variable
- of your module's object in your module's root `Makefile.am`.
+ /* ... */
+
+#ifdef BT_LOGW_STR
+ BT_LOGW_STR(...);
+#endif
-. Add the log level initializing environment variable name to the
- `log_level_env_var_names` array in `cli/babeltrace2.c`.
+ /* ... */
+}
+----
++
+The {c-cpp} source files which include this header file determine if
+logging is enabled or not for them, and if so, what is their
+<<choose-a-logging-tag,logging tag>> and <<run-time-log-level,run-time
+log level>> expression.
+.. Require that logging be enabled:
++
+[source,c]
+----
+/* Protection: this file uses BT_LOG*() macros directly */
+#ifndef BT_LOG_SUPPORTED
+# error Please include "logging/log.h" before including this file.
+#endif
+----
++
+Then, in the file, instrument your code with the
+<<gen-logging-statements,generic logging statement macros>>.
-[[logging-instrument-source]]
-==== Instrument a C source file
+[[logging-instrument-c-file-lib]]
+==== Instrument a library {c-cpp} source file
-To instrument a C source file (`.c`):
+To instrument a library {c-cpp} source file (`.c`/`.cpp`):
. At the top of the file, before the first `#include` line (if any),
- define your file's tag name and include the local `logging.h`:
+ define your file's <<choose-a-logging-tag,logging tag>> name (this
+ tag must start with `LIB/`):
+
--
[source,c]
----
-#define BT_LOG_TAG "MY-MODULE-MY-FILE"
-#include "logging.h"
+#define BT_LOG_TAG "LIB/THE-FILE"
----
--
+
+. Include `"lib/logging.h"`:
+
-A logging tag name is a namespace for a specific source file. Its name
-is part of every log message generated by the statements of the file. A
-logging tag name _must_ be only uppercase letters, digits, and the
-hyphen (`-`) character. See <<choose-a-tag,Choose a tag>> for
-a list of standard tags.
+[source,c]
+----
+#include "lib/logging.h"
+----
-. Use the <<logging-statements,logging statement macros>> in the file's
- functions to instrument it.
+. In the file, instrument your code with the
+ <<lib-logging-statements,library logging statement macros>> or with
+ the <<gen-logging-statements,generic logging statement macros>>.
+[[logging-instrument-h-file-lib]]
+==== Instrument a library {c-cpp} header file
-[[logging-instrument-header]]
-==== Instrument a C header file
+To instrument a library {c-cpp} header file (`.h`/`.hpp`), if you have
+`static inline` functions in it:
-To instrument a C header file (`.h`), if you have `static inline`
-functions in it:
+. Do not include `"lib/logging.h"`!
-. Do not include any logging header.
-. Use the <<logging-statements,logging statement macros>> in the file's
- functions to instrument it, making each of them conditional to the
- existence of the macro you're using:
+. Require that library logging be enabled:
++
+[source,c]
+----
+/* Protection: this file uses BT_LIB_LOG*() macros directly */
+#ifndef BT_LIB_LOG_SUPPORTED
+# error Please include "lib/logging.h" before including this file.
+#endif
+----
+
+. In the file, instrument your code with the
+ <<lib-logging-statements,library logging statement macros>> or with
+ the <<gen-logging-statements,generic logging statement macros>>.
+
+[[logging-instrument-c-file-compcls]]
+==== Instrument a component class {c-cpp} source file
+
+To instrument a component class {c-cpp} source file (`.c`/`.cpp`):
+
+. At the top of the file, before the first `#include` line (if any),
+ define your file's <<choose-a-logging-tag,logging tag>> name (this tag
+ must start with `PLUGIN/` followed by the component class identifier):
+
--
[source,c]
----
-static inline
-void some_function(void)
-{
- /* ... */
+#define BT_LOG_TAG "PLUGIN/SRC.MY-PLUGIN.MY-SRC"
+----
+--
-#ifdef BT_LOGV
- BT_LOGV(...);
-#endif
+. Below the line above, define the source file's log level expression,
+ `BT_LOG_OUTPUT_LEVEL`. This expression is evaluated for each
+ <<comp-logging-statements,logging statement>> to know the current
+ <<run-time-log-level,run-time log level>>.
++
+For a component class file, it is usually a member of a local component
+private structure variable:
++
+[source,c]
+----
+#define BT_LOG_OUTPUT_LEVEL (my_comp->log_level)
+----
+
+. Below the line above, define `BT_COMP_LOG_SELF_COMP` to an expression
+ which, evaluated in the context of the
+ <<comp-logging-statements,logging statements>>, evaluates to the self
+ component address (`+bt_self_component *+`) of the component.
++
+This is usually a member of a local component private structure
+variable:
++
+[source,c]
+----
+#define BT_COMP_LOG_SELF_COMP (my_comp->self_comp)
+----
+
+. Include `"logging/comp-logging.h"`:
++
+[source,c]
+----
+#include "logging/comp-logging.h"
+----
+. In the component initialization method, make sure to set the
+ component private structure's log level member to the initial
+ component's log level:
++
+[source,c]
+----
+struct my_comp {
+ bt_logging_level log_level;
/* ... */
+};
-#ifdef BT_LOGW_STR
- BT_LOGW_STR(...);
-#endif
+BT_HIDDEN
+bt_self_component_status my_comp_init(
+ bt_self_component_source *self_comp_src,
+ bt_value *params, void *init_method_data)
+{
+ struct my_comp *my_comp = g_new0(struct my_comp, 1);
+ bt_self_component *self_comp =
+ bt_self_component_source_as_self_component(self_comp_src);
+ const bt_component *comp = bt_self_component_as_component(self_comp);
+
+ BT_ASSERT(my_comp);
+ my_comp->log_level = bt_component_get_logging_level(comp);
/* ... */
}
----
---
+
+. In the file, instrument your code with the
+ <<comp-logging-statements,component logging statement macros>>.
+
+[[logging-instrument-h-file-compcls]]
+==== Instrument a component class {c-cpp} header file
+
+To instrument a component class {c-cpp} header file (`.h`/`.hpp`), if
+you have `static inline` functions in it:
+
+. Do not include `"logging/comp-logging.h"`!
+
+. Require that component logging be enabled:
+
-The C source files which include this header file determine if logging
-is enabled or not for them (if the source file is instrumented itself),
-and the tag of the included header's logging statement is the same as
-the including C source file.
+[source,c]
+----
+/* Protection: this file uses BT_COMP_LOG*() macros directly */
+#ifndef BT_COMP_LOG_SUPPORTED
+# error Please include "logging/comp-logging.h" before including this file.
+#endif
+----
+
+. In the file, instrument your code with the
+ <<comp-logging-statements,component logging statement macros>>.
+
+[[choose-a-logging-tag]]
+==== Choose a logging tag
+
+Each logging-enabled {c-cpp} source file must define `BT_LOG_TAG` to a
+logging tag. A logging tag is a namespace to identify the logging
+messages of this specific source file.
+
+In general, a logging tag name _must_ be only uppercase letters, digits,
+and the `-`, `.`, and `/` characters.
+Use `/` to show the subsystem to source file hierarchy.
-[[choose-a-tag]]
-=== Choose a tag
+For the {bt2} library, start with `LIB/`.
-For plugins, the format of the tag name for a given source file _must_
-be:
+For the CTF writer library, start with `CTF-WRITER/`.
+
+For component classes, use:
[verse]
-PLUGIN-__PNAME__-__CCNAME__-__CCTYPE__[-__FILE__]
+`PLUGIN/__CCTYPE__.__PNAME__.__CCNAME__[/__FILE__]`
+
+With:
+
+`__CCTYPE__`::
+ Component class's type (`SRC`, `FLT`, or `SINK`).
-__PNAME__::
+`__PNAME__`::
Plugin's name.
-__CCNAME__::
+`__CCNAME__`::
Component class's name.
-__CCTYPE__::
- Component class's type (`SRC`, `FLT`, or `SINK`).
-
-__FILE__::
+`__FILE__`::
Additional information to specify the source file name or module.
-Examples:
+For plugins (files common to many component classes), use:
-* `PLUGIN-CTF-LTTNG-LIVE-SRC`
-* `PLUGIN-CTF-LTTNG-LIVE-SRC-VIEWER`
-* `PLUGIN-UTILS-MUXER-FLT`
+[verse]
+`PLUGIN/__PNAME__[/__FILE__]`
+
+With:
+
+`__PNAME__`::
+ Plugin's name.
+`__FILE__`::
+ Additional information to specify the source file name or module.
-[[log-level]]
-=== Choose a log level
+[[choose-a-log-level]]
+==== Choose a log level
Choosing the appropriate level for your logging statement is very
important.
-[options="header,autowidth",cols="default,default,asciidoc,default"]
+[options="header,autowidth",cols="1,2,3a,4"]
|===
-|Log level |Description |Use cases |Impact on performance
+|Log level |Description |Use cases |Expected impact on performance
|_FATAL_
-|The program, library, or plugin cannot continue to work in this
+|
+The program, library, or plugin cannot continue to work in this
condition: it must be terminated immediately.
A _FATAL_-level logging statement should always be followed by
* Unexpected return values from system calls.
* Logic error in internal code, for example an unexpected value in a
`switch` statement.
-|Almost none: should be executed in production.
+* Failed assertion (within `BT_ASSERT()`).
+* Unsatisfied library precondition (within `BT_ASSERT_PRE()` or
+ `BT_ASSERT_PRE_DEV()`).
+* Unsatisfied library postcondition (within `BT_ASSERT_POST()` or
+ `BT_ASSERT_POST_DEV()`).
+|Almost none: always enabled.
|_ERROR_
-|An important error which is somewhat not fatal, that is, the program,
+|
+An important error which is somewhat not fatal, that is, the program,
library, or plugin can continue to work after this, but you judge that
it should be reported to the user.
least exit cleanly.
|
* Memory allocation errors.
+* Wrong component initialization parameters.
+* Corrupted, unrecoverable trace data.
* Failed to perform an operation which should work considering the
implementation and the satisfied preconditions. For example, the
failure to create an empty object (no parameters): most probably
failed internally because of an allocation error.
* Almost any error in terminal elements: CLI and plugins.
-|Almost none: should be executed in production.
-
-|_WARN_
-|A logic error which still allows the execution to continue.
+|Almost none: always enabled.
-_WARN_-level logging statements are for any error or weird action that
-is directly or indirectly caused by the user. For example, not having
-enough memory is considered beyond the user's control, so we always
-log memory errors with an _ERROR_ level (not _FATAL_ because we usually
-don't abort in this condition).
-
-Almost all the library's errors are logged as warnings because they are
-caused by the user.
+|_WARNING_
|
-* Not honoring a public function's preconditions (NULL parameters,
- index out of bounds, etc.).
-* Adding an invalid event class to a stream class which is already
- part of a trace.
-+
-For example, the caller tries to set a property of a frozen stream
-class.
-|Almost none: can be executed in production.
+An error which still allows the execution to continue, but you judge
+that it should be reported to the user.
+
+_WARNING_-level logging statements are for any error or weird action
+that is directly or indirectly caused by the user, often through some
+bad input data. For example, not having enough memory is considered
+beyond the user's control, so we always log memory errors with an
+_ERROR_ level (not _FATAL_ because we usually don't abort in this
+condition).
+|
+* Missing data within something that is expected to have it, but there's
+ an alternative.
+* Invalid file, but recoverable/fixable.
+|Almost none: always enabled.
|_INFO_
-|Any useful information which a non-developer user would understand.
|
-* Successful loading of a plugin (with name, version, etc.).
+Any useful information which a non-developer user would possibly
+understand.
+
+Anything logged with this level must _not_ happen repetitively on the
+fast path, that is, nothing related to each message, for example. This
+level is used for sporadic and one-shot events.
+|
+* CLI or component configuration report.
+* Successful plugin, component, or message iterator initialization.
+* In the library: anything related to plugins, graphs, component
+ classes, components, message iterators, connections, and ports which
+ is not on the fast path.
* Successful connection to or disconnection from another system.
* An _optional_ subsystem cannot be loaded.
-|Very little: can be executed in production if
-_INFO_ level information is desired.
+* An _optional_ field/datum cannot be found.
+|
+Very little: always enabled.
|_DEBUG_
-|Something that only Babeltrace developers would be interested into.
|
-* High-level function entry/exit.
-* Object creation, destruction, copying, and freezing.
-* The result of some computation/validation which does not
- occur in a tight loop.
-|Noticeable, but not as much as the _VERBOSE_ level: not executed in
-production.
-
-|_VERBOSE_
-|Low-level debugging context information. More appropriate for tracing
-in general.
+Something that only {bt2} developers would be interested into,
+which can occur on the fast path, but not more often than once per
+message.
+
+The _DEBUG_ level is the default <<build-time-log-level,build-time log
+level>> as, since it's not _too_ verbose, the performance is similar to
+an _INFO_ build.
+|
+* Object construction and destruction.
+* Object recycling (except fields).
+* Object copying (except fields and values).
+* Object freezing (whatever the type, as freezing only occurs in
+ developer mode).
+* Object interruption.
+* Calling user methods and logging the result.
+* Setting object properties (except fields and values).
+|
+Noticeable, but not as much as the _TRACE_ level: could be executed
+in production if you're going to need a thorough log for support
+tickets without having to rebuild the project.
+
+|_TRACE_
+|
+Low-level debugging context information (anything that does not fit the
+other log levels). More appropriate for tracing in general.
|
* Reference count change.
-* Status of each iteration of a loop.
-* State machine's state change.
-* Data structure lookup/modification.
-* List of ELF sections found in a plugin.
+* Fast path, low level state machine's state change.
* Get or set an object's property.
* Object comparison's intermediate results.
|Huge: not executed in production.
|===
-Make sure not to use a _WARN_ (or higher) log level when the condition
-leading to the logging statement can occur under normal circumstances.
-For example, a public function to get some object or property from an
-object by name or key that fails to find the value is not a warning: the
-user could legitimately use this function to check if the name/key
-exists in the object. In this case, use the _VERBOSE_ level (or do not
-log at all). If a numeric index is out of bounds, however, this
-qualifies for a _WARN_ level: such API functions have documented
-preconditions that the index must be in bounds (the user can always
-check with a count or size function).
-
+[IMPORTANT]
+--
+Make sure not to use a _WARNING_ (or higher) log level when the
+condition leading to the logging statement can occur under normal
+circumstances.
+
+For example, a public function to get some object or
+property from an object by name or key that fails to find the value is
+not a warning scenario: the user could legitimately use this function to
+check if the name/key exists in the object. In this case, use the
+_TRACE_ level (or do not log at all).
+--
[[message]]
-=== Write an appropriate message
+==== Write an appropriate message
Follow those rules when you write a logging statement's message:
-* Use an english sentence which starts with a capital letter. Start the
- sentence with the appropriate verb tense depending on the context. For
- example:
+* Use an English sentence which starts with a capital letter.
+
+* Start the sentence with the appropriate verb tense depending on the
+ context. For example:
+
--
** Beginning of operation (present continuous): _Creating ..._,
* Do not include the log level in the message itself. For example,
do not start the message with _Error while_ or _Warning:_.
-* Do not put newlines, tabs, or other special characters in the
- message, unless you want to log a string with such characters. Note
- that multiline log messages can be hard to parse, analyze, and filter,
- however, so prefer multiple `BT_LOG*()` statements over a single
- statement with newlines.
+* Do not put newlines, tabs, or other special characters in the message,
+ unless you want to log a string with such characters. Note that
+ multiline logging messages can be hard to parse, analyze, and filter,
+ however, so prefer multiple logging statements over a single statement
+ with newlines.
* **If there are fields that your logging statement must record**,
follow the message with `:` followed by a space, then with the list of
sentence with a period.
The statement's fields _must_ be a comma-separated list of
-+__name__=__value__+ tokens. Keep +__name__+ as simple as possible
-(lowercase if possible). If +__value__+ is a non-alphanumeric string,
-put it between double quotes. Always use the `PRId64` and `PRIu64`
-specifiers when logging `int64_t` and `uint64_t` values.
+`__name__=__value__` tokens. Keep `__name__` as simple as possible; use
+kebab case if possible. If `__value__` is a non-alphanumeric string, put
+it between double quotes (`"%s"` specifier). Always use the `PRId64` and
+`PRIu64` specifiers to log an `int64_t` or an `uint64_t` value. Use `%d`
+to log a boolean value.
Example:
- "Cannot add event class to stream class: stream-class-addr=%p, "
- "stream-class-name=\"%s\", stream-class-id=%" PRId64 ", "
- "event-class-addr=%p, event-class-name=\"%s\", event-class-id=%" PRId64
+ "Cannot read stream data for indexing: path=\"%s\", name=\"%s\", "
+ "stream-id=%" PRIu64 ", stream-fd=%d, "
+ "index=%" PRIu64 ", status=%s, is-mapped=%d"
-By following a standard format for the statement fields, it is easier
-to use tools like https://www.elastic.co/products/logstash[Logstash]
-to split fields and analyze logs.
+By following a standard format for the statement fields, it is easier to
+use tools like https://www.elastic.co/products/logstash[Logstash] or
+even https://www.splunk.com/[Splunk] to split fields and analyze logs.
Prefer the following suffixes in field names:
|`-addr` |Memory address |`%p`
|`-fd` |File descriptor |`%d`
-|`-fp` |File stream (`FILE *`) |`%p`
-|`-id` |Object's ID |`%" PRId64 "` or `%" PRIu64 "`
+|`-fp` |File stream (`+FILE *+`) |`%p`
+|`-id` |Object's ID |`%" PRIu64 "`
+|`-index` |Index |`%" PRIu64 "`
|`-name` |Object's name |`\"%s\"`
|===
-
=== Output
The log is printed to the standard error stream. A log line contains the
-time, the process and thread IDs, the <<log-level,log level>>, the
-<<choose-a-tag,tag>>, the source's function name, file name and
-line number, and the <<message,message>>.
+time, the process and thread IDs, the <<log-levels,log level>>, the
+<<choose-a-logging-tag,logging tag>>, the source's function name, file
+name and line number, and the <<message,message>>.
-When Babeltrace supports terminal color codes (depends on the
+When {bt2} supports terminal color codes (depends on the
`BABELTRACE_TERM_COLOR` environment variable's value and what the
standard output and error streams are plugged into), _INFO_-level lines
-are blue, _WARN_-level lines are yellow, and _ERROR_-level and
+are blue, _WARNING_-level lines are yellow, and _ERROR_-level and
_FATAL_-level lines are red.
Log line example:
- 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
+----
+05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
+----
-You can easily filter the log with `grep` or `ag`. For example, to
-keep only the _WARN_-level log messages that the `VALUES` module
+You can easily filter the log with `grep` or `ag`. For example, to keep
+only the _DEBUG_-level logging messages that the `FIELD-CLASS` module
generates:
- $ export BABELTRACE_LOGGING_GLOBAL_LEVEL=VERBOSE
- $ ./test_ctf_writer_complete 2>&1 | ag 'W VALUES'
+----
+$ babeltrace2 --log-level=D /path/to/trace |& ag 'D FIELD-CLASS'
+----
+
+== Valgrind
+
+To use Valgrind on an application (for example, the CLI or a test) which
+loads libbabeltrace2, use:
+
+----
+$ G_SLICE=always-malloc G_DEBUG=gc-friendly PYTHONMALLOC=malloc \
+ LIBBABELTRACE2_NO_DLCLOSE=1 valgrind --leak-check=full app
+----
+
+`G_SLICE=always-malloc` and `G_DEBUG=gc-friendly` is for GLib and
+`PYTHONMALLOC=malloc` is for the Python interpreter, if it is used by
+the Python plugin provider (Valgrind will probably show a lot of errors
+which originate from the Python interpreter anyway).
+
+`LIBBABELTRACE2_NO_DLCLOSE=1` makes libbabeltrace2 not close the shared
+libraries (plugins) which it loads. You need this to see the appropriate
+backtrace when Valgrind shows errors.
+
+== Testing
+
+[[test-env]]
+=== Environment
+
+Running `make check` in the build directory (regardless of whether the build is
+in-tree or out-of-tree) automatically sets up the appropriate environment for
+tests to run in, so nothing more is needed.
+
+If building in-tree, you can run single tests from the tree directly:
+
+----
+$ ./tests/plugins/sink.text.pretty/test_enum
+----
+
+If building out-of-tree, you can get the appropriate environment by sourcing
+the `tests/utils/env.sh` file residing in the build directory against which you
+want to run tests.
+
+----
+$ source /path/to/my/build/tests/utils/env.sh
+$ ./tests/plugins/sink.text.pretty/test_enum
+----
+
+==== Python
+
+You can use the `tests/utils/run_python_bt2` script to run any command
+within an environment making the build's `bt2` Python package available.
+
+`run_python_bt2` uses <<test-env,`utils.sh`>> which needs to know the
+build directory, so make sure you set the `BT_TESTS_BUILDDIR`
+environment variable correctly _if you build out of tree_, for example:
+
+----
+$ export BT_TESTS_BUILDDIR=/path/to/build/babeltrace/tests
+----
+
+You can run any command which needs the `bt2` Python package through
+`run_python_bt2`, for example:
+
+----
+$ ./tests/utils/run_python_bt2 ipython3
+----
+
+=== Report format
+
+All test scripts output the test results following the
+https://testanything.org/[Test Anything Protocol] (TAP) format.
+
+The TAP format has two mechanisms to print additional information about
+a test:
+
+* Print a line starting with `#` to the standard output.
++
+This is usually done with the `diag()` C function or the `diag` shell
+function.
+
+* Print to the standard error.
+
+=== Python bindings
+
+The `bt2` Python package tests are located in
+`tests/bindings/python/bt2`.
+
+==== Python test runner
+
+`tests/utils/python/testrunner.py` is {bt2}'s Python test runner
+which loads Python files containing unit tests, finds all the test
+cases, and runs the tests, producing a TAP report.
+
+You can see the test runner command's help with:
+
+----
+$ python3 ./tests/utils/python/testrunner.py --help
+----
+
+By default, the test runner reports failing tests (TAP's `not{nbsp}ok`
+line), but continues to run other tests. You can use the `--failfast`
+option to make the test runner fail as soon as a test fails.
+
+==== Guides
+
+To run all the `bt2` Python package tests:
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 ./tests/bindings/python/bt2/test_python_bt2
+----
++
+or:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -p '*.py'
+----
+
+To run **all the tests** in a test module (for example,
+`test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2 -t test_value
+----
+
+To run a **specific test case** (for example, `RealValueTestCase` within
+`test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase
+----
+
+To run a **specific test** (for example,
+`RealValueTestCase.test_assign_pos_int` within `test_value.py`):
+
+* Run:
++
+----
+$ ./tests/utils/run_python_bt2 python3 ./tests/utils/python/testrunner.py \
+ ./tests/bindings/python/bt2/ -t test_value.RealValueTestCase.test_assign_pos_int
+----
+
+== {cpp} usage
+
+Some parts of {bt2} are written in {cpp}.
+
+This section shows what's important to know about {cpp} to contribute
+to {bt2}.
+
+[IMPORTANT]
+====
+{bt2} only has {cpp} sources for _internal_ code.
+
+In other words, libbabeltrace2 _must_ expose a pure C99 API to preserve
+ABI compatibility over time.
+====
+
+=== Standard and dependencies
+
+The {bt2} project is configured to use the {cpp11} standard.
+
+{cpp11} makes it possible to build {bt2} with a broad range of
+compilers, from GCC{nbsp}4.8 and Clang{nbsp}3.3.
+
+=== Automake/Libtool requirements
+
+To add a {cpp} source file to a part of the project, use the `.cpp`
+extension and add it to the list of source files in `Makefile.am` as
+usual.
+
+If a program or a shared library has a direct {cpp} source file, then
+Libtool uses the {cpp} linker to create the result, dynamically
+linking important runtime libraries such as libstdc++ and libgcc_s.
+
+Because a Libtool _convenience library_ is just an archive (`.a`), it's
+_not_ dynamically linked to runtime libraries, even if one of its direct
+sources is a {cpp} file. This means that for each program or shared
+library named `my_target` in `Makefile.am` which is linked to a
+convenience library having {cpp} sources (recursively), you _must_ do
+one of:
+
+* Have at least one direct {cpp} source file in the
+ `+*_my_target_SOURCES+` list.
+
+* Add:
++
+----
+nodist_EXTRA_my_target_SOURCES = dummy.cpp
+----
++
+See
+https://www.gnu.org/software/automake/manual/automake.html#Libtool-Convenience-Libraries[Libtool
+Convenience Libraries] to learn more.
+
+For a given program or library, you _cannot_ have a C{nbsp}file and a
+{cpp}{nbsp}file having the same name, for example `list.c` and
+`list.cpp`.
+
+=== Coding style
+
+==== Whitespaces, indentation, and line breaks
+
+All the project's {cpp} files follow the
+https://clang.llvm.org/docs/ClangFormat.html[clang-format]
+https://clang.llvm.org/docs/ClangFormatStyleOptions.html[style] of the
+`.clang-format` file for whitespaces, indentation, and line breaks.
+
+You _must_ format modified and new {cpp} files with clang-format before
+you create a contribution patch.
+
+You need clang-format{nbsp}13 to use the project's `.clang-format` file.
+
+To automatically format all the project's {cpp} files, run:
+
+----
+$ ./tools/format-cpp
+----
+
+Use the `FORMATTER` environment variable to override the default
+formatter (`clang-format{nbsp}-i`):
+
+----
+$ FORMATTER='clang-format-10 -i' ./tools/format-cpp
+----
+
+==== Naming
+
+* Use camel case with a lowercase first letter for:
+** Variable names: `size`, `objSize`.
+** Function/method names: `size()`, `formatAndPrint()`.
+
+* Use camel case with an uppercase first letter for:
+** Types: `Pistachio`, `NutManager`.
+** Template parameters: `PlanetT`, `TotalSize`.
+
+* Use snake case with uppercase letters for:
+** Definition/macro names: `MARK_AS_UNUSED()`, `SOME_FEATURE_EXISTS`.
+** Enumerators: `Type::SIGNED_INT`, `Scope::FUNCTION`.
+
+* Use only lowercase letters and digits for namespaces: `mylib`, `bt2`.
+
+* Use the suffix `T` for type template parameters:
++
+[source,cpp]
+----
+template <typename NameT, typename ItemT>
+----
+
+* Name a template parameter pack `Args`.
++
+[source,cpp]
+----
+template <typename NameT, typename... Args>
+----
+
+* Use an underscore prefix for private and protected methods and member
+ type names: `_tryConnect()`, `_NodeType`.
+
+* Use the prefix `_m` for private and protected member variable names:
+ `_mLogger`, `_mSize`, `_mFieldClass`.
+
+* Name setters and getters like the property name, without `set` and
+ `get` prefixes.
+
+* Use the `is` or `has` prefix, if possible, to name the functions which
+ return `bool`.
+
+=== Coding convention
+
+In general, the project's contributors make an effort to follow,
+for {cpp11} code:
+
+* The
+ https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md[{cpp} Core Guidelines].
+
+* Scott Meyers's
+ "`https://www.oreilly.com/library/view/effective-modern-c/9781491908419/[Effective Modern {cpp}]`".
+
+Here are a few important reminders:
+
+* Namespace your code.
+
+* Create one header/source file pair per class when possible.
++
+For a class named `MyClass`, name the corresponding files `my-class.hpp`
+and `my-class.cpp`.
+
+* When defining a class, put constructors as the first methods, whatever
+ their access (public/protected/private), then the destructor, and then
+ the rest.
+
+* Declare variables as close to where they are used as possible.
+
+* Use `auto` when possible.
+
+* Use `const` as much as possible, even for pointer
+ (`+const char* const+`) and numeric values (`const unsigned int`)
+ which never need to change.
+
+* Implement simple setters, getters, and one-liners in header files and
+ everything else that's not a template in source files.
+
+* Make methods `const noexcept` or `const` as much as possible.
+
+* Make constructors `explicit` unless you really need an implicit
+ constructor (which is rare).
+
+* Use `std::unique_ptr` to manage memory when possible.
++
+However, use references (`+*my_unique_ptr+`) and raw pointers
+(`+my_unique_ptr.get()+`) when not transferring ownership.
+
+* Use `nullptr`, not `NULL` nor 0.
+
+* Return by value (rvalue) instead of by output parameter (non-const
+ lvalue reference), even complex objects, unless you can prove that the
+ performance is improved when returning by parameter.
+
+* For a function parameter or a return value of which the type needs to
+ be a reference or pointer, use:
++
+If the value is mandatory:::
+ A reference.
+If the value is optional:::
+ A raw pointer.
+
+* Don't use `+std::move()+` when you already have an rvalue, which
+ means:
+** Don't write `+return std::move(...);+` as this can interfere with
+ RVO.
+** Don't use `+std::move()+` with a function call
+ (`+std::move(func())+`).
+
+* For each possible move/copy constructor or assignment operator, do one
+ of:
+** Write a custom one.
+** Mark it as defaulted (`default`)
+** Mark it as deleted (`delete`).
+
+* Use scoped enumerations (`+enum class+`).
+
+* Mark classes known to be final with the `final` keyword.
+
+* Use type aliases (`using`), not type definitions (`typedef`).
+
+* Use anonymous namespaces for local functions instead of `static`.
+
+* Don't pollute the global namespace:
+** Don't use `using namespace xyz` anywhere.
+** Use only namespace aliases in source files (`.cpp`), trying to
+ use them in the smallest possible scope (function, or even smaller).
+
+* Return a structure with named members instead of a generic container
+ such as `std::pair` or `std::tuple`.
+
+* When a class inherits a base class with virtual methods, use the
+ `override` keyword to mark overridden virtual methods, and do not use
+ the `virtual` keyword again.
+
+* Define overloaded operators only if their meaning is obvious,
+ unsurprising, and consistent with the corresponding built-in
+ operators.
++
+For example, use `+|+` as a bitwise- or logical-or, not as a shell-style
+pipe.
+
+* Use RAII wrappers when managing system resources or interacting with
+ C{nbsp}libraries.
++
+In other words, don't rely on ``goto``s and error labels to clean up as
+you would do in{nbsp}C.
++
+Use the RAII, Luke.
+
+* Throw an exception when there's an unexpected, exceptional condition,
+ https://isocpp.org/wiki/faq/exceptions#ctors-can-throw[including from
+ a constructor], instead of returning a status code.
+
+* Accept a by-value parameter and move it (when it's moveable) when you
+ intend to copy it anyway.
++
+You can do this with most STL containers.
++
+Example:
++
+[source,cpp]
+----
+void Obj::doSomething(std::string str)
+{
+ _mName = std::move(str);
+ // ...
+}
+----
+
+.`baby.hpp`
+====
+This example shows a {cpp} header which follows the {bt2} {cpp} coding
+convention.
+
+[source,cpp]
+----
+/*
+ * SPDX-License-Identifier: MIT
+ *
+ * Copyright 2020 Harry Burnett <hburnett@reese.choco>
+ */
+
+#ifndef BABELTRACE_BABY_HPP
+#define BABELTRACE_BABY_HPP
+
+#include <string>
+#include <unordered_set>
+#include <utility>
+
+namespace life {
+
+class Toy;
+
+/*
+ * A baby is a little human.
+ */
+class Baby : public Human
+{
+public:
+ using Toys = std::unordered_set<Toy>;
+
+ enum class Gender
+ {
+ MALE,
+ FEMALE,
+ UNKNOWN,
+ };
+
+ Baby() = default;
+ explicit Baby(const Toys& toys);
+ Baby(const Baby&) = delete;
+ Baby(Baby&&) = delete;
+ Baby& operator=(const Baby&) = delete;
+ Baby& operator=(Baby&&) = delete;
+
+protected:
+ explicit Baby(Gender initialGender = Gender::UNKNOWN);
+
+public:
+ /*
+ * Eats `weight` grams of food.
+ */
+ void eat(unsigned long weight);
+
+ /*
+ * Sleeps for `duration` seconds.
+ */
+ void sleep(double duration);
+
+ /*
+ * Sets this baby's name to `name`.
+ */
+ void name(std::string name)
+ {
+ _mName = std::move(name);
+ }
+
+ /*
+ * This baby's name.
+ */
+ const std::string& name() const noexcept
+ {
+ return _mName;
+ }
+
+protected:
+ void _addTeeth(unsigned long index);
+ void _grow(double size) override;
+
+private:
+ std::string _mName {"Paul"};
+ Toys _mToys;
+};
+
+} // namespace life
+
+#endif // BABELTRACE_BABY_HPP
+----
+====
projects / babeltrace.git / blobdiff