X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=CONTRIBUTING.adoc;h=32f5363432f613ab34f000aef8acebd8afb15a25;hp=df4ae3cf167558a04d9b9d04952ac47a489f86b5;hb=dba8555979d55f701c773da6d07e9039df5fd19c;hpb=553c4bab3cad8ad569c14a01b39a66a2d8bcde7c diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index df4ae3cf..32f53634 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,30 +1,33 @@ // Render with Asciidoctor -= Babeltrace contributor's guide += Babeltrace{nbsp}2 contributor's guide Jérémie Galarneau, Philippe Proulx -v0.2, 19 June 2019 -:toc: -:toclevels: 5 - +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 +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]. - -== Babeltrace library +== {bt2} library === Object reference counting and lifetime -This section covers the rationale behind the design of Babeltrace's -object lifetime management. This applies to the Babeltrace library, as +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.0, 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 lifetime of some public objects is managed by reference counting. In @@ -32,17 +35,16 @@ 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 Let us consider a problematic case to illustrate the need for this distinction. -A user of the Babeltrace library creates a trace class, which _has_ a +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). @@ -72,10 +74,9 @@ never reach zero. 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 scheme employed in Babeltrace to break this cycle consists in the +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 @@ -114,7 +115,6 @@ 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 @@ -124,7 +124,6 @@ between objects: * Objects, beside the root, are only retrievable from their direct parent or children. - ==== Example The initial situation is rather simple: **User{nbsp}A** is holding a @@ -237,7 +236,7 @@ image::doc/contributing-images/bt-ref13.png[] 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 message iterator, and any deeply nested validation of a CTF IR object (within the `ctf` plugin), for example. With the @@ -246,13 +245,12 @@ can find the cause of a bug faster. While <> when placing _DEBUG_ to _FATAL_ logging statements, you should liberally instrument your -Babeltrace module with _TRACE_ logging statements to help future you +{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 +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 @@ -260,7 +258,7 @@ 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 -pass:[C++]. The zf_log source files were modified to have the `BT_` and +{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`. @@ -268,7 +266,6 @@ the project's `BT_DEBUG_MODE` definition instead of the standard The logging functions are implemented in the logging convenience library (`src/logging` directory). - [[logging-headers]] ==== Headers @@ -279,7 +276,7 @@ The logging API headers are: libbabeltrace2's current log level. `"logging/log.h"`:: - Internal, generic logging API which you can use in any Babeltrace + Internal, generic logging API which you can use in any {bt2} module. This is the translation of `zf_log.h`. + This header offers the <