2 @page api-fund API fundamentals
4 This page explains the basic principles of the \bt_api.
6 You \em must understand what the API expects before you create a
7 \bt_name \bt_plugin or an application which uses the API.
9 @section api-fund-header Header file
11 To use the \bt_api, include <code>%babeltrace2/babeltrace.h</code>:
14 #include <babeltrace2/babeltrace.h>
17 Do \em not include any other header file found in the \c babeltrace2
18 directory: the compiler prints an error when you try to.
20 @section api-fund-ns Namespace
22 - All libbabeltrace2 functions and types start with \c bt_.
24 - All libbabeltrace2 definitions, macros, and enumerators start
27 @section api-fund-pre-post Function contract checking
29 All the functions of libbabeltrace2 check that the caller meets their
30 <a href="https://en.wikipedia.org/wiki/Precondition">preconditions</a>.
32 All the functions of libbabeltrace2 which call a user function check
34 <a href="https://en.wikipedia.org/wiki/Postcondition">postconditions</a>
37 The function descriptions in the
38 <a class="el" href="modules.html">API reference modules</a>
39 list all their preconditions and postconditions, if any.
41 The libbabeltrace2 public functions offer a
42 <strong>narrow contract</strong>: when you break it, the library
43 prints how the precondition or postcondition was not satisfied, with
44 details, and then calls <code>abort()</code>.
46 Here's an example of what the library prints to the standard error
47 before aborting when you break a precondition (call
48 bt_value_bool_set() with a \c NULL value);
49 \ref api-fund-logging "logging" prefixes are removed for clarity:
52 Babeltrace 2 library precondition not satisfied.
53 ------------------------------------------------------------------------
54 Condition ID: `pre:value-bool-set:not-null:value-object`.
55 Function: bt_value_bool_set().
56 ------------------------------------------------------------------------
64 - <code>pre:value-bool-set:not-null:value-object</code> is the unique,
65 permanent ID of this precondition.
67 We use this ID for internal libbabeltrace2 testing.
69 - The <code>Function:</code> line shows which function's contract was
72 Because precondition and postcondition checks detect programming errors,
73 libbabeltrace2's approach is to abort as soon as possible so that you
74 fix the error. Therefore, the libbabeltrace2 functions never return a
75 programming error status (like what \c EINVAL means on Unix systems, for
79 Some precondition and postcondition checks which occur on the fast
80 path and which would therefore significantly impact performance
81 during a typical trace processing \bt_graph run are only enabled in
82 \ref guide-build-bt2-dev "developer mode".
84 Common function preconditions are:
86 - A pointer parameter is not \c NULL.
88 - An index parameter is not ouf of bounds.
90 - A string or container parameter is not empty.
92 - An object parameter has a given conceptual type. For example, you
93 cannot call bt_value_array_get_length() with a
96 - An object parameter is not \ref api-fund-freezing "frozen".
98 - An object parameter has some specific state.
100 @section api-fund-object Object model
103 <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented</a>.
105 With a few exceptions, API functions are actually
106 <a href="https://en.wikipedia.org/wiki/Method_(computer_programming)"><em>methods</em></a>
107 which operate on objects: their first parameter points to said object.
111 uint64_t bt_value_array_get_length(const bt_value *value);
114 You can create some types of objects with functions that contain the
115 word \c create, while for some other types, only the library can create
116 them behind the scenes. For example, you can create a
117 \bt_bool_val object with bt_value_bool_create(), but you cannot directly
118 create a \bt_ev object: you need to borrow one from a \bt_ev_msg which
121 Each type of object has its own C type. Learn more about typing in
122 \ref api-fund-c-typing below.
124 Some types of objects conceptually inherit other types of objects. If an
125 object type A inherits an object type B, then you can use both the A and
126 B API functions with an object of type A. For example, because an
127 \bt_enum_fc \em is conceptually an \bt_int_fc, you can use any integer
128 field class function with an enumeration field class.
129 The <a class="el" href="modules.html">API reference modules</a> always
130 indicate the inheritance relations.
132 @subsection api-fund-object-shared-unique Shared vs. unique objects
134 Some \bt_name objects are \em shared while some others are \em unique:
137 <dt>\anchor api-fund-shared-object Shared object</dt>
139 A \em shared object has a <a
140 href="https://en.wikipedia.org/wiki/Reference_counting">reference
143 A shared object's creation function returns a \em new reference.
145 The API of a given shared object type contains:
147 - A function to get a new reference, increasing the reference count,
148 which ends with \c _get_ref.
150 - A function to put an existing reference, decreasing the reference
151 count, which ends with \c _put_ref.
153 - A macro to put an existing reference and then set the passed
154 expression to \c NULL. This macro ends with \c _PUT_REF_AND_RESET.
156 - A macro to move an existing reference from a source expression to
157 a destination expression, putting the destination expression's
158 existing reference, and setting the source expression to \c NULL.
159 This macro ends with \c _MOVE_REF.
161 For example, bt_value_get_ref() and bt_value_put_ref() get and put
162 \bt_val object references, BT_VALUE_PUT_REF_AND_RESET() puts a
163 value reference and sets the expression to \c NULL, and
164 BT_VALUE_MOVE_REF() moves a value reference.
166 All <code>*_get_ref()</code> and <code>*_put_ref()</code> functions,
167 and all <code>*_PUT_REF_AND_RESET()</code> macros accept a \c NULL
170 When the reference count of a given object reaches zero, it \em can
171 be destroyed. Some shared objects, however, have a lifetime that is
172 managed by another shared object. For example, an \bt_ev_cls is not
173 destroyed until its parent \bt_stream_cls is also destroyed, even if
174 its reference count technically reaches zero.
176 A function which accepts a shared object never "takes" or steals the
177 caller's reference unless its name contains the word \c move: you
178 still have your own reference when the function returns. For
182 bt_event_class *event_class = bt_event_class_create(stream_class);
185 * At this point, we still have a reference of `stream_class`.
186 * We need to put it with bt_stream_class_put_ref() at some point.
190 A function which contains the word \c borrow returns a
191 <em>borrowed reference</em>: if you need your own reference, get
192 one with the appropriate <code>*_get_ref()</code> function.
195 <dt>\anchor api-fund-unique-object Unique object</dt>
197 A \em unique object does not have a reference count: another object
198 is always its sole owner.
200 Because you cannot get a new unique object reference, you \em must
201 ensure that you own the unique object's owner to keep it alive. The
202 <a class="el" href="modules.html">API reference modules</a> make it
203 clear, depending on the context, which
204 shared object is the ultimate owner of a given unique object.
206 In general, you cannot create a unique object: the library creates
207 it, and then you \em borrow it from another object (shared or unique
210 Unique objects exist for performance reasons: some optimizations are
211 challenging to implement without this concept.
215 In the <a class="el" href="modules.html">API reference</a>, each module
216 indicates whether the documented objects are shared or unique.
218 @subsection api-fund-freezing Object freezing
220 The library can \em freeze some types of \bt_name objects when specific
223 A frozen object is immutable: trying to set an object's property once
224 it's frozen represents a \ref api-fund-pre-post "precondition" break.
226 For example, the library freezes the source \bt_comp initialization
227 parameters when you call bt_graph_add_source_component(): this
228 guarantees to the component's
229 \ref api-comp-cls-dev-meth-init "initialization method" that the
230 parameters will never change for the rest of their lifetime.
232 When an object becomes frozen, its contained objects, if any, also
233 become frozen, recursively.
235 There's no function to check whether or not a given object is frozen.
236 Because the <a class="el" href="modules.html">API reference modules</a>
237 document which functions freeze which objects,
238 the "frozen" property is only useful for libbabeltrace2 to catch
239 programming errors (\ref api-fund-pre-post "precondition checks").
242 Some "frozen" property checks which occur on the fast path and which
243 would therefore significantly impact performance during a typical trace
244 processing \bt_graph run are only enabled in
245 \ref guide-build-bt2-dev "developer mode".
247 @section api-fund-c-typing C typing
249 The \bt_api typing system is very strict to catch many programming
250 errors at compile time.
252 Each type of object has its own C type. Consequently, functions accept
253 and return specific C types. For example, all the \bt_ev functions
254 accept a #bt_event pointer.
257 <a href="https://en.wikipedia.org/wiki/Opaque_pointer">opaque pointers</a>,
258 so that you don't having access to the object type's actual C structure.
259 This helps with the development of features and fixes in future releases
262 Some objects share the same C type when different conceptual types can
263 be contained in some collection. For example, all \bt_val objects have
264 the type #bt_value because an \bt_array_val can contain different
265 types of values. You must be careful to only call the functions which
266 apply to a specific type of such objects.
267 The <a class="el" href="modules.html">API reference modules</a> make
268 this clear in the precondition section. Such objects always have a
269 <code>*_get_type()</code> function to get the object's exact type
270 enumerator. For example, bt_value_get_type() returns the type enumerator
271 of a given \bt_val object.
273 When an object type A conceptually inherits an object type B, and when A
274 and B have different C types, the API offers a dedicated, inline
275 upcasting function named <code>bt_A_as_B()</code> to have access to the B
276 API at no cost. For example, an \bt_uenum_fc mapping \em is conceptually
277 an \bt_enum_fc mapping, but they have different C types:
278 #bt_field_class_enumeration_unsigned_mapping and
279 #bt_field_class_enumeration_mapping. Get the latter from the former with
280 bt_field_class_enumeration_unsigned_mapping_as_mapping_const().
281 The <code>bt_A_as_B()</code> functions do not change the object's
282 reference count and they accept \c NULL.
285 \b Never directly cast a \bt_name object pointer from some C type to
286 another C type: the API is designed so that you never need to do
289 @subsection api-fund-const const correctness
291 The \bt_api is <code>const</code>-correct: when a function has a
292 \c const object pointer parameter, it never modifies that object from
293 the user's viewpoint.
295 As such, when a function returns a \c const object pointer, directly or
296 through an output parameter, you can't modify the object.
299 \b Never remove a \bt_name object pointer's \c const qualifier. The
300 API is designed so that you never need to do that.
302 Functions which accept or return a \c const object pointer end with
303 \c _const when they have (or could have in the future) a non \c const
304 equivalent. For example, bt_value_map_borrow_entry_value_const() is the
305 \c const version of bt_value_map_borrow_entry_value().
307 Simple property getter functions do not end with \c _const.
309 \ref api-fund-shared-object "Reference count" changing functions, ending
310 with \c _get_ref and \c _put_ref(), accept a \c const object pointer
311 parameter: the library does not consider that an object's nature is
312 altered when its reference count changes.
314 @subsection api-fund-int-types C integer types
316 The API only uses \c uint64_t and \c int64_t as C integer types for
317 clarity and consistency.
319 @subsection api-fund-common-types Common C types and definitions
321 There are a few C types and definitions which are common to many parts
324 See \ref api-common-types.
326 @section api-fund-func-status Function return
328 libbabeltrace2 functions which cannot fail return a property or an
329 object pointer directly. For example, bt_value_array_get_length()
330 returns the length of an \bt_array_val, and
331 bt_value_array_borrow_element_by_index_const() returns a \bt_val
332 contained in an \bt_array_val. Both functions cannot fail: any
333 programming error \ref api-fund-pre-post "makes the program abort".
335 When a function returns an optional property or object:
338 <dt>If it's a pointer</dt>
340 The function returns \c NULL if the property/object is missing.
343 <dt>If it's not a pointer</dt>
346 <dt>If the property is available</dt>
348 The function returns the property by output parameter and returns
349 #BT_PROPERTY_AVAILABILITY_AVAILABLE.
352 <dt>If the property is not available</dt>
354 The function returns #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE.
360 Many libbabeltrace2 functions return a status code, that is, a C
361 enumerator containing the word \c STATUS. For example,
362 bt_value_copy() returns either #BT_VALUE_COPY_STATUS_OK or
363 #BT_VALUE_COPY_STATUS_MEMORY_ERROR.
365 Although the API guarantees that any status enumerator which has the
366 \c _OK status has the value 0, we recommend that you compare the
367 returned value to exact status enumerators for clarity, for example:
370 bt_value_copy_status status = bt_value_copy(obj, &val_copy);
372 if (status != BT_VALUE_COPY_STATUS_OK) {
377 The <a class="el" href="modules.html">API reference modules</a>
378 document, for each function, what each return status enumerator means.
380 Some functions return properties or objects by output parameter. When
381 such a function which accepts a property or object pointer \c ptr fails,
382 the library does \em not guarantee that <code>*ptr</code> remains
383 unchanged. Therefore, such a pattern is \em not safe:
386 bt_some_object *some_object = NULL;
388 status = bt_get_some_object(obj, &some_object);
395 Always rely on the returned status code:
398 bt_some_object *some_object;
400 status = bt_get_some_object(obj, &some_object);
402 if (status == BT_GET_SOME_OBJECT_STATUS_OK) {
407 @section api-fund-user-classes User classes
409 The whole \bt_name project is about extensibility: you can implement
410 \bt_p_comp_cls, and then package and distribute them as
413 When you implement a \bt_name \bt_comp_cls, you override protected
414 methods, just like you would do in any
415 <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
418 Here's the mapping of typical OOP language features to the
419 \bt_name library domain:
424 <th>\bt_name equivalent
428 Class object with implemented user functions.
430 For example: #bt_component_class_source.
432 <td>User class instance.
434 Instance object, created from a class object.
436 For example: #bt_component_source.
439 Instance pointer (\c this keyword in C++/Java and \c self variable
440 in Python, for example).
442 "Self" (private) object.
444 A "self" object has a specific, dedicated C type which starts
445 with <code>bt_self_</code>.
447 For example: #bt_self_component_source.
449 <td>Protected, final method.
451 Library function accepting an instance pointer ("self" object) as
454 Those functions always start with <code>bt_self_</code>.
456 For example: bt_self_component_source_add_output_port().
458 <td>Protected, overridable method.
460 User function with a specific signature, accepting an instance
461 pointer ("self" object) as its first parameter.
463 For example: #bt_component_class_source_initialize_method.
465 <td>Private user method.
467 Custom \c static user function having access to the instance
468 pointer ("self" object) somehow.
470 <td>Private user property or attribute.
472 Custom \bt_voidp data which you set and get using
473 dedicated protected methods (for example,
474 bt_self_component_set_data() and bt_self_component_get_data()).
477 @section api-fund-error Error reporting
479 libbabeltrace2 features a rich \ref api-error "error reporting"
480 mechanism to augment an error with custom causes without having to
481 explicitly pass an error object to the library functions.
483 When a library function or \ref api-fund-user-classes "user method"
484 returns an error status code (any status enumerator which contains
485 the word \c ERROR), it \em can add one or more error causes to the
486 current thread's error object.
488 This makes it possible for the end user to understand the contexts which
489 lead to the error, possibly across many \bt_p_plugin written by
490 different developers.
492 An error cause contains information about the source location where the
493 error occurred, the actor involved in the error, and a message.
495 When you "catch" an error, that is, react to a function returning an
496 error status code without returning an error status code yourself,
499 - Take the current thread's error with bt_current_thread_take_error() to
500 get its causes, possibly presenting them to the end user.
502 You then need to release the error with bt_error_release().
504 - Clear the current thread's error with bt_current_thread_clear_error().
507 You \em cannot call any libbabeltrace2 function when the current
508 thread has an error, except the
509 \ref api-fund-shared-object "reference counting" functions (ending
510 with <code>_get_ref()</code> or <code>_put_ref()</code>).
513 <a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2.1"><code>babeltrace2</code></a>
514 CLI uses this feature to pretty-print an error's causes to the end user,
518 ERROR: [Babeltrace CLI] (babeltrace2.c:2521)
519 Cannot create components.
520 CAUSED BY [Babeltrace CLI] (babeltrace2.c:2336)
521 Cannot create component: plugin-name="ctf", comp-cls-name="fs", comp-cls-type=0,
522 comp-name="auto-disc-source-ctf-fs"
523 CAUSED BY [libbabeltrace2] (graph.c:1343)
524 Component initialization method failed: status=ERROR, comp-addr=0x562fbd275f40,
525 comp-name="auto-disc-source-ctf-fs", comp-log-level=WARNING, comp-class-type=SOURCE,
526 comp-class-name="fs", comp-class-partial-descr="Read CTF traces from the file sy",
527 comp-class-is-frozen=1, comp-class-so-handle-addr=0x562fbd285810,
528 comp-class-so-handle-path="/usr/lib/babeltrace2/plugins/babeltrace-plugin-ctf.so",
529 comp-input-port-count=0, comp-output-port-count=0
530 CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:1148)
531 Cannot create trace for `/path/to/trace`.
532 CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:928)
533 Cannot add stream file `/path/to/trace/channel0_1` to stream file group
534 CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:734)
535 Cannot get stream file's first packet's header and context fields (`/path/to/trace/channel0_1`).
538 @section api-fund-logging Logging
540 libbabeltrace2 contains many hundreds of logging statements to help you
541 follow and debug your \bt_plugin or program.
543 By default, the library's logging is disabled. To enable it, use
544 bt_logging_set_global_level().
546 To set the library's initial logging level (checked once at library
547 loading time), set the \c LIBBABELTRACE2_INIT_LOG_LEVEL environment
548 variable, with one of:
553 - \c W, \c WARN, or \c WARNING
558 By default, the minimal, build-time logging level is \em DEBUG. We
559 recommend that you build libbabeltrace2 with the \em TRACE minimal
560 logging level for development. See \ref guide-build-bt2-dev.
562 libbabeltrace2 writes its logging statements to the standard error
565 A libbabeltrace2 (and \bt_name project plugin) logging line looks like
569 05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
572 The line contains, in order:
574 -# The date and time (<code>05-11 00:58:03.691</code>).
576 -# The process and thread IDs (<code>23402 23402</code>).
578 -# The logging level (\c D for \em DEBUG).
580 -# The function logging (\c bt_value_destroy).
582 -# The file and line number logging (<code>values.c:498</code>).
584 -# The message, which typically ends with a list of fields adding