<tab type="user" visible="yes" url="@ref examples" title="Examples"/>
<tab type="pages" visible="yes" title="All pages" intro=""/>
<tab type="modules" visible="yes" title="API reference"
- intro="List of all API reference modules:"/>
+ intro="List of all API reference pages:"/>
+ <tab type="topics" visible="yes" title="API reference"
+ intro="List of all API reference pages:"/>
</navindex>
<group>
when it returns.
The function descriptions in the
-<a class="el" href="modules.html">API reference modules</a>
+<a class="el" href="topics.html">API reference</a>
list all their preconditions and postconditions, if any.
The libbabeltrace2 public functions offer a
B API functions with an object of type A. For example, because an
\bt_enum_fc \em is conceptually an \bt_int_fc, you can use any integer
field class function with an enumeration field class.
-The <a class="el" href="modules.html">API reference modules</a> always
+The <a class="el" href="topics.html">API reference pages</a> always
indicate the inheritance relations.
@subsection api-fund-object-shared-unique Shared vs. unique objects
Because you cannot get a new unique object reference, you \em must
ensure that you own the unique object's owner to keep it alive. The
- <a class="el" href="modules.html">API reference modules</a> make it
+ <a class="el" href="topics.html">API reference pages</a> make it
clear, depending on the context, which
shared object is the ultimate owner of a given unique object.
</dd>
</dl>
-In the <a class="el" href="modules.html">API reference</a>, each module
+In the <a class="el" href="topics.html">API reference</a>, each page
indicates whether the documented objects are shared or unique.
@subsection api-fund-freezing Object freezing
become frozen, recursively.
There's no function to check whether or not a given object is frozen.
-Because the <a class="el" href="modules.html">API reference modules</a>
+Because the <a class="el" href="topics.html">API reference pages</a>
document which functions freeze which objects,
the "frozen" property is only useful for libbabeltrace2 to catch
programming errors (\ref api-fund-pre-post "precondition checks").
the type #bt_value because an \bt_array_val can contain different
types of values. You must be careful to only call the functions which
apply to a specific type of such objects.
-The <a class="el" href="modules.html">API reference modules</a> make
+The <a class="el" href="topics.html">API reference pages</a> make
this clear in the precondition section. Such objects always have a
<code>*_get_type()</code> function to get the object's exact type
enumerator. For example, bt_value_get_type() returns the type enumerator
}
@endcode
-The <a class="el" href="modules.html">API reference modules</a>
+The <a class="el" href="topics.html">API reference pages</a>
document, for each function, what each return status enumerator means.
Some functions return properties or objects by output parameter. When
domain objects and concepts (contents of \bt_p_msg).
The \bt_name
-<strong><em>trace IR</em></strong> (intermediate representation) modules
-contain everything you need to represent tracing domain concepts and
+<strong><em>trace IR</em></strong> (intermediate representation) API
+offers everything you need to represent tracing domain concepts and
objects so that many \bt_p_comp, written by different authors, can
exchange trace metadata and data.
parts of the API to accomplish real tasks.
</dd>
- <dt><a class="el" href="modules.html">API reference</a></dt>
+ <dt><a class="el" href="topics.html">API reference</a></dt>
<dd>
Documents all the \bt_name C functions, definitions, macros,
enumerators, and types.
- Each documentation module describes its API thoroughly and how it's
- related to other modules.
+ Each page describes its API thoroughly and how it's
+ related to other APIs.
</dd>
</dl>
*/
#include <babeltrace2-ctf-writer/object.h>
@endcode
-The macros and functions of this module are everything that is needed
+The macros and functions of this API are everything that is needed
to handle the <strong><em>reference counting</em></strong> of
Babeltrace objects.
@brief
Error reporting functions and macros.
-This module contains functions and macros to report rich errors from a
-user function (a \bt_comp_cls method, a
+This API offers functions and macros to report rich
+errors from a user function (a \bt_comp_cls method, a
\ref api-qexec "query operation", or a trace processing \bt_graph
listener, for example) to any function caller.
@image html component.png
@attention
- This module (component class development API) offers functions to
+ This API (component class development API) offers functions to
programmatically create component classes. To get the properties of
an existing component class, see \ref api-comp-cls.
-A component class has <em>methods</em>. This module essentially
+A component class has <em>methods</em>. This API essentially
offers:
- Component class method type definitions.
different types of component class methods.
A component class is a \ref api-fund-shared-object "shared object": see
-the \ref api-comp-cls module for the reference count functions.
+the \ref api-comp-cls API for the reference count functions.
Some library functions \ref api-fund-freezing "freeze" component classes
on success. The documentation of those functions indicate this
@image html component.png
@attention
- This module (component class API) offers basic, read-only functions
- to get component class properties. To \em create a component class,
- see \ref api-comp-cls-dev or \ref api-plugin-dev.
+ This API (component class API) offers basic,
+ read-only functions to get component class properties. To \em create
+ a component class, see \ref api-comp-cls-dev or \ref api-plugin-dev.
You can instantiate a given component class many times, with different
initialization parameters, to create many components with the
bt_component_class_filter_create() to set it as the created component
class's message iterator class.
-A message iterator class has <em>methods</em>. This module essentially
-offers:
+A message iterator class has <em>methods</em>. This API
+essentially offers:
- Message iterator class method type definitions.
welcome tool to make the project evolve gracefully.
The Message Interchange Protocol has no dedicated documentation as this
-very message module (and its submodules, like \ref api-tir)
+very message API (and its contained APIs, like \ref api-tir)
documentation is enough. You can consider that all the
functions of the message and trace IR objects have an implicit MIP
version \ref api-fund-pre-post "precondition". When a given
A query method receives a private query executor as its
\bt_p{query_executor} parameter.
-As of \bt_name_version_min_maj, this module only offers the
+As of \bt_name_version_min_maj, this API only offers the
bt_private_query_executor_as_query_executor_const() function to
\ref api-fund-c-typing "upcast" a private query executor to a
\c const query executor. You need this to get the query executor's
private views of a \bt_comp_cls from within a component class
\ref api-comp-cls-dev-class-meth "class method".
-As of \bt_name_version_min_maj, this module only contains functions
-to \ref api-fund-c-typing "upcast" the "self" (private) types to their
-public #bt_component_class, #bt_component_class_source,
+As of \bt_name_version_min_maj, this API only offers
+functions to \ref api-fund-c-typing "upcast" the "self" (private) types
+to their public #bt_component_class, #bt_component_class_source,
#bt_component_class_filter, and #bt_component_class_sink counterparts.
*/
@brief
Shared object plugin development.
-This module offers macros to create a \bt_name shared object plugin.
+This API offers macros to create a \bt_name shared
+object plugin.
-Behind the scenes, the <code>BT_PLUGIN_*()</code> macros of this module
-create and fill global tables which are located in sections of the
-shared object with specific names. The \ref api-plugin functions can
-load the resulting shared object file and create corresponding
-\bt_plugin objects.
+Behind the scenes, the <code>BT_PLUGIN_*()</code> macros of this
+API create and fill global tables which are located in
+sections of the shared object with specific names. The \ref api-plugin
+functions can load the resulting shared object file and create
+corresponding \bt_plugin objects.
See \ref guide-comp-link-plugin-so.
given plugin.
See \ref example-simple-plugin-def-file for a concrete example of how
-to use the macros of this module.
+to use the macros of this API.
<h1>\anchor api-plugin-dev-custom-plugin-id Custom plugin ID</h1>
@brief
General purpose utilities.
-This module contains general purpose utilities.
+This API offers general purpose utilities.
*/
/*! @{ */
@brief
Library version getters.
-This module contains functions to get information about the library's
-version:
+This API offers functions to get information about the
+library's version:
<dl>
<dt>Major version</dt>