Document libbabeltrace2's C API

This patch adds initial documentation for the Babeltrace 2 library's
C API using Doxygen.

The Doxygen project is located in `doc/api/libbabeltrace2`, as we can
eventually add `doc/api/libbabeltrace2-ctf-writer`.

To be able to use Doxygen's member grouping [1], I had to join some
header files (`const` and non `const` headers, for example), because
otherwise I could not get some functions in separate files to be in the
same member group in the order I want. In the end, the library user
includes `<babeltrace2/babeltrace.h>`, so how we organize the headers
exactly is not so crucial.

[1]: http://www.doxygen.nl/manual/grouping.html#memgroup

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I6d1dc2e7c5ee63fcd4220d0fd9f0931d361d2f31
Reviewed-on: https://review.lttng.org/c/babeltrace/+/2807
Tested-by: jenkins <jenkins@lttng.org>

diff --git a/.gitignore b/.gitignore
index f6ae6ec30f69aaf23da132ee31907148cfb0f7fd..16baf519da7b235bfd3152c0df1cfb33da9d2e64 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -61,7 +61,6 @@ __pycache__
 /src/babeltrace2-ctf-writer.pc
 TAGS
 cscope*
-doc/api/Doxyfile
 *.gcno
 *.gcda
 *.gcov

diff --git a/configure.ac b/configure.ac
index 7cbe3ba72220b691074dfd5a2a5d228cc6a1dbd0..6bbedb0361c0ba86fdfd399a817e06fb0a1a9cad 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -563,7 +563,7 @@ AS_IF([test "x$enable_api_doc" = "xyes"],
     DX_XML_FEATURE(OFF)
     DX_PDF_FEATURE(OFF)
     DX_PS_FEATURE(OFF)
-    DX_INIT_DOXYGEN([Babeltrace], [$(srcdir)/Doxyfile], [output])
+    DX_INIT_DOXYGEN([Babeltrace 2], [$(builddir)/Doxyfile], [output])
     AS_IF([test -z "$DX_DOXYGEN"],
          [AC_MSG_ERROR([You need doxygen to enable the API documentation])]
     )
@@ -724,8 +724,9 @@ program_transform_name="s&babeltrace2\.bin&babeltrace2&;$program_transform_name"
 AC_SUBST(program_transform_name)
 
 AC_CONFIG_FILES([
-       doc/api/Doxyfile
        doc/api/Makefile
+       doc/api/libbabeltrace2/Doxyfile
+       doc/api/libbabeltrace2/Makefile
        doc/bindings/Makefile
        doc/bindings/python/Makefile
        doc/contributing-images/Makefile

diff --git a/doc/api/.gitignore b/doc/api/.gitignore
deleted file mode 100644 (file)
index 6caf68a..0000000
--- a/doc/api/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-output
\ No newline at end of file

diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in
deleted file mode 100644 (file)
index 376888c..0000000
--- a/doc/api/Doxyfile.in
+++ /dev/null
@@ -1,239 +0,0 @@
-DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = "Babeltrace C API"
-PROJECT_NUMBER         = @PACKAGE_VERSION@
-PROJECT_BRIEF          = "Trace converter with plugin support"
-CREATE_SUBDIRS         = NO
-ALLOW_UNICODE_NAMES    = NO
-OUTPUT_LANGUAGE        = English
-BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = YES
-ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = YES
-STRIP_FROM_PATH        = "@top_srcdir@/include"
-STRIP_FROM_INC_PATH    =
-SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = NO
-QT_AUTOBRIEF           = NO
-MULTILINE_CPP_IS_BRIEF = YES
-INHERIT_DOCS           = YES
-SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 4
-ALIASES                =
-ALIASES               += btversion="@PACKAGE_VERSION@"
-ALIASES               += postsuccessrefcountretinc="@post <strong>On success</strong>, the reference count of the returned object is incremented."
-ALIASES               += postsuccessrefcountret1="@post <strong>On success</strong>, the reference count of the returned object is 1."
-ALIASES               += postsuccessrefcountinc{1}="@post <strong>On success</strong>, the reference count of \p \1 is incremented."
-ALIASES               += postrefcountsame{1}="@post The reference count of \p \1 is not modified."
-ALIASES               += postsuccessfrozen{1}="@post <strong>On success</strong>, \p \1 is frozen."
-ALIASES               += prenotnull{1}="@pre \p \1 is not \c NULL."
-ALIASES               += prehot{1}="@pre \p \1 is not frozen."
-ALIASES               += preisintft{1}="@pre \p \1 is a \link ctfirintfieldtype CTF IR integer field type\endlink."
-ALIASES               += preisfloatft{1}="@pre \p \1 is a \link ctfirfloatfieldtype CTF IR floating point number field type\endlink."
-ALIASES               += preisenumft{1}="@pre \p \1 is a \link ctfirenumfieldtype CTF IR enumeration field type\endlink."
-ALIASES               += preisstringft{1}="@pre \p \1 is a \link ctfirstringfieldtype CTF IR string field type\endlink."
-ALIASES               += preisstructft{1}="@pre \p \1 is a \link ctfirstructfieldtype CTF IR structure field type\endlink."
-ALIASES               += preisarrayft{1}="@pre \p \1 is a \link ctfirarrayfieldtype CTF IR array field type\endlink."
-ALIASES               += preisseqft{1}="@pre \p \1 is a \link ctfirseqfieldtype CTF IR sequence field type\endlink."
-ALIASES               += preisvarft{1}="@pre \p \1 is a \link ctfirvarfieldtype CTF IR variant field type\endlink."
-ALIASES               += preisintfield{1}="@pre \p \1 is a \link ctfirintfield CTF IR integer field\endlink."
-ALIASES               += preisfloatfield{1}="@pre \p \1 is a \link ctfirfloatfield CTF IR floating point number field\endlink."
-ALIASES               += preisenumfield{1}="@pre \p \1 is a \link ctfirenumfield CTF IR enumeration field\endlink."
-ALIASES               += preisstringfield{1}="@pre \p \1 is a \link ctfirstringfield CTF IR string field\endlink."
-ALIASES               += preisstructfield{1}="@pre \p \1 is a \link ctfirstructfield CTF IR structure field\endlink."
-ALIASES               += preisarrayfield{1}="@pre \p \1 is a \link ctfirarrayfield CTF IR array field\endlink."
-ALIASES               += preisseqfield{1}="@pre \p \1 is a \link ctfirseqfield CTF IR sequence field\endlink."
-ALIASES               += preisvarfield{1}="@pre \p \1 is a \link ctfirvarfield CTF IR variant field\endlink."
-ALIASES               += ft="\link ctfirfieldtypes CTF IR field type\endlink"
-ALIASES               += fts="\link ctfirfieldtypes CTF IR field types\endlink"
-ALIASES               += intft="\link ctfirintfieldtype CTF IR integer field type\endlink"
-ALIASES               += floatft="\link ctfirfloatfieldtype CTF IR floating point number field type\endlink"
-ALIASES               += enumft="\link ctfirenumfieldtype CTF IR enumeration field type\endlink"
-ALIASES               += enumftiter="\link ctfirenumftmappingiter CTF IR enumeration field type mapping iterator\endlink"
-ALIASES               += stringft="\link ctfirstringfieldtype CTF IR string field type\endlink"
-ALIASES               += structft="\link ctfirstructfieldtype CTF IR structure field type\endlink"
-ALIASES               += arrayft="\link ctfirarrayfieldtype CTF IR array field type\endlink"
-ALIASES               += seqft="\link ctfirseqfieldtype CTF IR sequence field type\endlink"
-ALIASES               += varft="\link ctfirvarfieldtype CTF IR variant field type\endlink"
-ALIASES               += intfts="\link ctfirintfieldtype CTF IR integer field types\endlink"
-ALIASES               += floatfts="\link ctfirfloatfieldtype CTF IR floating point number field types\endlink"
-ALIASES               += enumfts="\link ctfirenumfieldtype CTF IR enumeration field types\endlink"
-ALIASES               += stringfts="\link ctfirstringfieldtype CTF IR string field types\endlink"
-ALIASES               += structfts="\link ctfirstructfieldtype CTF IR structure field types\endlink"
-ALIASES               += arrayfts="\link ctfirarrayfieldtype CTF IR array field types\endlink"
-ALIASES               += seqfts="\link ctfirseqfieldtype CTF IR sequence field types\endlink"
-ALIASES               += varfts="\link ctfirvarfieldtype CTF IR variant field types\endlink"
-ALIASES               += field="\link ctfirfields CTF IR field\endlink"
-ALIASES               += fields="\link ctfirfields CTF IR fields\endlink"
-ALIASES               += intfield="\link ctfirintfield CTF IR integer field\endlink"
-ALIASES               += floatfield="\link ctfirfloatfield CTF IR floating point number field\endlink"
-ALIASES               += enumfield="\link ctfirenumfield CTF IR enumeration field\endlink"
-ALIASES               += stringfield="\link ctfirstringfield CTF IR string field\endlink"
-ALIASES               += structfield="\link ctfirstructfield CTF IR structure field\endlink"
-ALIASES               += arrayfield="\link ctfirarrayfield CTF IR array field\endlink"
-ALIASES               += seqfield="\link ctfirseqfield CTF IR sequence field\endlink"
-ALIASES               += varfield="\link ctfirvarfield CTF IR variant field\endlink"
-ALIASES               += intfields="\link ctfirintfield CTF IR integer fields\endlink"
-ALIASES               += floatfields="\link ctfirfloatfield CTF IR floating point number fields\endlink"
-ALIASES               += enumfields="\link ctfirenumfield CTF IR enumeration fields\endlink"
-ALIASES               += stringfields="\link ctfirstringfield CTF IR string fields\endlink"
-ALIASES               += structfields="\link ctfirstructfield CTF IR structure fields\endlink"
-ALIASES               += arrayfields="\link ctfirarrayfield CTF IR array fields\endlink"
-ALIASES               += seqfields="\link ctfirseqfield CTF IR sequence fields\endlink"
-ALIASES               += varfields="\link ctfirvarfield CTF IR variant fields\endlink"
-ALIASES               += imgpacketstructure="@image html ctf-stream-packet.png \"Structure of a CTF packet.\""
-ALIASES               += imgtracestructure="@image html ctf-trace.png \"Structure of a CTF trace.\""
-ALIASES               += noteexamplesassert="@note In the following examples, we use \c assert() to validate the results of the called functions."
-OPTIMIZE_OUTPUT_FOR_C  = YES
-MARKDOWN_SUPPORT       = YES
-TOC_INCLUDE_HEADINGS   = 0
-AUTOLINK_SUPPORT       = YES
-SUBGROUPING            = YES
-INLINE_GROUPED_CLASSES = NO
-INLINE_SIMPLE_STRUCTS  = NO
-TYPEDEF_HIDES_STRUCT   = NO
-LOOKUP_CACHE_SIZE      = 0
-
-EXTRACT_ALL            = NO
-EXTRACT_PRIVATE        = NO
-EXTRACT_PACKAGE        = NO
-EXTRACT_STATIC         = YES
-EXTRACT_LOCAL_CLASSES  = YES
-EXTRACT_LOCAL_METHODS  = NO
-EXTRACT_ANON_NSPACES   = NO
-HIDE_UNDOC_MEMBERS     = YES
-HIDE_UNDOC_CLASSES     = YES
-HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = YES
-INTERNAL_DOCS          = NO
-CASE_SENSE_NAMES       = NO
-HIDE_SCOPE_NAMES       = NO
-HIDE_COMPOUND_REFERENCE= NO
-SHOW_INCLUDE_FILES     = NO
-SHOW_GROUPED_MEMB_INC  = NO
-FORCE_LOCAL_INCLUDES   = NO
-INLINE_INFO            = YES
-SORT_MEMBER_DOCS       = NO
-SORT_BRIEF_DOCS        = NO
-SORT_MEMBERS_CTORS_1ST = NO
-SORT_GROUP_NAMES       = NO
-SORT_BY_SCOPE_NAME     = NO
-STRICT_PROTO_MATCHING  = NO
-GENERATE_TODOLIST      = YES
-GENERATE_TESTLIST      = YES
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS       =
-MAX_INITIALIZER_LINES  = 30
-SHOW_USED_FILES        = YES
-SHOW_FILES             = YES
-SHOW_NAMESPACES        = NO
-FILE_VERSION_FILTER    =
-LAYOUT_FILE            = "@srcdir@/DoxygenLayout.xml"
-CITE_BIB_FILES         =
-
-QUIET                  = NO
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = YES
-WARN_AS_ERROR          = NO
-WARN_FORMAT            = "$file:$line: $text"
-WARN_LOGFILE           =
-
-INPUT                  = "@top_srcdir@/include/babeltrace2/ctf-ir" \
-                         "@top_srcdir@/include/babeltrace2/component" \
-                         "@top_srcdir@/include/babeltrace2/plugin" \
-                         "@top_srcdir@/include/babeltrace2/ref.h" \
-                         "@top_srcdir@/include/babeltrace2/values.h" \
-                         "@top_srcdir@/include/babeltrace2/logging.h" \
-                         "@top_srcdir@/include/babeltrace2/types.h" \
-                         "@srcdir@/dox/main-page.dox" \
-                         "@srcdir@/dox/includes-build.dox" \
-                         "@srcdir@/dox/write-plugin.dox" \
-                         "@srcdir@/dox/use-ctf-writer.dox" \
-                         "@srcdir@/dox/examples.dox" \
-                         "@srcdir@/dox/examples-ctfir.dox" \
-                         "@srcdir@/dox/group-api-ref.dox" \
-                         "@srcdir@/dox/group-ctf-ir.dox"
-INPUT_ENCODING         = UTF-8
-FILE_PATTERNS          = *.h \
-                         *.hh \
-                         *.hpp \
-                         *.dox
-RECURSIVE              = NO
-EXCLUDE                =
-EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       =
-EXCLUDE_SYMBOLS        =
-EXAMPLE_PATH           =
-EXAMPLE_PATTERNS       = *
-EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = "@srcdir@/images"
-INPUT_FILTER           =
-FILTER_PATTERNS        =
-FILTER_SOURCE_FILES    = NO
-FILTER_SOURCE_PATTERNS =
-USE_MDFILE_AS_MAINPAGE =
-
-SOURCE_BROWSER         = NO
-INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = YES
-REFERENCED_BY_RELATION = NO
-REFERENCES_RELATION    = NO
-REFERENCES_LINK_SOURCE = YES
-SOURCE_TOOLTIPS        = YES
-USE_HTAGS              = NO
-VERBATIM_HEADERS       = YES
-
-ALPHABETICAL_INDEX     = YES
-COLS_IN_ALPHA_INDEX    = 5
-IGNORE_PREFIX          =
-
-OUTPUT_DIRECTORY       = output
-
-GENERATE_HTML          = YES
-HTML_FILE_EXTENSION    = .html
-HTML_HEADER            =
-HTML_FOOTER            =
-HTML_STYLESHEET        =
-HTML_EXTRA_STYLESHEET  =
-HTML_EXTRA_FILES       =
-HTML_COLORSTYLE_HUE    = 220
-HTML_COLORSTYLE_SAT    = 100
-HTML_COLORSTYLE_GAMMA  = 80
-HTML_TIMESTAMP         = YES
-HTML_DYNAMIC_SECTIONS  = YES
-HTML_INDEX_NUM_ENTRIES = 100
-
-GENERATE_DOCSET        = NO
-GENERATE_HTMLHELP      = NO
-GENERATE_CHI           = NO
-GENERATE_QHP           = NO
-GENERATE_ECLIPSEHELP   = NO
-
-DISABLE_INDEX          = NO
-GENERATE_TREEVIEW      = YES
-ENUM_VALUES_PER_LINE   = 4
-TREEVIEW_WIDTH         = 250
-EXT_LINKS_IN_WINDOW    = NO
-FORMULA_FONTSIZE       = 10
-FORMULA_TRANSPARENT    = YES
-USE_MATHJAX            = NO
-MATHJAX_FORMAT         = HTML-CSS
-MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
-MATHJAX_EXTENSIONS     =
-MATHJAX_CODEFILE       =
-SEARCHENGINE           = YES
-SERVER_BASED_SEARCH    = NO
-EXTERNAL_SEARCH        = NO
-SEARCHENGINE_URL       =
-SEARCHDATA_FILE        = searchdata.xml
-EXTERNAL_SEARCH_ID     =
-EXTRA_SEARCH_MAPPINGS  =
-
-GENERATE_LATEX         = NO
-GENERATE_RTF           = NO
-GENERATE_MAN           = NO
-GENERATE_XML           = NO
-GENERATE_PERLMOD       = NO

diff --git a/doc/api/DoxygenLayout.xml b/doc/api/DoxygenLayout.xml
deleted file mode 100644 (file)
index 0881dc8..0000000
--- a/doc/api/DoxygenLayout.xml
+++ /dev/null
@@ -1,194 +0,0 @@
-<doxygenlayout version="1.0">
-  <!-- Generated by doxygen 1.8.12 -->
-  <!-- Navigation index tabs for HTML output -->
-  <navindex>
-    <tab type="mainpage" visible="yes" title=""/>
-    <tab type="pages" visible="yes" title="" intro=""/>
-    <tab type="modules" visible="yes" title="" intro=""/>
-    <tab type="namespaces" visible="yes" title="">
-      <tab type="namespacelist" visible="yes" title="" intro=""/>
-      <tab type="namespacemembers" visible="yes" title="" intro=""/>
-    </tab>
-    <tab type="classes" visible="yes" title="">
-      <tab type="classlist" visible="yes" title="" intro=""/>
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
-      <tab type="hierarchy" visible="yes" title="" intro=""/>
-      <tab type="classmembers" visible="yes" title="" intro=""/>
-    </tab>
-    <tab type="files" visible="yes" title="">
-      <tab type="filelist" visible="yes" title="" intro=""/>
-      <tab type="globals" visible="yes" title="" intro=""/>
-    </tab>
-    <tab type="examples" visible="yes" title="" intro=""/>
-  </navindex>
-
-  <!-- Layout definition for a class page -->
-  <class>
-    <detaileddescription title=""/>
-    <briefdescription visible="no"/>
-    <includes visible="$SHOW_INCLUDE_FILES"/>
-    <inheritancegraph visible="$CLASS_GRAPH"/>
-    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
-    <memberdecl>
-      <nestedclasses visible="yes" title=""/>
-      <publictypes title=""/>
-      <services title=""/>
-      <interfaces title=""/>
-      <publicslots title=""/>
-      <signals title=""/>
-      <publicmethods title=""/>
-      <publicstaticmethods title=""/>
-      <publicattributes title=""/>
-      <publicstaticattributes title=""/>
-      <protectedtypes title=""/>
-      <protectedslots title=""/>
-      <protectedmethods title=""/>
-      <protectedstaticmethods title=""/>
-      <protectedattributes title=""/>
-      <protectedstaticattributes title=""/>
-      <packagetypes title=""/>
-      <packagemethods title=""/>
-      <packagestaticmethods title=""/>
-      <packageattributes title=""/>
-      <packagestaticattributes title=""/>
-      <properties title=""/>
-      <events title=""/>
-      <privatetypes title=""/>
-      <privateslots title=""/>
-      <privatemethods title=""/>
-      <privatestaticmethods title=""/>
-      <privateattributes title=""/>
-      <privatestaticattributes title=""/>
-      <friends title=""/>
-      <related title="" subtitle=""/>
-      <membergroups visible="yes"/>
-    </memberdecl>
-    <memberdef>
-      <inlineclasses title=""/>
-      <typedefs title=""/>
-      <enums title=""/>
-      <services title=""/>
-      <interfaces title=""/>
-      <constructors title=""/>
-      <functions title=""/>
-      <related title=""/>
-      <variables title=""/>
-      <properties title=""/>
-      <events title=""/>
-    </memberdef>
-    <allmemberslink visible="yes"/>
-    <usedfiles visible="$SHOW_USED_FILES"/>
-    <authorsection visible="yes"/>
-  </class>
-
-  <!-- Layout definition for a namespace page -->
-  <namespace>
-    <briefdescription visible="no"/>
-    <detaileddescription title=""/>
-    <memberdecl>
-      <nestednamespaces visible="yes" title=""/>
-      <constantgroups visible="yes" title=""/>
-      <classes visible="yes" title=""/>
-      <typedefs title=""/>
-      <enums title=""/>
-      <functions title=""/>
-      <variables title=""/>
-      <membergroups visible="yes"/>
-    </memberdecl>
-    <memberdef>
-      <inlineclasses title=""/>
-      <typedefs title=""/>
-      <enums title=""/>
-      <functions title=""/>
-      <variables title=""/>
-    </memberdef>
-    <authorsection visible="yes"/>
-  </namespace>
-
-  <!-- Layout definition for a file page -->
-  <file>
-    <briefdescription visible="no"/>
-    <detaileddescription title=""/>
-    <includes visible="$SHOW_INCLUDE_FILES"/>
-    <includegraph visible="$INCLUDE_GRAPH"/>
-    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
-    <sourcelink visible="yes"/>
-    <memberdecl>
-      <classes visible="yes" title=""/>
-      <namespaces visible="yes" title=""/>
-      <constantgroups visible="yes" title=""/>
-      <defines title=""/>
-      <typedefs title=""/>
-      <enums title=""/>
-      <functions title=""/>
-      <variables title=""/>
-      <membergroups visible="yes"/>
-    </memberdecl>
-    <memberdef>
-      <inlineclasses title=""/>
-      <defines title=""/>
-      <typedefs title=""/>
-      <enums title=""/>
-      <functions title=""/>
-      <variables title=""/>
-    </memberdef>
-    <authorsection/>
-  </file>
-
-  <!-- Layout definition for a group page -->
-  <group>
-    <detaileddescription title=""/>
-    <briefdescription visible="no"/>
-    <groupgraph visible="$GROUP_GRAPHS"/>
-    <memberdecl>
-      <nestedgroups visible="yes" title=""/>
-      <dirs visible="yes" title=""/>
-      <files visible="yes" title=""/>
-      <namespaces visible="yes" title=""/>
-      <classes visible="yes" title=""/>
-      <defines title=""/>
-      <typedefs title=""/>
-      <enums title=""/>
-      <enumvalues title=""/>
-      <functions title=""/>
-      <variables title=""/>
-      <signals title=""/>
-      <publicslots title=""/>
-      <protectedslots title=""/>
-      <privateslots title=""/>
-      <events title=""/>
-      <properties title=""/>
-      <friends title=""/>
-      <membergroups visible="yes"/>
-    </memberdecl>
-    <memberdef>
-      <pagedocs/>
-      <inlineclasses title=""/>
-      <defines title=""/>
-      <typedefs title=""/>
-      <enums title=""/>
-      <enumvalues title=""/>
-      <functions title=""/>
-      <variables title=""/>
-      <signals title=""/>
-      <publicslots title=""/>
-      <protectedslots title=""/>
-      <privateslots title=""/>
-      <events title=""/>
-      <properties title=""/>
-      <friends title=""/>
-    </memberdef>
-    <authorsection visible="yes"/>
-  </group>
-
-  <!-- Layout definition for a directory page -->
-  <directory>
-    <detaileddescription title=""/>
-    <briefdescription visible="no"/>
-    <directorygraph visible="yes"/>
-    <memberdecl>
-      <dirs visible="yes"/>
-      <files visible="yes"/>
-    </memberdecl>
-  </directory>
-</doxygenlayout>

diff --git a/doc/api/Makefile.am b/doc/api/Makefile.am
index c84bb770a3723798fa774eb24313d4a35dc879aa..18aeeba34db5555d910fa845861a71e098f07d08 100644 (file)
--- a/doc/api/Makefile.am
+++ b/doc/api/Makefile.am
@@ -1,17 +1 @@
-API_DOC_INSTALL_DIR = "$(DESTDIR)$(docdir)/api"
-
-all-local: doxygen-doc
-
-install-data-local: doxygen-doc
-       $(mkdir_p) "$(API_DOC_INSTALL_DIR)"
-       cp -rv output/html "$(API_DOC_INSTALL_DIR)"
-
-@DX_RULES@
-
-MOSTLYCLEANFILES = $(DX_CLEANFILES)
-EXTRA_DIST = Doxyfile.in \
-       README.adoc \
-       dox/group-api-ref.dox \
-       dox/group-ctf-ir.dox \
-       dox/main-page.dox \
-       dox/quick-start.dox
+SUBDIRS = libbabeltrace2

diff --git a/doc/api/README.adoc b/doc/api/README.adoc
deleted file mode 100644 (file)
index 3e6ce69..0000000
--- a/doc/api/README.adoc
+++ /dev/null
@@ -1,351 +0,0 @@
-= Babeltrace C API documentation guidelines
-
-Please follow those guidelines when you add to or modify the existing
-documentation of the Babeltrace C API.
-
-
-== Syntax
-
-Syntax example to document a function (tabs are converted to spaces
-in this example, but you really _must_ use tabs to indent):
-
-----
-/**
-@brief  Sets the name of the CTF IR stream class \p stream_class
-        to \p name.
-
-\p name must be unique amongst the names of all the stream classes
-of the trace class to which you eventually add \p stream_class.
-
-@remarks
-This is where you would put some remarks. Lorem ipsum dolor sit amet,
-consectetur adipiscing elit. Vestibulum sagittis tristique velit vitae
-tincidunt.
-
-@warning
-Use a warning command if this message is really important.
-
-@param[in] stream_class Stream class of which to set the name.
-@param[in] name         Name of the stream class (copied on success). If
-                        the description is too long, continue on the
-                        next line like this.
-@returns                0 on success, or a negative value on error.
-
-@prenotnull{stream_class}
-@prenotnull{name}
-@prehot{stream_class}
-@pre Some custom precondition.
-@postrefcountsame{stream_class}
-@post Some custom postcondition.
-
-@sa btstream_class_get_name(): Returns the name of a given stream class.
-*/
-----
-
-**Rules**:
-
-* Try to stay behind the 72th column mark if possible, and behind the
-  80th column otherwise.
-
-* Start the block with
-  https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdbrief[`@brief`]
-  followed by a tab followed by the brief description. If the brief
-  description needs more than one line, start the following lines with a
-  tab character.
-+
-Try to always refer to all the function or macro parameters in the brief
-description. The sentence _must_ begin with a verb, third-person
-singular. The brief description _must_ contain a single sentence
-which ends with a period.
-+
-Follow the brief description by zero or more paragraphs giving more
-details about the object you are documenting.
-+
-You can also use the
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdremark[`@remarks`]
-and
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdwarning[`@warning`]
-commands as needed to add special paragraphs.
-
-* When you refer to parameters, use the
-  https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdp[`\p`]
-  command:
-+
---
-----
-@brief  Transfers the ownership of a Babeltrace object from variable
-        \p _var_src to variable \p _var_dst.
-----
---
-
-* When you refer to any keyword or definition, use the
-  https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdc[`\c`]
-  command if it's a single word, otherwise surround the words with
-  `<code>` and `</code>`:
-+
---
-----
-@returns         Event class on success, or \c NULL on error.
-----
---
-
-* Add a new line before the parameter descriptions.
-
-* The syntax for a parameter line is one of:
-+
---
-----
-@param[in] in_param             Input parameter description.
-@param[out] out_param           Output parameter description.
-@param[in,out] inout_param      Input/output parameter description.
-----
---
-+
-That is:
-+
---
-. https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdparam[`@param`]
-. `[in]` (input parameter), `[out]` (output parameter), or `[in,out]`
-  (input/output parameter).
-+
-Output and input/output parameters are
-always pointers where, for a parameter named `param`, a result is
-stored _into_ `*param`.
-
-. A space.
-. The name of the parameter.
-. At least one tab.
-. The description which ends with a period.
---
-+
-Make sure all the beginnings of the parameter descriptions and of the
-return value description are vertically aligned by using as many tabs as
-required.
-+
-If more than one line is needed, align the beginning of the second line
-with the beginning of the first one (see the return value description in
-the example above).
-
-* The syntax for the return value line is:
-+
---
-. https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdreturns[`@returns`]
-  (_not_ `@return`).
-. At least one tab.
-. The description which ends with a period.
---
-+
-The return value description often takes the form:
-+
---
-----
-X on success, or Y on error.
-----
---
-
-* When needed, add an empty line after the return value line and add
-  preconditions and postconditions with the
-  https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdpre[`@pre`]
-  and
-  https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdpost[`@post`]
-  commands on the following lines.
-+
-Preconditions are a very clear way to indicate what the documented
-function or macro expects from the user in relation to its parameters.
-+
-Postconditions are a very clear way to indicate what the user should
-expect from the documented function or macro once it returns.
-+
-Use complete sentences, starting with a capital letter and ending with
-a period, when writing conditions. Use the present tense. If there's a
-conditional part, put it in bold at the beginning of the sentence.
-+
-If the condition is too long for a single line, continue on the
-following line, after a tab.
-+
-Examples:
-+
---
-----
-@pre The size of \p array_obj is equal to the size of \p map_obj.
-@post <strong>On success</strong>, the reference count of \p array_obj
-        is incremented.
-@post The reference count of \p map_obj is not modified.
-----
---
-+
-IMPORTANT: You should use aliases when possible to avoid duplication.
-See the list of available aliases in the `Doxyfile.in` file.
-
-* When relevant, add a new line after the return value line (or after
-  the precondition or postcondition lines, if any) and add
-  as many _see also_ links as needed on the following lines.
-+
-The syntax of those lines is:
-+
---
-. https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdsa[`@sa`]
-. A single space.
-. The name of the function, macro, variable, group, file, or page name
-  to see also.
-. `:` (colon).
-. A single space.
-. The capitalized brief description which ends with a period. The
-  sentence _must_ begin with a verb, third-person singular.
---
-+
-This is a way for you to inform the reader about other existing, related
-functions, macros, or any other documentation. Keep in mind that the
-reader does not always know where to look for things.
-+
-If the description is too long for a single line, continue on the
-following line, after a tab:
-+
---
-----
-@sa some_function() Lorem ipsum dolor sit amet, consectetur adipiscing
-        cras iaculis lectus quis dolor congue tempor.
-----
---
-
-* Always prefer the `@` commands to the `\` commands when you use them
-  outside of the text itself.
-
-
-== Style
-
-The ultimate goal of the Babeltrace C API documentation is to make the
-layman write code using this API as fast as possible without having to
-ask for help. For this purpose, the documentation should always be as
-clear as possible, just like the function and type names try to be.
-
-Do not hesitate to repeat technical terms, even in the same sentence, if
-needed. For example, if you document a _value object_, then always use
-the term _value object_ in the documentation, not _value_, nor _object_,
-since they are ambiguous.
-
-You can use light emphasis to show the importance of a part of the text
-with the
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdem[`\em`]
-command (one word) or by surrounding the text to emphasize with `<em>`
-and `</em>`. Likewise, you can use strong emphasis when needed with the
-https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdb[`\b`]
-command (one word) or with `<strong>`/`</strong>`. In general, prefer
-light emphasis to strong emphasis.
-
-Links to other parts of the documentation are very important. Consider
-that the reader never knows that other functions exist other than the
-current one. Use as many internal links as possible. Use the following
-forms of links:
-
-* `func()`: automatic link to the function (or macro) `func()`.
-* `file.h`: automatic link to the file named `file.h`.
-* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref
-  group`]: link to the
-  https://www.stack.nl/\~dimitri/doxygen/manual/grouping.html[group]
-  named `group` (prefer this over a link to a file).
-* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref
-  variable`]: link to the variable `variable`.
-* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdlink[`\link
-  reference some text\endlink`]: link to `reference` (file name, group
-  name, function or macro name, etc.) using the text `some text`.
-+
-Example:
-+
---
-----
-You can create a \link events CTF IR event\endlink using [...]
-By calling \link func() said function\endlink, [...]
-----
---
-+
---
-[NOTE]
-.Doxygen limitation.
-====
-Do not put a space between the end of the text and the `\endlink`
-command, because this space becomes part of the hyperlink's text.
-
-Do _not_ do:
-
-----
-You can create a \link events CTF IR event \endlink using [...]
-By calling \link func() said function \endlink, [...]
-----
-====
---
-
-See Doxygen's
-https://www.stack.nl/\~dimitri/doxygen/manual/autolink.html[Automatic
-link generation] for other ways to create automatic links.
-
-Try to follow as much as possible the
-https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual of Style]
-(4th edition) when you document the API. This includes:
-
-* Use an active voice.
-* Use a gender-neutral language.
-* Use the present tense (you should never need the future tense).
-* Address your reader directly (use _you_).
-* Avoid anthropomorphism.
-* Ensure parallelism in lists, procedures, and sentences.
-* Terminate list items with a period.
-* Do not use Latin abbreviations.
-* Use _and_ or _or_ instead of a slash.
-* Avoid using negatives.
-* Avoid using _should_: most of the time, you mean _must_.
-
-
-== Babeltrace terminology
-
-Here are the official names of the Babeltrace objects that you must use
-as is in the API documentation:
-
-* Value objects:
-** The null value object (_the_, not _a_, since it's a singleton
-   variable)
-** Boolean value object
-** Integer value object
-** Floating point number value object
-** String value object
-** Array value object
-** Map value object
-* CTF IR field path object
-* CTF IR field types
-** CTF IR integer field type
-** CTF IR floating point number field type
-** CTF IR enumeration field type
-** CTF IR string field type
-** CTF IR array field type
-** CTF IR sequence field type
-** CTF IR structure field type
-** CTF IR variant field type
-* CTF IR fields:
-** CTF IR integer field
-** CTF IR floating point number field
-** CTF IR enumeration field
-** CTF IR string field
-** CTF IR array field
-** CTF IR sequence field
-** CTF IR structure field
-** CTF IR variant field
-* CTF IR clock class
-* CTF IR event class
-* CTF IR stream class
-* CTF IR trace class
-* CTF IR event
-* CTF IR packet
-* CTF IR stream
-* CTF IR writer
-* Component
-* Source component
-* Sink component
-* Component class
-* Source component class
-* Sink component class
-* Plugin
-* Notification
-* Iterator
-
-Note that once you mention _CTF IR_ in an object name, you can omit
-it in the few following paragraphs.

diff --git a/doc/api/dox/examples-ctfir.dox b/doc/api/dox/examples-ctfir.dox
deleted file mode 100644 (file)
index 3c1850d..0000000
--- a/doc/api/dox/examples-ctfir.dox
+++ /dev/null
@@ -1,139 +0,0 @@
-/**
-@page ctfirexamples CTF IR examples
-
-<strong>List of CTF IR examples</strong>:
-
-- @subpage ctfirfieldtypesexamples CTF IR field types examples
-
-@sa ctfir (API reference)
-
-
-@page ctfirfieldtypesexamples CTF IR field types examples
-
-This page contains usage examples of the \ref ctfirfieldtypes API.
-
-@noteexamplesassert
-
-
-@section ctfirfieldtypesexamples_intfieldtype Integer field type
-
-@sa ctfirintfieldtype
-
-@subsection ctfirfieldtypesexamples_intfieldtype0 Create a default, 16-bit integer field type
-
-@code{.c}
-#include <assert.h>
-#include <babeltrace2/ctf-ir/field-types.h>
-
-struct bt_field_type *create_int_field_type(void)
-{
-    struct bt_field_type *field_type;
-
-    field_type = bt_field_type_integer_create(16);
-    assert(field_type);
-
-    return field_type;
-}
-@endcode
-
-@subsection ctfirfieldtypesexamples_intfieldtype1 Create a 23-bit, signed, big-endian integer field type
-
-@code{.c}
-#include <assert.h>
-#include <babeltrace2/ctf-ir/field-types.h>
-
-struct bt_field_type *create_int_field_type(void)
-{
-    int ret;
-    struct bt_field_type *field_type;
-
-    field_type = bt_field_type_integer_create(23);
-    assert(field_type);
-
-    ret = bt_field_type_set_byte_order(field_type,
-                                           BT_BYTE_ORDER_BIG_ENDIAN);
-    assert(ret == 0);
-
-    ret = bt_field_type_integer_set_signed(field_type, 1);
-    assert(ret == 0);
-
-    return field_type;
-}
-@endcode
-
-@subsection ctfirfieldtypesexamples_intfieldtype2 Create an 8-bit integer field type, displayed in hexadecimal, mapped to a CTF IR clock class
-
-@code{.c}
-#include <assert.h>
-#include <babeltrace2/ctf-ir/field-types.h>
-
-struct bt_field_type *create_int_field_type(
-        struct bt_clock_class *clock_class)
-{
-    int ret;
-    struct bt_field_type *field_type;
-
-    field_type = bt_field_type_integer_create(8);
-    assert(field_type);
-
-    ret = bt_field_type_integer_set_base(field_type,
-                                             BT_INTEGER_BASE_HEXADECIMAL);
-    assert(ret == 0);
-
-    ret = bt_field_type_integer_set_mapped_clock(field_type, clock_class);
-    assert(ret == 0);
-
-    return field_type;
-}
-@endcode
-
-
-@section ctfirfieldtypesexamples_floatfieldtype Floating point number field type
-
-@sa ctfirfloatfieldtype
-
-@subsection ctfirfieldtypesexamples_floatfieldtype0 Create a default floating point number field type
-
-@code{.c}
-#include <assert.h>
-#include <babeltrace2/ctf-ir/field-types.h>
-
-struct bt_field_type *create_float_field_type(void)
-{
-    struct bt_field_type *field_type;
-
-    field_type = bt_field_type_floating_point_create();
-    assert(field_type);
-
-    return field_type;
-}
-@endcode
-
-@subsection ctfirfieldtypesexamples_floatfieldtype1 Create a "double", little-endian floating point number field type
-
-@code{.c}
-#include <assert.h>
-#include <babeltrace2/ctf-ir/field-types.h>
-
-struct bt_field_type *create_float_field_type(void)
-{
-    int ret;
-    struct bt_field_type *field_type;
-
-    field_type = bt_field_type_floating_point_create();
-    assert(field_type);
-
-    ret = bt_field_type_set_byte_order(field_type,
-                                           BT_BYTE_ORDER_LITTLE_ENDIAN);
-    assert(ret == 0);
-
-    ret = bt_field_type_floating_point_set_exponent_digits(field_type, 11);
-    assert(ret == 0);
-
-    ret = bt_field_type_floating_point_set_mantissa_digits(field_type, 53);
-    assert(ret == 0);
-
-    return field_type;
-}
-@endcode
-*/

diff --git a/doc/api/dox/examples.dox b/doc/api/dox/examples.dox
deleted file mode 100644 (file)
index 34691ad..0000000
--- a/doc/api/dox/examples.dox
+++ /dev/null
@@ -1,7 +0,0 @@
-/**
-@page examples Examples
-
-<strong>List of examples</strong>:
-
-- @subpage ctfirexamples CTF IR examples
-*/

diff --git a/doc/api/dox/group-api-ref.dox b/doc/api/dox/group-api-ref.dox
deleted file mode 100644 (file)
index 23a838c..0000000
--- a/doc/api/dox/group-api-ref.dox
+++ /dev/null
@@ -1,30 +0,0 @@
-/**
-@defgroup apiref API reference
-@brief Babeltrace C API reference.
-
-This module and its submodules accurately document the C API of the
-Babeltrace library (v\btversion). See the \ref writeplugin and
-\ref usectfwriter pages for official, procedural user guides to help
-you get started with this API. See \ref examples for informal examples.
-
-The API is divided into the following modules:
-
-- \ref refs contains the macros and functions that you can use
-  to manage the reference count of Babeltrace objects.
-- \ref values is a set of generic value objects which are used at
-  various locations of the API.
-- \ref ctfir is an internal representation of the
-  <a href="http://diamon.org/ctf/">CTF</a> model which Babeltrace
-  uses as a common foundation between trace formats.
-- \ref btcomponents is the Babeltrace component API. A component is an
-  instance of a specific component class within a trace conversion
-  graph of connected iterators.
-- \ref ctfwriter is an API to write concrete CTF traces to the
-  file system.
-
-All the functions and macros documented here indicate their
-\em preconditions and \em postconditions. Unless there is an
-unexpected error (out of memory, resource not available, bug, etc.),
-if you honor the preconditions when you call a function, you are
-guaranteed that this function in turn honors the postconditions.
-*/

diff --git a/doc/api/dox/group-ctf-ir.dox b/doc/api/dox/group-ctf-ir.dox
deleted file mode 100644 (file)
index f7878da..0000000
--- a/doc/api/dox/group-ctf-ir.dox
+++ /dev/null
@@ -1,21 +0,0 @@
-/**
-@defgroup ctfir CTF IR
-@ingroup apiref
-@brief Common Trace Format Intermediate Representation.
-
-The <em>Common Trace Format Intermediate Representation</em>,
-or <strong><em>CTF IR</em></strong>, is the representation of the
-<a href="http://diamon.org/ctf">CTF</a> model within Babeltrace.
-
-As with any Babeltrace object, all the CTF IR objects have
-<a href="https://en.wikipedia.org/wiki/Reference_counting">reference
-counts</a>. See \ref refs to learn more about the reference counting
-management of Babeltrace objects.
-
-When the documentation says that a given
-\link ctfirfieldtypes CTF IR field type\endlink must be
-<em>equivalent to</em> another one, it means that
-bt_field_type_compare() \em must return 0.
-
-@sa \ref ctfirexamples "Examples"
-*/

diff --git a/doc/api/dox/includes-build.dox b/doc/api/dox/includes-build.dox
deleted file mode 100644 (file)
index f7b42c1..0000000
--- a/doc/api/dox/includes-build.dox
+++ /dev/null
@@ -1,74 +0,0 @@
-/**
-@page includesbuild Include files and how to build
-
-@section includefiles Include files
-
-You can find all the Babeltrace library include files (C headers) in the
-\c babeltrace2 directory under the include files directory chosen when
-installing Babeltrace. By default, this is <code>/usr/include</code>.
-If you build Babeltrace from source without specifying an installation
-prefix, this is <code>/usr/local/include</code>.
-
-The documentation modules in \ref apiref always show which header file
-to include to use the documented functions and types.
-
-You can also use the "master" include file which provides everything,
-but which necessarily makes the compilation slower:
-
-@code
-#include <babeltrace2/babeltrace.h>
-@endcode
-
-@section howtobuild How to build
-
-Multiple types of applications can use the Babeltrace library:
-
-- A user plugin (shared object) to be loaded by the \c babeltrace2
-  converter program or by another application.
-- A user application or library which loads plugins to manually connect
-  existing components in a specific way.
-- A user application or library which creates its own component classes
-  and manually connects them.
-
-In any way, the only library to link to is `libbabeltrace2`.
-
-@subsection howtobuildplugin Build a plugin
-
-To build a user plugin:
-
-<ol>
-    <li>Compile the source files which form your plugin:
-
-@verbatim
-cc -c -fpic my-plugin.c
-@endverbatim
-    </li>
-
-    <li>Create the plugin shared object:
-
-@verbatim
-cc -shared my-plugin.o -lbabeltrace2 -o my-plugin.so
-@endverbatim
-    </li>
-</ol>
-
-@subsection howtobuildapp Build an application
-
-To build an application which uses the Babeltrace library:
-
-<ol>
-    <li>Compile the source files which form your application:
-
-@verbatim
-cc -c my-app.c
-@endverbatim
-    </li>
-
-    <li>Create the executable application:
-
-@verbatim
-cc my-app.o -lbabeltrace2 -o my-app
-@endverbatim
-    </li>
-</ol>
-*/

diff --git a/doc/api/dox/main-page.dox b/doc/api/dox/main-page.dox
deleted file mode 100644 (file)
index edc79d4..0000000
--- a/doc/api/dox/main-page.dox
+++ /dev/null
@@ -1,136 +0,0 @@
-/**
-@mainpage Welcome!
-
-Welcome to the
-<strong><em>Babeltrace \btversion C API</em></strong> documentation!
-
-<a href="http://diamon.org/babeltrace">Babeltrace</a> is an open
-source converter of
-<a href="https://en.wikipedia.org/wiki/Tracing_(software)">trace</a>
-formats. You can use its C API to
-write custom source, sink, and filter
-\link btcomponents component classes\endlink which you can package as user
-\link btplugins plugins\endlink.
-
-
-@section intro What's this API for?
-
-The goal of using this API is to create user
-\link btplugins <em>plugins</em>\endlink.
-
-A Babeltrace plugin contains one or more
-\link btcomponents <em>component classes</em>\endlink.
-
-A component class is either:
-
-- A \b source component class: creates producers of trace
-  events.
-- A \b sink component class: creates consumers of trace events.
-- A \b filter component class: creates components which are both a
-  producers and consumers of trace events.
-
-A program or library can instantiate as many concrete \em components as
-needed from a single component class. At component instantiation time,
-the component class's registered user initialization function is called
-with custom user parameters.
-
-Plugins, as of Babeltrace \btversion, are built as dynamic libraries
-(<code>.so</code> or <code>.dll</code> files) and loaded by the \c
-babeltrace converter program. You can also get plugin objects from a
-shared object file or from a directory containing shared object files
-thanks to the C API. The converter program is responsible for passing
-notifications and events from source components to filter components, if
-any, and from filter components to sink components.
-
-@image html babeltrace-cli.png
-
-@section mainpagectfir CTF IR
-
-The internal representations of a trace, a stream, and an event follow
-the <a href="http://diamon.org/ctf">Common Trace Format</a> model.
-Within the Babeltrace C API, this representation is called the
-<em>Common Trace Format Intermediate Representation</em>, or
-\link ctfir CTF IR\endlink. CTF IR is flexible enough to represent
-almost any trace or logging format.
-
-The CTF IR model contains the following objects, amongst others:
-
-- A \link ctfirfieldtypes field type\endlink is the type of concrete
-  \link ctfirfields fields\endlink.
-
-  For example, an integer field type contains the size (in bits) of the
-  integer fields it creates, as well as their byte order, whether or not
-  they are signed, and so on. An integer field that you create out of an
-  integer field type, however, only contains a raw integral value. You
-  can create many fields from a single field type.
-
-- An \link ctfireventclass event class\endlink is the type of
-  a concrete \link ctfirevent event\endlink.
-
-  An event class contains the field types of its various scopes, while
-  an event contains the actual fields holding their values.
-
-- A \link ctfirstreamclass stream class\endlink is the type of
-  a concrete \link ctfirstream stream\endlink.
-
-  A stream class contains the field types of its various scopes, while
-  \link ctfirpacket packets\endlink attached to a
-  \link ctfirstream stream\endlink instantiated from a
-  stream class contains the actual
-  fields holding their values. <p> A stream class is the parent of one or
-  more event classes.
-
-
-- A \link ctfirtraceclass trace class\endlink describes traces.
-
-  A trace class is the parent of one or more stream classes.
-
-- A \link ctfirclockclass clock class\endlink holds the common
-  properties of clock values that are instantiated in \link ctfirevent
-  events\endlink.
-
-@section mainpagevalues Value objects
-
-Some parts of the Babeltrace API require typical, generic scalar values
-(boolean, integer, floating point number, string) organized in compound
-objects (array, map). This is similar to the model that
-<a href="http://json.org/">JSON</a> offers.
-
-For example, the environment of a
-\link ctfirtraceclass CTF IR trace class\endlink maps strings to strings
-or to integers, and the parameters passed to component instances take
-the form of a map.
-
-For this purpose, the API uses
-\link values value objects\endlink.
-
-@section mainpageref Reference counting
-
-All the <em>Babeltrace objects</em> have a
-<a href="https://en.wikipedia.org/wiki/Reference_counting">reference count</a>
-to make them shareable.
-When you use a Babeltrace object creation function (for example,
-bt_value_bool_create()), you get a new reference to the created
-object. When you add this object to another one, the latter takes its
-own reference using bt_get(), incrementing the shared object's reference
-count. When you are done with an object, you must call bt_put() to drop
-your reference, decrementing its reference count. When an object's
-reference count reaches 0, the object is considered \em destroyed and
-cannot be used anymore.
-
-See \ref refs for more details.
-
-The postconditions of the functions and macros documented here indicate
-what you can expect from the reference counts of the Babeltrace objects
-passed as parameters to and returned from API functions.
-
-@section mainpagefreeze Frozen objects
-
-The Babeltrace library can \em freeze almost all of the Babeltrace
-objects. A frozen object is considered \em immutable, although you can
-still get and put references to this object.
-
-The preconditions of the functions and macros documented here indicate
-when they expect unfrozen objects. The postconditions indicate when
-the functions and macros freeze an object.
-*/

diff --git a/doc/api/dox/quick-start.dox b/doc/api/dox/quick-start.dox
deleted file mode 100644 (file)
index 662bbc5..0000000
--- a/doc/api/dox/quick-start.dox
+++ /dev/null
@@ -1,6 +0,0 @@
-/**
-@page quickstart Quick start
-@tableofcontents
-
-lol lol
-*/

diff --git a/doc/api/images/babeltrace-cli.png b/doc/api/images/babeltrace-cli.png
deleted file mode 100644 (file)
index e21dc53..0000000
Binary files a/doc/api/images/babeltrace-cli.png and /dev/null differ

diff --git a/doc/api/images/ctf-stream-packet.png b/doc/api/images/ctf-stream-packet.png
deleted file mode 100644 (file)
index 0c41fcf..0000000
Binary files a/doc/api/images/ctf-stream-packet.png and /dev/null differ

diff --git a/doc/api/images/ctf-trace.png b/doc/api/images/ctf-trace.png
deleted file mode 100644 (file)
index 64a389c..0000000
Binary files a/doc/api/images/ctf-trace.png and /dev/null differ

diff --git a/doc/api/images/ref-count-api-returns.png b/doc/api/images/ref-count-api-returns.png
deleted file mode 100644 (file)
index e8f3471..0000000
Binary files a/doc/api/images/ref-count-api-returns.png and /dev/null differ

diff --git a/doc/api/images/ref-count-callback.png b/doc/api/images/ref-count-callback.png
deleted file mode 100644 (file)
index 4e75862..0000000
Binary files a/doc/api/images/ref-count-callback.png and /dev/null differ

diff --git a/doc/api/images/ref-count-user-calls.png b/doc/api/images/ref-count-user-calls.png
deleted file mode 100644 (file)
index 0502c8f..0000000
Binary files a/doc/api/images/ref-count-user-calls.png and /dev/null differ

diff --git a/doc/api/libbabeltrace2/.gitignore b/doc/api/libbabeltrace2/.gitignore
new file mode 100644 (file)
index 0000000..15523a7
--- /dev/null
+++ b/doc/api/libbabeltrace2/.gitignore
@@ -0,0 +1,3 @@
+output
+Doxyfile
+README.html

diff --git a/doc/api/libbabeltrace2/Doxyfile.in b/doc/api/libbabeltrace2/Doxyfile.in
new file mode 100644 (file)
index 0000000..cd94819
--- /dev/null
+++ b/doc/api/libbabeltrace2/Doxyfile.in
@@ -0,0 +1,776 @@
+DOXYFILE_ENCODING       = UTF-8
+PROJECT_NAME            = "Babeltrace 2 C API"
+PROJECT_NUMBER          = @PACKAGE_VERSION@
+PROJECT_BRIEF           = "Open-source trace manipulation framework"
+CREATE_SUBDIRS          = NO
+ALLOW_UNICODE_NAMES     = NO
+OUTPUT_LANGUAGE         = English
+BRIEF_MEMBER_DESC       = YES
+REPEAT_BRIEF            = YES
+ALWAYS_DETAILED_SEC     = NO
+INLINE_INHERITED_MEMB   = NO
+FULL_PATH_NAMES         = YES
+STRIP_FROM_PATH         = "@top_srcdir@/include"
+STRIP_FROM_INC_PATH     =
+SHORT_NAMES             = NO
+JAVADOC_AUTOBRIEF       = NO
+QT_AUTOBRIEF            = NO
+MULTILINE_CPP_IS_BRIEF  = YES
+INHERIT_DOCS            = YES
+SEPARATE_MEMBER_PAGES   = NO
+TAB_SIZE                = 4
+ALIASES                 =
+
+# Aliases: general
+ALIASES                += bt_version_min_maj="2.0"
+ALIASES                += bt_version="@PACKAGE_VERSION@"
+ALIASES                += bt_max_mip_version="0"
+ALIASES                += bt_name="Babeltrace 2"
+ALIASES                += bt_name_version_min_maj="Babeltrace \bt_version_min_maj"
+ALIASES                += bt_api="Babeltrace 2 C API"
+ALIASES                += bt_p{1}="<span class="bt-param">\1</span>"
+ALIASES                += bt_dt_opt="<strong><em>Optional</em></strong>:"
+ALIASES                += bt_man{2}="<a href=\"https://babeltrace.org/docs/v\bt_version_min_maj/man\2/\1.\2/\"><code><strong>\1</strong>(\2)</code></a>"
+ALIASES                += bt_cli="<a href=\"https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2.1\"><code>babeltrace2</code></a>"
+ALIASES                += bt_voidp="<code>void&nbsp;*</code>"
+
+# Aliases: preconditions: general
+ALIASES                += bt_pre_not_null{1}="@pre \bt_p{\1} is \em not \c NULL."
+ALIASES                += bt_pre_hot{1}="@pre \bt_p{\1} is \em not \link api-fund-freezing frozen\endlink."
+ALIASES                += bt_pre_assign_expr{1}="@pre \bt_p{\1} is an assignable expression."
+ALIASES                += bt_pre_valid_fmt{1}="@pre \bt_p{\1} is a valid <code>printf()</code>-like format string."
+ALIASES                += bt_pre_fc_not_in_tc{1}="@pre \bt_p{\1} is not already part of another field class, an \bt_ev_cls, or a \bt_stream_cls."
+
+# Aliases: postconditions
+ALIASES                += bt_post_success_frozen{1}="@post <strong>On success</strong>, \bt_p{\1} is \link api-fund-freezing frozen\endlink."
+ALIASES                += bt_post_no_error="@post The current thread has no \link api-error error\endlink."
+
+# Aliases: preconditions: graph
+ALIASES                += bt_pre_graph_not_configured{1}="@pre \bt_p{\1} is \em not completely \link api-graph-lc configured\endlink yet (you didn't call bt_graph_run() or bt_graph_run_once() with it)."
+ALIASES                += bt_pre_graph_not_faulty{1}="@pre \bt_p{\1} is \em not faulty: no previous \link api-graph-lc-add component adding\endlink or component \link api-graph-lc-connect port connecting\endlink functions failed with it."
+ALIASES                += bt_pre_hot{1}="@pre \bt_p{\1} is \em not \link api-fund-freezing frozen\endlink."
+ALIASES                += bt_pre_assign_expr{1}="@pre \bt_p{\1} is an assignable expression."
+ALIASES                += bt_pre_valid_fmt{1}="@pre \bt_p{\1} is a valid <code>printf()</code>-like format string."
+ALIASES                += bt_pre_fc_not_in_tc{1}="@pre \bt_p{\1} is not already part of another field class, an \bt_ev_cls, or a \bt_stream_cls."
+
+# Aliases: preconditions: field class object type
+ALIASES                += bt_pre_is_ba_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-ba bit array field class\endlink."
+ALIASES                += bt_pre_is_bool_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-bool boolean field class\endlink."
+ALIASES                += bt_pre_is_int_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-int integer field class\endlink."
+ALIASES                += bt_pre_is_real_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-real real field class\endlink."
+ALIASES                += bt_pre_is_enum_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-enum enumeration field class\endlink."
+ALIASES                += bt_pre_is_uenum_fc{1}="@pre \bt_p{\1} is an unsigned \link api-tir-fc-enum enumeration field class\endlink."
+ALIASES                += bt_pre_is_senum_fc{1}="@pre \bt_p{\1} is a signed \link api-tir-fc-enum enumeration field class\endlink."
+ALIASES                += bt_pre_is_string_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-string string field class\endlink."
+ALIASES                += bt_pre_is_struct_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-struct structure field class\endlink."
+ALIASES                += bt_pre_is_array_fc{1}="@pre \bt_p{\1} is an array \link api-tir-fc-array field class\endlink."
+ALIASES                += bt_pre_is_sarray_fc{1}="@pre \bt_p{\1} is a static \link api-tir-fc-array array field class\endlink."
+ALIASES                += bt_pre_is_darray_fc{1}="@pre \bt_p{\1} is a dynamic \link api-tir-fc-array array field class\endlink."
+ALIASES                += bt_pre_is_darray_wl_fc{1}="@pre \bt_p{\1} is a dynamic \link api-tir-fc-array array field class\endlink (with a length field)."
+ALIASES                += bt_pre_is_opt_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink."
+ALIASES                += bt_pre_is_opt_ws_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with a selector field)."
+ALIASES                += bt_pre_is_opt_wbs_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with a boolean selector field)."
+ALIASES                += bt_pre_is_opt_wsis_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with a signed integer selector field)."
+ALIASES                += bt_pre_is_opt_wuis_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with an unsigned integer selector field)."
+ALIASES                += bt_pre_is_var_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink."
+ALIASES                += bt_pre_is_var_wos_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (without a selector field)."
+ALIASES                += bt_pre_is_var_ws_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (with a selector field)."
+ALIASES                += bt_pre_is_var_wuis_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (with an unsigned integer selector field)."
+ALIASES                += bt_pre_is_var_wsis_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (with a signed integer selector field)."
+
+# Aliases: preconditions: field object type
+ALIASES                += bt_pre_is_ba_field{1}="@pre \bt_p{\1} is a \link api-tir-field-ba bit array field\endlink."
+ALIASES                += bt_pre_is_bool_field{1}="@pre \bt_p{\1} is a \link api-tir-field-bool boolean field\endlink."
+ALIASES                += bt_pre_is_sint_field{1}="@pre \bt_p{\1} is a signed \link api-tir-field-int integer field\endlink."
+ALIASES                += bt_pre_is_uint_field{1}="@pre \bt_p{\1} is an unsigned \link api-tir-field-int integer field\endlink."
+ALIASES                += bt_pre_is_sreal_field{1}="@pre \bt_p{\1} is a single-precision \link api-tir-field-real real field\endlink."
+ALIASES                += bt_pre_is_dreal_field{1}="@pre \bt_p{\1} is a double-precision \link api-tir-field-real real field\endlink."
+ALIASES                += bt_pre_is_enum_field{1}="@pre \bt_p{\1} is an \link api-tir-field-enum enumeration field\endlink."
+ALIASES                += bt_pre_is_uenum_field{1}="@pre \bt_p{\1} is an unsigned \link api-tir-field-enum enumeration field\endlink."
+ALIASES                += bt_pre_is_senum_field{1}="@pre \bt_p{\1} is a signed \link api-tir-field-enum enumeration field\endlink."
+ALIASES                += bt_pre_is_string_field{1}="@pre \bt_p{\1} is a \link api-tir-field-string string field\endlink."
+ALIASES                += bt_pre_is_struct_field{1}="@pre \bt_p{\1} is a \link api-tir-field-struct structure field\endlink."
+ALIASES                += bt_pre_is_array_field{1}="@pre \bt_p{\1} is an \link api-tir-field-array array field\endlink."
+ALIASES                += bt_pre_is_sarray_field{1}="@pre \bt_p{\1} is a static \link api-tir-field-array array field\endlink."
+ALIASES                += bt_pre_is_darray_field{1}="@pre \bt_p{\1} is a dynamic \link api-tir-field-array array field\endlink."
+ALIASES                += bt_pre_is_opt_field{1}="@pre \bt_p{\1} is an \link api-tir-field-opt option field\endlink."
+ALIASES                += bt_pre_is_var_field{1}="@pre \bt_p{\1} is a \link api-tir-field-var variant field\endlink."
+ALIASES                += bt_pre_is_var_wuis_field{1}="@pre \bt_p{\1} is a \link api-tir-field-var variant field\endlink (with an unsigned integer selector field)."
+ALIASES                += bt_pre_is_var_wsis_field{1}="@pre \bt_p{\1} is a \link api-tir-field-var variant field\endlink (with a signed integer selector field)."
+
+# Aliases: preconditions: value object type
+ALIASES                += bt_pre_is_null_val{1}="@pre \bt_p{\1} is a null \link api-val value\endlink (\bt_p{\1} is equal to #bt_value_null)."
+ALIASES                += bt_pre_is_bool_val{1}="@pre \bt_p{\1} is a boolean \link api-val value\endlink (bt_value_is_bool() returns #BT_TRUE)."
+ALIASES                += bt_pre_is_sint_val{1}="@pre \bt_p{\1} is a signed integer \link api-val value\endlink (bt_value_is_signed_integer() returns #BT_TRUE)."
+ALIASES                += bt_pre_is_uint_val{1}="@pre \bt_p{\1} is an unsigned integer \link api-val value\endlink (bt_value_is_unsigned_integer() returns #BT_TRUE)."
+ALIASES                += bt_pre_is_real_val{1}="@pre \bt_p{\1} is a real \link api-val value\endlink (bt_value_is_real() returns #BT_TRUE)."
+ALIASES                += bt_pre_is_string_val{1}="@pre \bt_p{\1} is a string \link api-val value\endlink (bt_value_is_string() returns #BT_TRUE)."
+ALIASES                += bt_pre_is_array_val{1}="@pre \bt_p{\1} is an array \link api-val value\endlink (bt_value_is_array() returns #BT_TRUE)."
+ALIASES                += bt_pre_is_map_val{1}="@pre \bt_p{\1} is a map \link api-val value\endlink (bt_value_is_map() returns #BT_TRUE)."
+
+# Aliases: preconditions: message object type
+ALIASES                += bt_pre_is_disc_ev_msg{1}="@pre \bt_p{\1} is a \link api-msg-disc-ev discarded events message\endlink."
+ALIASES                += bt_pre_is_disc_pkt_msg{1}="@pre \bt_p{\1} is a \link api-msg-disc-pkt discarded packets message\endlink."
+ALIASES                += bt_pre_is_ev_msg{1}="@pre \bt_p{\1} is an \link api-msg-ev event message\endlink."
+ALIASES                += bt_pre_is_inac_msg{1}="@pre \bt_p{\1} is a \link api-msg-inac message iterator inactivity message\endlink."
+ALIASES                += bt_pre_is_pb_msg{1}="@pre \bt_p{\1} is a \link api-msg-pb packet beginning message\endlink."
+ALIASES                += bt_pre_is_pe_msg{1}="@pre \bt_p{\1} is a \link api-msg-pe packet end message\endlink."
+ALIASES                += bt_pre_is_sb_msg{1}="@pre \bt_p{\1} is a \link api-msg-sb stream beginning message\endlink."
+ALIASES                += bt_pre_is_se_msg{1}="@pre \bt_p{\1} is a \link api-msg-se stream end message\endlink."
+
+# Aliases: field class object types: singular
+ALIASES                += bt_fc="\link api-tir-fc field class\endlink"
+ALIASES                += bt_ba_fc="\link api-tir-fc-ba bit array field class\endlink"
+ALIASES                += bt_bool_fc="\link api-tir-fc-bool boolean field class\endlink"
+ALIASES                += bt_int_fc="\link api-tir-fc-int integer field class\endlink"
+ALIASES                += bt_sint_fc="signed \link api-tir-fc-int integer field class\endlink"
+ALIASES                += bt_uint_fc="unsigned \link api-tir-fc-int integer field class\endlink"
+ALIASES                += bt_real_fc="\link api-tir-fc-real real field class\endlink"
+ALIASES                += bt_enum_fc="\link api-tir-fc-enum enumeration field class\endlink"
+ALIASES                += bt_senum_fc="signed \link api-tir-fc-enum enumeration field class\endlink"
+ALIASES                += bt_uenum_fc="unsigned \link api-tir-fc-enum enumeration field class\endlink"
+ALIASES                += bt_string_fc="\link api-tir-fc-string string field class\endlink"
+ALIASES                += bt_struct_fc="\link api-tir-fc-struct structure field class\endlink"
+ALIASES                += bt_array_fc="\link api-tir-fc-array array field class\endlink"
+ALIASES                += bt_sarray_fc="static \link api-tir-fc-array array field class\endlink"
+ALIASES                += bt_darray_fc="dynamic \link api-tir-fc-array array field class\endlink"
+ALIASES                += bt_opt_fc="\link api-tir-fc-opt option field class\endlink"
+ALIASES                += bt_var_fc="\link api-tir-fc-var variant field class\endlink"
+
+# Aliases: field class object types: singular, capitalized
+ALIASES                += bt_c_fc="\link api-tir-fc Field class\endlink"
+ALIASES                += bt_c_ba_fc="\link api-tir-fc-ba Bit array field class\endlink"
+ALIASES                += bt_c_bool_fc="\link api-tir-fc-bool Boolean field class\endlink"
+ALIASES                += bt_c_int_fc="\link api-tir-fc-int Integer field class\endlink"
+ALIASES                += bt_c_sint_fc="Signed \link api-tir-fc-int integer field class\endlink"
+ALIASES                += bt_c_uint_fc="Unsigned \link api-tir-fc-int integer field class\endlink"
+ALIASES                += bt_c_real_fc="\link api-tir-fc-real Real field class\endlink"
+ALIASES                += bt_c_enum_fc="\link api-tir-fc-enum Enumeration field class\endlink"
+ALIASES                += bt_c_senum_fc="Signed \link api-tir-fc-enum enumeration field class\endlink"
+ALIASES                += bt_c_uenum_fc="Unsigned \link api-tir-fc-enum enumeration field class\endlink"
+ALIASES                += bt_c_string_fc="\link api-tir-fc-string String field class\endlink"
+ALIASES                += bt_c_struct_fc="\link api-tir-fc-struct Structure field class\endlink"
+ALIASES                += bt_c_array_fc="\link api-tir-fc-array Array field class\endlink"
+ALIASES                += bt_c_sarray_fc="Static \link api-tir-fc-array array field class\endlink"
+ALIASES                += bt_c_darray_fc="Dynamic \link api-tir-fc-array array field class\endlink"
+ALIASES                += bt_c_opt_fc="\link api-tir-fc-opt Option field class\endlink"
+ALIASES                += bt_c_var_fc="\link api-tir-fc-var Variant field class\endlink"
+
+# Aliases: field class object types: plural
+ALIASES                += bt_p_fc="\link api-tir-fc field classes\endlink"
+ALIASES                += bt_p_ba_fc="\link api-tir-fc-ba bit array field classes\endlink"
+ALIASES                += bt_p_bool_fc="\link api-tir-fc-bool boolean field classes\endlink"
+ALIASES                += bt_p_int_fc="\link api-tir-fc-int integer field classes\endlink"
+ALIASES                += bt_p_sint_fc="signed \link api-tir-fc-int integer field classes\endlink"
+ALIASES                += bt_p_uint_fc="unsigned \link api-tir-fc-int integer field classes\endlink"
+ALIASES                += bt_p_real_fc="\link api-tir-fc-real real field classes\endlink"
+ALIASES                += bt_p_enum_fc="\link api-tir-fc-enum enumeration field classes\endlink"
+ALIASES                += bt_p_senum_fc="signed \link api-tir-fc-enum enumeration field classes\endlink"
+ALIASES                += bt_p_uenum_fc="unsigned \link api-tir-fc-enum enumeration field classes\endlink"
+ALIASES                += bt_p_string_fc="\link api-tir-fc-string string field classes\endlink"
+ALIASES                += bt_p_struct_fc="\link api-tir-fc-struct structure field classes\endlink"
+ALIASES                += bt_p_array_fc="\link api-tir-fc-array array field classes\endlink"
+ALIASES                += bt_p_sarray_fc="static \link api-tir-fc-array array field classes\endlink"
+ALIASES                += bt_p_darray_fc="dynamic \link api-tir-fc-array array field classes\endlink"
+ALIASES                += bt_p_opt_fc="\link api-tir-fc-opt option field classes\endlink"
+ALIASES                += bt_p_var_fc="\link api-tir-fc-var variant field classes\endlink"
+
+# Aliases: field class object types: plural, capitalized
+ALIASES                += bt_cp_fc="\link api-tir-fc Field classes\endlink"
+ALIASES                += bt_cp_ba_fc="\link api-tir-fc-ba Bit array field classes\endlink"
+ALIASES                += bt_cp_bool_fc="\link api-tir-fc-bool Boolean field classes\endlink"
+ALIASES                += bt_cp_int_fc="\link api-tir-fc-int Integer field classes\endlink"
+ALIASES                += bt_cp_sint_fc="Signed \link api-tir-fc-int integer field classes\endlink"
+ALIASES                += bt_cp_uint_fc="Unsigned \link api-tir-fc-int integer field classes\endlink"
+ALIASES                += bt_cp_real_fc="\link api-tir-fc-real Real field classes\endlink"
+ALIASES                += bt_cp_enum_fc="\link api-tir-fc-enum Enumeration field classes\endlink"
+ALIASES                += bt_cp_senum_fc="Signed \link api-tir-fc-enum enumeration field classes\endlink"
+ALIASES                += bt_cp_uenum_fc="Unsigned \link api-tir-fc-enum enumeration field classes\endlink"
+ALIASES                += bt_cp_string_fc="\link api-tir-fc-string String field classes\endlink"
+ALIASES                += bt_cp_struct_fc="\link api-tir-fc-struct Structure field classes\endlink"
+ALIASES                += bt_cp_array_fc="\link api-tir-fc-array Array field classes\endlink"
+ALIASES                += bt_cp_sarray_fc="Static \link api-tir-fc-array array field classes\endlink"
+ALIASES                += bt_cp_darray_fc="Dynamic \link api-tir-fc-array array field classes\endlink"
+ALIASES                += bt_cp_opt_fc="\link api-tir-fc-opt Option field classes\endlink"
+ALIASES                += bt_cp_var_fc="\link api-tir-fc-var Variant field classes\endlink"
+
+# Aliases: field object types: singular
+ALIASES                += bt_field="\link api-tir-field field\endlink"
+ALIASES                += bt_ba_field="\link api-tir-field-ba bit array field\endlink"
+ALIASES                += bt_bool_field="\link api-tir-field-bool boolean field\endlink"
+ALIASES                += bt_int_field="\link api-tir-field-int integer field\endlink"
+ALIASES                += bt_sint_field="signed \link api-tir-field-int integer field\endlink"
+ALIASES                += bt_uint_field="unsigned \link api-tir-field-int integer field\endlink"
+ALIASES                += bt_real_field="\link api-tir-field-real real field\endlink"
+ALIASES                += bt_sreal_field="single-precision \link api-tir-field-real real field\endlink"
+ALIASES                += bt_dreal_field="double-precision \link api-tir-field-real real field\endlink"
+ALIASES                += bt_enum_field="\link api-tir-field-enum enumeration field\endlink"
+ALIASES                += bt_senum_field="signed \link api-tir-field-enum enumeration field\endlink"
+ALIASES                += bt_uenum_field="unsigned \link api-tir-field-enum enumeration field\endlink"
+ALIASES                += bt_string_field="\link api-tir-field-string string field\endlink"
+ALIASES                += bt_struct_field="\link api-tir-field-struct structure field\endlink"
+ALIASES                += bt_array_field="\link api-tir-field-array array field\endlink"
+ALIASES                += bt_sarray_field="static \link api-tir-field-array array field\endlink"
+ALIASES                += bt_darray_field="dynamic \link api-tir-field-array array field\endlink"
+ALIASES                += bt_opt_field="\link api-tir-field-opt option field\endlink"
+ALIASES                += bt_var_field="\link api-tir-field-var variant field\endlink"
+
+# Aliases: field object types: singular, capitalized
+ALIASES                += bt_c_field="\link api-tir-field Field\endlink"
+ALIASES                += bt_c_ba_field="\link api-tir-field-ba Bit array field\endlink"
+ALIASES                += bt_c_bool_field="\link api-tir-field-bool Boolean field\endlink"
+ALIASES                += bt_c_int_field="\link api-tir-field-int Integer field\endlink"
+ALIASES                += bt_c_sint_field="Signed \link api-tir-field-int integer field\endlink"
+ALIASES                += bt_c_uint_field="Unsigned \link api-tir-field-int integer field\endlink"
+ALIASES                += bt_c_real_field="\link api-tir-field-real Real field\endlink"
+ALIASES                += bt_c_sreal_field="Single-precision \link api-tir-field-real real field\endlink"
+ALIASES                += bt_c_dreal_field="Double-precision \link api-tir-field-real real field\endlink"
+ALIASES                += bt_c_enum_field="\link api-tir-field-enum Enumeration field\endlink"
+ALIASES                += bt_c_senum_field="Signed \link api-tir-field-enum enumeration field\endlink"
+ALIASES                += bt_c_uenum_field="Unsigned \link api-tir-field-enum enumeration field\endlink"
+ALIASES                += bt_c_string_field="\link api-tir-field-string String field\endlink"
+ALIASES                += bt_c_struct_field="\link api-tir-field-struct Structure field\endlink"
+ALIASES                += bt_c_array_field="\link api-tir-field-array Array field\endlink"
+ALIASES                += bt_c_sarray_field="Static \link api-tir-field-array array field\endlink"
+ALIASES                += bt_c_darray_field="Dynamic \link api-tir-field-array array field\endlink"
+ALIASES                += bt_c_opt_field="\link api-tir-field-opt Option field\endlink"
+ALIASES                += bt_c_var_field="\link api-tir-field-var Variant field\endlink"
+
+# Aliases: field object types: plural
+ALIASES                += bt_p_field="\link api-tir-field fields\endlink"
+ALIASES                += bt_p_ba_field="\link api-tir-field-ba bit array fields\endlink"
+ALIASES                += bt_p_bool_field="\link api-tir-field-bool boolean fields\endlink"
+ALIASES                += bt_p_int_field="\link api-tir-field-int integer fields\endlink"
+ALIASES                += bt_p_sint_field="signed \link api-tir-field-int integer fields\endlink"
+ALIASES                += bt_p_uint_field="unsigned \link api-tir-field-int integer fields\endlink"
+ALIASES                += bt_p_real_field="\link api-tir-field-real real fields\endlink"
+ALIASES                += bt_p_sreal_field="single-precision \link api-tir-field-real real fields\endlink"
+ALIASES                += bt_p_dreal_field="double-precision \link api-tir-field-real real fields\endlink"
+ALIASES                += bt_p_enum_field="\link api-tir-field-enum enumeration fields\endlink"
+ALIASES                += bt_p_senum_field="signed \link api-tir-field-enum enumeration fields\endlink"
+ALIASES                += bt_p_uenum_field="unsigned \link api-tir-field-enum enumeration fields\endlink"
+ALIASES                += bt_p_string_field="\link api-tir-field-string string fields\endlink"
+ALIASES                += bt_p_struct_field="\link api-tir-field-struct structure fields\endlink"
+ALIASES                += bt_p_array_field="\link api-tir-field-array array fields\endlink"
+ALIASES                += bt_p_sarray_field="static \link api-tir-field-array array fields\endlink"
+ALIASES                += bt_p_darray_field="dynamic \link api-tir-field-array array fields\endlink"
+ALIASES                += bt_p_opt_field="\link api-tir-field-opt option fields\endlink"
+ALIASES                += bt_p_var_field="\link api-tir-field-var variant fields\endlink"
+
+# Aliases: field object types: plural, capitalized
+ALIASES                += bt_cp_field="\link api-tir-field Fields\endlink"
+ALIASES                += bt_cp_ba_field="\link api-tir-field-ba Bit array fields\endlink"
+ALIASES                += bt_cp_bool_field="\link api-tir-field-bool Boolean fields\endlink"
+ALIASES                += bt_cp_int_field="\link api-tir-field-int Integer fields\endlink"
+ALIASES                += bt_cp_sint_field="Signed \link api-tir-field-int integer fields\endlink"
+ALIASES                += bt_cp_uint_field="Unsigned \link api-tir-field-int integer fields\endlink"
+ALIASES                += bt_cp_real_field="\link api-tir-field-real Real fields\endlink"
+ALIASES                += bt_cp_sreal_field="Single-precision \link api-tir-field-real real fields\endlink"
+ALIASES                += bt_cp_dreal_field="Double-precision \link api-tir-field-real real fields\endlink"
+ALIASES                += bt_cp_enum_field="\link api-tir-field-enum Enumeration fields\endlink"
+ALIASES                += bt_cp_senum_field="Signed \link api-tir-field-enum enumeration fields\endlink"
+ALIASES                += bt_cp_uenum_field="Unsigned \link api-tir-field-enum enumeration fields\endlink"
+ALIASES                += bt_cp_string_field="\link api-tir-field-string String fields\endlink"
+ALIASES                += bt_cp_struct_field="\link api-tir-field-struct Structure fields\endlink"
+ALIASES                += bt_cp_array_field="\link api-tir-field-array Array fields\endlink"
+ALIASES                += bt_cp_sarray_field="Static \link api-tir-field-array array fields\endlink"
+ALIASES                += bt_cp_darray_field="Dynamic \link api-tir-field-array array fields\endlink"
+ALIASES                += bt_cp_opt_field="\link api-tir-field-opt Option fields\endlink"
+ALIASES                += bt_cp_var_field="\link api-tir-field-var Variant fields\endlink"
+
+# Aliases: trace IR objects: singular
+ALIASES                += bt_clock_cls="\link api-tir-clock-cls clock class\endlink"
+ALIASES                += bt_cs="\link api-tir-cs clock snapshot\endlink"
+ALIASES                += bt_ev_cls="\link api-tir-ev-cls event class\endlink"
+ALIASES                += bt_ev="\link api-tir-ev event\endlink"
+ALIASES                += bt_field_path="\link api-tir-field-path field path\endlink"
+ALIASES                += bt_pkt="\link api-tir-pkt packet\endlink"
+ALIASES                += bt_stream_cls="\link api-tir-stream-cls stream class\endlink"
+ALIASES                += bt_stream="\link api-tir-stream stream\endlink"
+ALIASES                += bt_trace="\link api-tir-trace trace\endlink"
+ALIASES                += bt_trace_cls="\link api-tir-trace-cls trace class\endlink"
+
+# Aliases: trace IR objects: singular, capitalized
+ALIASES                += bt_c_clock_cls="\link api-tir-clock-cls Clock class\endlink"
+ALIASES                += bt_c_cs="\link api-tir-cs Clock snapshot\endlink"
+ALIASES                += bt_c_ev_cls="\link api-tir-ev-cls Event class\endlink"
+ALIASES                += bt_c_ev="\link api-tir-ev Event\endlink"
+ALIASES                += bt_c_field_path="\link api-tir-field-path Field path\endlink"
+ALIASES                += bt_c_pkt="\link api-tir-pkt Packet\endlink"
+ALIASES                += bt_c_stream_cls="\link api-tir-stream-cls Stream class\endlink"
+ALIASES                += bt_c_stream="\link api-tir-stream Stream\endlink"
+ALIASES                += bt_c_trace="\link api-tir-trace Trace\endlink"
+ALIASES                += bt_c_trace_cls="\link api-tir-trace-cls Trace class\endlink"
+
+# Aliases: trace IR objects: plural
+ALIASES                += bt_p_clock_cls="\link api-tir-clock-cls clock classes\endlink"
+ALIASES                += bt_p_cs="\link api-tir-cs clock snapshots\endlink"
+ALIASES                += bt_p_ev_cls="\link api-tir-ev-cls event classes\endlink"
+ALIASES                += bt_p_ev="\link api-tir-ev events\endlink"
+ALIASES                += bt_p_field_path="\link api-tir-field-path field paths\endlink"
+ALIASES                += bt_p_pkt="\link api-tir-pkt packets\endlink"
+ALIASES                += bt_p_stream_cls="\link api-tir-stream-cls stream classes\endlink"
+ALIASES                += bt_p_stream="\link api-tir-stream streams\endlink"
+ALIASES                += bt_p_trace="\link api-tir-trace traces\endlink"
+ALIASES                += bt_p_trace_cls="\link api-tir-trace-cls trace classes\endlink"
+
+# Aliases: trace IR objects: plural, capitalized
+ALIASES                += bt_cp_clock_cls="\link api-tir-clock-cls Clock classes\endlink"
+ALIASES                += bt_cp_cs="\link api-tir-cs Clock snapshots\endlink"
+ALIASES                += bt_cp_ev_cls="\link api-tir-ev-cls event classes\endlink"
+ALIASES                += bt_cp_ev="\link api-tir-ev Events\endlink"
+ALIASES                += bt_cp_field_path="\link api-tir-field-path Field paths\endlink"
+ALIASES                += bt_cp_pkt="\link api-tir-pkt Packets\endlink"
+ALIASES                += bt_cp_stream_cls="\link api-tir-stream-cls Stream classes\endlink"
+ALIASES                += bt_cp_stream="\link api-tir-stream Streams\endlink"
+ALIASES                += bt_cp_trace="\link api-tir-trace Traces\endlink"
+ALIASES                += bt_cp_trace_cls="\link api-tir-trace-cls Trace classes\endlink"
+
+# Aliases: graph objects: singular
+ALIASES                += bt_comp="\link api-comp component\endlink"
+ALIASES                += bt_comp_cls="\link api-comp-cls component class\endlink"
+ALIASES                += bt_comp_descr_set="\link api-comp-descr-set component descriptor set\endlink"
+ALIASES                += bt_conn="\link api-conn connection\endlink"
+ALIASES                += bt_flt_comp="\link api-comp-flt filter component\endlink"
+ALIASES                += bt_flt_comp_cls="\link api-comp-cls-flt filter component class\endlink"
+ALIASES                += bt_graph="\link api-graph graph\endlink"
+ALIASES                += bt_intr="\link api-intr interrupter\endlink"
+ALIASES                += bt_ip_msg_iter="\link api-ip-msg-iter self component input port message iterator\endlink"
+ALIASES                += bt_iport="\link api-port-in input port\endlink"
+ALIASES                += bt_mip="\link api-msg-mip Message Interchange Protocol\endlink"
+ALIASES                += bt_msg_iter="\link api-msg-iter message iterator\endlink"
+ALIASES                += bt_msg_iter_cls="\link api-msg-iter-cls message iterator class\endlink"
+ALIASES                += bt_oport="\link api-port-out output port\endlink"
+ALIASES                += bt_port="\link api-port port\endlink"
+ALIASES                += bt_priv_qexec="\link api-priv-qexec private query executor\endlink"
+ALIASES                += bt_qexec="\link api-qexec query executor\endlink"
+ALIASES                += bt_self_comp="\link api-self-comp self component\endlink"
+ALIASES                += bt_self_comp_port="\link api-self-comp-port self component port\endlink"
+ALIASES                += bt_self_comp_iport="\link api-self-comp-port self component input port\endlink"
+ALIASES                += bt_self_comp_oport="\link api-self-comp-port self component output port\endlink"
+ALIASES                += bt_self_comp_cls="\link api-self-comp-cls self component class\endlink"
+ALIASES                += bt_self_flt_comp="\link api-self-comp self filter component\endlink"
+ALIASES                += bt_self_flt_comp_cls="\link api-self-comp-cls self filter component class\endlink"
+ALIASES                += bt_self_msg_iter="\link api-self-msg-iter self message iterator\endlink"
+ALIASES                += bt_self_sink_comp="\link api-self-comp self sink component\endlink"
+ALIASES                += bt_self_sink_comp_cls="\link api-self-comp-cls self sink component class\endlink"
+ALIASES                += bt_self_src_comp="\link api-self-comp self source component\endlink"
+ALIASES                += bt_self_src_comp_cls="\link api-self-comp-cls self source component class\endlink"
+ALIASES                += bt_sink_comp="\link api-comp-sink sink component\endlink"
+ALIASES                += bt_sink_comp_cls="\link api-comp-cls-sink sink component class\endlink"
+ALIASES                += bt_src_comp="\link api-comp-src source component\endlink"
+ALIASES                += bt_src_comp_cls="\link api-comp-cls-src source component class\endlink"
+
+# Aliases: graph objects: singular, capitalized
+ALIASES                += bt_c_comp="\link api-comp Component\endlink"
+ALIASES                += bt_c_comp_cls="\link api-comp-cls Component class\endlink"
+ALIASES                += bt_c_comp_descr="\link api-comp-descr-set Component descriptor set\endlink"
+ALIASES                += bt_c_conn="\link api-conn Connection\endlink"
+ALIASES                += bt_c_flt_comp="\link api-comp-flt Filter component\endlink"
+ALIASES                += bt_c_flt_comp_cls="\link api-comp-cls-flt Filter component class\endlink"
+ALIASES                += bt_c_graph="\link api-graph Graph\endlink"
+ALIASES                += bt_c_intr="\link api-intr Interrupter\endlink"
+ALIASES                += bt_c_ip_msg_iter="\link api-ip-msg-iter Self component input port message iterator\endlink"
+ALIASES                += bt_c_iport="\link api-port-in Input port\endlink"
+ALIASES                += bt_c_msg_iter="\link api-msg-iter Message iterator\endlink"
+ALIASES                += bt_c_msg_iter_cls="\link api-msg-iter-cls Message iterator class\endlink"
+ALIASES                += bt_c_oport="\link api-port-out Output port\endlink"
+ALIASES                += bt_c_port="\link api-port Port\endlink"
+ALIASES                += bt_c_priv_qexec="\link api-priv-qexec Private query executor\endlink"
+ALIASES                += bt_c_qexec="\link api-qexec Query executor\endlink"
+ALIASES                += bt_c_self_comp="\link api-self-comp Self component\endlink"
+ALIASES                += bt_c_self_comp_port="\link api-self-comp-port Self component port\endlink"
+ALIASES                += bt_c_self_comp_iport="\link api-self-comp-port Self component input port\endlink"
+ALIASES                += bt_c_self_comp_oport="\link api-self-comp-port Self component output port\endlink"
+ALIASES                += bt_c_self_comp_cls="\link api-self-comp-cls Self component class\endlink"
+ALIASES                += bt_c_self_flt_comp="\link api-self-comp Self filter component\endlink"
+ALIASES                += bt_c_self_flt_comp_cls="\link api-self-comp-cls Self filter component class\endlink"
+ALIASES                += bt_c_self_msg_iter="\link api-self-msg-iter Self message iterator\endlink"
+ALIASES                += bt_c_self_sink_comp="\link api-self-comp Self sink component\endlink"
+ALIASES                += bt_c_self_sink_comp_cls="\link api-self-comp-cls Self sink component class\endlink"
+ALIASES                += bt_c_self_src_comp="\link api-self-comp Self source component\endlink"
+ALIASES                += bt_c_self_src_comp_cls="\link api-self-comp-cls Self source component class\endlink"
+ALIASES                += bt_c_sink_comp="\link api-comp-sink Sink component\endlink"
+ALIASES                += bt_c_sink_comp_cls="\link api-comp-cls-sink Sink component class\endlink"
+ALIASES                += bt_c_src_comp="\link api-comp-src Source component\endlink"
+ALIASES                += bt_c_src_comp_cls="\link api-comp-cls-src Source component class\endlink"
+
+# Aliases: graph objects: plural
+ALIASES                += bt_p_comp="\link api-comp components\endlink"
+ALIASES                += bt_p_comp_cls="\link api-comp-cls component classes\endlink"
+ALIASES                += bt_p_comp_descr="\link api-comp-descr-set component descriptor sets\endlink"
+ALIASES                += bt_p_conn="\link api-conn connections\endlink"
+ALIASES                += bt_p_flt_comp="\link api-comp-flt filter components\endlink"
+ALIASES                += bt_p_flt_comp_cls="\link api-comp-cls-flt filter component classes\endlink"
+ALIASES                += bt_p_graph="\link api-graph graphs\endlink"
+ALIASES                += bt_p_intr="\link api-intr interrupters\endlink"
+ALIASES                += bt_p_ip_msg_iter="\link api-ip-msg-iter self component input port message iterators\endlink"
+ALIASES                += bt_p_iport="\link api-port-in input ports\endlink"
+ALIASES                += bt_p_msg_iter="\link api-msg-iter message iterators\endlink"
+ALIASES                += bt_p_msg_iter_cls="\link api-msg-iter-cls message iterator classes\endlink"
+ALIASES                += bt_p_oport="\link api-port-out output ports\endlink"
+ALIASES                += bt_p_port="\link api-port ports\endlink"
+ALIASES                += bt_p_priv_qexec="\link api-priv-qexec private query executors\endlink"
+ALIASES                += bt_p_qexec="\link api-qexec query executors\endlink"
+ALIASES                += bt_p_self_comp="\link api-self-comp self components\endlink"
+ALIASES                += bt_p_self_comp_port="\link api-self-comp-port self component ports\endlink"
+ALIASES                += bt_p_self_comp_iport="\link api-self-comp-port self component input ports\endlink"
+ALIASES                += bt_p_self_comp_oport="\link api-self-comp-port self component output ports\endlink"
+ALIASES                += bt_p_self_comp_cls="\link api-self-comp-cls self component classes\endlink"
+ALIASES                += bt_p_self_flt_comp="\link api-self-comp self filter components\endlink"
+ALIASES                += bt_p_self_flt_comp_cls="\link api-self-comp-cls self filter component classes\endlink"
+ALIASES                += bt_p_self_msg_iter="\link api-self-msg-iter self message iterators\endlink"
+ALIASES                += bt_p_self_sink_comp="\link api-self-comp self sink components\endlink"
+ALIASES                += bt_p_self_sink_comp_cls="\link api-self-comp-cls self sink component classes\endlink"
+ALIASES                += bt_p_self_src_comp="\link api-self-comp self source components\endlink"
+ALIASES                += bt_p_self_src_comp_cls="\link api-self-comp-cls self source component classes\endlink"
+ALIASES                += bt_p_sink_comp="\link api-comp-sink sink components\endlink"
+ALIASES                += bt_p_sink_comp_cls="\link api-comp-cls-sink sink component classes\endlink"
+ALIASES                += bt_p_src_comp="\link api-comp-src source components\endlink"
+ALIASES                += bt_p_src_comp_cls="\link api-comp-cls-src source component classes\endlink"
+
+# Aliases: graph objects: plural, capitalized
+ALIASES                += bt_cp_comp="\link api-comp Components\endlink"
+ALIASES                += bt_cp_comp_cls="\link api-comp-cls Component classes\endlink"
+ALIASES                += bt_cp_comp_descr="\link api-comp-descr-set Component descriptor sets\endlink"
+ALIASES                += bt_cp_conn="\link api-conn Connections\endlink"
+ALIASES                += bt_cp_flt_comp="\link api-comp-flt Filter components\endlink"
+ALIASES                += bt_cp_flt_comp_cls="\link api-comp-cls-flt Filter component classes\endlink"
+ALIASES                += bt_cp_graph="\link api-graph Graphs\endlink"
+ALIASES                += bt_cp_intr="\link api-intr Interrupters\endlink"
+ALIASES                += bt_cp_ip_msg_iter="\link api-ip-msg-iter Self component input port message iterators\endlink"
+ALIASES                += bt_cp_iport="\link api-port-in Input ports\endlink"
+ALIASES                += bt_cp_msg_iter="\link api-msg-iter Message iterators\endlink"
+ALIASES                += bt_cp_msg_iter_cls="\link api-msg-iter-cls Message iterator classes\endlink"
+ALIASES                += bt_cp_oport="\link api-port-out Output ports\endlink"
+ALIASES                += bt_cp_port="\link api-port Ports\endlink"
+ALIASES                += bt_cp_priv_qexec="\link api-priv-qexec Private query executors\endlink"
+ALIASES                += bt_cp_qexec="\link api-qexec Query executors\endlink"
+ALIASES                += bt_cp_self_comp="\link api-self-comp Self components\endlink"
+ALIASES                += bt_cp_self_comp_port="\link api-self-comp-port Self component ports\endlink"
+ALIASES                += bt_cp_self_comp_iport="\link api-self-comp-port Self component input ports\endlink"
+ALIASES                += bt_cp_self_comp_oport="\link api-self-comp-port Self component output ports\endlink"
+ALIASES                += bt_cp_self_comp_cls="\link api-self-comp-cls Self component classes\endlink"
+ALIASES                += bt_cp_self_flt_comp="\link api-self-comp Self filter components\endlink"
+ALIASES                += bt_cp_self_flt_comp_cls="\link api-self-comp-cls Self filter component classes\endlink"
+ALIASES                += bt_cp_self_msg_iter="\link api-self-msg-iter Self message iterators\endlink"
+ALIASES                += bt_cp_self_sink_comp="\link api-self-comp Self sink components\endlink"
+ALIASES                += bt_cp_self_sink_comp_cls="\link api-self-comp-cls Self sink component classes\endlink"
+ALIASES                += bt_cp_self_src_comp="\link api-self-comp Self source components\endlink"
+ALIASES                += bt_cp_self_src_comp_cls="\link api-self-comp-cls Self source component classes\endlink"
+ALIASES                += bt_cp_sink_comp="\link api-comp-sink Sink components\endlink"
+ALIASES                += bt_cp_sink_comp_cls="\link api-comp-cls-sink Sink component classes\endlink"
+ALIASES                += bt_cp_src_comp="\link api-comp-src Source components\endlink"
+ALIASES                += bt_cp_src_comp_cls="\link api-comp-cls-src Source component classes\endlink"
+
+# Aliases: message objects: singular
+ALIASES                += bt_disc_ev_msg="\link api-msg-disc-ev discarded events message\endlink"
+ALIASES                += bt_disc_pkt_msg="\link api-msg-disc-pkt discarded packets message\endlink"
+ALIASES                += bt_ev_msg="\link api-msg-ev event message\endlink"
+ALIASES                += bt_inac_msg="\link api-msg-inac message iterator inactivity message\endlink"
+ALIASES                += bt_msg="\link api-msg message\endlink"
+ALIASES                += bt_pb_msg="\link api-msg-pb packet beginning message\endlink"
+ALIASES                += bt_pe_msg="\link api-msg-pe packet end message\endlink"
+ALIASES                += bt_sb_msg="\link api-msg-sb stream beginning message\endlink"
+ALIASES                += bt_se_msg="\link api-msg-se stream end message\endlink"
+
+# Aliases: message objects: singular, capitalized
+ALIASES                += bt_c_disc_ev_msg="\link api-msg-disc-ev Discarded events message\endlink"
+ALIASES                += bt_c_disc_pkt_msg="\link api-msg-disc-pkt Discarded packets message\endlink"
+ALIASES                += bt_c_ev_msg="\link api-msg-ev Event message\endlink"
+ALIASES                += bt_c_inac_msg="\link api-msg-inac Message iterator inactivity message\endlink"
+ALIASES                += bt_c_msg="\link api-msg Message\endlink"
+ALIASES                += bt_c_pb_msg="\link api-msg-pb Packet beginning message\endlink"
+ALIASES                += bt_c_pe_msg="\link api-msg-pe Packet end message\endlink"
+ALIASES                += bt_c_sb_msg="\link api-msg-sb Stream beginning message\endlink"
+ALIASES                += bt_c_se_msg="\link api-msg-se Stream end message\endlink"
+
+# Aliases: message objects: plural
+ALIASES                += bt_p_disc_ev_msg="\link api-msg-disc-ev discarded events messages\endlink"
+ALIASES                += bt_p_disc_pkt_msg="\link api-msg-disc-pkt discarded packets messages\endlink"
+ALIASES                += bt_p_ev_msg="\link api-msg-ev event messages\endlink"
+ALIASES                += bt_p_inac_msg="\link api-msg-inac message iterator inactivity messages\endlink"
+ALIASES                += bt_p_msg="\link api-msg messages\endlink"
+ALIASES                += bt_p_pb_msg="\link api-msg-pb packet beginning messages\endlink"
+ALIASES                += bt_p_pe_msg="\link api-msg-pe packet end messages\endlink"
+ALIASES                += bt_p_sb_msg="\link api-msg-sb stream beginning messages\endlink"
+ALIASES                += bt_p_se_msg="\link api-msg-se stream end messages\endlink"
+
+# Aliases: message objects: plural, capitalized
+ALIASES                += bt_cp_disc_ev_msg="\link api-msg-disc-ev Discarded events messages\endlink"
+ALIASES                += bt_cp_disc_pkt_msg="\link api-msg-disc-pkt Discarded packets messages\endlink"
+ALIASES                += bt_cp_ev_msg="\link api-msg-ev Event messages\endlink"
+ALIASES                += bt_cp_inac_msg="\link api-msg-inac Message iterator inactivity messages\endlink"
+ALIASES                += bt_cp_msg="\link api-msg Messages\endlink"
+ALIASES                += bt_cp_pb_msg="\link api-msg-pb Packet beginning messages\endlink"
+ALIASES                += bt_cp_pe_msg="\link api-msg-pe Packet end messages\endlink"
+ALIASES                += bt_cp_sb_msg="\link api-msg-sb Stream beginning messages\endlink"
+ALIASES                += bt_cp_se_msg="\link api-msg-se Stream end messages\endlink"
+
+# Aliases: plugin objects: singular
+ALIASES                += bt_plugin="\link api-plugin plugin\endlink"
+ALIASES                += bt_plugin_set="\link api-plugin plugin set\endlink"
+
+# Aliases: plugin objects: singular, capitalized
+ALIASES                += bt_c_plugin="\link api-plugin Plugin\endlink"
+ALIASES                += bt_c_plugin_set="\link api-plugin Plugin set\endlink"
+
+# Aliases: plugin objects: plural
+ALIASES                += bt_p_plugin="\link api-plugin plugins\endlink"
+ALIASES                += bt_p_plugin_set="\link api-plugin plugin sets\endlink"
+
+# Aliases: plugin objects: plural, capitalized
+ALIASES                += bt_cp_plugin="\link api-plugin Plugins\endlink"
+ALIASES                += bt_cp_plugin_set="\link api-plugin Plugin sets\endlink"
+
+# Aliases: value objects: singular
+ALIASES                += bt_val="\link api-val value\endlink"
+ALIASES                += bt_null_val="null \link api-val value\endlink"
+ALIASES                += bt_bool_val="boolean \link api-val value\endlink"
+ALIASES                += bt_sint_val="signed integer \link api-val value\endlink"
+ALIASES                += bt_uint_val="unsigned integer \link api-val value\endlink"
+ALIASES                += bt_real_val="real \link api-val value\endlink"
+ALIASES                += bt_string_val="string \link api-val value\endlink"
+ALIASES                += bt_map_val="map \link api-val value\endlink"
+ALIASES                += bt_array_val="array \link api-val value\endlink"
+
+# Aliases: value objects: singular, capitalized
+ALIASES                += bt_c_val="\link api-val Value\endlink"
+ALIASES                += bt_c_null_val="Null \link api-val value\endlink"
+ALIASES                += bt_c_bool_val="Boolean \link api-val value\endlink"
+ALIASES                += bt_c_sint_val="Signed integer \link api-val value\endlink"
+ALIASES                += bt_c_uint_val="Unsigned integer \link api-val value\endlink"
+ALIASES                += bt_c_real_val="Real \link api-val value\endlink"
+ALIASES                += bt_c_string_val="String \link api-val value\endlink"
+ALIASES                += bt_c_map_val="Map \link api-val value\endlink"
+ALIASES                += bt_c_array_val="Array \link api-val value\endlink"
+
+# Aliases: value objects: plural
+ALIASES                += bt_p_val="\link api-val values\endlink"
+ALIASES                += bt_p_null_val="null \link api-val values\endlink"
+ALIASES                += bt_p_bool_val="boolean \link api-val values\endlink"
+ALIASES                += bt_p_sint_val="signed integer \link api-val values\endlink"
+ALIASES                += bt_p_uint_val="unsigned integer \link api-val values\endlink"
+ALIASES                += bt_p_real_val="real \link api-val values\endlink"
+ALIASES                += bt_p_string_val="string \link api-val values\endlink"
+ALIASES                += bt_p_map_val="map \link api-val values\endlink"
+ALIASES                += bt_p_array_val="array \link api-val values\endlink"
+
+# Aliases: value objects: plural, capitalized
+ALIASES                += bt_cp_val="\link api-val Values\endlink"
+ALIASES                += bt_cp_null_val="Null \link api-val values\endlink"
+ALIASES                += bt_cp_bool_val="Boolean \link api-val values\endlink"
+ALIASES                += bt_cp_sint_val="Signed integer \link api-val values\endlink"
+ALIASES                += bt_cp_uint_val="Unsigned integer \link api-val values\endlink"
+ALIASES                += bt_cp_real_val="Real \link api-val values\endlink"
+ALIASES                += bt_cp_string_val="String \link api-val values\endlink"
+ALIASES                += bt_cp_map_val="Map \link api-val values\endlink"
+ALIASES                += bt_cp_array_val="Array \link api-val values\endlink"
+
+# Aliases: integer range set objects: singular
+ALIASES                += bt_sint_rg="\link api-int-rs signed integer range\endlink"
+ALIASES                += bt_uint_rg="\link api-int-rs unsigned integer range\endlink"
+ALIASES                += bt_int_rs="\link api-int-rs integer range set\endlink"
+ALIASES                += bt_sint_rs="\link api-int-rs signed integer range set\endlink"
+ALIASES                += bt_uint_rs="\link api-int-rs unsigned integer range set\endlink"
+
+# Aliases: integer range set objects: singular, capitalized
+ALIASES                += bt_c_sint_rg="\link api-int-rs Signed integer range\endlink"
+ALIASES                += bt_c_uint_rg="\link api-int-rs Unsigned integer range\endlink"
+ALIASES                += bt_c_int_rs="\link api-int-rs Integer range set\endlink"
+ALIASES                += bt_c_sint_rs="\link api-int-rs Signed integer range set\endlink"
+ALIASES                += bt_c_uint_rs="\link api-int-rs Unsigned integer range set\endlink"
+
+# Aliases: integer range set objects: plural
+ALIASES                += bt_p_sint_rg="\link api-int-rs signed integer ranges\endlink"
+ALIASES                += bt_p_uint_rg="\link api-int-rs unsigned integer ranges\endlink"
+ALIASES                += bt_p_int_rs="\link api-int-rs integer range sets\endlink"
+ALIASES                += bt_p_sint_rs="\link api-int-rs signed integer range sets\endlink"
+ALIASES                += bt_p_uint_rs="\link api-int-rs unsigned integer range sets\endlink"
+
+# Aliases: integer range set objects: plural, capitalized
+ALIASES                += bt_cp_sint_rg="\link api-int-rs Signed integer ranges\endlink"
+ALIASES                += bt_cp_uint_rg="\link api-int-rs Unsigned integer ranges\endlink"
+ALIASES                += bt_cp_int_rs="\link api-int-rs Integer range sets\endlink"
+ALIASES                += bt_cp_sint_rs="\link api-int-rs Signed integer range sets\endlink"
+ALIASES                += bt_cp_uint_rs="\link api-int-rs Unsigned integer range sets\endlink"
+
+OPTIMIZE_OUTPUT_FOR_C   = YES
+MARKDOWN_SUPPORT        = NO
+TOC_INCLUDE_HEADINGS    = 0
+AUTOLINK_SUPPORT        = YES
+SUBGROUPING             = YES
+INLINE_GROUPED_CLASSES  = NO
+INLINE_SIMPLE_STRUCTS   = NO
+TYPEDEF_HIDES_STRUCT    = NO
+LOOKUP_CACHE_SIZE       = 0
+
+EXTRACT_ALL             = NO
+EXTRACT_PRIVATE         = NO
+EXTRACT_PACKAGE         = NO
+EXTRACT_STATIC          = YES
+EXTRACT_LOCAL_CLASSES   = YES
+EXTRACT_LOCAL_METHODS   = NO
+EXTRACT_ANON_NSPACES    = NO
+HIDE_UNDOC_MEMBERS      = YES
+HIDE_UNDOC_CLASSES      = YES
+HIDE_FRIEND_COMPOUNDS   = NO
+HIDE_IN_BODY_DOCS       = YES
+INTERNAL_DOCS           = NO
+CASE_SENSE_NAMES        = NO
+HIDE_SCOPE_NAMES        = NO
+HIDE_COMPOUND_REFERENCE = NO
+SHOW_INCLUDE_FILES      = NO
+SHOW_GROUPED_MEMB_INC   = NO
+FORCE_LOCAL_INCLUDES    = NO
+INLINE_INFO             = YES
+SORT_MEMBER_DOCS        = NO
+SORT_BRIEF_DOCS         = NO
+SORT_MEMBERS_CTORS_1ST  = NO
+SORT_GROUP_NAMES        = NO
+SORT_BY_SCOPE_NAME      = NO
+STRICT_PROTO_MATCHING   = NO
+GENERATE_TODOLIST       = YES
+GENERATE_TESTLIST       = YES
+GENERATE_BUGLIST        = YES
+GENERATE_DEPRECATEDLIST = YES
+ENABLED_SECTIONS        =
+MAX_INITIALIZER_LINES   = 0
+SHOW_USED_FILES         = NO
+SHOW_FILES              = NO
+SHOW_NAMESPACES         = NO
+FILE_VERSION_FILTER     =
+LAYOUT_FILE             = "@srcdir@/DoxygenLayout.xml"
+CITE_BIB_FILES          =
+
+QUIET                   = NO
+WARNINGS                = YES
+WARN_IF_UNDOCUMENTED    = YES
+WARN_IF_DOC_ERROR       = YES
+WARN_NO_PARAMDOC        = YES
+WARN_AS_ERROR           = NO
+WARN_FORMAT             = "$file:$line: $text"
+WARN_LOGFILE            =
+
+INPUT                   = "@srcdir@/dox/main-page.dox" \
+                          "@srcdir@/dox/api-fund.dox" \
+                          "@srcdir@/dox/guides.dox" \
+                          "@srcdir@/dox/examples.dox" \
+                          "@top_srcdir@/include/babeltrace2/types.h" \
+                          "@top_srcdir@/include/babeltrace2/error-reporting.h" \
+                          "@top_srcdir@/include/babeltrace2/util.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/graph.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/component-class-dev.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/message.h" \
+                          "@srcdir@/dox/group-trace-ir.dox" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/clock-class.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/clock-snapshot.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/event.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/event-class.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/field.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/field-class.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/field-path.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/packet.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/stream.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/stream-class.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/trace.h" \
+                          "@top_srcdir@/include/babeltrace2/trace-ir/trace-class.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/message-iterator.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/message-iterator-class.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/self-message-iterator.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/private-query-executor.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/self-component.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/self-component-port.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/self-component-class.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/component.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/component-class.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/component-descriptor-set.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/connection.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/port.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/interrupter.h" \
+                          "@top_srcdir@/include/babeltrace2/graph/query-executor.h" \
+                          "@top_srcdir@/include/babeltrace2/integer-range-set.h" \
+                          "@top_srcdir@/include/babeltrace2/version.h" \
+                          "@top_srcdir@/include/babeltrace2/logging.h" \
+                          "@top_srcdir@/include/babeltrace2/plugin/plugin-dev.h" \
+                          "@top_srcdir@/include/babeltrace2/plugin/plugin-loading.h" \
+                          "@top_srcdir@/include/babeltrace2/value.h"
+INPUT_ENCODING          = UTF-8
+FILE_PATTERNS           = *.h *.hh *.hpp *.dox
+RECURSIVE               = NO
+EXCLUDE                 =
+EXCLUDE_SYMLINKS        = NO
+EXCLUDE_PATTERNS        =
+EXCLUDE_SYMBOLS         =
+EXAMPLE_PATH            = "@srcdir@/examples"
+EXAMPLE_PATTERNS        = *
+EXAMPLE_RECURSIVE       = NO
+IMAGE_PATH              = "@srcdir@/images"
+INPUT_FILTER            =
+FILTER_PATTERNS         =
+FILTER_SOURCE_FILES     = NO
+FILTER_SOURCE_PATTERNS  =
+USE_MDFILE_AS_MAINPAGE  =
+
+SOURCE_BROWSER          = NO
+INLINE_SOURCES          = NO
+STRIP_CODE_COMMENTS     = YES
+REFERENCED_BY_RELATION  = NO
+REFERENCES_RELATION     = NO
+REFERENCES_LINK_SOURCE  = YES
+SOURCE_TOOLTIPS         = YES
+USE_HTAGS               = NO
+VERBATIM_HEADERS        = YES
+
+ALPHABETICAL_INDEX      = YES
+COLS_IN_ALPHA_INDEX     = 5
+IGNORE_PREFIX           =
+
+OUTPUT_DIRECTORY        = @builddir@/output
+
+GENERATE_HTML           = YES
+HTML_FILE_EXTENSION     = .html
+HTML_HEADER             =
+HTML_FOOTER             =
+HTML_STYLESHEET         =
+HTML_EXTRA_STYLESHEET   = @srcdir@/style.css
+HTML_EXTRA_FILES        =
+HTML_COLORSTYLE_HUE     = 220
+HTML_COLORSTYLE_SAT     = 100
+HTML_COLORSTYLE_GAMMA   = 120
+HTML_TIMESTAMP          = NO
+HTML_DYNAMIC_SECTIONS   = NO
+HTML_DYNAMIC_MENUS      = NO
+HTML_INDEX_NUM_ENTRIES  = 100
+
+GENERATE_DOCSET         = NO
+GENERATE_HTMLHELP       = NO
+GENERATE_CHI            = NO
+GENERATE_QHP            = NO
+GENERATE_ECLIPSEHELP    = NO
+
+DISABLE_INDEX           = NO
+GENERATE_TREEVIEW       = NO
+ENUM_VALUES_PER_LINE    = 1
+TREEVIEW_WIDTH          = 250
+EXT_LINKS_IN_WINDOW     = NO
+FORMULA_FONTSIZE        = 10
+FORMULA_TRANSPARENT     = YES
+USE_MATHJAX             = NO
+MATHJAX_FORMAT          = HTML-CSS
+MATHJAX_RELPATH         = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS      =
+MATHJAX_CODEFILE        =
+SEARCHENGINE            = YES
+SERVER_BASED_SEARCH     = NO
+EXTERNAL_SEARCH         = NO
+SEARCHENGINE_URL        =
+SEARCHDATA_FILE         = searchdata.xml
+EXTERNAL_SEARCH_ID      =
+EXTRA_SEARCH_MAPPINGS   =
+
+GENERATE_LATEX          = NO
+GENERATE_RTF            = NO
+GENERATE_MAN            = NO
+GENERATE_XML            = NO
+GENERATE_PERLMOD        = NO

diff --git a/doc/api/libbabeltrace2/DoxygenLayout.xml b/doc/api/libbabeltrace2/DoxygenLayout.xml
new file mode 100644 (file)
index 0000000..7e40db8
--- /dev/null
+++ b/doc/api/libbabeltrace2/DoxygenLayout.xml
@@ -0,0 +1,46 @@
+<doxygenlayout version="1.0">
+  <navindex>
+    <tab type="mainpage" visible="yes" title="Välkommen!"/>
+    <tab type="user" visible="yes" url="@ref api-fund" title="API fundamentals"/>
+    <tab type="user" visible="yes" url="@ref guides" title="Guides"/>
+    <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:"/>
+  </navindex>
+
+  <group>
+    <detaileddescription/>
+    <briefdescription visible="no"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <defines title=""/>
+      <variables title=""/>
+      <functions title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <memberdef>
+      <pagedocs/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <defines title=""/>
+      <variables title=""/>
+      <functions title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </group>
+
+  <directory>
+    <detaileddescription title=""/>
+    <briefdescription visible="no"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+  </directory>
+</doxygenlayout>

diff --git a/doc/api/libbabeltrace2/Makefile.am b/doc/api/libbabeltrace2/Makefile.am
new file mode 100644 (file)
index 0000000..87b565d
--- /dev/null
+++ b/doc/api/libbabeltrace2/Makefile.am
@@ -0,0 +1,19 @@
+API_DOC_INSTALL_DIR = "$(DESTDIR)$(docdir)/api"
+
+all-local: doxygen-doc
+
+install-data-local: doxygen-doc
+       $(mkdir_p) "$(API_DOC_INSTALL_DIR)"
+       cp -rv output/html "$(API_DOC_INSTALL_DIR)"
+
+@DX_RULES@
+
+MOSTLYCLEANFILES = $(DX_CLEANFILES)
+EXTRA_DIST = \
+       Doxyfile.in \
+       DoxygenLayout.xml \
+       README.adoc \
+       style.css \
+       dox \
+       examples \
+       images

diff --git a/doc/api/libbabeltrace2/README.adoc b/doc/api/libbabeltrace2/README.adoc
new file mode 100644 (file)
index 0000000..71675a6
--- /dev/null
+++ b/doc/api/libbabeltrace2/README.adoc
@@ -0,0 +1,386 @@
+// Render with Asciidoctor
+
+= Babeltrace{nbsp}2 C API documentation guidelines
+Philippe Proulx <pproulx@efficios.com>
+6 October 2019
+
+This document explains how to write documentation for the
+Babeltrace{nbsp}2 C API.
+
+
+== General rules
+
+* Use four spaces to indent.
+
+* Try to stay behind the 72^th^ column mark if possible.
+
+* Use `+&nbsp;+` wherever needed.
+
+* Refer to a function using the `func()` form and to an enumerator or
+  type using the `#name` syntax.
+
+* When you refer to any keyword or definition, use the `\c` command if
+  it's a single word, otherwise surround the words with `<code>` and
+  `</code>`:
++
+--
+----
+@returns
+    Event class on success, or \c NULL on error.
+----
+--
+
+* Use the `\command` style in text and the `@command` style for other
+  locations (for example, `@brief`, `@param`, `@sa`, `@file`).
+
+* Use a `@code{.unparsed}` block for a plain text block (shell input,
+  for example):
++
+----
+@code{.unparsed}
+$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
+@endcode
+----
+
+* In the text, use `\bt_p{__param__}` to refer to the parameter named
+  `__param__`.
+
+
+== Function documentation
+
+Full example:
+
+----
+/*!
+@brief
+    Does something (third person singular, simple present) with some
+    parameter \bt_p{param} unless some other parameter
+    \bt_p{other_param} is some value.
+
+Full documentation goes here and adds any relevant information that's
+not in the brief description.
+
+@code
+/* If needed, put any C code in a code block. */
+@endcode
+
+Crucifix scenester vegan organic neutra palo santo glossier occupy
+truffaut. Meh fixie taiyaki single-origin coffee wayfarers. Thundercats
+farm-to-table shoreditch vinyl.
+
+@remarks
+    This is where you would put some remarks. Occupy flexitarian neutra,
+    edison bulb bespoke sriracha post-ironic. Mlkshk plaid pop-up
+    polaroid chillwave, ennui neutra.
+
+See this image:
+
+@image html mein-illustration.png "In elit et."
+
+@note
+    @parblock
+    This is a multiparagraph note.
+
+    Tote bag sartorial distillery, try-hard succulents wayfarers DIY
+    YOLO four loko jianbing farm-to-table unicorn vice.
+
+    Mumblecore semiotics raw denim palo santo chartreuse helvetica
+    shabby chic, distillery pabst poke swag copper mug blue bottle.
+    @endpar
+
+@attention
+    Use an attention command if this message is really important.
+
+@attention
+    @parblock
+    An attention block with more than one paragraph:
+
+    @code
+    some_code(23)
+    @endcode
+
+    Elit dolore pariatur ex anim officia cupidatat adipisicing mollit
+    incididunt irure anim nostrud.
+    @endparblock
+
+@param[in] param
+    Description of this parameter.
+@param[in] other_param
+    @parblock
+    Description of this other parameter. Nulla consequat tempus libero,
+    sed finibus velit.
+
+    Offal actually vinyl taiyaki kickstarter etsy.
+    @endparblock
+@param[out] out_param
+    <strong>On success</strong>, \bt_p{*out_param} contains to something
+    useful.
+
+@retval #SOME_STATUS_OK
+    Success.
+@retval #SOME_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #SOME_STATUS_ERROR
+    @parblock
+    Longer description for this specific status.
+
+    Organic locavore sartorial 3 wolf moon brooklyn, VHS pug distillery
+    schlitz tofu banjo chambray you probably haven't heard of them hot
+    chicken copper mug.
+
+    Neutra kale chips kombucha, salvia green juice live-edge swag
+    biodiesel scenester austin yuccie dreamcatcher cronut small batch.
+    @endparblock
+
+@bt_pre_not_null{param}
+@bt_pre_not_null{other_param}
+@bt_pre_hot{param}
+@pre
+    \bt_p{param} is like this or like that.
+
+@bt_post_ref_cnt_same{other_param}
+@post
+    \bt_p{other_param} is still in some state, and woke jean waistcoat.
+
+@sa bt_some_other_function() &mdash;
+    Does something else with a parameter.
+@sa bt_another_function() &mdash;
+    Cardigan celiac palo santo, tacos chicharrones pitchfork chambray
+    photo booth subway tile 90's street.
+*/
+----
+
+Parts:
+
+. **Opening Doxygen comment**.
++
+Use `/*!`.
+
+. **Brief description**.
++
+Use third person singular in the simple present tense: you are
+documenting what the function does. Assume that the sentence implicitly
+starts with "`This function`".
++
+Try to mention, briefly, all the parameters (with `\bt_p`) and what the
+function returns.
++
+End the sentence with a period.
+
+
+. **Detailed description**.
++
+Write complete sentences.
++
+Refer to parameters (with `\bt_p`) as much as possible.
++
+In general, keep paragraphs short: often, a single sentence is enough.
++
+Write notes (`@note` command), remarks (`@remark` command), or
+attentions (`@attention` command) when appropriate. Most notes and
+remarks, however, can be simple paragraphs. Use `@parblock` end
+`@endparblock` to have more than one note/remark/warning paragraph.
+
+. **Parameter descriptions** (if any).
++
+Use the `@param[in]`, `@param[out]`, and `@param[in,out]` commands
+depending on the parameter direction.
++
+Document parameters in the declaration order.
++
+Refer to other parameters (with `\bt_p`) when useful for the reader.
++
+End each description with a period.
++
+Use `@parblock` end `@endparblock` to have more than one paragraph for a
+given parameter description.
++
+Make sure there's no blank line, except within a `@parblock` block,
+within the parameter description block so that Doxygen puts all the
+descriptions in the same section. For example, **do not** write this:
++
+----
+@param[in] hexagon
+    Ugh literally +1 aesthetic, fashion axe try-hard mixtape pork belly
+    four loko.
+
+@param[in] selfies
+    Brooklyn ethical migas, viral edison bulb meggings butcher
+    flexitarian letterpress humblebrag kombucha pour-over etsy sriracha
+    blog.
+----
+
+
+. **Return value** (if any).
++
+--
+* If the function returns a status code, use the `@retval` command
+  multiple times to document each status:
++
+----
+@retval #BT_VALUE_COPY_STATUS_OK
+    Success.
+@retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
+    Out of memory.
+----
++
+End each description with a period.
++
+Use `@parblock` end `@endparblock` to have more than one paragraph
+for a given return value description.
++
+Make sure there's no blank line, except within a `@parblock` block,
+within the return value description block so that Doxygen puts all the
+descriptions in the same section. For example, **do not** write this:
++
+----
+@retval #BT_VALUE_COPY_STATUS_OK
+    Success.
+
+@retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
+    Out of memory.
+----
+
+* If the function returns a simple value, use the `@returns` command
+  to document it.
++
+Refer to parameters (with `\bt_p`) when useful for the reader.
++
+End the description with a period.
+--
+
+. **Preconditions** (if any).
++
+List all the function's preconditions with the `@pre` command or any
+alias which starts with `@bt_pre`.
++
+Use the simple present tense.
++
+Do not write the word "`must`" as a precondition is already a
+requirement.
++
+End the description with a period.
++
+Make sure there's no blank line within the precondition description
+block so that Doxygen puts all the descriptions in the same section. For
+example, **do not** write this:
++
+----
+@bt_pre_hot{param}
+
+@pre
+    \bt_p{param} is like this or like that.
+----
+
+. **Postconditions** (if any).
++
+List all the function's _relevant_ postconditions with the `@post`
+command or any alias which starts with `@bt_post`.
++
+Anything that the function's documentation body describes and which
+forms the nature of the function does not need to be written as an
+explicit postcondition. For example, if a function adds some object A
+to some object B, do not write the postcondition "B contains A".
++
+Use the simple present tense.
++
+End the description with a period.
++
+Make sure there's no blank line within the postcondition description
+block so that Doxygen puts all the descriptions in the same section. For
+example, **do not** write this:
++
+----
+@bt_post_ref_cnt_same{other_param}
+
+@post
+    \bt_p{other_param} is still in some state, and woke jean waistcoat.
+----
+
+. **Items to see also** (if any).
++
+Use the `@sa` command, multiple times if needed, to refer to related
+functions or types.
++
+This is a way for you to inform the reader about other existing, related
+items. Keep in mind that the reader does not always know where to look
+for things.
++
+In the referred item's brief description, do _not_ mention its
+parameters, if any.
++
+End each brief description with a period.
++
+Make sure there's no blank line within the "`see also`" description
+block so that Doxygen puts all the descriptions in the same section. For
+example, **do not** write this:
++
+----
+@sa bt_some_other_function() &mdash;
+    Does something else with a parameter.
+
+@sa bt_another_function() &mdash;
+    Cardigan celiac palo santo, tacos chicharrones pitchfork chambray
+    photo booth subway tile 90's street.
+----
+
+
+== Writing style
+
+The ultimate goal of the Babeltrace{nbsp}2 C API documentation is to
+make the layman write code using this API as fast and correct as
+possible without having to ask for help. For this purpose, the
+documentation must be as clear as possible, just like the function and
+type names try to be.
+
+Do not hesitate to repeat technical terms, even in the same sentence, if
+needed. For example, if you document a "`value object`", then always use
+the term "`value object`" in the documentation, not "`value`", nor
+"`object`", since they are ambiguous.
+
+You can use light emphasis to show the importance of a part of the text
+with the `\em` command (one word) or by surrounding the text to
+emphasize with `<em>` and `</em>`. Likewise, you can use strong emphasis
+when needed with the `\b` command (one word) or with `<strong>` and
+`</strong>`. In general, prefer light emphasis to strong emphasis, and
+use it economically.
+
+Links to other parts of the documentation are very important. Consider
+that the reader never knows that other functions exist other than the
+one she's reading. Use as many internal links as possible. Use the
+following forms of links:
+
+`__func__()`::
+    Automatic link to the function or macro named `__func__`.
+
+`#__name__`::
+    Automatic link to the type or enumerator named `__name__`.
+
+`\ref __ref__`::
+    Link to `__ref__` (page name, group name, function or macro name,
+    type name, variable name, etc.) using its default text.
+
+`\ref __ref__ "__some text__"`::
+    Link to `__ref__` (page name, group name, function or macro name,
+    type name, variable name, etc.) using the text `__some text__`.
+
+See Doxygen's http://www.doxygen.nl/manual/autolink.html[Automatic link
+generation] for other ways to create automatic links.
+
+Follow, as much as possible, the
+https://docs.microsoft.com/en-ca/style-guide/welcome/[Microsoft Style
+Guide] when you document the API. This includes:
+
+* Use an active voice.
+* Use a gender-neutral language.
+* Use the present tense (you almost never need the future tense).
+* Address your reader directly (use "`you`").
+* Use contractions ("`it's`", "`you're`", "`don't`", and the rest).
+* Avoid anthropomorphism.
+* Ensure parallelism in lists, procedures, and sentences.
+* Terminate list items with a period.
+* Do not use Latin abbreviations.
+* Use "`and`" or "`or`" instead of a slash.
+* Avoid using negatives.
+* Avoid using "`should`": most of the time, you mean "`must`", and
+  that's very clear for the reader.

diff --git a/doc/api/libbabeltrace2/dox/api-fund.dox b/doc/api/libbabeltrace2/dox/api-fund.dox
new file mode 100644 (file)
index 0000000..f8026b2
--- /dev/null
+++ b/doc/api/libbabeltrace2/dox/api-fund.dox
@@ -0,0 +1,569 @@
+/*!
+@page api-fund API fundamentals
+
+This page explains the basic principles of the \bt_api.
+
+You \em must understand what the API expects before you create a
+\bt_name \bt_plugin or an application which uses the API.
+
+@section api-fund-header Header file
+
+To use the \bt_api, include <code>%babeltrace2/babeltrace.h</code>:
+
+@code
+#include <babeltrace2/babeltrace.h>
+@endcode
+
+Do \em not include any other header file found in the \c babeltrace2
+directory: the compiler prints an error when you try to.
+
+@section api-fund-ns Namespace
+
+- All libbabeltrace2 functions and types start with \c bt_.
+
+- All libbabeltrace2 definitions, macros, and enumerators start
+  with \c BT_.
+
+@section api-fund-pre-post Function precondition and postcondition checking
+
+All the functions of libbabeltrace2 which have parameters check that
+the caller meets their
+<a href="https://en.wikipedia.org/wiki/Precondition">preconditions</a>.
+
+All the functions of libbabeltrace2 which call a user function which
+returns something check that the returned value meets their
+<a href="https://en.wikipedia.org/wiki/Postcondition">postconditions</a>.
+
+The function descriptions in the
+<a class="el" href="modules.html">API reference modules</a>
+list all their preconditions and postconditions, if any.
+
+libbabeltrace2 is very strict regarding function preconditions and
+postconditions: when you break any of them, the library prints how the
+precondition or postcondition was not satisfied, with details, and then
+calls <code>abort()</code>.
+
+Here's an example of what the library prints to the standard error
+before aborting when you break a precondition:
+
+@code{.unparsed}
+10-06 09:12:20.228 62362 62362 F LIB/VALUE bt_value_array_get_length@value.c:887 Babeltrace 2 library precondition not satisfied; error is:
+10-06 09:12:20.228 62362 62362 F LIB/VALUE bt_value_array_get_length@value.c:887 Value object is NULL:
+10-06 09:12:20.228 62362 62362 F LIB/VALUE bt_value_array_get_length@value.c:887 Aborting...
+@endcode
+
+Because precondition and postcondition checks detect programming errors,
+libbabeltrace2's approach is to abort as soon as possible so that you
+fix the error. Therefore, the libbabeltrace2 functions never return a
+programming error status (like what \c EINVAL means on Unix systems, for
+example).
+
+@attention
+    Some precondition and postcondition checks which occur on the fast
+    path and which would therefore significantly impact performance
+    during a typical trace processing \bt_graph run are only enabled in
+    \ref guide-build-bt2-dev "developer mode".
+
+Common function preconditions are:
+
+- A pointer parameter is not \c NULL.
+
+- An index parameter is not ouf of bounds.
+
+- A string or container parameter is not empty.
+
+- An object parameter has a given conceptual type. For example, you
+  cannot call bt_value_array_get_length() with a
+  \bt_bool_val.
+
+- An object parameter is not \ref api-fund-freezing "frozen".
+
+- An object parameter has some specific state.
+
+@section api-fund-object Object model
+
+The \bt_api is
+<a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented</a>.
+
+With a few exceptions, API functions are actually
+<a href="https://en.wikipedia.org/wiki/Method_(computer_programming)"><em>methods</em></a>
+which operate on objects: their first parameter points to said object.
+For example:
+
+@code
+uint64_t bt_value_array_get_length(const bt_value *value);
+@endcode
+
+You can create some types of objects with functions that contain the
+word \c create, while for some other types, only the library can create
+them behind the scenes. For example, you can create a
+\bt_bool_val object with bt_value_bool_create(), but you cannot directly
+create a \bt_ev object: you need to borrow one from a \bt_ev_msg which
+contains it.
+
+Each type of object has its own C type. Learn more about typing in
+\ref api-fund-c-typing below.
+
+Some types of objects conceptually inherit other types of objects. If an
+object type A inherits an object type B, then you can use both the A and
+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
+indicate the inheritance relations.
+
+@subsection api-fund-object-shared-unique Shared vs. unique objects
+
+Some \bt_name objects are \em shared while some others are \em unique:
+
+<dl>
+  <dt>\anchor api-fund-shared-object Shared object</dt>
+  <dd>
+    A \em shared object has a <a
+    href="https://en.wikipedia.org/wiki/Reference_counting">reference
+    count</a>.
+
+    A shared object's creation function returns a \em new reference.
+
+    The API of a given shared object type contains:
+
+    - A function to get a new reference, increasing the reference count,
+      which ends with \c _get_ref.
+
+    - A function to put an existing reference, decreasing the reference
+      count, which ends with \c _put_ref.
+
+    - A macro to put an existing reference and then set the passed
+      expression to \c NULL. This macro ends with \c _PUT_REF_AND_RESET.
+
+    - A macro to move an existing reference from a source expression to
+      a destination expression, putting the destination expression's
+      existing reference, and setting the source expression to \c NULL.
+      This macro ends with \c _MOVE_REF.
+
+    For example, bt_value_get_ref() and bt_value_put_ref() get and put
+    \bt_val object references, BT_VALUE_PUT_REF_AND_RESET() puts a
+    value reference and sets the expression to \c NULL, and
+    BT_VALUE_MOVE_REF() moves a value reference.
+
+    All <code>*_get_ref()</code> and <code>*_put_ref()</code> functions,
+    and all <code>*_PUT_REF_AND_RESET()</code> macros accept a \c NULL
+    parameter.
+
+    When the reference count of a given object reaches zero, it \em can
+    be destroyed. Some shared objects, however, have a lifetime that is
+    managed by another shared object. For example, an \bt_ev_cls is not
+    destroyed until its parent \bt_stream_cls is also destroyed, even if
+    its reference count technically reaches zero.
+
+    A function which accepts a shared object never "takes" or steals the
+    caller's reference unless its name contains the word \c move: you
+    still have your own reference when the function returns. For
+    example:
+
+    @code
+    bt_event_class *event_class = bt_event_class_create(stream_class);
+
+    /*
+     * At this point, we still have a reference of `stream_class`.
+     * We need to put it with bt_stream_class_put_ref() at some point.
+     */
+    @endcode
+
+    A function which contains the word \c borrow returns a
+    <em>borrowed reference</em>: if you need your own reference, get
+    one with the appropriate <code>*_get_ref()</code> function.
+  </dd>
+
+  <dt>\anchor api-fund-unique-object Unique object</dt>
+  <dd>
+    A \em unique object does not have a reference count: another object
+    is always its sole owner.
+
+    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
+    clear, depending on the context, which
+    shared object is the ultimate owner of a given unique object.
+
+    In general, you cannot create a unique object: the library creates
+    it, and then you \em borrow it from another object (shared or unique
+    itself).
+
+    Unique objects exist for performance reasons: some optimizations are
+    challenging to implement without this concept.
+  </dd>
+</dl>
+
+In the <a class="el" href="modules.html">API reference</a>, each module
+indicates whether the documented objects are shared or unique.
+
+@subsection api-fund-freezing Object freezing
+
+The library can \em freeze some types of \bt_name objects when specific
+functions succeed.
+
+A frozen object is immutable: trying to set an object's property once
+it's frozen represents a \ref api-fund-pre-post "precondition" break.
+
+For example, the library freezes the source \bt_comp initialization
+parameters when you call bt_graph_add_source_component(): this
+guarantees to the component's
+\ref api-comp-cls-dev-meth-init "initialization method" that the
+parameters will never change for the rest of their lifetime.
+
+When an object becomes frozen, its contained objects, if any, also
+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>
+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").
+
+@attention
+    Some "frozen" property checks which occur on the fast path and which
+    would therefore significantly impact performance during a typical trace
+    processing \bt_graph run are only enabled in
+    \ref guide-build-bt2-dev "developer mode".
+
+@section api-fund-c-typing C typing
+
+The \bt_api typing system is very strict to catch many programming
+errors at compile time.
+
+Each type of object has its own C type. Consequently, functions accept
+and return specific C types. For example, all the \bt_ev functions
+accept a #bt_event pointer.
+
+The API uses
+<a href="https://en.wikipedia.org/wiki/Opaque_pointer">opaque pointers</a>,
+so that you don't having access to the object type's actual C structure.
+This helps with the development of features and fixes in future releases
+of \bt_name.
+
+Some objects share the same C type when different conceptual types can
+be contained in some collection. For example, all \bt_val objects have
+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
+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
+of a given \bt_val object.
+
+When an object type A conceptually inherits an object type B, and when A
+and B have different C types, the API offers a dedicated, inline
+upcasting function named <code>bt_A_as_B()</code> to have access to the B
+API at no cost. For example, an \bt_uenum_fc mapping \em is conceptually
+an \bt_enum_fc mapping, but they have different C types:
+#bt_field_class_enumeration_unsigned_mapping and
+#bt_field_class_enumeration_mapping. Get the latter from the former with
+bt_field_class_enumeration_unsigned_mapping_as_mapping_const().
+The <code>bt_A_as_B()</code> functions do not change the object's
+reference count and they accept \c NULL.
+
+@attention
+    \b Never directly cast a \bt_name object pointer from some C type to
+    another C type: the API is designed so that you never need to do
+    that.
+
+@subsection api-fund-const const correctness
+
+The \bt_api is <code>const</code>-correct: when a function has a
+\c const object pointer parameter, it never modifies that object from
+the user's viewpoint.
+
+As such, when a function returns a \c const object pointer, directly or
+through an output parameter, you can't modify the object.
+
+@attention
+    \b Never remove a \bt_name object pointer's \c const qualifier. The
+    API is designed so that you never need to do that.
+
+Functions which accept or return a \c const object pointer end with
+\c _const when they have (or could have in the future) a non \c const
+equivalent. For example, bt_value_map_borrow_entry_value_const() is the
+\c const version of bt_value_map_borrow_entry_value().
+
+Simple property getter functions do not end with \c _const.
+
+\ref api-fund-shared-object "Reference count" changing functions, ending
+with \c _get_ref and \c _put_ref(), accept a \c const object pointer
+parameter: the library does not consider that an object's nature is
+altered when its reference count changes.
+
+@subsection api-fund-int-types C integer types
+
+The API only uses \c uint64_t and \c int64_t as C integer types for
+clarity and consistency.
+
+@subsection api-fund-common-types Common C types and definitions
+
+There are a few C types and definitions which are common to many parts
+of the \bt_api.
+
+See \ref api-common-types.
+
+@section api-fund-func-status Function return
+
+libbabeltrace2 functions which cannot fail return a property or an
+object pointer directly. For example, bt_value_array_get_length()
+returns the length of an \bt_array_val, and
+bt_value_array_borrow_element_by_index_const() returns a \bt_val
+contained in an \bt_array_val. Both functions cannot fail: any
+programming error \ref api-fund-pre-post "makes the program abort".
+
+When a function returns an optional property or object:
+
+<dl>
+  <dt>If it's a pointer</dt>
+  <dd>
+    The function returns \c NULL if the property/object is missing.
+  </dd>
+
+  <dt>If it's not a pointer</dt>
+  <dd>
+    <dl>
+      <dt>If the property is available</dt>
+      <dd>
+        The function returns the property by output parameter and returns
+        #BT_PROPERTY_AVAILABILITY_AVAILABLE.
+      </dd>
+
+      <dt>If the property is not available</dt>
+      <dd>
+        The function returns #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE.
+      </dd>
+    </dl>
+  </dd>
+</dl>
+
+Many libbabeltrace2 functions return a status code, that is, a C
+enumerator containing the word \c STATUS. For example,
+bt_value_copy() returns either #BT_VALUE_COPY_STATUS_OK or
+#BT_VALUE_COPY_STATUS_MEMORY_ERROR.
+
+Although the API guarantees that any status enumerator which has the
+\c _OK status has the value 0, we recommend that you compare the
+returned value to exact status enumerators for clarity, for example:
+
+@code
+bt_value_copy_status status = bt_value_copy(obj, &val_copy);
+
+if (status != BT_VALUE_COPY_STATUS_OK) {
+    /* handle error */
+}
+@endcode
+
+The <a class="el" href="modules.html">API reference modules</a>
+document, for each function, what each return status enumerator means.
+
+Some functions return properties or objects by output parameter. When
+such a function which accepts a property or object pointer \c ptr fails,
+the library does \em not guarantee that <code>*ptr</code> remains
+unchanged. Therefore, such a pattern is \em not safe:
+
+@code
+bt_some_object *some_object = NULL;
+
+status = bt_get_some_object(obj, &some_object);
+
+if (some_object) {
+    /* ... */
+}
+@endcode
+
+Always rely on the returned status code:
+
+@code
+bt_some_object *some_object;
+
+status = bt_get_some_object(obj, &some_object);
+
+if (status == BT_GET_SOME_OBJECT_STATUS_OK) {
+    /* ... */
+}
+@endcode
+
+@section api-fund-user-classes User classes
+
+The whole \bt_name project is about extensibility: you can implement
+\bt_p_comp_cls, and then package and distribute them as
+\bt_p_plugin.
+
+When you implement a \bt_name \bt_comp_cls, you override protected
+methods, just like you would do in any
+<a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
+(OOP) language.
+
+Here's the mapping of typical OOP language features to the
+\bt_name library domain:
+
+<table>
+  <tr>
+    <th>OOP concept
+    <th>\bt_name equivalent
+  <tr>
+    <td>User class.
+    <td>
+      Class object with implemented user functions.
+
+      For example: #bt_component_class_source.
+  <tr>
+    <td>User class instance.
+    <td>
+      Instance object, created from a class object.
+
+      For example: #bt_component_source.
+  <tr>
+    <td>
+      Instance pointer (\c this keyword in C++/Java and \c self variable
+      in Python, for example).
+    <td>
+      "Self" (private) object.
+
+      A "self" object has a specific, dedicated C type which starts
+      with <code>bt_self_</code>.
+
+      For example: #bt_self_component_source.
+  <tr>
+    <td>Protected, final method.
+    <td>
+      Library function accepting an instance pointer ("self" object) as
+      its first parameter.
+
+      Those functions always start with <code>bt_self_</code>.
+
+      For example: bt_self_component_source_add_output_port().
+  <tr>
+    <td>Protected, overridable method.
+    <td>
+      User function with a specific signature, accepting an instance
+      pointer ("self" object) as its first parameter.
+
+      For example: #bt_component_class_source_initialize_method.
+  <tr>
+    <td>Private user method.
+    <td>
+      Custom \c static user function having access to the instance
+      pointer ("self" object) somehow.
+  <tr>
+    <td>Private user property or attribute.
+    <td>
+      Custom \bt_voidp data which you set and get using
+      dedicated protected methods (for example,
+      bt_self_component_set_data() and bt_self_component_get_data()).
+</table>
+
+@section api-fund-error Error reporting
+
+libbabeltrace2 features a rich \ref api-error "error reporting"
+mechanism to augment an error with custom causes without having to
+explicitly pass an error object to the library functions.
+
+When a library function or \ref api-fund-user-classes "user method"
+returns an error status code (any status enumerator which contains
+the word \c ERROR), it \em can add one or more error causes to the
+current thread's error object.
+
+This makes it possible for the end user to understand the contexts which
+lead to the error, possibly across many \bt_p_plugin written by
+different developers.
+
+An error cause contains information about the source location where the
+error occured, the actor involved in the error, and a message.
+
+When you "catch" an error, that is, react to a function returning an
+error status code without returning an error status code yourself,
+you can:
+
+- Take the current thread's error with bt_current_thread_take_error() to
+  get its causes, possibly presenting them to the end user.
+
+  You then need to release the error with bt_error_release().
+
+- Clear the current thread's error with bt_current_thread_clear_error().
+
+@attention
+    You \em cannot call any libbabeltrace2 function when the current
+    thread has an error, except the
+    \ref api-fund-shared-object "reference counting" functions (ending
+    with <code>_get_ref()</code> or <code>_put_ref()</code>).
+
+The
+<a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2.1"><code>babeltrace2</code></a>
+CLI uses this feature to pretty-print an error's causes to the end user,
+for example:
+
+@code{.unparsed}
+ERROR:    [Babeltrace CLI] (babeltrace2.c:2521)
+  Cannot create components.
+CAUSED BY [Babeltrace CLI] (babeltrace2.c:2336)
+  Cannot create component: plugin-name="ctf", comp-cls-name="fs", comp-cls-type=0,
+  comp-name="auto-disc-source-ctf-fs"
+CAUSED BY [libbabeltrace2] (graph.c:1343)
+  Component initialization method failed: status=ERROR, comp-addr=0x562fbd275f40,
+  comp-name="auto-disc-source-ctf-fs", comp-log-level=WARNING, comp-class-type=SOURCE,
+  comp-class-name="fs", comp-class-partial-descr="Read CTF traces from the file sy",
+  comp-class-is-frozen=1, comp-class-so-handle-addr=0x562fbd285810,
+  comp-class-so-handle-path="/usr/lib/babeltrace2/plugins/babeltrace-plugin-ctf.so",
+  comp-input-port-count=0, comp-output-port-count=0
+CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:1148)
+  Cannot create trace for `/path/to/trace`.
+CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:928)
+  Cannot add stream file `/path/to/trace/channel0_1` to stream file group
+CAUSED BY [auto-disc-source-ctf-fs: 'source.ctf.fs'] (fs.c:734)
+  Cannot get stream file's first packet's header and context fields (`/path/to/trace/channel0_1`).
+@endcode
+
+@section api-fund-logging Logging
+
+libbabeltrace2 contains many hundreds of logging statements to help you
+follow and debug your \bt_plugin or program.
+
+By default, the library's logging is disabled. To enable it, use
+bt_logging_set_global_level().
+
+To set the library's initial logging level (checked once at library
+loading time), set the \c LIBBABELTRACE2_INIT_LOG_LEVEL environment
+variable, with one of:
+
+- \c N or \c NONE
+- \c F or \c FATAL
+- \c E or \c ERROR
+- \c W, \c WARN, or \c WARNING
+- \c I or \c INFO
+- \c D or \c DEBUG
+- \c T or \c TRACE
+
+By default, the minimal, build-time logging level is \em DEBUG. We
+recommend that you build libbabeltrace2 with the \em TRACE minimal
+logging level for development. See \ref guide-build-bt2-dev.
+
+libbabeltrace2 writes its logging statements to the standard error
+stream.
+
+A libbabeltrace2 (and \bt_name project plugin) logging line looks like
+this:
+
+@code{.unparsed}
+05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
+@endcode
+
+The line contains, in order:
+
+-# The date and time (<code>05-11 00:58:03.691</code>).
+
+-# The process and thread IDs (<code>23402 23402</code>).
+
+-# The logging level (\c D for \em DEBUG).
+
+-# The function logging (\c bt_value_destroy).
+
+-# The file and line number logging (<code>values.c:498</code>).
+
+-# The message, which typically ends with a list of fields adding
+   details.
+*/

diff --git a/doc/api/libbabeltrace2/dox/examples.dox b/doc/api/libbabeltrace2/dox/examples.dox
new file mode 100644 (file)
index 0000000..507b6e4
--- /dev/null
+++ b/doc/api/libbabeltrace2/dox/examples.dox
@@ -0,0 +1,233 @@
+/*!
+@page examples Examples
+
+The examples of this section apply the different parts of the
+libbabeltrace2 API to accomplish real tasks.
+
+The available examples are:
+
+- \subpage example-simple-plugin-def-file
+- \subpage example-simple-src-cmp-cls
+- \subpage example-simple-flt-cmp-cls
+- \subpage example-simple-sink-cmp-cls
+
+@page example-simple-plugin-def-file Simple shared object plugin definition C file
+
+This example shows a basic \bt_name
+\ref api-plugin-dev "shared object plugin" definition C file.
+
+The shared object plugin's name is <code>vestige</code>. Therefore
+the \c input and \c output \bt_p_comp_cls would be identified in the
+\bt_cli command-line tool as \c source.vestige.input and
+<code>sink.vestige.output</code>.
+
+Assume that \c vestige.c contains the actual source and sink component
+classes's code, and that \c vestige.h contains its declarations.
+
+<code>vestige-plugin.c</code>:
+
+@include vestige-plugin.c
+
+See \ref guide-comp-link-plugin-so to learn how you could compile and
+link those files as a \bt_name shared object plugin.
+
+@page example-simple-src-cmp-cls Simple source component class
+
+This example shows a basic \bt_src_comp_cls packaged as a
+\ref api-plugin-dev "shared object plugin".
+
+The name of the plugin is <code>dust</code> and the name of the source
+component class is <code>input</code>. Therefore the
+component class is identified in the \bt_cli
+command-line tool as <code>source.dust.input</code>.
+
+A <code>source.dust.input</code> \bt_comp reads a text file having this
+fictitious format:
+
+@verbinclude dust
+
+That is:
+
+- Each line represents an event record.
+- For a given line:
+  - The first token is the
+    <a href="https://en.wikipedia.org/wiki/Unix_time">Unix timestamp</a>
+    (seconds since the Unix epoch) of the record.
+  - The second token is a number of microseconds to add to the Unix
+    timestamp.
+  - The third token is the event record's name: only \c send-msg and
+    \c recv-msg are possible.
+  - The remaining characters form the event record's message (payload).
+
+A <code>source.dust.input</code> component accepts a single
+\ref api-comp-cls-dev-meth-init "initialization parameter",
+<code>path</code>, which is the path of the file to open and read.
+
+A <code>source.dust.input</code> component creates a single
+\bt_oport named <code>out</code>.
+
+For each line of the input file, a <code>source.dust.input</code>
+component's \bt_msg_iter emits an \bt_ev_msg.
+
+To simplify this example, a <code>source.dust.input</code> component is
+not resilient and needs a valid input and valid initialization
+parameters. The code also doesn't check the return status codes of API
+functions for simplicity, but you must check them in production code.
+
+The source component class implementation and the shared object plugin
+macros are in the same file, <code>dust.c</code>:
+
+@include dust.c
+
+As per the \ref guide-comp-link-plugin-so guide, you can build the
+shared object plugin as such:
+
+@code{.unparsed}
+$ cc dust.c -fPIC -c $(pkg-config --cflags babeltrace2)
+$ ld dust.o -o dust.so -shared $(pkg-config --libs babeltrace2)
+@endcode
+
+With the \bt_cli tool, assuming you have a valid input file named
+<code>dust</code>, you can view the event messages that a
+<code>source.dust.input</code> message iterator emits:
+
+@code{.unparsed}
+$ babeltrace2 --plugin-path=. --component=source.dust.input --params='path="dust"'
+@endcode
+
+The output is similar to:
+
+@code{.unparsed}
+[17:10:37.154215000] (+?.?????????) send-msg: { msg = "Jowl pig filet mignon, turducken capicola." }
+[17:10:37.200774000] (+0.046559000) recv-msg: { msg = "Pork belly pig burgdoggen venison bacon." }
+[17:10:41.001831000] (+3.801057000) send-msg: { msg = "Bacon ipsum dolor amet strip steak." }
+[17:10:41.944187000] (+0.942356000) send-msg: { msg = "Spare ribs filet mignon boudin bresaola." }
+[17:10:45.115406000] (+3.171219000) recv-msg: { msg = "Rump cow t-bone hamburger short tenderloin." }
+@endcode
+
+You can also view more details with
+
+@code{.unparsed}
+$ babeltrace2 --plugin-path=. --component=source.dust.input --params='path="dust"' \
+                              --component=sink.text.details
+@endcode
+
+@page example-simple-flt-cmp-cls Simple filter component class
+
+This example shows a basic \bt_flt_comp_cls packaged as a
+\ref api-plugin-dev "shared object plugin".
+
+The name of the plugin is <code>distill</code> and the name of the
+filter component class is <code>theone</code>. Therefore the
+component class is identified in the \bt_cli
+command-line tool as <code>filter.distill.theone</code>.
+
+A <code>filter.distill.theone</code> \bt_comp removes specific
+\bt_p_ev_msg from a \bt_stream based on their \bt_ev_cls's name.
+
+A <code>filter.distill.theone</code> component accepts a single
+\ref api-comp-cls-dev-meth-init "initialization parameter",
+<code>names</code>, which is an \bt_array_val of string values. The
+array value contains the names of the classes of the events to discard.
+
+A <code>filter.distill.theone</code> component creates a single
+\bt_iport named <code>in</code> and a single \bt_oport named
+<code>out</code>.
+
+To simplify this example, a <code>filter.distill.theone</code> component
+is not resilient and needs a valid input and valid initialization
+parameters. The code also doesn't check the return status codes of API
+functions for simplicity, but you must check them in production code.
+
+The filter component class implementation and the shared object plugin
+macros are in the same file, <code>distill.c</code>:
+
+@include distill.c
+
+As per the \ref guide-comp-link-plugin-so guide, you can build the
+shared object plugin as such:
+
+@code{.unparsed}
+$ cc distill.c -fPIC -c $(pkg-config --cflags babeltrace2)
+$ ld distill.o -o distill.so -shared $(pkg-config --libs babeltrace2)
+@endcode
+
+With the \bt_cli tool, you can use a
+<code>filter.distill.theone</code> component, reading a
+<a href="https://diamon.org/ctf/">CTF</a> trace
+(see \bt_man{babeltrace2-source.ctf.fs,7}) for example:
+
+@code{.unparsed}
+$ babeltrace2 --plugin-path=. /path/to/ctf/trace \
+              --component=filter.distill.theone \
+              --params='names=["sched_switch", "rcu_utilization", "kmem_kfree"]'
+@endcode
+
+@page example-simple-sink-cmp-cls Simple sink component class
+
+This example shows a basic \bt_sink_comp_cls packaged as a
+\ref api-plugin-dev "shared object plugin".
+
+The name of the plugin is <code>epitome</code> and the name of the
+sink component class is <code>output</code>. Therefore the component
+class is identified in the \bt_cli
+command-line tool as <code>sink.epitome.output</code>.
+
+A <code>sink.epitome.output</code> \bt_comp prints one text line to
+the standard output for each \bt_ev_msg it consumes, for
+example:
+
+@code{.unparsed}
+#1: kmem_kmalloc (5 payload members)
+#2: kmem_kfree (2 payload members)
+#3: sched_waking (4 payload members)
+#4: sched_migrate_task (5 payload members)
+#5: sched_stat_runtime (4 payload members)
+#6: sched_wakeup (4 payload members)
+#7: rcu_utilization (1 payload member)
+#8: rcu_utilization (1 payload member)
+#9: sched_switch (7 payload members)
+#10: syscall_entry_write (3 payload members)
+...
+@endcode
+
+For each line, there is:
+
+- The event message's index (simple counter).
+- The event message's \bt_ev_cls \ref api-tir-ev-cls-prop-name "name".
+- The number of members in the event message's \bt_ev's
+  \ref api-tir-ev-prop-payload "payload field".
+
+A <code>sink.epitome.output</code> component does not need any
+\ref api-comp-cls-dev-meth-init "initialization parameter": it just
+prints to the standard output.
+
+A <code>sink.epitome.output</code> component creates a single
+\bt_iport named <code>in</code>.
+
+To simplify this example, a <code>sink.epitome.output</code> component
+doesn't check the return status codes of API functions,
+but you must check them in production code.
+
+The sink component class implementation and the shared object plugin
+macros are in the same file, <code>epitome.c</code>:
+
+@include epitome.c
+
+As per the \ref guide-comp-link-plugin-so guide, you can build the
+shared object plugin as such:
+
+@code{.unparsed}
+$ cc epitome.c -fPIC -c $(pkg-config --cflags babeltrace2)
+$ ld epitome.o -o epitome.so -shared $(pkg-config --libs babeltrace2)
+@endcode
+
+With the \bt_cli tool, you can use a
+<code>sink.epitome.output</code> component, reading a
+<a href="https://diamon.org/ctf/">CTF</a> trace
+(see \bt_man{babeltrace2-source.ctf.fs,7}) for example:
+
+@code{.unparsed}
+$ babeltrace2 --plugin-path=. /path/to/ctf/trace --component=sink.epitome.output
+@endcode
+*/

diff --git a/doc/api/libbabeltrace2/dox/group-trace-ir.dox b/doc/api/libbabeltrace2/dox/group-trace-ir.dox
new file mode 100644 (file)
index 0000000..db25805
--- /dev/null
+++ b/doc/api/libbabeltrace2/dox/group-trace-ir.dox
@@ -0,0 +1,108 @@
+/*!
+@defgroup api-tir Trace IR
+@ingroup api-msg
+
+@brief
+    Intermediate representation of
+    <a href="https://en.wikipedia.org/wiki/Tracing_(software)">tracing</a>
+    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
+objects so that many \bt_p_comp, written by different authors, can
+exchange trace metadata and data.
+
+The trace IR objects are divided into two main categories:
+
+<dl>
+  <dt>Metadata</dt>
+  <dd>
+    Classes of data objects.
+
+    A metadata object describes many data objects.
+
+    For example, an \bt_ev_cls describes the numeric ID, name, logging
+    level, and \ref api-tir-fc "classes" of payload \bt_p_field of all
+    the \bt_p_ev you create from it.
+
+    Metadata objects are one of the most valuable concepts of
+    \bt_name: because they describe the structures of many
+    data objects at once, they enable great space and time
+    optimizations.
+
+    For example, a \bt_sink_comp which writes a trace following a
+    metadata-supporting format, such as the
+    <a href="https://diamon.org/ctf/">Common Trace Format</a>, can
+    serialize the metadata objects once so that the data objects are
+    more compact and take less time to write.
+
+    The metadata objects are:
+
+    - \bt_c_clock_cls
+    - \bt_c_ev_cls
+    - \bt_cp_fc
+    - \bt_c_field_path
+    - \bt_c_stream_cls
+    - \bt_c_trace_cls
+  </dd>
+
+  <dt>Data</dt>
+  <dd>
+    Instances of metadata objects.
+
+    For example, a \bt_stream is an instance of a \bt_stream_cls.
+
+    The data objects are:
+
+    - \bt_c_cs
+    - \bt_c_ev
+    - \bt_cp_field
+    - \bt_c_pkt
+    - \bt_c_stream
+    - \bt_c_trace
+  </dd>
+</dl>
+
+The trace IR metadata to data object association is:
+
+<table>
+  <tr>
+    <th>Metadata object
+    <th>Data object
+  <tr>
+    <td>\bt_c_clock_cls
+    <td>Stream clock (see \ref api-tir-cs)
+  <tr>
+    <td>\bt_c_ev_cls
+    <td>\bt_c_ev
+  <tr>
+    <td>\bt_c_fc
+    <td>\bt_c_field
+  <tr>
+    <td>\bt_c_stream_cls
+    <td>\bt_c_stream
+  <tr>
+    <td>\bt_c_trace_cls
+    <td>\bt_c_trace
+</table>
+
+Within a trace processing \bt_graph, \bt_p_msg carry data objects from
+\bt_comp to component.
+
+You need to create metadata objects \em before you create data objects.
+You can then use the data objects to create messages.
+
+For example, you need a \bt_stream_cls to create a \bt_stream. With
+a \bt_stream, you can create a \bt_p_sb_msg, \bt_p_se_msg, \bt_p_ev_msg,
+and other types of messages.
+
+Usually, when you create a data object from a metadata object, the
+metadata object becomes \ref api-fund-freezing "frozen": you cannot
+modify it for the rest of its lifetime.
+
+All metadata objects and some data objects have an optional <em>user
+attributes</em> property (a \bt_map_val): you can use it to attach
+custom attributes, without any semantics specified by the \bt_name
+project, to those objects.
+*/

diff --git a/doc/api/libbabeltrace2/dox/guides.dox b/doc/api/libbabeltrace2/dox/guides.dox
new file mode 100644 (file)
index 0000000..ad2166f
--- /dev/null
+++ b/doc/api/libbabeltrace2/dox/guides.dox
@@ -0,0 +1,211 @@
+/*!
+@page guides Guides
+
+The guides in this section are step-by-step procedures to accomplish
+common tasks with libbabeltrace2.
+
+Guides help you navigate through the most important features of
+the library and its API.
+
+Make sure to eventually read \ref api-fund before you use the \bt_api
+seriously.
+
+The available guides are:
+
+- \subpage guide-build-bt2-dev
+- \subpage guide-comp-link-plugin-so
+- \subpage guide-comp-link-app
+
+@if meow
+
+- \subpage guide-create-graph
+- \subpage guide-write-min-src-comp-cls
+- \subpage guide-write-min-flt-comp-cls
+- \subpage guide-write-min-sink-comp-cls
+- \subpage guide-write-simple-sink-comp-cls
+- \subpage guide-create-plugin
+- \subpage guide-write-full-src-comp-cls
+- \subpage guide-write-full-flt-comp-cls
+- \subpage guide-write-full-sink-comp-cls
+- \subpage guide-query
+- \subpage guide-seek-msg-iter
+- \subpage guide-intr-graph
+- \subpage guide-intr-query
+- \subpage guide-graph-listeners
+
+@endif
+
+@page guide-build-bt2-dev Build Babeltrace 2 for development
+
+If you are developing a \bt_name \bt_plugin or an application which uses
+libbabeltrace2, we recommend that:
+
+- You build \bt_name from source in <em>developer mode</em>.
+
+  The \bt_name developer mode enables more \ref api-fund-pre-post
+  "precondition and postcondition" assertions to detect
+  programming errors.
+
+- You use \em TRACE as the minimal logging level at build time to have
+  access to more \ref api-fund-logging "logging", should you need it
+  to debug your plugin or application.
+
+To build \bt_name from source in developer mode and using \em TRACE
+as the minimal logging level:
+
+<ol>
+  <li>
+    <a href="https://babeltrace.org/#bt2-get">Download the
+    \bt_name tarball</a> and extract it.
+
+    See the project's
+    <a href="https://github.com/efficios/babeltrace/blob/stable-\bt_version_min_maj/README.adoc">README</a>
+    for build-time requirements and detailed build instructions.
+  <li>
+    Configure the build in developer mode and with the \em TRACE
+    minimal logging level:
+
+@code{.unparsed}
+$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
+@endcode
+  <li>
+    Build and install the project:
+
+@code{.unparsed}
+$ make
+# make install
+@endcode
+</ol>
+
+\bt_name developer mode build configuration command line examples:
+
+@code{.unparsed}
+$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
+  --enable-python-bindings --enable-python-plugins
+@endcode
+
+@code{.unparsed}
+$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
+  --prefix="$PWD/install" --disable-man-pages --disable-debug-info
+@endcode
+
+@note
+    @parblock
+    The development build creates a libbabeltrace2 library which is
+    slower to execute than a production (default) build.
+
+    We believe that, during the development process, a less efficient,
+    but more strict library is more desirable than the opposite.
+    @endparblock
+
+@page guide-comp-link-plugin-so Compile and link a Babeltrace 2 shared object plugin
+
+To compile and link a \bt_name shared object plugin:
+
+<ol>
+  <li>
+    Compile the plugin's C/C++ source files with the
+    <a href="https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html"><code>\-fPIC</code></a>
+    and
+    <a href="https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html"><code>\-c</code></a>
+    compiler options to produce position-independent code and
+    to compile without linking:
+
+    @code{.unparsed}
+    $ cc my-plugin.c analysis.c -fPIC -c $(pkg-config --cflags babeltrace2)
+    @endcode
+  </li>
+
+  <li>
+    Link the resulting object files with the
+    <a href="https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html"><code>\-shared</code></a>
+    linker option and with the \bt_name library:
+
+    @code{.unparsed}
+    $ ld my-plugin.o analysis.o -o my-plugin.so -shared $(pkg-config --libs babeltrace2)
+    @endcode
+  </li>
+</ol>
+
+@note
+    At least one of your C/C++ files must declare a \bt_name plugin
+    and one or more \bt_p_comp_cls using the \ref api-plugin-dev macros.
+
+@page guide-comp-link-app Compile and link an application which uses libbabeltrace2
+
+To compile and link an application which uses libbabeltrace2:
+
+<ol>
+  <li>
+    Compile your C/C++ files as usual.
+  </li>
+
+  <li>
+    Link the resulting object files with the \bt_name library:
+
+    @code{.unparsed}
+    $ ld my-app.o analysis.o -o my-app $(pkg-config --libs babeltrace2)
+    @endcode
+  </li>
+</ol>
+
+@if meow
+
+@page guide-create-graph Create a graph from existing component classes and run it
+
+TODO!
+
+@page guide-write-min-src-comp-cls Write a minimal source component class
+
+TODO!
+
+@page guide-write-min-flt-comp-cls Write a minimal filter component class
+
+TODO!
+
+@page guide-write-min-sink-comp-cls Write a minimal sink component class
+
+TODO!
+
+@page guide-write-simple-sink-comp-cls Write a simple sink component class
+
+TODO!
+
+@page guide-create-plugin Create a Babeltrace 2 plugin
+
+TODO!
+
+@page guide-write-full-src-comp-cls Write a complete source component class
+
+TODO!
+
+@page guide-write-full-flt-comp-cls Write a complete filter component class
+
+TODO!
+
+@page guide-write-full-sink-comp-cls Write a complete sink component class
+
+TODO!
+
+@page guide-query Query an object from a component class
+
+TODO!
+
+@page guide-seek-msg-iter Make a message iterator seek
+
+TODO!
+
+@page guide-intr-graph Interrupt a running graph
+
+TODO!
+
+@page guide-intr-query Interrupt a query operation
+
+TODO!
+
+@page guide-graph-listeners Use graph listeners to react to topology events
+
+TODO!
+
+@endif
+*/

diff --git a/doc/api/libbabeltrace2/dox/main-page.dox b/doc/api/libbabeltrace2/dox/main-page.dox
new file mode 100644 (file)
index 0000000..22c1e5d
--- /dev/null
+++ b/doc/api/libbabeltrace2/dox/main-page.dox
@@ -0,0 +1,124 @@
+/*!
+@mainpage Välkommen!
+
+@note
+This documentation (text and illustrations) is licensed under a
+<a href="https://creativecommons.org/licenses/by-sa/4.0/legalcode">Creative
+Commons Attribution-ShareAlike 4.0 International</a> license.
+
+Welcome to the
+<strong><em>\bt_api</em></strong> (libbabeltrace2) documentation!
+
+To get an idea of how to use the libbabeltrace2 API, have a look at
+the \ref guides "guides" and \ref examples "examples".
+That being said, we recommend that you read the \ref api-fund to
+understand what the API expects exactly.
+
+If you are developing a \bt_name \bt_plugin or an application which
+uses libbabeltrace2, we recommend that you
+\ref guide-build-bt2-dev "build the \bt_name library for development".
+
+@section main-bt2-nutshell \bt_name in a nutshell
+
+<a href="https://babeltrace.org/"><strong><em>\bt_name</em></strong></a>
+is an open-source software project by
+<a href="https://www.efficios.com/">EfficiOS</a>; its purpose is to
+process or convert
+<a href="https://en.wikipedia.org/wiki/Tracing_(software)">traces</a>.
+
+The \bt_name project contains:
+
+- A library, libbabeltrace2, which all the other parts rely on.
+
+  libbabeltrace2 offers a
+  <a href="https://en.wikipedia.org/wiki/C99">C99</a> interface.
+
+  This documentation is about libbabeltrace2's API.
+
+- A command-line program, \bt_cli, which can convert and manipulate
+  traces.
+
+- Python&nbsp;3 bindings which offer a Pythonic interface of
+  libbabeltrace2.
+
+- "Standard" plugins which ship with the project.
+
+  <a href="https://diamon.org/ctf/">Common Trace Format</a> (CTF) input
+  and output, plain text input and output, and various utilities are
+  part of those plugins.
+
+With the \bt_name library, you can:
+
+- Write custom \ref api-comp-cls-src "source",
+  \ref api-comp-cls-flt "filter", \ref api-comp-cls-sink "sink"
+  component classes which you can package as \bt_p_plugin.
+
+  Component classes are instantiated as \bt_p_comp within a trace
+  processing \bt_graph and components are assembled to accomplish a
+  trace manipulation or conversion job.
+
+- Load \bt_p_plugin, instantiate their component classes within a
+  trace processing \bt_graph, connect the components as needed, and
+  run the graph to accomplish a trace manipulation or conversion job.
+
+  This is what the \bt_cli CLI tool's
+  <a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2-convert.1"><code>convert</code></a>
+  and
+  <a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2-run.1"><code>run</code></a>
+  commands do, for example.
+
+A trace processing \bt_graph contains connected components. The specific
+component topology determines the trace processing task to realize.
+
+@image html basic-convert-graph.png "A conversion graph, a specific trace processing graph."
+
+Between the components of a trace processing graph, \bt_p_msg flow from
+\bt_p_oport to \bt_p_iport following the configured \bt_p_conn through
+\bt_p_msg_iter. There are many types of messages, chief amongst which is
+the \bt_ev_msg.
+
+With libbabeltrace2, you can also \ref api-qexec "query" some specific
+object from a component class (for example, the available LTTng live sessions
+of an <a href="https://lttng.org">LTTng</a> relay daemon).
+This is what the \bt_cli CLI tool's
+<a href="https://babeltrace.org/docs/v\bt_version_min_maj/man1/babeltrace2-query.1"><code>query</code></a>
+command does, for example.
+
+Make sure to read \bt_man{babeltrace2-intro,7}
+to learn even more about the \bt_name project and its core concepts.
+
+@section main-contents What's in this documentation?
+
+<dl>
+  <dt>\ref api-fund</dt>
+  <dd>
+    Explains the basic principles of the \bt_api.
+
+    Make sure you understand this section as you need this knowledge to
+    use the API correctly.
+  </dd>
+
+  <dt>\ref guides</dt>
+  <dd>
+    Shows how to achieve common tasks with libbabeltrace2.
+
+    Guides help you navigate through the most important features of
+    the library and its API.
+  </dd>
+
+  <dt>\ref examples</dt>
+  <dd>
+    Contains simple and more complex examples which apply the different
+    parts of the API to accomplish real tasks.
+  </dd>
+
+  <dt><a class="el" href="modules.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.
+  </dd>
+</dl>
+*/

diff --git a/doc/api/libbabeltrace2/examples/distill.c b/doc/api/libbabeltrace2/examples/distill.c
new file mode 100644 (file)
index 0000000..81fe2e8
--- /dev/null
+++ b/doc/api/libbabeltrace2/examples/distill.c
@@ -0,0 +1,284 @@
+#include <stdlib.h>
+#include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+#include <stdbool.h>
+#include <babeltrace2/babeltrace.h>
+
+/* Filter component's private data */
+struct distill {
+    /* Names of the classes of the events to discard (owned by this) */
+    const bt_value *names_value;
+
+    /* Component's input port (weak) */
+    bt_self_component_port_input *in_port;
+};
+
+/*
+ * Initializes the filter component.
+ */
+static
+bt_component_class_initialize_method_status distill_initialize(
+        bt_self_component_filter *self_component_filter,
+        bt_self_component_filter_configuration *configuration,
+        const bt_value *params, void *initialize_method_data)
+{
+    /* Allocate a private data structure */
+    struct distill *distill = malloc(sizeof(*distill));
+
+    /*
+     * Keep a reference of the `names` array value parameter so that the
+     * "next" method of a message iterator can access it to decide
+     * whether or not to discard an event message.
+     */
+    distill->names_value =
+        bt_value_map_borrow_entry_value_const(params, "names");
+    bt_value_get_ref(distill->names_value);
+
+    /* Set the component's user data to our private data structure */
+    bt_self_component_set_data(
+        bt_self_component_filter_as_self_component(self_component_filter),
+        distill);
+
+    /*
+     * Add an input port named `in` to the filter component.
+     *
+     * This is needed so that this filter component can be connected to
+     * a filter or a source component. With a connected upstream
+     * component, this filter component's message iterator can create a
+     * message iterator to consume messages.
+     *
+     * Add an output port named `out` to the filter component.
+     *
+     * This is needed so that this filter component can be connected to
+     * a filter or a sink component. Once a downstream component is
+     * connected, it can create our message iterator.
+     */
+    bt_self_component_filter_add_input_port(self_component_filter,
+        "in", NULL, &distill->in_port);
+    bt_self_component_filter_add_output_port(self_component_filter,
+        "out", NULL, NULL);
+
+    return BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK;
+}
+
+/*
+ * Finalizes the filter component.
+ */
+static
+void distill_finalize(bt_self_component_filter *self_component_filter)
+{
+    /* Retrieve our private data from the component's user data */
+    struct distill *distill = bt_self_component_get_data(
+        bt_self_component_filter_as_self_component(self_component_filter));
+
+    /* Put all references */
+    bt_value_put_ref(distill->names_value);
+
+    /* Free the allocated structure */
+    free(distill);
+}
+
+/* Message iterator's private data */
+struct distill_message_iterator {
+    /* (Weak) link to the component's private data */
+    struct distill *distill;
+
+    /* Upstream message iterator (owned by this) */
+    bt_message_iterator *message_iterator;
+};
+
+/*
+ * Initializes the message iterator.
+ */
+static
+bt_message_iterator_class_initialize_method_status
+distill_message_iterator_initialize(
+        bt_self_message_iterator *self_message_iterator,
+        bt_self_message_iterator_configuration *configuration,
+        bt_self_component_port_output *self_port)
+{
+    /* Allocate a private data structure */
+    struct distill_message_iterator *distill_iter =
+        malloc(sizeof(*distill_iter));
+
+    /* Retrieve the component's private data from its user data */
+    struct distill *distill = bt_self_component_get_data(
+        bt_self_message_iterator_borrow_component(self_message_iterator));
+
+    /* Keep a link to the component's private data */
+    distill_iter->distill = distill;
+
+    /* Create the uptream message iterator */
+    bt_message_iterator_create_from_message_iterator(self_message_iterator,
+        distill->in_port, &distill_iter->message_iterator);
+
+    /* Set the message iterator's user data to our private data structure */
+    bt_self_message_iterator_set_data(self_message_iterator, distill_iter);
+
+    return BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK;
+}
+
+/*
+ * Finalizes the message iterator.
+ */
+static
+void distill_message_iterator_finalize(
+        bt_self_message_iterator *self_message_iterator)
+{
+    /* Retrieve our private data from the message iterator's user data */
+    struct distill_message_iterator *distill_iter =
+        bt_self_message_iterator_get_data(self_message_iterator);
+
+    /* Free the allocated structure */
+    free(distill_iter);
+}
+
+/*
+ * Returns `true` if `message` passes, that is, one of:
+ *
+ * * It's not an event message.
+ * * The event message does not need to be discarded based on its event
+ *   class's name.
+ */
+static
+bool message_passes(struct distill_message_iterator *distill_iter,
+        const bt_message *message)
+{
+    bool passes = true;
+
+    /* Move as is if it's not an event message */
+    if (bt_message_get_type(message) != BT_MESSAGE_TYPE_EVENT) {
+        passes = false;
+        goto end;
+    }
+
+    /* Borrow the event message's event and its class */
+    const bt_event *event =
+        bt_message_event_borrow_event_const(message);
+    const bt_event_class *event_class = bt_event_borrow_class_const(event);
+
+    /* Get the event class's name */
+    const char *name = bt_event_class_get_name(event_class);
+
+    for (uint64_t i = 0; i < bt_value_array_get_length(
+            distill_iter->distill->names_value); i++) {
+        const char *discard_name = bt_value_string_get(
+            bt_value_array_borrow_element_by_index_const(
+                distill_iter->distill->names_value, i));
+
+        if (strcmp(name, discard_name) == 0) {
+            passes = false;
+            goto end;
+        }
+    }
+
+end:
+    return passes;
+}
+
+/*
+ * Returns the next message to the message iterator's user.
+ *
+ * This method can fill the `messages` array with up to `capacity`
+ * messages.
+ *
+ * To keep this example simple, we put a single message into `messages`
+ * and set `*count` to 1 (if the message iterator is not ended).
+ */
+static
+bt_message_iterator_class_next_method_status distill_message_iterator_next(
+        bt_self_message_iterator *self_message_iterator,
+        bt_message_array_const messages, uint64_t capacity,
+        uint64_t *count)
+{
+    /* Retrieve our private data from the message iterator's user data */
+    struct distill_message_iterator *distill_iter =
+        bt_self_message_iterator_get_data(self_message_iterator);
+
+    /* Consume a batch of messages from the upstream message iterator */
+    bt_message_array_const upstream_messages;
+    uint64_t upstream_message_count;
+    bt_message_iterator_next_status next_status;
+
+consume_upstream_messages:
+    next_status = bt_message_iterator_next(distill_iter->message_iterator,
+        &upstream_messages, &upstream_message_count);
+
+    /* Initialize the return status to a success */
+    bt_message_iterator_class_next_method_status status =
+        BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK;
+
+    switch (next_status) {
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_END:
+        /* End of iteration: put the message iterator's reference */
+        bt_message_iterator_put_ref(distill_iter->message_iterator);
+        status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END;
+        goto end;
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN:
+        status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN;
+        goto end;
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR:
+        status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR;
+        goto end;
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR:
+        status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR;
+        goto end;
+    default:
+        break;
+    }
+
+    /* Output message array index */
+    uint64_t i = 0;
+
+    /* For each consumed message */
+    for (uint64_t upstream_i = 0; upstream_i < upstream_message_count;
+            upstream_i++) {
+        /* Current message */
+        const bt_message *upstream_message = upstream_messages[upstream_i];
+
+        /* Check if the upstream message passes */
+        if (message_passes(distill_iter, upstream_message)) {
+            /* Move upstream message to output message array */
+            messages[i] = upstream_message;
+            i++;
+            continue;
+        }
+
+        /* Discard upstream message: put its reference */
+        bt_message_put_ref(upstream_message);
+    }
+
+    if (i == 0) {
+        /*
+         * We discarded all the upstream messages: get a new batch of
+         * messages, because this method _cannot_ return
+         * `BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK` and put no
+         * messages into its output message array.
+         */
+        goto consume_upstream_messages;
+    }
+
+    *count = i;
+
+end:
+    return status;
+}
+
+/* Mandatory */
+BT_PLUGIN_MODULE();
+
+/* Define the `distill` plugin */
+BT_PLUGIN(distill);
+
+/* Define the `theone` filter component class */
+BT_PLUGIN_FILTER_COMPONENT_CLASS(theone, distill_message_iterator_next);
+
+/* Set some of the `theone` filter component class's optional methods */
+BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD(theone, distill_initialize);
+BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD(theone, distill_finalize);
+BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(
+    theone, distill_message_iterator_initialize);
+BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(theone,
+    distill_message_iterator_finalize);

diff --git a/doc/api/libbabeltrace2/examples/dust b/doc/api/libbabeltrace2/examples/dust
new file mode 100644 (file)
index 0000000..de23860
--- /dev/null
+++ b/doc/api/libbabeltrace2/examples/dust
@@ -0,0 +1,5 @@
+1578694237 154215 send-msg Jowl pig filet mignon, turducken capicola.
+1578694237 200774 recv-msg Pork belly pig burgdoggen venison bacon.
+1578694241 001831 send-msg Bacon ipsum dolor amet strip steak.
+1578694241 944187 send-msg Spare ribs filet mignon boudin bresaola.
+1578694245 115406 recv-msg Rump cow t-bone hamburger short tenderloin.

diff --git a/doc/api/libbabeltrace2/examples/dust.c b/doc/api/libbabeltrace2/examples/dust.c
new file mode 100644 (file)
index 0000000..fd1f1db
--- /dev/null
+++ b/doc/api/libbabeltrace2/examples/dust.c
@@ -0,0 +1,436 @@
+#include <stdlib.h>
+#include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+#include <babeltrace2/babeltrace.h>
+
+/* Source component's private data */
+struct dust_in {
+    /* Input file path parameter value (owned by this) */
+    const bt_value *path_value;
+
+    /* Stream (owned by this) */
+    bt_stream *stream;
+
+    /* Event classes for each type of event (owned by this) */
+    bt_event_class *send_msg_event_class;
+    bt_event_class *recv_msg_event_class;
+};
+
+/*
+ * Creates an event class within `stream_class` named `name`.
+ */
+static
+bt_event_class *create_event_class(bt_stream_class *stream_class,
+        const char *name)
+{
+    /* Borrow trace class from stream class */
+    bt_trace_class *trace_class =
+        bt_stream_class_borrow_trace_class(stream_class);
+
+    /* Create a default event class */
+    bt_event_class *event_class = bt_event_class_create(stream_class);
+
+    /* Name the event class */
+    bt_event_class_set_name(event_class, name);
+
+    /*
+     * Create an empty structure field class to be used as the
+     * event class's payload field class.
+     */
+    bt_field_class *payload_field_class =
+        bt_field_class_structure_create(trace_class);
+
+    /*
+     * Create a string field class to be used as the payload field
+     * class's `msg` member.
+     */
+    bt_field_class *msg_field_class =
+        bt_field_class_string_create(trace_class);
+
+    /*
+     * Append the string field class to the structure field class as the
+     * `msg` member.
+     */
+    bt_field_class_structure_append_member(payload_field_class, "msg",
+        msg_field_class);
+
+    /* Set the event class's payload field class */
+    bt_event_class_set_payload_field_class(event_class, payload_field_class);
+
+    /* Put the references we don't need anymore */
+    bt_field_class_put_ref(payload_field_class);
+    bt_field_class_put_ref(msg_field_class);
+
+    return event_class;
+}
+
+/*
+ * Creates the source component's metadata and stream objects.
+ */
+static
+void create_metadata_and_stream(bt_self_component *self_component,
+        struct dust_in *dust_in)
+{
+    /* Create a default trace class */
+    bt_trace_class *trace_class = bt_trace_class_create(self_component);
+
+    /* Create a stream trace class within `trace_class` */
+    bt_stream_class *stream_class = bt_stream_class_create(trace_class);
+
+    /* Create a default clock class (1 GHz frequency) */
+    bt_clock_class *clock_class = bt_clock_class_create(self_component);
+
+    /*
+     * Set `clock_class` as the default clock class of `stream_class`.
+     *
+     * This means all the streams created from `stream_class` have a
+     * conceptual default clock which is an instance of `clock_class`.
+     * Any event message created for such a stream has a snapshot of the
+     * stream's default clock.
+     */
+    bt_stream_class_set_default_clock_class(stream_class, clock_class);
+
+    /* Create the two event classes we need */
+    dust_in->send_msg_event_class = create_event_class(stream_class,
+        "send-msg");
+    dust_in->recv_msg_event_class = create_event_class(stream_class,
+        "recv-msg");
+
+    /* Create a default trace from (instance of `trace_class`) */
+    bt_trace *trace = bt_trace_create(trace_class);
+
+    /*
+     * Create the source component's stream (instance of `stream_class`
+     * within `trace`).
+     */
+    dust_in->stream = bt_stream_create(stream_class, trace);
+
+    /* Put the references we don't need anymore */
+    bt_trace_put_ref(trace);
+    bt_clock_class_put_ref(clock_class);
+    bt_stream_class_put_ref(stream_class);
+    bt_trace_class_put_ref(trace_class);
+}
+
+/*
+ * Initializes the source component.
+ */
+static
+bt_component_class_initialize_method_status dust_in_initialize(
+        bt_self_component_source *self_component_source,
+        bt_self_component_source_configuration *configuration,
+        const bt_value *params, void *initialize_method_data)
+{
+    /* Allocate a private data structure */
+    struct dust_in *dust_in = malloc(sizeof(*dust_in));
+
+    /*
+     * Keep a reference of the `path` string value parameter so that the
+     * initialization method of a message iterator can read its string
+     * value to open the file.
+     */
+    dust_in->path_value =
+        bt_value_map_borrow_entry_value_const(params, "path");
+    bt_value_get_ref(dust_in->path_value);
+
+    /* Upcast `self_component_source` to the `bt_self_component` type */
+    bt_self_component *self_component =
+        bt_self_component_source_as_self_component(self_component_source);
+
+    /* Create the source component's metadata and stream objects */
+    create_metadata_and_stream(self_component, dust_in);
+
+    /* Set the component's user data to our private data structure */
+    bt_self_component_set_data(self_component, dust_in);
+
+    /*
+     * Add an output port named `out` to the source component.
+     *
+     * This is needed so that this source component can be connected to
+     * a filter or a sink component. Once a downstream component is
+     * connected, it can create our message iterator.
+     */
+    bt_self_component_source_add_output_port(self_component_source,
+        "out", NULL, NULL);
+
+    return BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK;
+}
+
+/*
+ * Finalizes the source component.
+ */
+static
+void dust_in_finalize(bt_self_component_source *self_component_source)
+{
+    /* Retrieve our private data from the component's user data */
+    struct dust_in *dust_in = bt_self_component_get_data(
+        bt_self_component_source_as_self_component(self_component_source));
+
+    /* Put all references */
+    bt_value_put_ref(dust_in->path_value);
+    bt_event_class_put_ref(dust_in->send_msg_event_class);
+    bt_event_class_put_ref(dust_in->recv_msg_event_class);
+    bt_stream_put_ref(dust_in->stream);
+
+    /* Free the allocated structure */
+    free(dust_in);
+}
+
+/* State of a message iterator */
+enum dust_in_message_iterator_state {
+    /* Emit a stream beginning message */
+    DUST_IN_MESSAGE_ITERATOR_STATE_STREAM_BEGINNING,
+
+    /* Emit an event message */
+    DUST_IN_MESSAGE_ITERATOR_STATE_EVENT,
+
+    /* Message iterator is ended */
+    DUST_IN_MESSAGE_ITERATOR_STATE_ENDED,
+};
+
+/* Message iterator's private data */
+struct dust_in_message_iterator {
+    /* (Weak) link to the component's private data */
+    struct dust_in *dust_in;
+
+    /* Current message iterator's state */
+    enum dust_in_message_iterator_state state;
+
+    /* Input file */
+    FILE *file;
+
+    /* Buffers to read data from the input file */
+    char name_buffer[32];
+    char msg_buffer[1024];
+};
+
+/*
+ * Initializes the message iterator.
+ */
+static
+bt_message_iterator_class_initialize_method_status
+dust_in_message_iterator_initialize(
+        bt_self_message_iterator *self_message_iterator,
+        bt_self_message_iterator_configuration *configuration,
+        bt_self_component_port_output *self_port)
+{
+    /* Allocate a private data structure */
+    struct dust_in_message_iterator *dust_in_iter =
+        malloc(sizeof(*dust_in_iter));
+
+    /* Retrieve the component's private data from its user data */
+    struct dust_in *dust_in = bt_self_component_get_data(
+        bt_self_message_iterator_borrow_component(self_message_iterator));
+
+    /* Keep a link to the component's private data */
+    dust_in_iter->dust_in = dust_in;
+
+    /* Set the message iterator's initial state */
+    dust_in_iter->state = DUST_IN_MESSAGE_ITERATOR_STATE_STREAM_BEGINNING;
+
+    /* Get the raw value of the input file path string value */
+    const char *path = bt_value_string_get(dust_in->path_value);
+
+    /* Open the input file in text mode */
+    dust_in_iter->file = fopen(path, "r");
+
+    /* Set the message iterator's user data to our private data structure */
+    bt_self_message_iterator_set_data(self_message_iterator, dust_in_iter);
+
+    return BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK;
+}
+
+/*
+ * Finalizes the message iterator.
+ */
+static
+void dust_in_message_iterator_finalize(
+        bt_self_message_iterator *self_message_iterator)
+{
+    /* Retrieve our private data from the message iterator's user data */
+    struct dust_in_message_iterator *dust_in_iter =
+        bt_self_message_iterator_get_data(self_message_iterator);
+
+    /* Close the input file */
+    fclose(dust_in_iter->file);
+
+    /* Free the allocated structure */
+    free(dust_in_iter);
+}
+
+/*
+ * Creates a message from the message iterator's input file's current
+ * line.
+ *
+ * If there's a line to process, this function creates an event message.
+ * Otherwise it creates a stream end message and sets the message
+ * iterator's state accordingly.
+ */
+static
+bt_message *create_message_from_line(
+        struct dust_in_message_iterator *dust_in_iter,
+        bt_self_message_iterator *self_message_iterator)
+{
+    uint64_t timestamp;
+    uint64_t extra_us;
+    bt_message *message;
+
+    /* Try to read a line from the input file into individual tokens */
+    int count = fscanf(dust_in_iter->file, "%" PRIu64 " %" PRIu64 " %s %[^\n]",
+        &timestamp, &extra_us, &dust_in_iter->name_buffer[0],
+        &dust_in_iter->msg_buffer[0]);
+
+    /* Reached the end of the file? */
+    if (count == EOF || feof(dust_in_iter->file)) {
+        /*
+         * Reached the end of the file: create a stream end message and
+         * set the message iterator's state to
+         * `DUST_IN_MESSAGE_ITERATOR_STATE_ENDED` so that the next call
+         * to dust_in_message_iterator_next() returns
+         * `BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END` (end of
+         * iteration).
+         */
+        message = bt_message_stream_end_create(self_message_iterator,
+            dust_in_iter->dust_in->stream);
+        dust_in_iter->state = DUST_IN_MESSAGE_ITERATOR_STATE_ENDED;
+        goto end;
+    }
+
+    /* Choose the correct event class, depending on the event name token */
+    bt_event_class *event_class;
+
+    if (strcmp(dust_in_iter->name_buffer, "send-msg") == 0) {
+        event_class = dust_in_iter->dust_in->send_msg_event_class;
+    } else {
+        event_class = dust_in_iter->dust_in->recv_msg_event_class;
+    }
+
+    /*
+     * At this point `timestamp` contains seconds since the Unix epoch.
+     * Multiply it by 1,000,000,000 to get nanoseconds since the Unix
+     * epoch because the stream's clock's frequency is 1 GHz.
+     */
+    timestamp *= UINT64_C(1000000000);
+
+    /* Add the extra microseconds (as nanoseconds) to `timestamp` */
+    timestamp += extra_us * UINT64_C(1000);
+
+    /* Create the event message */
+    message = bt_message_event_create_with_default_clock_snapshot(
+        self_message_iterator, event_class, dust_in_iter->dust_in->stream,
+        timestamp);
+
+    /*
+     * At this point `message` is an event message which contains
+     * an empty event object.
+     *
+     * We need to fill its fields.
+     *
+     * The only field to fill is the payload field's `msg` field
+     * which is the event record's message.
+     *
+     * All the references below are borrowed references, therefore we
+     * don't need to put them.
+     */
+    bt_event *event = bt_message_event_borrow_event(message);
+    bt_field *payload_field = bt_event_borrow_payload_field(event);
+    bt_field *msg_field = bt_field_structure_borrow_member_field_by_index(
+        payload_field, 0);
+
+    bt_field_string_set_value(msg_field, dust_in_iter->msg_buffer);
+
+end:
+    return message;
+}
+
+/*
+ * Returns the next message to the message iterator's user.
+ *
+ * This method can fill the `messages` array with up to `capacity`
+ * messages.
+ *
+ * To keep this example simple, we put a single message into `messages`
+ * and set `*count` to 1 (if the message iterator is not ended).
+ */
+static
+bt_message_iterator_class_next_method_status dust_in_message_iterator_next(
+        bt_self_message_iterator *self_message_iterator,
+        bt_message_array_const messages, uint64_t capacity,
+        uint64_t *count)
+{
+    /* Retrieve our private data from the message iterator's user data */
+    struct dust_in_message_iterator *dust_in_iter =
+        bt_self_message_iterator_get_data(self_message_iterator);
+
+    /*
+     * This is the message to return (by moving it to the `messages`
+     * array).
+     *
+     * We initialize it to `NULL`. If it's not `NULL` after the
+     * processing below, then we move it to the message array.
+     */
+    bt_message *message = NULL;
+
+    /* Initialize the return status to a success */
+    bt_message_iterator_class_next_method_status status =
+        BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK;
+
+    switch (dust_in_iter->state) {
+    case DUST_IN_MESSAGE_ITERATOR_STATE_STREAM_BEGINNING:
+        /* Create a stream beginning message */
+        message = bt_message_stream_beginning_create(self_message_iterator,
+            dust_in_iter->dust_in->stream);
+
+        /* Next state: an event message */
+        dust_in_iter->state = DUST_IN_MESSAGE_ITERATOR_STATE_EVENT;
+        break;
+    case DUST_IN_MESSAGE_ITERATOR_STATE_EVENT:
+        /*
+         * Create an event or a stream end message from the message
+         * iterator's input file's current line.
+         *
+         * This function also updates the message iterator's state if
+         * needed.
+         */
+        message = create_message_from_line(dust_in_iter,
+            self_message_iterator);
+        break;
+    case DUST_IN_MESSAGE_ITERATOR_STATE_ENDED:
+        /* Message iterator is ended: return the corresponding status */
+        status =
+            BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END;
+        goto end;
+    }
+
+    if (message) {
+        /*
+         * We created a message above: move it to the beginning of the
+         * `messages` array, setting `*count` to 1 to indicate that the
+         * array contains a single message.
+         */
+        messages[0] = message;
+        *count = 1;
+    }
+
+end:
+    return status;
+}
+
+/* Mandatory */
+BT_PLUGIN_MODULE();
+
+/* Define the `dust` plugin */
+BT_PLUGIN(dust);
+
+/* Define the `input` source component class */
+BT_PLUGIN_SOURCE_COMPONENT_CLASS(input, dust_in_message_iterator_next);
+
+/* Set some of the `input` source component class's optional methods */
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD(input, dust_in_initialize);
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD(input, dust_in_finalize);
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(input,
+    dust_in_message_iterator_initialize);
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(input,
+    dust_in_message_iterator_finalize);

diff --git a/doc/api/libbabeltrace2/examples/epitome.c b/doc/api/libbabeltrace2/examples/epitome.c
new file mode 100644 (file)
index 0000000..852ca3f
--- /dev/null
+++ b/doc/api/libbabeltrace2/examples/epitome.c
@@ -0,0 +1,196 @@
+#include <stdlib.h>
+#include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
+#include <string.h>
+#include <babeltrace2/babeltrace.h>
+
+/* Sink component's private data */
+struct epitome_out {
+    /* Upstream message iterator (owned by this) */
+    bt_message_iterator *message_iterator;
+
+    /* Current event message index */
+    uint64_t index;
+};
+
+/*
+ * Initializes the sink component.
+ */
+static
+bt_component_class_initialize_method_status epitome_out_initialize(
+        bt_self_component_sink *self_component_sink,
+        bt_self_component_sink_configuration *configuration,
+        const bt_value *params, void *initialize_method_data)
+{
+    /* Allocate a private data structure */
+    struct epitome_out *epitome_out = malloc(sizeof(*epitome_out));
+
+    /* Initialize the first event message's index */
+    epitome_out->index = 1;
+
+    /* Set the component's user data to our private data structure */
+    bt_self_component_set_data(
+        bt_self_component_sink_as_self_component(self_component_sink),
+        epitome_out);
+
+    /*
+     * Add an input port named `in` to the sink component.
+     *
+     * This is needed so that this sink component can be connected to a
+     * filter or a source component. With a connected upstream
+     * component, this sink component can create a message iterator
+     * to consume messages.
+     */
+    bt_self_component_sink_add_input_port(self_component_sink,
+        "in", NULL, NULL);
+
+    return BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK;
+}
+
+/*
+ * Finalizes the sink component.
+ */
+static
+void epitome_out_finalize(bt_self_component_sink *self_component_sink)
+{
+    /* Retrieve our private data from the component's user data */
+    struct epitome_out *epitome_out = bt_self_component_get_data(
+        bt_self_component_sink_as_self_component(self_component_sink));
+
+    /* Free the allocated structure */
+    free(epitome_out);
+}
+
+/*
+ * Called when the trace processing graph containing the sink component
+ * is configured.
+ *
+ * This is where we can create our upstream message iterator.
+ */
+static
+bt_component_class_sink_graph_is_configured_method_status
+epitome_out_graph_is_configured(bt_self_component_sink *self_component_sink)
+{
+    /* Retrieve our private data from the component's user data */
+    struct epitome_out *epitome_out = bt_self_component_get_data(
+        bt_self_component_sink_as_self_component(self_component_sink));
+
+    /* Borrow our unique port */
+    bt_self_component_port_input *in_port =
+        bt_self_component_sink_borrow_input_port_by_index(
+            self_component_sink, 0);
+
+    /* Create the uptream message iterator */
+    bt_message_iterator_create_from_sink_component(self_component_sink,
+        in_port, &epitome_out->message_iterator);
+
+    return BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK;
+}
+
+/*
+ * Prints a line for `message`, if it's an event message, to the
+ * standard output.
+ */
+static
+void print_message(struct epitome_out *epitome_out, const bt_message *message)
+{
+    /* Discard if it's not an event message */
+    if (bt_message_get_type(message) != BT_MESSAGE_TYPE_EVENT) {
+        goto end;
+    }
+
+    /* Borrow the event message's event and its class */
+    const bt_event *event =
+        bt_message_event_borrow_event_const(message);
+    const bt_event_class *event_class = bt_event_borrow_class_const(event);
+
+    /* Get the number of payload field members */
+    const bt_field *payload_field =
+        bt_event_borrow_payload_field_const(event);
+    uint64_t member_count = bt_field_class_structure_get_member_count(
+        bt_field_borrow_class_const(payload_field));
+
+    /* Write a corresponding line to the standard output */
+    printf("#%" PRIu64 ": %s (%" PRIu64 " payload member%s)\n",
+        epitome_out->index, bt_event_class_get_name(event_class),
+        member_count, member_count == 1 ? "" : "s");
+
+    /* Increment the current event message's index */
+    epitome_out->index++;
+
+end:
+    return;
+}
+
+/*
+ * Consumes a batch of messages and writes the corresponding lines to
+ * the standard output.
+ */
+bt_component_class_sink_consume_method_status epitome_out_consume(
+        bt_self_component_sink *self_component_sink)
+{
+    bt_component_class_sink_consume_method_status status =
+        BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK;
+
+    /* Retrieve our private data from the component's user data */
+    struct epitome_out *epitome_out = bt_self_component_get_data(
+        bt_self_component_sink_as_self_component(self_component_sink));
+
+    /* Consume a batch of messages from the upstream message iterator */
+    bt_message_array_const messages;
+    uint64_t message_count;
+    bt_message_iterator_next_status next_status =
+        bt_message_iterator_next(epitome_out->message_iterator, &messages,
+            &message_count);
+
+    switch (next_status) {
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_END:
+        /* End of iteration: put the message iterator's reference */
+        bt_message_iterator_put_ref(epitome_out->message_iterator);
+        status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END;
+        goto end;
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN:
+        status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN;
+        goto end;
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR:
+        status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR;
+        goto end;
+    case BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR:
+        status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR;
+        goto end;
+    default:
+        break;
+    }
+
+    /* For each consumed message */
+    for (uint64_t i = 0; i < message_count; i++) {
+        /* Current message */
+        const bt_message *message = messages[i];
+
+        /* Print line for current message if it's an event message */
+        print_message(epitome_out, message);
+
+        /* Put this message's reference */
+        bt_message_put_ref(message);
+    }
+
+end:
+    return status;
+}
+
+/* Mandatory */
+BT_PLUGIN_MODULE();
+
+/* Define the `epitome` plugin */
+BT_PLUGIN(epitome);
+
+/* Define the `output` sink component class */
+BT_PLUGIN_SINK_COMPONENT_CLASS(output, epitome_out_consume);
+
+/* Set some of the `output` sink component class's optional methods */
+BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD(output,
+    epitome_out_initialize);
+BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD(output, epitome_out_finalize);
+BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD(output,
+    epitome_out_graph_is_configured);

diff --git a/doc/api/libbabeltrace2/examples/vestige-plugin.c b/doc/api/libbabeltrace2/examples/vestige-plugin.c
new file mode 100644 (file)
index 0000000..5f607ff
--- /dev/null
+++ b/doc/api/libbabeltrace2/examples/vestige-plugin.c
@@ -0,0 +1,45 @@
+/* Component class method declarations */
+#include "vestige.h"
+
+/* Always start with this line */
+BT_PLUGIN_MODULE();
+
+/* Declare the `vestige` plugin */
+BT_PLUGIN(vestige);
+
+/* Set some optional plugin properties */
+BT_PLUGIN_DESCRIPTION("Input and output for the Vestige format.");
+BT_PLUGIN_AUTHOR("Denis Rondeau");
+BT_PLUGIN_LICENSE("MIT");
+
+/* Add the `input` source component class */
+BT_PLUGIN_SOURCE_COMPONENT_CLASS(input, vestige_in_iter_next);
+
+/* Set the source component class's optional description */
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION(input,
+    "Read a Vestige trace file.");
+
+/* Set some optional methods of the source component class */
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD(input,
+    vestige_in_init);
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD(input,
+    vestige_in_finalize);
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(
+    input, vestige_in_iter_init);
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(
+    input, vestige_in_iter_fini);
+
+/* Add the `output` sink component class */
+BT_PLUGIN_SINK_COMPONENT_CLASS(output, vestige_out_consume);
+
+/* Set the sink component class's optional description */
+BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION(output,
+    "Write a Vestige trace file.");
+
+/* Set some optional methods of the sink component class */
+BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD(output,
+    vestige_out_init);
+BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD(output,
+    vestige_out_finalize);
+BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD(output,
+    vestige_out_graph_is_configured);

diff --git a/doc/api/libbabeltrace2/images/all-field-classes.png b/doc/api/libbabeltrace2/images/all-field-classes.png
new file mode 100644 (file)
index 0000000..aa39252
Binary files /dev/null and b/doc/api/libbabeltrace2/images/all-field-classes.png differ

diff --git a/doc/api/libbabeltrace2/images/all-fields.png b/doc/api/libbabeltrace2/images/all-fields.png
new file mode 100644 (file)
index 0000000..7385064
Binary files /dev/null and b/doc/api/libbabeltrace2/images/all-fields.png differ

diff --git a/doc/api/libbabeltrace2/images/basic-convert-graph.png b/doc/api/libbabeltrace2/images/basic-convert-graph.png
new file mode 100644 (file)
index 0000000..a97dfca
Binary files /dev/null and b/doc/api/libbabeltrace2/images/basic-convert-graph.png differ

diff --git a/doc/api/libbabeltrace2/images/clock-terminology.png b/doc/api/libbabeltrace2/images/clock-terminology.png
new file mode 100644 (file)
index 0000000..5e26b5b
Binary files /dev/null and b/doc/api/libbabeltrace2/images/clock-terminology.png differ

diff --git a/doc/api/libbabeltrace2/images/clocks.png b/doc/api/libbabeltrace2/images/clocks.png
new file mode 100644 (file)
index 0000000..0a3f375
Binary files /dev/null and b/doc/api/libbabeltrace2/images/clocks.png differ

diff --git a/doc/api/libbabeltrace2/images/complex-graph.png b/doc/api/libbabeltrace2/images/complex-graph.png
new file mode 100644 (file)
index 0000000..53d7bf6
Binary files /dev/null and b/doc/api/libbabeltrace2/images/complex-graph.png differ

diff --git a/doc/api/libbabeltrace2/images/component-zoom.png b/doc/api/libbabeltrace2/images/component-zoom.png
new file mode 100644 (file)
index 0000000..7d2b7aa
Binary files /dev/null and b/doc/api/libbabeltrace2/images/component-zoom.png differ

diff --git a/doc/api/libbabeltrace2/images/component.png b/doc/api/libbabeltrace2/images/component.png
new file mode 100644 (file)
index 0000000..eb9c621
Binary files /dev/null and b/doc/api/libbabeltrace2/images/component.png differ

diff --git a/doc/api/libbabeltrace2/images/darray-link.png b/doc/api/libbabeltrace2/images/darray-link.png
new file mode 100644 (file)
index 0000000..0c219c6
Binary files /dev/null and b/doc/api/libbabeltrace2/images/darray-link.png differ

diff --git a/doc/api/libbabeltrace2/images/error-reporting-step-5.png b/doc/api/libbabeltrace2/images/error-reporting-step-5.png
new file mode 100644 (file)
index 0000000..0f3fbc6
Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-step-5.png differ

diff --git a/doc/api/libbabeltrace2/images/error-reporting-step-6.png b/doc/api/libbabeltrace2/images/error-reporting-step-6.png
new file mode 100644 (file)
index 0000000..561d5c7
Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-step-6.png differ

diff --git a/doc/api/libbabeltrace2/images/error-reporting-step-7.png b/doc/api/libbabeltrace2/images/error-reporting-step-7.png
new file mode 100644 (file)
index 0000000..313ffcd
Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-step-7.png differ

diff --git a/doc/api/libbabeltrace2/images/error-reporting-steps-1234.png b/doc/api/libbabeltrace2/images/error-reporting-steps-1234.png
new file mode 100644 (file)
index 0000000..fe6f7a8
Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-steps-1234.png differ

diff --git a/doc/api/libbabeltrace2/images/error-reporting-steps-89.png b/doc/api/libbabeltrace2/images/error-reporting-steps-89.png
new file mode 100644 (file)
index 0000000..5a95c87
Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-steps-89.png differ

diff --git a/doc/api/libbabeltrace2/images/error-reporting.png b/doc/api/libbabeltrace2/images/error-reporting.png
new file mode 100644 (file)
index 0000000..690def6
Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-array.png b/doc/api/libbabeltrace2/images/fc-array.png
new file mode 100644 (file)
index 0000000..2764459
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-array.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-ba.png b/doc/api/libbabeltrace2/images/fc-ba.png
new file mode 100644 (file)
index 0000000..9d3af46
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-ba.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-bool.png b/doc/api/libbabeltrace2/images/fc-bool.png
new file mode 100644 (file)
index 0000000..34274eb
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-bool.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-enum.png b/doc/api/libbabeltrace2/images/fc-enum.png
new file mode 100644 (file)
index 0000000..56c74af
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-enum.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-int.png b/doc/api/libbabeltrace2/images/fc-int.png
new file mode 100644 (file)
index 0000000..4e7e876
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-int.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-opt.png b/doc/api/libbabeltrace2/images/fc-opt.png
new file mode 100644 (file)
index 0000000..60b3fcf
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-opt.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-real.png b/doc/api/libbabeltrace2/images/fc-real.png
new file mode 100644 (file)
index 0000000..21d7240
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-real.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-string.png b/doc/api/libbabeltrace2/images/fc-string.png
new file mode 100644 (file)
index 0000000..3232f01
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-string.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-struct.png b/doc/api/libbabeltrace2/images/fc-struct.png
new file mode 100644 (file)
index 0000000..467e570
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-struct.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-to-field.png b/doc/api/libbabeltrace2/images/fc-to-field.png
new file mode 100644 (file)
index 0000000..47d4540
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-to-field.png differ

diff --git a/doc/api/libbabeltrace2/images/fc-var.png b/doc/api/libbabeltrace2/images/fc-var.png
new file mode 100644 (file)
index 0000000..b4a88c0
Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-var.png differ

diff --git a/doc/api/libbabeltrace2/images/field-class-zoom.png b/doc/api/libbabeltrace2/images/field-class-zoom.png
new file mode 100644 (file)
index 0000000..4a577e5
Binary files /dev/null and b/doc/api/libbabeltrace2/images/field-class-zoom.png differ

diff --git a/doc/api/libbabeltrace2/images/graph-lifetime.png b/doc/api/libbabeltrace2/images/graph-lifetime.png
new file mode 100644 (file)
index 0000000..3d1079a
Binary files /dev/null and b/doc/api/libbabeltrace2/images/graph-lifetime.png differ

diff --git a/doc/api/libbabeltrace2/images/linking.png b/doc/api/libbabeltrace2/images/linking.png
new file mode 100644 (file)
index 0000000..c137fc2
Binary files /dev/null and b/doc/api/libbabeltrace2/images/linking.png differ

diff --git a/doc/api/libbabeltrace2/images/msg-iter-cls.png b/doc/api/libbabeltrace2/images/msg-iter-cls.png
new file mode 100644 (file)
index 0000000..03526cc
Binary files /dev/null and b/doc/api/libbabeltrace2/images/msg-iter-cls.png differ

diff --git a/doc/api/libbabeltrace2/images/msg-iter-complex.png b/doc/api/libbabeltrace2/images/msg-iter-complex.png
new file mode 100644 (file)
index 0000000..ba16db3
Binary files /dev/null and b/doc/api/libbabeltrace2/images/msg-iter-complex.png differ

diff --git a/doc/api/libbabeltrace2/images/msg-iter.png b/doc/api/libbabeltrace2/images/msg-iter.png
new file mode 100644 (file)
index 0000000..d261404
Binary files /dev/null and b/doc/api/libbabeltrace2/images/msg-iter.png differ

diff --git a/doc/api/libbabeltrace2/images/opt-link.png b/doc/api/libbabeltrace2/images/opt-link.png
new file mode 100644 (file)
index 0000000..784fa47
Binary files /dev/null and b/doc/api/libbabeltrace2/images/opt-link.png differ

diff --git a/doc/api/libbabeltrace2/images/plugin-comp-cls-full.png b/doc/api/libbabeltrace2/images/plugin-comp-cls-full.png
new file mode 100644 (file)
index 0000000..95915e6
Binary files /dev/null and b/doc/api/libbabeltrace2/images/plugin-comp-cls-full.png differ

diff --git a/doc/api/libbabeltrace2/images/plugin.png b/doc/api/libbabeltrace2/images/plugin.png
new file mode 100644 (file)
index 0000000..3ca5058
Binary files /dev/null and b/doc/api/libbabeltrace2/images/plugin.png differ

diff --git a/doc/api/libbabeltrace2/images/trace-structure-msg-seq.png b/doc/api/libbabeltrace2/images/trace-structure-msg-seq.png
new file mode 100644 (file)
index 0000000..1529774
Binary files /dev/null and b/doc/api/libbabeltrace2/images/trace-structure-msg-seq.png differ

diff --git a/doc/api/libbabeltrace2/images/trace-structure.png b/doc/api/libbabeltrace2/images/trace-structure.png
new file mode 100644 (file)
index 0000000..6228eac
Binary files /dev/null and b/doc/api/libbabeltrace2/images/trace-structure.png differ

diff --git a/doc/api/libbabeltrace2/images/var-link.png b/doc/api/libbabeltrace2/images/var-link.png
new file mode 100644 (file)
index 0000000..6ddfe07
Binary files /dev/null and b/doc/api/libbabeltrace2/images/var-link.png differ

diff --git a/doc/api/libbabeltrace2/style.css b/doc/api/libbabeltrace2/style.css
new file mode 100644 (file)
index 0000000..4a42678
--- /dev/null
+++ b/doc/api/libbabeltrace2/style.css
@@ -0,0 +1,79 @@
+.contents h1,
+.contents h2,
+.contents h3 {
+    color: #6A2F43;
+}
+
+.contents h1,
+.contents h2 {
+    border-bottom: 1px solid #ccc;
+    display: inline-block;
+}
+
+.contents h1 {
+    font-size: 1.5em;
+    margin-top: 2em;
+}
+
+.contents h2 {
+    font-size: 1.2em;
+    margin-top: 1.5em;
+}
+
+.contents dl {
+    margin-left: 2em;
+}
+
+.contents dl.params,
+.contents dl.section,
+.contents dl.retval,
+.contents dl.exception,
+.contents dl.tparams {
+    margin-left: 0;
+}
+
+.contents .image {
+    background-color: rgba(0, 0, 0, .05);
+    padding-top: 1em;
+    padding-bottom: 1em;
+}
+
+.contents .image img {
+    border: 1px solid #ccc;
+    background-color: white;
+    padding: 1em;
+}
+
+.contents .image .caption {
+    font-size: 75%;
+}
+
+.contents .fragment {
+    padding: 1em;
+}
+
+#projectname {
+    font-size: 200%;
+}
+
+#projectbrief {
+    display: none;
+}
+
+span.bt-param,
+table.params .paramname {
+    color: #602020;
+    font-weight: bold;
+    font-family: monospace;
+    font-size: 90%;
+}
+
+.contents dl.attention {
+    background-color: #fbdfda;
+    padding-top: 1em;
+    padding-bottom: 1em;
+}
+
+.contents table.doxtable th {
+    background-color: #5173b3;
+}

diff --git a/include/Makefile.am b/include/Makefile.am
index dbb6efa5d796952fad49c7b59925b0b2f08efd04..159482c96ea08daa48a01a5e053338c38151545e 100644 (file)
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -2,18 +2,13 @@
 babeltrace2includedir = "$(includedir)/babeltrace2"
 babeltrace2include_HEADERS = \
        babeltrace2/babeltrace.h \
-       babeltrace2/current-thread.h \
-       babeltrace2/error-cause-const.h \
-       babeltrace2/error-const.h \
+       babeltrace2/error-reporting.h \
        babeltrace2/func-status.h \
-       babeltrace2/integer-range-set-const.h \
        babeltrace2/integer-range-set.h \
-       babeltrace2/logging.h \
        babeltrace2/logging-defs.h \
-       babeltrace2/property.h \
+       babeltrace2/logging.h \
        babeltrace2/types.h \
        babeltrace2/util.h \
-       babeltrace2/value-const.h \
        babeltrace2/value.h \
        babeltrace2/version.h
 
@@ -39,94 +34,42 @@ babeltrace2ctfwriterinclude_HEADERS = \
 # Trace IR API
 babeltrace2traceirincludedir = "$(includedir)/babeltrace2/trace-ir"
 babeltrace2traceirinclude_HEADERS = \
-       babeltrace2/trace-ir/clock-class-const.h \
        babeltrace2/trace-ir/clock-class.h \
-       babeltrace2/trace-ir/clock-snapshot-const.h \
-       babeltrace2/trace-ir/event-class-const.h \
+       babeltrace2/trace-ir/clock-snapshot.h \
        babeltrace2/trace-ir/event-class.h \
-       babeltrace2/trace-ir/event-const.h \
        babeltrace2/trace-ir/event.h \
-       babeltrace2/trace-ir/field-class-const.h \
        babeltrace2/trace-ir/field-class.h \
-       babeltrace2/trace-ir/field-path-const.h \
-       babeltrace2/trace-ir/field-const.h \
+       babeltrace2/trace-ir/field-path.h \
        babeltrace2/trace-ir/field.h \
-       babeltrace2/trace-ir/packet-const.h \
        babeltrace2/trace-ir/packet.h \
-       babeltrace2/trace-ir/stream-class-const.h \
        babeltrace2/trace-ir/stream-class.h \
-       babeltrace2/trace-ir/stream-const.h \
        babeltrace2/trace-ir/stream.h \
-       babeltrace2/trace-ir/trace-class-const.h \
        babeltrace2/trace-ir/trace-class.h \
-       babeltrace2/trace-ir/trace-const.h \
        babeltrace2/trace-ir/trace.h
 
 # Plugin and plugin development API
 babeltrace2pluginincludedir = "$(includedir)/babeltrace2/plugin"
 babeltrace2plugininclude_HEADERS = \
        babeltrace2/plugin/plugin-dev.h \
-       babeltrace2/plugin/plugin-const.h \
-       babeltrace2/plugin/plugin-set-const.h
+       babeltrace2/plugin/plugin-loading.h
 
 # Graph, component, and message API
 babeltrace2graphincludedir = "$(includedir)/babeltrace2/graph"
 babeltrace2graphinclude_HEADERS = \
-       babeltrace2/graph/component-class-const.h \
-       babeltrace2/graph/component-class-filter-const.h \
-       babeltrace2/graph/component-class-filter.h \
-       babeltrace2/graph/component-class-sink-const.h \
-       babeltrace2/graph/component-class-sink.h \
-       babeltrace2/graph/component-class-source-const.h \
-       babeltrace2/graph/component-class-source.h \
+       babeltrace2/graph/component-class-dev.h \
        babeltrace2/graph/component-class.h \
-       babeltrace2/graph/component-const.h \
-       babeltrace2/graph/component-descriptor-set-const.h \
        babeltrace2/graph/component-descriptor-set.h \
-       babeltrace2/graph/component-filter-const.h \
-       babeltrace2/graph/component-sink-const.h \
-       babeltrace2/graph/component-source-const.h \
-       babeltrace2/graph/connection-const.h \
-       babeltrace2/graph/graph-const.h \
+       babeltrace2/graph/component.h \
+       babeltrace2/graph/connection.h \
        babeltrace2/graph/graph.h \
-       babeltrace2/graph/interrupter-const.h \
        babeltrace2/graph/interrupter.h \
-       babeltrace2/graph/message-const.h \
-       babeltrace2/graph/message-discarded-events-const.h \
-       babeltrace2/graph/message-discarded-events.h \
-       babeltrace2/graph/message-discarded-packets-const.h \
-       babeltrace2/graph/message-discarded-packets.h \
-       babeltrace2/graph/message-event-const.h \
-       babeltrace2/graph/message-event.h \
-       babeltrace2/graph/message-message-iterator-inactivity-const.h \
-       babeltrace2/graph/message-message-iterator-inactivity.h \
-       babeltrace2/graph/message-iterator.h \
        babeltrace2/graph/message-iterator-class.h \
-       babeltrace2/graph/message-packet-beginning-const.h \
-       babeltrace2/graph/message-packet-beginning.h \
-       babeltrace2/graph/message-packet-end-const.h \
-       babeltrace2/graph/message-packet-end.h \
-       babeltrace2/graph/message-stream-beginning-const.h \
-       babeltrace2/graph/message-stream-beginning.h \
-       babeltrace2/graph/message-stream-const.h \
-       babeltrace2/graph/message-stream-end-const.h \
-       babeltrace2/graph/message-stream-end.h \
-       babeltrace2/graph/mip.h \
-       babeltrace2/graph/port-const.h \
-       babeltrace2/graph/port-input-const.h \
-       babeltrace2/graph/port-output-const.h \
+       babeltrace2/graph/message-iterator.h \
+       babeltrace2/graph/message.h \
+       babeltrace2/graph/port.h \
        babeltrace2/graph/private-query-executor.h \
-       babeltrace2/graph/query-executor-const.h \
        babeltrace2/graph/query-executor.h \
-       babeltrace2/graph/self-component-class-filter.h \
-       babeltrace2/graph/self-component-class-sink.h \
-       babeltrace2/graph/self-component-class-source.h \
        babeltrace2/graph/self-component-class.h \
-       babeltrace2/graph/self-component-filter.h \
-       babeltrace2/graph/self-component-port-input.h \
-       babeltrace2/graph/self-component-port-output.h \
        babeltrace2/graph/self-component-port.h \
-       babeltrace2/graph/self-component-sink.h \
-       babeltrace2/graph/self-component-source.h \
        babeltrace2/graph/self-component.h \
        babeltrace2/graph/self-message-iterator.h

diff --git a/include/babeltrace2/babeltrace.h b/include/babeltrace2/babeltrace.h
index ffb8109e7c7680a2518b59d6dda51f83de7ae8c5..3f919cf30a6ea65f29caf4b5de8fa6ac30d485e1 100644 (file)
--- a/include/babeltrace2/babeltrace.h
+++ b/include/babeltrace2/babeltrace.h
@@ -44,119 +44,43 @@
 # define __BT_UPCAST_CONST(_type, _p)  ((const _type *) (_p))
 #endif
 
-/* Core API */
-#include <babeltrace2/current-thread.h>
-#include <babeltrace2/error-cause-const.h>
-#include <babeltrace2/error-const.h>
-#include <babeltrace2/integer-range-set-const.h>
+#include <babeltrace2/error-reporting.h>
+#include <babeltrace2/graph/component-class-dev.h>
+#include <babeltrace2/graph/component-class.h>
+#include <babeltrace2/graph/component-descriptor-set.h>
+#include <babeltrace2/graph/component.h>
+#include <babeltrace2/graph/connection.h>
+#include <babeltrace2/graph/graph.h>
+#include <babeltrace2/graph/interrupter.h>
+#include <babeltrace2/graph/message-iterator.h>
+#include <babeltrace2/graph/message.h>
+#include <babeltrace2/graph/port.h>
+#include <babeltrace2/graph/private-query-executor.h>
+#include <babeltrace2/graph/query-executor.h>
+#include <babeltrace2/graph/self-component-class.h>
+#include <babeltrace2/graph/self-component-port.h>
+#include <babeltrace2/graph/self-component.h>
+#include <babeltrace2/graph/self-message-iterator.h>
 #include <babeltrace2/integer-range-set.h>
 #include <babeltrace2/logging.h>
-#include <babeltrace2/property.h>
-#include <babeltrace2/types.h>
-#include <babeltrace2/util.h>
-#include <babeltrace2/value-const.h>
-#include <babeltrace2/value.h>
-#include <babeltrace2/version.h>
-
-/* Trace IR API */
-#include <babeltrace2/trace-ir/clock-class-const.h>
+#include <babeltrace2/plugin/plugin-dev.h>
+#include <babeltrace2/plugin/plugin-loading.h>
 #include <babeltrace2/trace-ir/clock-class.h>
-#include <babeltrace2/trace-ir/clock-snapshot-const.h>
-#include <babeltrace2/trace-ir/event-class-const.h>
+#include <babeltrace2/trace-ir/clock-snapshot.h>
 #include <babeltrace2/trace-ir/event-class.h>
-#include <babeltrace2/trace-ir/event-const.h>
 #include <babeltrace2/trace-ir/event.h>
-#include <babeltrace2/trace-ir/field-class-const.h>
 #include <babeltrace2/trace-ir/field-class.h>
-#include <babeltrace2/trace-ir/field-const.h>
-#include <babeltrace2/trace-ir/field-path-const.h>
+#include <babeltrace2/trace-ir/field-path.h>
 #include <babeltrace2/trace-ir/field.h>
-#include <babeltrace2/trace-ir/packet-const.h>
 #include <babeltrace2/trace-ir/packet.h>
-#include <babeltrace2/trace-ir/stream-class-const.h>
 #include <babeltrace2/trace-ir/stream-class.h>
-#include <babeltrace2/trace-ir/stream-const.h>
 #include <babeltrace2/trace-ir/stream.h>
-#include <babeltrace2/trace-ir/trace-class-const.h>
 #include <babeltrace2/trace-ir/trace-class.h>
-#include <babeltrace2/trace-ir/trace-const.h>
 #include <babeltrace2/trace-ir/trace.h>
-
-/* Component class API */
-#include <babeltrace2/graph/component-class-const.h>
-#include <babeltrace2/graph/component-class-filter-const.h>
-#include <babeltrace2/graph/component-class-filter.h>
-#include <babeltrace2/graph/component-class-sink-const.h>
-#include <babeltrace2/graph/component-class-sink.h>
-#include <babeltrace2/graph/component-class-source-const.h>
-#include <babeltrace2/graph/component-class-source.h>
-#include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/graph/self-component-class-filter.h>
-#include <babeltrace2/graph/self-component-class-sink.h>
-#include <babeltrace2/graph/self-component-class-source.h>
-#include <babeltrace2/graph/self-component-class.h>
-
-/* Component API */
-#include <babeltrace2/graph/component-const.h>
-#include <babeltrace2/graph/component-filter-const.h>
-#include <babeltrace2/graph/component-sink-const.h>
-#include <babeltrace2/graph/component-source-const.h>
-#include <babeltrace2/graph/self-component-filter.h>
-#include <babeltrace2/graph/self-component-port-input.h>
-#include <babeltrace2/graph/self-component-port-output.h>
-#include <babeltrace2/graph/self-component-port.h>
-#include <babeltrace2/graph/self-component-sink.h>
-#include <babeltrace2/graph/self-component-source.h>
-#include <babeltrace2/graph/self-component.h>
-
-/* Message iterator API */
-#include <babeltrace2/graph/message-iterator.h>
-#include <babeltrace2/graph/self-message-iterator.h>
-
-/* Message API */
-#include <babeltrace2/graph/message-const.h>
-#include <babeltrace2/graph/message-discarded-events-const.h>
-#include <babeltrace2/graph/message-discarded-events.h>
-#include <babeltrace2/graph/message-discarded-packets-const.h>
-#include <babeltrace2/graph/message-discarded-packets.h>
-#include <babeltrace2/graph/message-event-const.h>
-#include <babeltrace2/graph/message-event.h>
-#include <babeltrace2/graph/message-message-iterator-inactivity-const.h>
-#include <babeltrace2/graph/message-message-iterator-inactivity.h>
-#include <babeltrace2/graph/message-packet-beginning-const.h>
-#include <babeltrace2/graph/message-packet-beginning.h>
-#include <babeltrace2/graph/message-packet-end-const.h>
-#include <babeltrace2/graph/message-packet-end.h>
-#include <babeltrace2/graph/message-stream-beginning-const.h>
-#include <babeltrace2/graph/message-stream-beginning.h>
-#include <babeltrace2/graph/message-stream-const.h>
-#include <babeltrace2/graph/message-stream-end-const.h>
-#include <babeltrace2/graph/message-stream-end.h>
-
-/* Graph API */
-#include <babeltrace2/graph/component-descriptor-set-const.h>
-#include <babeltrace2/graph/component-descriptor-set.h>
-#include <babeltrace2/graph/connection-const.h>
-#include <babeltrace2/graph/graph-const.h>
-#include <babeltrace2/graph/graph.h>
-#include <babeltrace2/graph/interrupter-const.h>
-#include <babeltrace2/graph/interrupter.h>
-#include <babeltrace2/graph/mip.h>
-#include <babeltrace2/graph/port-const.h>
-#include <babeltrace2/graph/port-input-const.h>
-#include <babeltrace2/graph/port-output-const.h>
-
-/* Query executor API */
-#include <babeltrace2/graph/private-query-executor.h>
-#include <babeltrace2/graph/query-executor-const.h>
-#include <babeltrace2/graph/query-executor.h>
-
-/* Plugin API */
-#include <babeltrace2/plugin/plugin-const.h>
-#include <babeltrace2/plugin/plugin-set-const.h>
-
-/* Plugin development */
-#include <babeltrace2/plugin/plugin-dev.h>
+#include <babeltrace2/types.h>
+#include <babeltrace2/util.h>
+#include <babeltrace2/value.h>
+#include <babeltrace2/version.h>
 
 /* Cancel private definitions */
 #undef __BT_FUNC_STATUS_AGAIN

diff --git a/include/babeltrace2/current-thread.h b/include/babeltrace2/current-thread.h
deleted file mode 100644 (file)
index 39c6ae2..0000000
--- a/include/babeltrace2/current-thread.h
+++ /dev/null
@@ -1,102 +0,0 @@
-#ifndef BABELTRACE2_CURRENT_THREAD_H
-#define BABELTRACE2_CURRENT_THREAD_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdarg.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-const bt_error *bt_current_thread_take_error(void);
-
-extern
-void bt_current_thread_clear_error(void);
-
-extern
-void bt_current_thread_move_error(const bt_error *error);
-
-typedef enum bt_current_thread_error_append_cause_status {
-       BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK                  = __BT_FUNC_STATUS_OK,
-} bt_current_thread_error_append_cause_status;
-
-extern
-bt_current_thread_error_append_cause_status
-bt_current_thread_error_append_cause_from_unknown(
-               const char *module_name, const char *file_name,
-               uint64_t line_no, const char *msg_fmt, ...);
-
-extern
-bt_current_thread_error_append_cause_status
-bt_current_thread_error_append_cause_from_component(
-               bt_self_component *self_comp, const char *file_name,
-               uint64_t line_no, const char *msg_fmt, ...);
-
-extern
-bt_current_thread_error_append_cause_status
-bt_current_thread_error_append_cause_from_component_class(
-               bt_self_component_class *self_comp_class, const char *file_name,
-               uint64_t line_no, const char *msg_fmt, ...);
-
-extern
-bt_current_thread_error_append_cause_status
-bt_current_thread_error_append_cause_from_message_iterator(
-               bt_self_message_iterator *self_iter, const char *file_name,
-               uint64_t line_no, const char *msg_fmt, ...);
-
-#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(_module_name, _msg_fmt, ...) \
-       bt_current_thread_error_append_cause_from_unknown( \
-               (_module_name), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__)
-
-#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(_self_comp, _msg_fmt, ...) \
-       bt_current_thread_error_append_cause_from_component( \
-               (_self_comp), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__)
-
-#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(_self_cc, _msg_fmt, ...) \
-       bt_current_thread_error_append_cause_from_component_class( \
-               (_self_cc), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__)
-
-#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(_self_iter, _msg_fmt, ...) \
-       bt_current_thread_error_append_cause_from_message_iterator( \
-               (_self_iter), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__)
-
-#define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_var)   \
-       do {                                            \
-               bt_current_thread_move_error(_var);     \
-               (_var) = NULL;                          \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_CURRENT_THREAD_H */

diff --git a/include/babeltrace2/error-cause-const.h b/include/babeltrace2/error-cause-const.h
deleted file mode 100644 (file)
index 004741f..0000000
--- a/include/babeltrace2/error-cause-const.h
+++ /dev/null
@@ -1,117 +0,0 @@
-#ifndef BABELTRACE2_ERROR_CAUSE_CONST_H
-#define BABELTRACE2_ERROR_CAUSE_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-#include <stddef.h>
-
-#include <babeltrace2/types.h>
-#include <babeltrace2/graph/component-class-const.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_error_cause_actor_type {
-       BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN               = 1 << 0,
-       BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT             = 1 << 1,
-       BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS       = 1 << 2,
-       BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR      = 1 << 3,
-} bt_error_cause_actor_type;
-
-extern
-bt_error_cause_actor_type bt_error_cause_get_actor_type(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_get_message(const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_get_module_name(const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_get_file_name(const bt_error_cause *cause);
-
-extern
-uint64_t bt_error_cause_get_line_number(const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_component_actor_get_component_name(
-               const bt_error_cause *cause);
-
-extern
-bt_component_class_type bt_error_cause_component_actor_get_component_class_type(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_component_actor_get_component_class_name(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_component_actor_get_plugin_name(
-               const bt_error_cause *cause);
-
-extern
-bt_component_class_type
-bt_error_cause_component_class_actor_get_component_class_type(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_component_class_actor_get_component_class_name(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_component_class_actor_get_plugin_name(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_message_iterator_actor_get_component_name(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_message_iterator_actor_get_component_output_port_name(
-               const bt_error_cause *cause);
-
-extern
-bt_component_class_type
-bt_error_cause_message_iterator_actor_get_component_class_type(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_message_iterator_actor_get_component_class_name(
-               const bt_error_cause *cause);
-
-extern
-const char *bt_error_cause_message_iterator_actor_get_plugin_name(
-               const bt_error_cause *cause);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_ERROR_CAUSE_CONST_H */

diff --git a/include/babeltrace2/error-const.h b/include/babeltrace2/error-const.h
deleted file mode 100644 (file)
index 8f09b4b..0000000
--- a/include/babeltrace2/error-const.h
+++ /dev/null
@@ -1,53 +0,0 @@
-#ifndef BABELTRACE2_ERROR_CONST_H
-#define BABELTRACE2_ERROR_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-#include <stddef.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-uint64_t bt_error_get_cause_count(const bt_error *error);
-
-extern
-const bt_error_cause *bt_error_borrow_cause_by_index(
-               const bt_error *error, uint64_t index);
-
-extern
-void bt_error_release(const bt_error *error);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_ERROR_CONST_H */

diff --git a/include/babeltrace2/error-reporting.h b/include/babeltrace2/error-reporting.h
new file mode 100644 (file)
index 0000000..8539ddf
--- /dev/null
+++ b/include/babeltrace2/error-reporting.h
@@ -0,0 +1,1471 @@
+#ifndef BABELTRACE2_ERROR_REPORTING_H
+#define BABELTRACE2_ERROR_REPORTING_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <stdarg.h>
+
+#include <babeltrace2/types.h>
+#include <babeltrace2/graph/component-class.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-error Error reporting
+
+@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
+\ref api-qexec "query operation", or a trace processing \bt_graph
+listener, for example) to any function caller.
+
+Because \bt_name orchestrates pieces written by different authors,
+it is important that an error which occurs deep into the function call
+stack can percolate up to its callers.
+
+The very basic mechanism to report an error from a function is to
+\ref api-fund-func-status "return an error status"
+(a status code enumerator which contains the word
+\c ERROR): each function caller can clean its own context and return an
+error status code itself until one caller "catches" the status code and
+reacts to it. For example, the reaction can be to show an error message
+to the end user.
+
+This error reporting API adds a layer so that each function which
+returns an error status code can append a message which describes the
+cause of the error within the function's context.
+
+Functions append error causes to the current thread's error. Having one
+error object per thread makes this API thread-safe.
+
+Here's a visual, step-by-step example:
+
+@image html error-reporting-steps-1234.png
+
+-# The trace processing \bt_graph user calls bt_graph_run().
+
+-# bt_graph_run() calls the
+   \ref api-comp-cls-dev-meth-consume "consuming method" of the
+   \bt_sink_comp.
+
+-# The sink \bt_comp calls bt_message_iterator_next() on its upstream
+   source \bt_msg_iter.
+
+-# bt_message_iterator_next() calls the source message iterator's
+   \link api-msg-iter-cls-meth-next "next" method\endlink.
+
+@image html error-reporting-step-5.png
+
+<ol start="5">
+  <li>
+    An error occurs within the "next" method of the source message
+    iterator: the function cannot read a file because permission was
+    denied.
+</ol>
+
+@image html error-reporting-step-6.png
+
+<ol start="6">
+  <li>
+    The source message iterator's "next" method appends the error
+    cause <em>"Cannot read file /some/file: permission denied"</em>
+    and returns
+    #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR.
+</ol>
+
+@image html error-reporting-step-7.png
+
+<ol start="7">
+  <li>
+    bt_message_iterator_next() appends
+    the error cause <em>"Message iterator's 'next' method failed"</em>
+    with details about the source component and
+    returns #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR.
+</ol>
+
+@image html error-reporting-steps-89.png
+
+<ol start="8">
+  <li>
+    The sink component's "consume" method appends the error
+    cause <em>"Cannot consume upstream message iterator's messages"</em>
+    and returns #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR.
+
+  <li>
+    bt_graph_run() appends the error cause <em>"Component's 'consume'
+    method failed"</em> with details about the sink component and
+    returns #BT_GRAPH_RUN_STATUS_ERROR.
+</ol>
+
+At this point, the current thread's error contains four causes:
+
+- <em>"Cannot read file /some/file: permission denied"</em>
+- <em>"Message iterator's 'next' method failed"</em>
+- <em>"Cannot consume upstream message iterator's messages"</em>
+- <em>"Component's 'consume' method failed"</em>
+
+This list of error causes is much richer for the end user than dealing
+only with #BT_GRAPH_RUN_STATUS_ERROR (the last error status code).
+
+Both error (#bt_error) and error cause (#bt_error_cause) objects are
+\ref api-fund-unique-object "unique objects":
+
+- An error belongs to either
+  the library or you (see \ref api-error-handle "Handle an error").
+
+- An error cause belongs to the error which contains it.
+
+<h1>\anchor api-error-append-cause Append an error cause</h1>
+
+When your function returns an error status code, use one of the
+<code>bt_current_thread_error_append_cause_from_*()</code>
+functions or <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code>
+macros to append an error cause to the
+current thread's error. Use the appropriate function or macro
+depending on your function's actor amongst:
+
+<dl>
+  <dt>Component</dt>
+  <dd>
+    Append an error cause from a \bt_comp method.
+
+    Use bt_current_thread_error_append_cause_from_component() or
+    BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT().
+  </dd>
+
+  <dt>Message iterator</dt>
+  <dd>
+    Append an error cause from a \bt_msg_iter method.
+
+    Use bt_current_thread_error_append_cause_from_message_iterator() or
+    BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR().
+  </dd>
+
+  <dt>Component class</dt>
+  <dd>
+    Append an error cause from a \bt_comp_cls method
+    ("query" method).
+
+    Use bt_current_thread_error_append_cause_from_component_class() or
+    BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().
+  </dd>
+
+  <dt>Unknown</dt>
+  <dd>
+    Append an error cause from any other function, for example
+    a \bt_graph listener or a function of your user application).
+
+    Use bt_current_thread_error_append_cause_from_unknown() or
+    BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN().
+  </dd>
+</dl>
+
+The <code>BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*()</code> macros
+uses \c __FILE__ and \c __LINE__ as the file name and line number
+parameters of their corresponding
+<code>bt_current_thread_error_append_cause_from_*()</code> function.
+
+<h1>\anchor api-error-handle Handle an error</h1>
+
+If any libbabeltrace2 function you call returns an error status code, do
+one of:
+
+- Return an error status code too.
+
+  In that case, you \em can
+  \ref api-error-append-cause "append an error cause" to the current
+  thread's error.
+
+- \em Take the current thread's error with
+  bt_current_thread_take_error().
+
+  This function moves the ownership of the error object from the library
+  to you.
+
+  At this point, you can inspect its causes with
+  bt_error_get_cause_count() and bt_error_borrow_cause_by_index(), and
+  then do one of:
+
+  - Call bt_error_release() to free the error object.
+
+    In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
+    terms, this corresponds to catching an exception and discarding it.
+
+  - Call bt_current_thread_move_error() to move back the error object's
+    ownership to the library.
+
+    In object-oriented programming terms, this corresponds to catching
+    an exception and rethrowing it.
+
+bt_current_thread_clear_error() is a helper which is the equivalent of:
+
+@code
+bt_error_release(bt_current_thread_take_error());
+@endcode
+
+<h1>Error cause</h1>
+
+All error causes have the type #bt_error_cause.
+
+There are four types of error cause actors:
+
+- \bt_c_comp
+- \bt_c_msg_iter
+- \bt_c_comp_cls
+- Unknown
+
+Get the type enumerator of an error cause's actor with
+bt_error_cause_get_actor_type().
+
+An error cause has the following common properties:
+
+<dl>
+  <dt>Message</dt>
+  <dd>
+    Description of the error cause.
+
+    Use bt_error_cause_get_message().
+  </dd>
+
+  <dt>Module name</dt>
+  <dd>
+    Name of the module causing the error.
+
+    For example, libbabeltrace2 uses "libbabeltrace2" and the \bt_cli
+    CLI tool uses "Babeltrace CLI".
+
+    Use bt_error_cause_get_module_name().
+  </dd>
+
+  <dt>File name</dt>
+  <dd>
+    Name of the source file causing the error.
+
+    Use bt_error_cause_get_file_name().
+  </dd>
+
+  <dt>Line number</dt>
+  <dd>
+    Line number of the statement causing the error.
+
+    Use bt_error_cause_get_line_number().
+  </dd>
+</dl>
+
+<h2>Error cause with a component actor</h2>
+
+An error cause with a \bt_comp actor has the following specific
+properties:
+
+<dl>
+  <dt>Component name</dt>
+  <dd>
+    Name of the component.
+
+    Use bt_error_cause_component_actor_get_component_name().
+  </dd>
+
+  <dt>Component class name</dt>
+  <dd>
+    Name of the component's \ref api-comp-cls "class".
+
+    Use bt_error_cause_component_actor_get_component_class_type().
+  </dd>
+
+  <dt>Component class type</dt>
+  <dd>
+    Type of the component's class.
+
+    Use bt_error_cause_component_actor_get_component_class_name().
+  </dd>
+
+  <dt>\bt_dt_opt Plugin name</dt>
+  <dd>
+    Name of the \bt_plugin which provides the component's class, if any.
+
+    Use bt_error_cause_component_actor_get_plugin_name().
+  </dd>
+</dl>
+
+<h2>Error cause with a message iterator actor</h2>
+
+An error cause with a \bt_msg_iter actor has the following specific
+properties:
+
+<dl>
+  <dt>Component output port name</dt>
+  <dd>
+    Name of the \bt_comp \bt_oport from which the message iterator
+    was created.
+
+    Use bt_error_cause_component_actor_get_component_name().
+  </dd>
+
+  <dt>Component name</dt>
+  <dd>
+    Name of the component.
+
+    Use bt_error_cause_component_actor_get_component_name().
+  </dd>
+
+  bt_error_cause_message_iterator_actor_get_component_output_port_name
+
+  <dt>Component class name</dt>
+  <dd>
+    Name of the component's \ref api-comp-cls "class".
+
+    Use bt_error_cause_component_actor_get_component_class_type().
+  </dd>
+
+  <dt>Component class type</dt>
+  <dd>
+    Type of the component's class.
+
+    Use bt_error_cause_component_actor_get_component_class_name().
+  </dd>
+
+  <dt>\bt_dt_opt Plugin name</dt>
+  <dd>
+    Name of the \bt_plugin which provides the component's class, if any.
+
+    Use bt_error_cause_component_actor_get_plugin_name().
+  </dd>
+</dl>
+
+<h2>Error cause with a component class actor</h2>
+
+An error cause with a \bt_comp_cls actor has the following specific
+properties:
+
+<dl>
+  <dt>Component class name</dt>
+  <dd>
+    Name of the component class.
+
+    Use bt_error_cause_component_class_actor_get_component_class_type().
+  </dd>
+
+  <dt>Component class type</dt>
+  <dd>
+    Type of the component class.
+
+    Use bt_error_cause_component_class_actor_get_component_class_name().
+  </dd>
+
+  <dt>\bt_dt_opt Plugin name</dt>
+  <dd>
+    Name of the \bt_plugin which provides the component class, if any.
+
+    Use bt_error_cause_component_class_actor_get_plugin_name().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_error bt_error;
+
+@brief
+    Error.
+
+
+@typedef struct bt_error_cause bt_error_cause;
+
+@brief
+    Error cause.
+
+@}
+*/
+
+/*!
+@name Current thread's error
+@{
+*/
+
+/*!
+@brief
+    \em Takes the current thread's error, that is, moves its ownership
+    from the library to the caller.
+
+This function can return \c NULL if the current thread has no error.
+
+Once you are done with the returned error, do one of:
+
+- Call bt_error_release() to free the error object.
+
+  In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
+  terms, this corresponds to catching an exception and discarding it.
+
+- Call bt_current_thread_move_error() to move back the error object's
+  ownership to the library.
+
+  In object-oriented programming terms, this corresponds to catching
+  an exception and rethrowing it.
+
+@returns
+    Unique reference of the current thread's error, or \c NULL if the
+    current thread has no error.
+
+@post
+    <strong>If this function does not return <code>NULL</code></strong>,
+    the caller owns the returned error.
+
+@sa bt_error_release() &mdash;
+    Releases (frees) an error.
+@sa bt_current_thread_move_error() &mdash;
+    Moves an error's ownership to the library.
+*/
+extern
+const bt_error *bt_current_thread_take_error(void);
+
+/*!
+@brief
+    Moves the ownership of the error \bt_p{error} from the caller to
+    the library.
+
+After you call this function, you don't own \bt_p{error} anymore.
+
+In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
+terms, calling this function corresponds to catching an
+exception and rethrowing it.
+
+You can instead release (free) the error with bt_error_release(), which,
+in object-oriented programming terms,
+corresponds to catching an exception and discarding it.
+
+@param[in] error
+    Error of which to move the ownership from you to the library.
+
+@bt_pre_not_null{error}
+@pre
+    The caller owns \bt_p{error}.
+
+@post
+    The library owns \bt_p{error}.
+
+@sa bt_error_release() &mdash;
+    Releases (frees) an error.
+@sa BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() &mdash;
+    Calls this function and assigns \c NULL to the expression.
+*/
+extern
+void bt_current_thread_move_error(const bt_error *error);
+
+/*!
+@brief
+    Moves the ownership of the error \bt_p{_error} from the caller to
+    the library, and then sets \bt_p{_error} to \c NULL.
+
+@param[in] _error
+    Error of which to move the ownership from you to the library.
+
+@bt_pre_not_null{_error}
+@bt_pre_assign_expr{_error}
+@pre
+    The caller owns \bt_p{_error}.
+
+@post
+    The library owns \bt_p{_error}.
+
+@sa bt_current_thread_move_error() &mdash;
+    Moves an error's ownership to the library.
+*/
+#define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_error) \
+       do {                                            \
+               bt_current_thread_move_error(_error);   \
+               (_error) = NULL;                        \
+       } while (0)
+
+/*!
+@brief
+    Releases the current thread's error, if any.
+
+This function is equivalent to:
+
+@code
+bt_error_release(bt_current_thread_take_error());
+@endcode
+
+@post
+    The current thread has no error.
+
+@sa bt_error_release() &mdash;
+    Releases (frees) an error.
+@sa bt_current_thread_take_error &mdash;
+    Takes the current thread's error, moving its ownership from the
+    library to the caller.
+*/
+extern
+void bt_current_thread_clear_error(void);
+
+/*! @} */
+
+/*!
+@name Error cause appending
+@{
+*/
+
+/*!
+@brief
+    Status codes for the
+    <code>bt_current_thread_error_append_cause_from_*()</code>
+    functions.
+*/
+typedef enum bt_current_thread_error_append_cause_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK                  = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_current_thread_error_append_cause_status;
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from a
+    \bt_comp method.
+
+This this a <code>printf()</code>-like function starting from the
+format string parameter \bt_p{message_format}.
+
+On success, the appended error cause's module name
+(see bt_error_cause_get_module_name()) is:
+
+@code{.unparsed}
+NAME: CC-TYPE.PLUGIN-NAME.CC-NAME
+@endcode
+
+or
+
+@code{.unparsed}
+NAME: CC-TYPE.CC-NAME
+@endcode
+
+if no \bt_plugin provides the class of \bt_p{self_component}, with:
+
+<dl>
+  <dt>\c NAME</dt>
+  <dd>Name of \bt_p{self_component}.</dd>
+
+  <dt>\c CC-TYPE</dt>
+  <dd>
+    Type of the \ref api-comp-cls "class" of \bt_p{self_component}
+    (\c src, \c flt, or \c sink).
+  </dd>
+
+  <dt>\c PLUGIN-NAME</dt>
+  <dd>
+    Name of the plugin which provides the class of
+    \bt_p{self_component}.
+  </dd>
+
+  <dt>\c CC-NAME</dt>
+  <dd>Name of the class of \bt_p{self_component}.</dd>
+</dl>
+
+@param[in] self_component
+    Self component of the appending method.
+@param[in] file_name
+    Name of the source file containing the method which appends the
+    error cause.
+@param[in] line_number
+    Line number of the statement which appends the error cause.
+@param[in] message_format
+    Format string which specifies how the function converts the
+    subsequent arguments (like <code>printf()</code>).
+
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
+    Success.
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{file_name}
+@bt_pre_not_null{message_format}
+@bt_pre_valid_fmt{message_format}
+
+@post
+    <strong>On success</strong>, the number of error causes in the
+    current thread's error is incremented.
+
+@sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT() &mdash;
+    Calls this function with \c __FILE__ and \c __LINE__ as the
+    \bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+extern
+bt_current_thread_error_append_cause_status
+bt_current_thread_error_append_cause_from_component(
+               bt_self_component *self_component, const char *file_name,
+               uint64_t line_number, const char *message_format, ...);
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from a
+    \bt_comp method using \c __FILE__ and \c __LINE__ as the source
+    file name and line number.
+
+This macro calls bt_current_thread_error_append_cause_from_component()
+with \c __FILE__ and \c __LINE__ as its
+\bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(_self_component, _message_format, ...) \
+       bt_current_thread_error_append_cause_from_component( \
+               (_self_component), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from a
+    \bt_msg_iter method.
+
+This this a <code>printf()</code>-like function starting from the
+format string parameter \bt_p{message_format}.
+
+On success, the appended error cause's module name
+(see bt_error_cause_get_module_name()) is:
+
+@code{.unparsed}
+COMP-NAME (OUT-PORT-NAME): CC-TYPE.PLUGIN-NAME.CC-NAME
+@endcode
+
+or
+
+@code{.unparsed}
+COMP-NAME (OUT-PORT-NAME): CC-TYPE.CC-NAME
+@endcode
+
+if no \bt_plugin provides the component class of
+\bt_p{self_message_iterator}, with:
+
+<dl>
+  <dt>\c COMP-NAME</dt>
+  <dd>Name of the \bt_comp of \bt_p{self_message_iterator}.</dd>
+
+  <dt>\c OUT-PORT-NAME</dt>
+  <dd>
+    Name of the \bt_oport from which \bt_p{self_message_iterator}.
+    was created.
+  </dd>
+
+  <dt>\c CC-TYPE</dt>
+  <dd>
+    Type of the \bt_comp_cls of \bt_p{self_message_iterator}
+    (\c src, \c flt, or \c sink).
+  </dd>
+
+  <dt>\c PLUGIN-NAME</dt>
+  <dd>
+    Name of the plugin which provides the component class of
+    \bt_p{self_message_iterator}.
+  </dd>
+
+  <dt>\c CC-NAME</dt>
+  <dd>Name of the component class of \bt_p{self_message_iterator}.</dd>
+</dl>
+
+@param[in] self_message_iterator
+    Self message iterator of the appending method.
+@param[in] file_name
+    Name of the source file containing the method which appends the
+    error cause.
+@param[in] line_number
+    Line number of the statement which appends the error cause.
+@param[in] message_format
+    Format string which specifies how the function converts the
+    subsequent arguments (like <code>printf()</code>).
+
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
+    Success.
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{file_name}
+@bt_pre_not_null{message_format}
+@bt_pre_valid_fmt{message_format}
+
+@post
+    <strong>On success</strong>, the number of error causes in the
+    current thread's error is incremented.
+
+@sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR() &mdash;
+    Calls this function with \c __FILE__ and \c __LINE__ as the
+    \bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+extern
+bt_current_thread_error_append_cause_status
+bt_current_thread_error_append_cause_from_message_iterator(
+               bt_self_message_iterator *self_message_iterator,
+               const char *file_name, uint64_t line_number,
+               const char *message_format, ...);
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from a
+    \bt_msg_iter method using \c __FILE__ and \c __LINE__ as the source file
+    name and line number.
+
+This macro calls
+bt_current_thread_error_append_cause_from_message_iterator() with
+\c __FILE__ and \c __LINE__ as its
+\bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(_self_message_iterator, _message_format, ...) \
+       bt_current_thread_error_append_cause_from_message_iterator( \
+               (_self_message_iterator), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from a
+    \bt_comp_cls method.
+
+This this a <code>printf()</code>-like function starting from the
+format string parameter \bt_p{message_format}.
+
+As of \bt_name_version_min_maj, the only component class method is the
+\ref api-qexec "query" method.
+
+On success, the appended error cause's module name
+(see bt_error_cause_get_module_name()) is:
+
+@code{.unparsed}
+CC-TYPE.PLUGIN-NAME.CC-NAME
+@endcode
+
+or
+
+@code{.unparsed}
+CC-TYPE.CC-NAME
+@endcode
+
+if no \bt_plugin provides \bt_p{self_component_class}, with:
+
+<dl>
+  <dt>\c CC-TYPE</dt>
+  <dd>
+    Type of \bt_p{self_component_class} (\c src, \c flt, or \c sink).
+  </dd>
+
+  <dt>\c PLUGIN-NAME</dt>
+  <dd>
+    Name of the plugin which provides \bt_p{self_component_class}.
+  </dd>
+
+  <dt>\c CC-NAME</dt>
+  <dd>Name of \bt_p{self_component_class}.</dd>
+</dl>
+
+@param[in] self_component_class
+    Self component class of the appending method.
+@param[in] file_name
+    Name of the source file containing the method which appends the
+    error cause.
+@param[in] line_number
+    Line number of the statement which appends the error cause.
+@param[in] message_format
+    Format string which specifies how the function converts the
+    subsequent arguments (like <code>printf()</code>).
+
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
+    Success.
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{self_component_class}
+@bt_pre_not_null{file_name}
+@bt_pre_not_null{message_format}
+@bt_pre_valid_fmt{message_format}
+
+@post
+    <strong>On success</strong>, the number of error causes in the
+    current thread's error is incremented.
+
+@sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS() &mdash;
+    Calls this function with \c __FILE__ and \c __LINE__ as the
+    \bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+extern
+bt_current_thread_error_append_cause_status
+bt_current_thread_error_append_cause_from_component_class(
+               bt_self_component_class *self_component_class,
+               const char *file_name, uint64_t line_number,
+               const char *message_format, ...);
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from a
+    component class method using \c __FILE__ and \c __LINE__ as the
+    source file name and line number.
+
+This macro calls
+bt_current_thread_error_append_cause_from_component_class()
+with \c __FILE__ and \c __LINE__ as its
+\bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(_self_component_class, _message_format, ...) \
+       bt_current_thread_error_append_cause_from_component_class( \
+               (_self_component_class), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from any
+    function.
+
+Use this function when you cannot use
+bt_current_thread_error_append_cause_from_component(),
+bt_current_thread_error_append_cause_from_message_iterator(),
+or bt_current_thread_error_append_cause_from_component_class().
+
+This this a <code>printf()</code>-like function starting from the
+format string parameter \bt_p{message_format}.
+
+@param[in] module_name
+    Module name of the error cause to append.
+@param[in] file_name
+    Name of the source file containing the method which appends the
+    error cause.
+@param[in] line_number
+    Line number of the statement which appends the error cause.
+@param[in] message_format
+    Format string which specifies how the function converts the
+    subsequent arguments (like <code>printf()</code>).
+
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK
+    Success.
+@retval #BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{module_name}
+@bt_pre_not_null{file_name}
+@bt_pre_not_null{message_format}
+@bt_pre_valid_fmt{message_format}
+
+@post
+    <strong>On success</strong>, the number of error causes in the
+    current thread's error is incremented.
+
+@sa BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN() &mdash;
+    Calls this function with \c __FILE__ and \c __LINE__ as the
+    \bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+extern
+bt_current_thread_error_append_cause_status
+bt_current_thread_error_append_cause_from_unknown(
+               const char *module_name, const char *file_name,
+               uint64_t line_number, const char *message_format, ...);
+
+/*!
+@brief
+    Appends an error cause to the current thread's error from any
+    function using \c __FILE__ and \c __LINE__ as the source
+    file name and line number.
+
+Use this function when you cannot use
+BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(),
+BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(),
+or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS().
+
+This macro calls bt_current_thread_error_append_cause_from_unknown()
+with \c __FILE__ and \c __LINE__ as its
+\bt_p{file_name} and \bt_p{line_number} parameters.
+*/
+#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(_module_name, _message_format, ...) \
+       bt_current_thread_error_append_cause_from_unknown( \
+               (_module_name), __FILE__, __LINE__, (_message_format), ##__VA_ARGS__)
+
+/*! @} */
+
+/*!
+@name Error
+@{
+*/
+
+/*!
+@brief
+    Returns the number of error causes contained in the error
+    \bt_p{error}.
+
+@param[in] error
+    Error of which to get the number of contained error causes.
+
+@returns
+    Number of contained error causes in \bt_p{error}.
+
+@bt_pre_not_null{error}
+*/
+extern
+uint64_t bt_error_get_cause_count(const bt_error *error);
+
+/*!
+@brief
+    Borrows the error cause at index \bt_p{index} from the
+    error \bt_p{error}.
+
+@param[in] error
+    Error from which to borrow the error cause at index \bt_p{index}.
+@param[in] index
+    Index of the error cause to borrow from \bt_p{error}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the error cause of
+    \bt_p{error} at index \bt_p{index}.
+
+    The returned pointer remains valid until \bt_p{error} is modified.
+    @endparblock
+
+@bt_pre_not_null{error}
+@pre
+    \bt_p{index} is less than the number of error causes in
+    \bt_p{error} (as returned by bt_error_get_cause_count()).
+*/
+extern
+const bt_error_cause *bt_error_borrow_cause_by_index(
+               const bt_error *error, uint64_t index);
+
+/*!
+@brief
+    Releases (frees) the error \bt_p{error}.
+
+After you call this function, \bt_p{error} does not exist.
+
+Take the current thread's error with bt_current_thread_take_error().
+
+In <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>
+terms, calling this function corresponds to catching an
+exception and discarding it.
+
+You can instead move the ownership of \bt_p{error} to the library with
+bt_current_thread_move_error(), which,
+in object-oriented programming terms,
+corresponds to catching an exception and rethrowing it.
+
+@param[in] error
+    Error to release (free).
+
+@bt_pre_not_null{error}
+
+@post
+    \bt_p{error} does not exist.
+
+@sa bt_current_thread_move_error() &mdash;
+    Moves an error's ownership to the library.
+*/
+extern
+void bt_error_release(const bt_error *error);
+
+/*! @} */
+
+/*!
+@name Error cause: common
+@{
+*/
+
+/*!
+@brief
+    Error cause actor type enumerators.
+*/
+typedef enum bt_error_cause_actor_type {
+       /*!
+       @brief
+           Any function.
+       */
+       BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN               = 1 << 0,
+
+       /*!
+       @brief
+           Component method.
+       */
+       BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT             = 1 << 1,
+
+       /*!
+       @brief
+           Component class method.
+       */
+       BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS       = 1 << 2,
+
+       /*!
+       @brief
+           Message iterator method.
+       */
+       BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR      = 1 << 3,
+} bt_error_cause_actor_type;
+
+/*!
+@brief
+    Returns the actor type enumerator of the error cause
+    \bt_p{error_cause}.
+
+@param[in] error_cause
+    Error cause of which to get the actor type enumerator.
+
+@returns
+    Actor type enumerator of \bt_p{error_cause}.
+
+@bt_pre_not_null{error_cause}
+*/
+extern
+bt_error_cause_actor_type bt_error_cause_get_actor_type(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the message of the error cause \bt_p{error_cause}.
+
+@param[in] error_cause
+    Error cause of which to get the message.
+
+@returns
+    @parblock
+    Message of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+*/
+extern
+const char *bt_error_cause_get_message(const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the module name of the error cause \bt_p{error_cause}.
+
+@param[in] error_cause
+    Error cause of which to get the module name.
+
+@returns
+    @parblock
+    Module name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+*/
+extern
+const char *bt_error_cause_get_module_name(const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the name of the source file which contains the function
+    which appended the error cause \bt_p{error_cause} to the
+    current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the source file name.
+
+@returns
+    @parblock
+    Source file name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+*/
+extern
+const char *bt_error_cause_get_file_name(const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the line number of the statement
+    which appended the error cause \bt_p{error_cause} to the
+    current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the source statement's line number.
+
+@returns
+    Source statement's line number of \bt_p{error_cause}.
+
+@bt_pre_not_null{error_cause}
+*/
+extern
+uint64_t bt_error_cause_get_line_number(const bt_error_cause *error_cause);
+
+/*! @} */
+
+/*!
+@name Error cause with a component actor
+@{
+*/
+
+/*!
+@brief
+    Returns the name of the \bt_comp of which a method
+    appended the error cause \bt_p{error_cause} to the current
+    thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component name.
+
+@returns
+    @parblock
+    Component name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
+*/
+extern
+const char *bt_error_cause_component_actor_get_component_name(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the \ref api-comp-cls "class" type of the
+    \bt_comp of which a method appended the error cause
+    \bt_p{error_cause} to the current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component class type.
+
+@returns
+    Component class type of \bt_p{error_cause}.
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
+*/
+extern
+bt_component_class_type bt_error_cause_component_actor_get_component_class_type(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the \ref api-comp-cls "class" name of the
+    \bt_comp of which a method appended the error cause
+    \bt_p{error_cause} to the current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component class name.
+
+@returns
+    @parblock
+    Component class name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
+*/
+extern
+const char *bt_error_cause_component_actor_get_component_class_name(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the name of the \bt_plugin which provides the
+    \ref api-comp-cls "class" of the \bt_comp of which a method
+    appended the error cause \bt_p{error_cause} to the
+    current thread's error.
+
+This function returns \c NULL if no plugin provides the error cause's
+component class.
+
+@param[in] error_cause
+    Error cause of which to get the plugin name.
+
+@returns
+    @parblock
+    Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
+    provides the component class of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT.
+*/
+extern
+const char *bt_error_cause_component_actor_get_plugin_name(
+               const bt_error_cause *error_cause);
+
+/*! @} */
+
+/*!
+@name Error cause with a message iterator actor
+@{
+*/
+
+/*!
+@brief
+    Returns the name of the \bt_oport from which was created
+    the message iterator of which the method
+    appended the error cause \bt_p{error_cause} to the current
+    thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the output port name.
+
+@returns
+    @parblock
+    Output port name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
+*/
+extern
+const char *bt_error_cause_message_iterator_actor_get_component_output_port_name(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the name of the \bt_comp of which a message iterator method
+    appended the error cause \bt_p{error_cause} to the current
+    thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component name.
+
+@returns
+    @parblock
+    Component name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
+*/
+extern
+const char *bt_error_cause_message_iterator_actor_get_component_name(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the \ref api-comp-cls "class" type of the
+    \bt_comp of which a message iterator method appended the error cause
+    \bt_p{error_cause} to the current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component class type.
+
+@returns
+    Component class type of \bt_p{error_cause}.
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
+*/
+extern
+bt_component_class_type
+bt_error_cause_message_iterator_actor_get_component_class_type(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the \ref api-comp-cls "class" name of the
+    \bt_comp of which a message iterator method appended the error cause
+    \bt_p{error_cause} to the current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component class name.
+
+@returns
+    @parblock
+    Component class name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
+*/
+extern
+const char *bt_error_cause_message_iterator_actor_get_component_class_name(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the name of the \bt_plugin which provides the
+    \ref api-comp-cls "class" of the \bt_comp of which a
+    message iterator method
+    appended the error cause \bt_p{error_cause} to the
+    current thread's error.
+
+This function returns \c NULL if no plugin provides the error cause's
+component class.
+
+@param[in] error_cause
+    Error cause of which to get the plugin name.
+
+@returns
+    @parblock
+    Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
+    provides the component class of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR.
+*/
+extern
+const char *bt_error_cause_message_iterator_actor_get_plugin_name(
+               const bt_error_cause *error_cause);
+
+/*! @} */
+
+/*!
+@name Error cause with a component class actor
+@{
+*/
+
+/*!
+@brief
+    Returns the name of the \bt_comp_cls
+    of which a method appended the error cause
+    \bt_p{error_cause} to the current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component class name.
+
+@returns
+    Component class name of \bt_p{error_cause}.
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
+*/
+extern
+bt_component_class_type
+bt_error_cause_component_class_actor_get_component_class_type(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the name of the \bt_comp_cls
+    of which a method appended the error cause
+    \bt_p{error_cause} to the current thread's error.
+
+@param[in] error_cause
+    Error cause of which to get the component class name.
+
+@returns
+    @parblock
+    Component class name of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
+*/
+extern
+const char *bt_error_cause_component_class_actor_get_component_class_name(
+               const bt_error_cause *error_cause);
+
+/*!
+@brief
+    Returns the name of the \bt_plugin which provides the
+    \bt_comp_cls of which a method
+    appended the error cause \bt_p{error_cause} to the
+    current thread's error.
+
+This function returns \c NULL if no plugin provides the error cause's
+component class.
+
+@param[in] error_cause
+    Error cause of which to get the plugin name.
+
+@returns
+    @parblock
+    Plugin name of \bt_p{error_cause}, or \c NULL if no plugin
+    provides the component class of \bt_p{error_cause}.
+
+    The returned pointer remains valid as long as the error which
+    contains \bt_p{error_cause} exists.
+    @endparblock
+
+@bt_pre_not_null{error_cause}
+@pre
+    The actor type of \bt_p{error_cause} is
+    #BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS.
+*/
+extern
+const char *bt_error_cause_component_class_actor_get_plugin_name(
+               const bt_error_cause *error_cause);
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_ERROR_REPORTING_H */

diff --git a/include/babeltrace2/graph/component-class-const.h b/include/babeltrace2/graph/component-class-const.h
deleted file mode 100644 (file)
index da46d29..0000000
--- a/include/babeltrace2/graph/component-class-const.h
+++ /dev/null
@@ -1,101 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_CLASS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_component_class_type {
-       BT_COMPONENT_CLASS_TYPE_SOURCE  = 1 << 0,
-       BT_COMPONENT_CLASS_TYPE_FILTER  = 1 << 1,
-       BT_COMPONENT_CLASS_TYPE_SINK    = 1 << 2,
-} bt_component_class_type;
-
-extern const char *bt_component_class_get_name(
-               const bt_component_class *component_class);
-
-extern const char *bt_component_class_get_description(
-               const bt_component_class *component_class);
-
-extern const char *bt_component_class_get_help(
-               const bt_component_class *component_class);
-
-extern bt_component_class_type bt_component_class_get_type(
-               const bt_component_class *component_class);
-
-static inline
-bt_bool bt_component_class_is_source(
-               const bt_component_class *component_class)
-{
-       return bt_component_class_get_type(component_class) ==
-               BT_COMPONENT_CLASS_TYPE_SOURCE;
-}
-
-static inline
-bt_bool bt_component_class_is_filter(
-               const bt_component_class *component_class)
-{
-       return bt_component_class_get_type(component_class) ==
-               BT_COMPONENT_CLASS_TYPE_FILTER;
-}
-
-static inline
-bt_bool bt_component_class_is_sink(
-               const bt_component_class *component_class)
-{
-       return bt_component_class_get_type(component_class) ==
-               BT_COMPONENT_CLASS_TYPE_SINK;
-}
-
-extern void bt_component_class_get_ref(
-               const bt_component_class *component_class);
-
-extern void bt_component_class_put_ref(
-               const bt_component_class *component_class);
-
-#define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_var)     \
-       do {                                            \
-               bt_component_class_put_ref(_var);       \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_COMPONENT_CLASS_MOVE_REF(_var_dst, _var_src)        \
-       do {                                            \
-               bt_component_class_put_ref(_var_dst);   \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_CONST_H */

diff --git a/include/babeltrace2/graph/component-class-dev.h b/include/babeltrace2/graph/component-class-dev.h
new file mode 100644 (file)
index 0000000..1fa6016
--- /dev/null
+++ b/include/babeltrace2/graph/component-class-dev.h
@@ -0,0 +1,2225 @@
+#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H
+#define BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <babeltrace2/types.h>
+#include <babeltrace2/logging.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-comp-cls-dev Component class development
+@ingroup api-graph
+
+@brief
+    Component class development (creation).
+
+A <strong><em>component class</em></strong> is the class of a \bt_comp:
+
+@image html component.png
+
+@attention
+    This module (component class development API) offers functions to
+    programatically 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
+offers:
+
+- Component class method type definitions.
+
+- Component class creation functions, to which you pass a mandatory
+  \bt_msg_iter_cls or method.
+
+- Functions to set optional component class methods.
+
+- Functions to set optional component class properties.
+
+A component class method is a user function. There are two types of
+methods:
+
+<dl>
+  <dt>\anchor api-comp-cls-dev-instance-meth Instance method</dt>
+  <dd>
+    Operates on an instance (a \bt_comp).
+
+    The type of the method's first parameter is
+    #bt_self_component_source, #bt_self_component_filter, or
+    bt_self_component_sink, depending on the component class's type.
+
+    This is similar to an instance method in Python (where the instance
+    object name is generally <code>self</code>) or a member function
+    in C++ (where the instance pointer is named <code>this</code>),
+    for example.
+  </dd>
+
+  <dt>\anchor api-comp-cls-dev-class-meth Class method</dt>
+  <dd>
+    Operates on a component class.
+
+    The type of the method's first parameter is
+    #bt_self_component_class_source, #bt_self_component_class_filter, or
+    bt_self_component_class_sink, depending on the component class's
+    type.
+
+    This is similar to a class method in Python or a static member
+    function in C++, for example.
+  </dd>
+</dl>
+
+See \ref api-comp-cls-dev-methods "Methods" to learn more about the
+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.
+
+Some library functions \ref api-fund-freezing "freeze" component classes
+on success. The documentation of those functions indicate this
+postcondition.
+
+Create a component class with bt_component_class_source_create(),
+bt_component_class_filter_create(), and
+bt_component_class_sink_create(). You must give the component class a
+name (not unique in any way) at creation time.
+
+When you create a \bt_src_comp_cls or a \bt_flt_comp_cls, you must pass
+a \bt_msg_iter_cls. This is the class of any \bt_msg_iter created for
+one of the component class's instance's \bt_oport.
+
+When you create a \bt_sink_comp_cls, you must pass a
+\ref api-comp-cls-dev-meth-consume "consuming method".
+
+\ref api-fund-c-typing "Upcast" the #bt_component_class_source,
+#bt_component_class_filter, and bt_component_class_sink types returned
+by the creation functions to the #bt_component_class type with
+bt_component_class_source_as_component_class(),
+bt_component_class_filter_as_component_class(), and
+bt_component_class_sink_as_component_class().
+
+Set the \ref api-comp-cls-prop-descr "description" and the
+\ref api-comp-cls-prop-help "help text" of a component class with
+bt_component_class_set_description() and
+bt_component_class_set_help().
+
+<h1>\anchor api-comp-cls-dev-methods Methods</h1>
+
+To learn when exactly the methods below are called, see
+\ref api-graph-lc "Trace processing graph life cycle".
+
+The available component class methods to implement are:
+
+<table>
+  <tr>
+    <th>Name
+    <th>Method type
+    <th>Component class types
+    <th>Requirement
+    <th>Graph is \ref api-graph-lc "configured"?
+    <th>C types
+  <tr>
+    <td>Consume
+    <td>\ref api-comp-cls-dev-instance-meth "Instance"
+    <td>Sink
+    <td>Mandatory
+    <td>Yes
+    <td>#bt_component_class_sink_consume_method
+  <tr>
+    <td>Finalize
+    <td>Instance
+    <td>All
+    <td>Optional
+    <td>Yes
+    <td>
+      #bt_component_class_source_finalize_method<br>
+      #bt_component_class_filter_finalize_method<br>
+      #bt_component_class_sink_finalize_method
+  <tr>
+    <td>Get supported \bt_mip (MIP) versions
+    <td>\ref api-comp-cls-dev-class-meth "Class"
+    <td>All
+    <td>Optional
+    <td>N/A
+    <td>
+      #bt_component_class_source_get_supported_mip_versions_method<br>
+      #bt_component_class_filter_get_supported_mip_versions_method<br>
+      #bt_component_class_sink_get_supported_mip_versions_method
+  <tr>
+    <td>Graph is \ref api-graph-lc "configured"
+    <td>Instance
+    <td>Sink
+    <td>Mandatory
+    <td>Yes
+    <td>#bt_component_class_sink_graph_is_configured_method
+  <tr>
+    <td>Initialize
+    <td>Instance
+    <td>All
+    <td>Optional
+    <td>No
+    <td>
+      #bt_component_class_source_initialize_method<br>
+      #bt_component_class_filter_initialize_method<br>
+      #bt_component_class_sink_initialize_method
+  <tr>
+    <td>\bt_c_iport connected
+    <td>Instance
+    <td>Filter and sink
+    <td>Optional
+    <td>No
+    <td>
+      #bt_component_class_filter_input_port_connected_method<br>
+      #bt_component_class_sink_input_port_connected_method
+  <tr>
+    <td>\bt_c_oport connected
+    <td>Instance
+    <td>Source and filter
+    <td>Optional
+    <td>No
+    <td>
+      #bt_component_class_source_output_port_connected_method<br>
+      #bt_component_class_filter_output_port_connected_method
+  <tr>
+    <td>Query
+    <td>Class
+    <td>All
+    <td>Optional
+    <td>N/A
+    <td>
+      #bt_component_class_source_query_method<br>
+      #bt_component_class_filter_query_method<br>
+      #bt_component_class_sink_query_method
+</table>
+
+<dl>
+  <dt>
+    \anchor api-comp-cls-dev-meth-consume
+    Consume
+  </dt>
+  <dd>
+    Called within bt_graph_run() or bt_graph_run_once() to make your
+    \bt_sink_comp consume and process \bt_p_msg.
+
+    This method typically gets \em one message batch from one (or more)
+    upstream \bt_msg_iter. You are free to get more than one batch of
+    messages if needed; however, keep in mind that the \bt_name project
+    recommends that this method executes fast enough so as not to block
+    an interactive application running on the same thread.
+
+    During what you consider to be a long, blocking operation, the
+    project recommends that you periodically check whether or not you
+    are interrupted with bt_self_component_sink_is_interrupted(). When
+    you are, you can return either
+    #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN or
+    #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR, depending on
+    your capability to continue the current operation later.
+
+    If you need to block the thread, you can instead report to
+    try again later to the bt_graph_run() or bt_graph_run_once() caller
+    by returning #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN.
+
+    If your sink component is done consuming and processing, return
+    #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END from this method.
+    The trace processing \bt_graph can continue to run afterwards if
+    other sink components are still consuming.
+
+    Within this method, you \em cannot add an \bt_iport with
+    bt_self_component_sink_add_input_port().
+
+    Set this mandatory method at sink component class creation time with
+    bt_component_class_sink_create().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-dev-meth-fini
+    Finalize
+  </dt>
+  <dd>
+    Called to finalize your \bt_comp, that is, to let you
+    destroy/free/finalize any user data you have (retrieved with
+    bt_self_component_get_data()).
+
+    The \bt_name library does not specify exactly when this method is
+    called, but guarantees that it's called before the component is
+    destroyed.
+
+    For \bt_p_src_comp and \bt_p_flt_comp, the library guarantees that
+    this method is called \em after all the component's \bt_p_msg_iter
+    are finalized.
+
+    This method is \em not called if the component's
+    \ref api-comp-cls-dev-meth-init "initialization method"
+    previously returned an error status code.
+
+    Within this method, you cannot:
+
+    - Add a \bt_port.
+    - Use any \bt_msg_iter.
+
+    Set this optional method with
+    bt_component_class_source_set_finalize_method(),
+    bt_component_class_filter_set_finalize_method(), and
+    bt_component_class_sink_set_finalize_method().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-dev-meth-mip
+    Get supported \bt_mip (MIP) versions
+  </dt>
+  <dd>
+    Called within bt_get_greatest_operative_mip_version() to get the
+    set of MIP versions that an eventual \bt_comp supports.
+
+    This is a \ref api-comp-cls-dev-class-meth "class method" because
+    you can call bt_get_greatest_operative_mip_version() before you even
+    create a trace processing \bt_graph.
+
+    In this method, you receive initialization parameters as the
+    \bt_p{params} parameter and initialization method data as the
+    \bt_p{initialize_method_data}. Those parameters are set
+    when bt_component_descriptor_set_add_descriptor() is called, before
+    bt_get_greatest_operative_mip_version() is called.
+
+    Considering those initialization parameters, you need to fill the
+    received \bt_uint_rs \bt_p{supported_versions} with the rangs of
+    MIP versions you support.
+
+    As of \bt_name_version_min_maj, you can only support MIP version 0.
+
+    Not having this method is equivalent to having one which adds the
+    [0,&nbsp;0] range to the \bt_p{supported_versions} set.
+
+    Set this optional method with
+    bt_component_class_source_set_get_supported_mip_versions_method(),
+    bt_component_class_filter_set_get_supported_mip_versions_method(),
+    and bt_component_class_sink_set_get_supported_mip_versions_method().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-dev-meth-graph-configured
+    Graph is \ref api-graph-lc "configured"
+  </dt>
+  <dd>
+    For a given trace processing \bt_graph, called the first time
+    bt_graph_run() or bt_graph_run_once() is called to notify your
+    \bt_sink_comp that the graph is now configured.
+
+    Within this method, you can create \bt_p_msg_iter on your sink
+    component's \bt_p_iport. You can also manipulate those message
+    iterators, for example get and process initial messages or make
+    them.
+
+    This method is called \em after the component's
+    \ref api-comp-cls-dev-meth-init "initialization method"
+    is called. You cannot create a message iterator in the
+    initialization method.
+
+    Within this method, you \em cannot add an \bt_iport with
+    bt_self_component_sink_add_input_port().
+
+    Set this optional method with
+    bt_component_class_sink_set_graph_is_configured_method().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-dev-meth-init
+    Initialize
+  </dt>
+  <dd>
+    Called within a <code>bt_graph_add_*_component*()</code> function
+    (see \ref api-graph) to initialize your \bt_comp.
+
+    Within this method, you receive the initialization parameters and
+    initialization method data passed to the
+    <code>bt_graph_add_*_component*()</code> function.
+
+    This method is where you can add initial \bt_p_port to your
+    component with bt_self_component_source_add_output_port(),
+    bt_self_component_filter_add_input_port(),
+    bt_self_component_filter_add_output_port(), or
+    bt_self_component_sink_add_input_port().
+    You can also add ports in the
+    \ref api-comp-cls-dev-meth-iport-connected "input port connected"
+    and
+    \ref api-comp-cls-dev-meth-oport-connected "output port connected"
+    methods.
+
+    You can create user data and set it as the \bt_self_comp's user data
+    with bt_self_component_set_data().
+
+    If you return #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK from
+    this method, then your component's
+    \ref api-comp-cls-dev-meth-fini "finalization method" will be
+    called, if it exists, when your component is finalized.
+
+    Set this optional method with
+    bt_component_class_source_set_initialize_method(),
+    bt_component_class_filter_set_initialize_method(),
+    and bt_component_class_sink_set_initialize_method().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-dev-meth-iport-connected
+    \bt_c_iport connected
+  </dt>
+  <dd>
+    Called within bt_graph_connect_ports() to notify your \bt_comp that
+    one of its input ports has been connected.
+
+    Within this method, you can add more \bt_p_port to your
+    component with bt_self_component_source_add_output_port(),
+    bt_self_component_filter_add_input_port(),
+    bt_self_component_filter_add_output_port(), or
+    bt_self_component_sink_add_input_port().
+
+    Set this optional method with
+    bt_component_class_filter_set_input_port_connected_method() and
+    bt_component_class_sink_set_input_port_connected_method().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-dev-meth-oport-connected
+    \bt_c_oport connected
+  </dt>
+  <dd>
+    Called within bt_graph_connect_ports() to notify your \bt_comp that
+    one of its output ports has been connected.
+
+    Within this method, you can add more \bt_p_port to your
+    component with bt_self_component_source_add_output_port(),
+    bt_self_component_filter_add_input_port(),
+    bt_self_component_filter_add_output_port(), or
+    bt_self_component_sink_add_input_port().
+
+    Set this optional method with
+    bt_component_class_source_set_output_port_connected_method() and
+    bt_component_class_filter_set_output_port_connected_method().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-dev-meth-query
+    Query
+  </dt>
+  <dd>
+    Called within bt_query_executor_query() to make your \bt_comp_cls
+    perform a query operation.
+
+    Within this method, you receive the query object name, the
+    query parameters, and the method data passed when the
+    \bt_qexec was created with bt_query_executor_create() or
+    bt_query_executor_create_with_method_data().
+
+    You also receive a private view of the query executor which you can
+    cast to a \c const query executor with
+    bt_private_query_executor_as_query_executor_const() to access the
+    executor's logging level with bt_query_executor_get_logging_level().
+
+    On success, set \bt_p{*result} to the query operation's result: a
+    \em new \bt_val reference.
+
+    If the queried object's name (\bt_p{object_name} parameter) is
+    unknown, return
+    #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT.
+
+    If you need to block the thread, you can instead report to
+    try again later to the bt_query_executor_query() caller
+    by returning #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN.
+
+    Set this optional method with
+    bt_component_class_source_set_query_method(),
+    bt_component_class_filter_set_query_method(), and
+    bt_component_class_sink_set_query_method().
+  </dd>
+</dl>
+
+@attention
+    @parblock
+    In any of the methods above:
+
+    - \em Never call bt_component_get_ref(),
+      bt_component_source_get_ref(), bt_component_filter_get_ref(), or
+      bt_component_sink_get_ref() on your own (upcasted) \bt_self_comp
+      to avoid reference cycles.
+
+      You can keep a borrowed (weak) \bt_self_comp reference in your
+      component's user data (see bt_self_component_set_data()).
+
+    - \em Never call bt_port_get_ref(), bt_port_input_get_ref(), or
+      bt_port_output_get_ref() on one of your own (upcasted)
+      \bt_p_self_comp_port to avoid reference cycles.
+
+    - \em Never call bt_component_class_get_ref(),
+      bt_component_class_source_get_ref(),
+      bt_component_class_filter_get_ref(), or
+      bt_component_class_sink_get_ref() on your own (upcasted)
+      \bt_comp_cls to avoid reference cycles.
+    @endparblock
+
+Within any \ref api-comp-cls-dev-instance-meth "instance method", you
+can access the \bt_comp's configured
+\ref #bt_logging_level "logging level" by first upcasting the
+\bt_self_comp to the #bt_component type with
+bt_self_component_as_component(), and then with
+bt_component_get_logging_level().
+*/
+
+/*! @{ */
+
+/*!
+@name Method types
+@{
+*/
+
+/*!
+@brief
+    Status codes for #bt_component_class_sink_consume_method.
+*/
+typedef enum bt_component_class_sink_consume_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Sink component is finished processing.
+       */
+       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END               = __BT_FUNC_STATUS_END,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN             = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+} bt_component_class_sink_consume_method_status;
+
+/*!
+@brief
+    \bt_c_sink_comp consuming method.
+
+See the \ref api-comp-cls-dev-meth-consume "consume" method.
+
+@param[in] self_component
+    \bt_c_sink_comp instance.
+
+@retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END
+    Finished processing.
+@retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+
+@sa bt_component_class_sink_create() &mdash;
+    Creates a \bt_sink_comp.
+*/
+typedef bt_component_class_sink_consume_method_status
+(*bt_component_class_sink_consume_method)(
+               bt_self_component_sink *self_component);
+
+/*!
+@brief
+    \bt_c_src_comp finalization method.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] self_component
+    Source component instance.
+
+@bt_pre_not_null{self_component}
+
+@bt_post_no_error
+
+@sa bt_component_class_source_set_finalize_method() &mdash;
+    Sets the finalization method of a source component class.
+*/
+typedef void (*bt_component_class_source_finalize_method)(
+               bt_self_component_source *self_component);
+
+/*!
+@brief
+    \bt_c_flt_comp finalization method.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] self_component
+    Filter component instance.
+
+@bt_pre_not_null{self_component}
+
+@bt_post_no_error
+
+@sa bt_component_class_filter_set_finalize_method() &mdash;
+    Sets the finalization method of a filter component class.
+*/
+typedef void (*bt_component_class_filter_finalize_method)(
+               bt_self_component_filter *self_component);
+
+/*!
+@brief
+    \bt_c_sink_comp finalization method.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] self_component
+    Sink component instance.
+
+@bt_pre_not_null{self_component}
+
+@bt_post_no_error
+
+@sa bt_component_class_sink_set_finalize_method() &mdash;
+    Sets the finalization method of a sink component class.
+*/
+typedef void (*bt_component_class_sink_finalize_method)(
+               bt_self_component_sink *self_component);
+
+/*!
+@brief
+    Status codes for
+    #bt_component_class_source_get_supported_mip_versions_method,
+    #bt_component_class_filter_get_supported_mip_versions_method, and
+    #bt_component_class_sink_get_supported_mip_versions_method.
+*/
+typedef enum bt_component_class_get_supported_mip_versions_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK                  = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
+} bt_component_class_get_supported_mip_versions_method_status;
+
+/*!
+@brief
+    \bt_c_src_comp_cls \"get supported \bt_mip versions\" method.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+As of \bt_name_version_min_maj, you can only add the range [0,&nbsp;0]
+to \bt_p{supported_versions}.
+
+@param[in] self_component_class
+    Source component class.
+@param[in] params
+    @parblock
+    Initialization parameters, as passed as the \bt_p{params} parameter
+    of bt_component_descriptor_set_add_descriptor() or
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] initialize_method_data
+    User data for this method, as passed as the
+    \bt_p{init_method_data} parameter of
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+@param[in] logging_level
+    Logging level to use during this method's execution, as passed
+    as the \bt_p{logging_level} parameter of
+    bt_get_greatest_operative_mip_version().
+@param[in] supported_versions
+    \bt_c_uint_rs to which to add the ranges of supported MIP versions
+    of an eventual instance of \bt_p{self_component_class} considering
+    \bt_p{params} and \bt_p{initialize_method_data}.
+
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component_class}
+@bt_pre_not_null{params}
+@bt_pre_is_map_val{params}
+@bt_pre_not_null{supported_versions}
+@pre
+    \bt_p{supported_versions} is empty.
+
+@sa bt_component_class_source_set_get_supported_mip_versions_method() &mdash;
+    Sets the "get supported MIP versions" method of a source
+    component class.
+*/
+typedef bt_component_class_get_supported_mip_versions_method_status
+(*bt_component_class_source_get_supported_mip_versions_method)(
+               bt_self_component_class_source *self_component_class,
+               const bt_value *params, void *initialize_method_data,
+               bt_logging_level logging_level,
+               bt_integer_range_set_unsigned *supported_versions);
+
+
+/*!
+@brief
+    \bt_c_flt_comp_cls \"get supported \bt_mip versions\" method.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+As of \bt_name_version_min_maj, you can only add the range [0,&nbsp;0]
+to \bt_p{supported_versions}.
+
+@param[in] self_component_class
+    Filter component class.
+@param[in] params
+    @parblock
+    Initialization parameters, as passed as the \bt_p{params} parameter
+    of bt_component_descriptor_set_add_descriptor() or
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] initialize_method_data
+    User data for this method, as passed as the
+    \bt_p{init_method_data} parameter of
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+@param[in] logging_level
+    Logging level to use during this method's execution, as passed
+    as the \bt_p{logging_level} parameter of
+    bt_get_greatest_operative_mip_version().
+@param[in] supported_versions
+    \bt_c_uint_rs to which to add the ranges of supported MIP versions
+    of an eventual instance of \bt_p{self_component_class} considering
+    \bt_p{params} and \bt_p{initialize_method_data}.
+
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component_class}
+@bt_pre_not_null{params}
+@bt_pre_is_map_val{params}
+@bt_pre_not_null{supported_versions}
+@pre
+    \bt_p{supported_versions} is empty.
+
+@sa bt_component_class_filter_set_get_supported_mip_versions_method() &mdash;
+    Sets the "get supported MIP versions" method of a filter
+    component class.
+*/
+typedef bt_component_class_get_supported_mip_versions_method_status
+(*bt_component_class_filter_get_supported_mip_versions_method)(
+               bt_self_component_class_filter *source_component_class,
+               const bt_value *params, void *initialize_method_data,
+               bt_logging_level logging_level,
+               bt_integer_range_set_unsigned *supported_versions);
+
+/*!
+@brief
+    \bt_c_sink_comp_cls \"get supported \bt_mip versions\" method.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+As of \bt_name_version_min_maj, you can only add the range [0,&nbsp;0]
+to \bt_p{supported_versions}.
+
+@param[in] self_component_class
+    Sink component class.
+@param[in] params
+    @parblock
+    Initialization parameters, as passed as the \bt_p{params} parameter
+    of bt_component_descriptor_set_add_descriptor() or
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] initialize_method_data
+    User data for this method, as passed as the
+    \bt_p{init_method_data} parameter of
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+@param[in] logging_level
+    Logging level to use during this method's execution, as passed
+    as the \bt_p{logging_level} parameter of
+    bt_get_greatest_operative_mip_version().
+@param[in] supported_versions
+    \bt_c_uint_rs to which to add the ranges of supported MIP versions
+    of an eventual instance of \bt_p{self_component_class} considering
+    \bt_p{params} and \bt_p{initialize_method_data}.
+
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component_class}
+@bt_pre_not_null{params}
+@bt_pre_is_map_val{params}
+@bt_pre_not_null{supported_versions}
+@pre
+    \bt_p{supported_versions} is empty.
+
+@sa bt_component_class_sink_set_get_supported_mip_versions_method() &mdash;
+    Sets the "get supported MIP versions" method of a sink
+    component class.
+*/
+typedef bt_component_class_get_supported_mip_versions_method_status
+(*bt_component_class_sink_get_supported_mip_versions_method)(
+               bt_self_component_class_sink *source_component_class,
+               const bt_value *params, void *initialize_method_data,
+               bt_logging_level logging_level,
+               bt_integer_range_set_unsigned *supported_versions);
+
+/*!
+@brief
+    Status codes for
+    #bt_component_class_sink_graph_is_configured_method.
+*/
+typedef enum bt_component_class_sink_graph_is_configured_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK            = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
+} bt_component_class_sink_graph_is_configured_method_status;
+
+/*!
+@brief
+    \bt_c_sink_comp "graph is configured" method.
+
+See the \ref api-comp-cls-dev-meth-graph-configured
+"graph is configured" method.
+
+@param[in] self_component
+    Sink component instance.
+
+@retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+
+@sa bt_component_class_sink_set_graph_is_configured_method() &mdash;
+    Sets the "graph is configured" method of a sink component class.
+*/
+typedef bt_component_class_sink_graph_is_configured_method_status
+(*bt_component_class_sink_graph_is_configured_method)(
+               bt_self_component_sink *self_component);
+
+/*!
+@brief
+    Status codes for
+    #bt_component_class_source_initialize_method,
+    #bt_component_class_filter_initialize_method, and
+    #bt_component_class_sink_initialize_method.
+*/
+typedef enum bt_component_class_initialize_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK                  = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
+} bt_component_class_initialize_method_status;
+
+/*!
+@brief
+    \bt_c_src_comp initialization method.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
+is not used.
+
+@param[in] self_component
+    Source component instance.
+@param[in] configuration
+    Initial component configuration (unused).
+@param[in] params
+    @parblock
+    Initialization parameters, as passed as the \bt_p{params} parameter
+    of bt_graph_add_source_component() or
+    bt_graph_add_source_component_with_initialize_method_data().
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] initialize_method_data
+    User data for this method, as passed as the
+    \bt_p{initialize_method_data} parameter of
+    bt_graph_add_source_component_with_initialize_method_data().
+
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{configuration}
+@bt_pre_not_null{params}
+@bt_pre_is_map_val{params}
+
+@sa bt_component_class_source_set_initialize_method() &mdash;
+    Sets the initialization method of a source component class.
+*/
+typedef bt_component_class_initialize_method_status
+(*bt_component_class_source_initialize_method)(
+               bt_self_component_source *self_component,
+               bt_self_component_source_configuration *configuration,
+               const bt_value *params, void *initialize_method_data);
+
+/*!
+@brief
+    \bt_c_flt_comp initialization method.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
+is not used.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] configuration
+    Initial component configuration (unused).
+@param[in] params
+    @parblock
+    Initialization parameters, as passed as the \bt_p{params} parameter
+    of bt_graph_add_filter_component() or
+    bt_graph_add_filter_component_with_initialize_method_data().
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] initialize_method_data
+    User data for this method, as passed as the
+    \bt_p{initialize_method_data} parameter of
+    bt_graph_add_filter_component_with_initialize_method_data().
+
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{configuration}
+@bt_pre_not_null{params}
+@bt_pre_is_map_val{params}
+
+@sa bt_component_class_filter_set_initialize_method() &mdash;
+    Sets the initialization method of a filter component class.
+*/
+typedef bt_component_class_initialize_method_status
+(*bt_component_class_filter_initialize_method)(
+               bt_self_component_filter *self_component,
+               bt_self_component_filter_configuration *configuration,
+               const bt_value *params, void *initialize_method_data);
+
+/*!
+@brief
+    \bt_c_sink_comp initialization method.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+As of \bt_name_version_min_maj, the \bt_p{configuration} parameter
+is not used.
+
+@param[in] self_component
+    Sink component instance.
+@param[in] configuration
+    Initial component configuration (unused).
+@param[in] params
+    @parblock
+    Initialization parameters, as passed as the \bt_p{params} parameter
+    of bt_graph_add_sink_component(),
+    bt_graph_add_sink_component_with_initialize_method_data(), or
+    bt_graph_add_simple_sink_component().
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] initialize_method_data
+    User data for this method, as passed as the
+    \bt_p{initialize_method_data} parameter of
+    bt_graph_add_sink_component_with_initialize_method_data().
+
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{configuration}
+@bt_pre_not_null{params}
+@bt_pre_is_map_val{params}
+
+@sa bt_component_class_sink_set_initialize_method() &mdash;
+    Sets the initialization method of a sink component class.
+*/
+typedef bt_component_class_initialize_method_status
+(*bt_component_class_sink_initialize_method)(
+               bt_self_component_sink *self_component,
+               bt_self_component_sink_configuration *configuration,
+               const bt_value *params, void *initialize_method_data);
+
+/*!
+@brief
+    Status codes for
+    #bt_component_class_source_output_port_connected_method,
+    #bt_component_class_filter_input_port_connected_method,
+    #bt_component_class_filter_output_port_connected_method, and
+    #bt_component_class_sink_input_port_connected_method.
+*/
+typedef enum bt_component_class_port_connected_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
+} bt_component_class_port_connected_method_status;
+
+/*!
+@brief
+    \bt_c_src_comp "output port connected" method.
+
+See the
+\ref api-comp-cls-dev-meth-oport-connected "output port connected"
+method.
+
+@param[in] self_component
+    Source component instance.
+@param[in] self_port
+    Connected \bt_oport of \bt_p{self_component}.
+@param[in] other_port
+    \bt_c_conn's other (input) port.
+
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{self_port}
+@bt_pre_not_null{other_port}
+
+@sa bt_component_class_source_set_output_port_connected_method() &mdash;
+    Sets the "output port connected" method of a source component class.
+*/
+typedef bt_component_class_port_connected_method_status
+(*bt_component_class_source_output_port_connected_method)(
+               bt_self_component_source *self_component,
+               bt_self_component_port_output *self_port,
+               const bt_port_input *other_port);
+
+/*!
+@brief
+    \bt_c_flt_comp "input port connected" method.
+
+See the
+\ref api-comp-cls-dev-meth-iport-connected "input port connected"
+method.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] self_port
+    Connected \bt_iport of \bt_p{self_component}.
+@param[in] other_port
+    \bt_c_conn's other (output) port.
+
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{self_port}
+@bt_pre_not_null{other_port}
+
+@sa bt_component_class_filter_set_input_port_connected_method() &mdash;
+    Sets the "input port connected" method of a filter component class.
+*/
+typedef bt_component_class_port_connected_method_status
+(*bt_component_class_filter_input_port_connected_method)(
+               bt_self_component_filter *self_component,
+               bt_self_component_port_input *self_port,
+               const bt_port_output *other_port);
+
+/*!
+@brief
+    \bt_c_flt_comp "output port connected" method.
+
+See the
+\ref api-comp-cls-dev-meth-oport-connected "output port connected"
+method.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] self_port
+    Connected \bt_oport of \bt_p{self_component}.
+@param[in] other_port
+    \bt_c_conn's other (input) port.
+
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{self_port}
+@bt_pre_not_null{other_port}
+
+@sa bt_component_class_filter_set_output_port_connected_method() &mdash;
+    Sets the "output port connected" method of a filter component class.
+*/
+typedef bt_component_class_port_connected_method_status
+(*bt_component_class_filter_output_port_connected_method)(
+               bt_self_component_filter *self_component,
+               bt_self_component_port_output *self_port,
+               const bt_port_input *other_port);
+
+/*!
+@brief
+    \bt_c_sink_comp "input port connected" method.
+
+See the
+\ref api-comp-cls-dev-meth-iport-connected "input port connected"
+method.
+
+@param[in] self_component
+    Sink component instance.
+@param[in] self_port
+    Connected \bt_iport of \bt_p{self_component}.
+@param[in] other_port
+    \bt_c_conn's other (output) port.
+
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{self_port}
+@bt_pre_not_null{other_port}
+
+@sa bt_component_class_sink_set_input_port_connected_method() &mdash;
+    Sets the "input port connected" method of a sink component class.
+*/
+typedef bt_component_class_port_connected_method_status
+(*bt_component_class_sink_input_port_connected_method)(
+               bt_self_component_sink *self_component,
+               bt_self_component_port_input *self_port,
+               const bt_port_output *other_port);
+
+/*!
+@brief
+    Status codes for
+    #bt_component_class_source_query_method,
+    #bt_component_class_filter_query_method, and
+    #bt_component_class_sink_query_method.
+*/
+typedef enum bt_component_class_query_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Unknown object to query.
+       */
+       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT   = __BT_FUNC_STATUS_UNKNOWN_OBJECT,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
+} bt_component_class_query_method_status;
+
+/*!
+@brief
+    \bt_c_src_comp_cls query method.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] self_component_class
+    Source component class, as passed as the \bt_p{component_class}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's \ref api-qexec "executor".
+@param[in] query_executor
+    Private view of this query operation's executor.
+@param[in] object_name
+    Name of the object to query, as passed as the \bt_p{object_name}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's executor.
+@param[in] params
+    @parblock
+    Query parameters, as passed as the \bt_p{params}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's executor.
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] method_data
+    User data for this method, as passed as the \bt_p{method_data}
+    parameter of bt_query_executor_create_with_method_data() when
+    creating this query operation's executor.
+@param[out] result
+    <strong>On success</strong>, \bt_p{*result} is
+    a \em new reference of this query operation's result.
+
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
+    \bt_p{object_name} is unknown.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component_class}
+@bt_pre_not_null{query_executor}
+@bt_pre_not_null{object_name}
+@bt_pre_not_null{params}
+@bt_pre_not_null{result}
+
+@post
+    <strong>On success</strong>, \bt_p{*result} is set.
+
+@sa bt_component_class_source_set_query_method() &mdash;
+    Sets the query method of a source component class.
+*/
+typedef bt_component_class_query_method_status
+(*bt_component_class_source_query_method)(
+               bt_self_component_class_source *self_component_class,
+               bt_private_query_executor *query_executor,
+               const char *object_name, const bt_value *params,
+               void *method_data, const bt_value **result);
+
+/*!
+@brief
+    \bt_c_flt_comp_cls query method.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] self_component_class
+    Filter component class, as passed as the \bt_p{component_class}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's \ref api-qexec "executor".
+@param[in] query_executor
+    Private view of this query operation's executor.
+@param[in] object_name
+    Name of the object to query, as passed as the \bt_p{object_name}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's executor.
+@param[in] params
+    @parblock
+    Query parameters, as passed as the \bt_p{params}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's executor.
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] method_data
+    User data for this method, as passed as the \bt_p{method_data}
+    parameter of bt_query_executor_create_with_method_data() when
+    creating this query operation's executor.
+@param[out] result
+    <strong>On success</strong>, \bt_p{*result} is
+    a \em new reference of this query operation's result.
+
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
+    \bt_p{object_name} is unknown.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component_class}
+@bt_pre_not_null{query_executor}
+@bt_pre_not_null{object_name}
+@bt_pre_not_null{params}
+@bt_pre_not_null{result}
+
+@post
+    <strong>On success</strong>, \bt_p{*result} is set.
+
+@sa bt_component_class_filter_set_query_method() &mdash;
+    Sets the query method of a filter component class.
+*/
+typedef bt_component_class_query_method_status
+(*bt_component_class_filter_query_method)(
+               bt_self_component_class_filter *self_component_class,
+               bt_private_query_executor *query_executor,
+               const char *object_name, const bt_value *params,
+               void *method_data, const bt_value **result);
+
+/*!
+@brief
+    \bt_c_sink_comp_cls query method.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] self_component_class
+    Sink component class, as passed as the \bt_p{component_class}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's \ref api-qexec "executor".
+@param[in] query_executor
+    Private view of this query operation's executor.
+@param[in] object_name
+    Name of the object to query, as passed as the \bt_p{object_name}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's executor.
+@param[in] params
+    @parblock
+    Query parameters, as passed as the \bt_p{params}
+    parameter of bt_query_executor_create() or
+    bt_query_executor_create_with_method_data() when creating this query
+    operation's executor.
+
+    \bt_p{params} is frozen.
+    @endparblock
+@param[in] method_data
+    User data for this method, as passed as the \bt_p{method_data}
+    parameter of bt_query_executor_create_with_method_data() when
+    creating this query operation's executor.
+@param[out] result
+    <strong>On success</strong>, \bt_p{*result} is
+    a \em new reference of this query operation's result.
+
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT
+    \bt_p{object_name} is unknown.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_component_class}
+@bt_pre_not_null{query_executor}
+@bt_pre_not_null{object_name}
+@bt_pre_not_null{params}
+@bt_pre_not_null{result}
+
+@post
+    <strong>On success</strong>, \bt_p{*result} is set.
+
+@sa bt_component_class_sink_set_query_method() &mdash;
+    Sets the query method of a sink component class.
+*/
+typedef bt_component_class_query_method_status
+(*bt_component_class_sink_query_method)(
+               bt_self_component_class_sink *self_component_class,
+               bt_private_query_executor *query_executor,
+               const char *object_name, const bt_value *params,
+               void *method_data, const bt_value **result);
+
+/*! @} */
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_src_comp_cls named \bt_p{name} and having the
+    \bt_msg_iter_cls \bt_p{message_iterator_class}.
+
+On success, the returned source component class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-comp-cls-prop-name "Name"
+    <td>\bt_p{name}
+  <tr>
+    <td>\ref api-comp-cls-prop-descr "Description"
+    <td>\em None
+  <tr>
+    <td>\ref api-comp-cls-prop-help "Help text"
+    <td>\em None
+</table>
+
+@param[in] name
+    Name of the source component class to create (copied).
+@param[in] message_iterator_class
+    Message iterator class of the source component class to create.
+
+@returns
+    New source component class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{name}
+@bt_pre_not_null{message_iterator_class}
+
+@bt_post_success_frozen{message_iterator_class}
+
+@sa bt_message_iterator_class_create() &mdash;
+    Creates a message iterator class.
+*/
+extern
+bt_component_class_source *bt_component_class_source_create(
+               const char *name,
+               bt_message_iterator_class *message_iterator_class);
+
+/*!
+@brief
+    Creates a \bt_flt_comp_cls named \bt_p{name} and having the
+    \bt_msg_iter_cls \bt_p{message_iterator_class}.
+
+On success, the returned filter component class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-comp-cls-prop-name "Name"
+    <td>\bt_p{name}
+  <tr>
+    <td>\ref api-comp-cls-prop-descr "Description"
+    <td>\em None
+  <tr>
+    <td>\ref api-comp-cls-prop-help "Help text"
+    <td>\em None
+</table>
+
+@param[in] name
+    Name of the filter component class to create (copied).
+@param[in] message_iterator_class
+    Message iterator class of the filter component class to create.
+
+@returns
+    New filter component class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{name}
+@bt_pre_not_null{message_iterator_class}
+
+@bt_post_success_frozen{message_iterator_class}
+
+@sa bt_message_iterator_class_create() &mdash;
+    Creates a message iterator class.
+*/
+extern
+bt_component_class_filter *bt_component_class_filter_create(
+               const char *name,
+               bt_message_iterator_class *message_iterator_class);
+
+/*!
+@brief
+    Creates a \bt_sink_comp_cls named \bt_p{name} and having the
+    \ref api-comp-cls-dev-meth-consume "consuming method"
+    \bt_p{consume_method}.
+
+On success, the returned sink component class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-comp-cls-prop-name "Name"
+    <td>\bt_p{name}
+  <tr>
+    <td>\ref api-comp-cls-prop-descr "Description"
+    <td>\em None
+  <tr>
+    <td>\ref api-comp-cls-prop-help "Help text"
+    <td>\em None
+</table>
+
+@param[in] name
+    Name of the sink component class to create (copied).
+@param[in] consume_method
+    Consuming method of the sink component class to create.
+
+@returns
+    New sink component class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{name}
+@bt_pre_not_null{consume_method}
+*/
+extern
+bt_component_class_sink *bt_component_class_sink_create(
+               const char *name,
+               bt_component_class_sink_consume_method consume_method);
+
+/*! @} */
+
+/*!
+@name Common properties
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_component_class_set_description().
+*/
+typedef enum bt_component_class_set_description_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK            = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_component_class_set_description_status;
+
+/*!
+@brief
+    Sets the description of the component class \bt_p{component_class}
+    to a copy of \bt_p{description}.
+
+See the \ref api-comp-cls-prop-descr "description" property.
+
+@param[in] component_class
+    Component class of which to set the description to
+    \bt_p{description}.
+@param[in] description
+    New description of \bt_p{component_class} (copied).
+
+@retval #BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{description}
+
+@sa bt_component_class_get_description() &mdash;
+    Returns the description of a component class.
+*/
+extern bt_component_class_set_description_status
+bt_component_class_set_description(bt_component_class *component_class,
+               const char *description);
+
+/*!
+@brief
+    Status codes for bt_component_class_set_help().
+*/
+typedef enum bt_component_class_set_help_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_SET_HELP_STATUS_OK           = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_component_class_set_help_status;
+
+/*!
+@brief
+    Sets the help text of the component class \bt_p{component_class}
+    to a copy of \bt_p{help_text}.
+
+See the \ref api-comp-cls-prop-help "help text" property.
+
+@param[in] component_class
+    Component class of which to set the help text to
+    \bt_p{help_text}.
+@param[in] help_text
+    New help text of \bt_p{component_class} (copied).
+
+@retval #BT_COMPONENT_CLASS_SET_HELP_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{help_text}
+
+@sa bt_component_class_get_help() &mdash;
+    Returns the help text of a component class.
+*/
+extern bt_component_class_set_help_status bt_component_class_set_help(
+               bt_component_class *component_class,
+               const char *help_text);
+
+/*! @} */
+
+/*!
+@name Method setting
+@{
+*/
+
+/*!
+@brief
+    Status code for the
+    <code>bt_component_class_*_set_*_method()</code> functions.
+*/
+typedef enum bt_component_class_set_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK =       __BT_FUNC_STATUS_OK,
+} bt_component_class_set_method_status;
+
+/*!
+@brief
+    Sets the optional finalization method of the \bt_src_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] component_class
+    Source component class of which to set the finalization method to
+    \bt_p{method}.
+@param[in] method
+    New finalization method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_source_set_finalize_method(
+               bt_component_class_source *component_class,
+               bt_component_class_source_finalize_method method);
+
+/*!
+@brief
+    Sets the optional finalization method of the \bt_flt_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] component_class
+    Filter component class of which to set the finalization method to
+    \bt_p{method}.
+@param[in] method
+    New finalization method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_filter_set_finalize_method(
+               bt_component_class_filter *component_class,
+               bt_component_class_filter_finalize_method method);
+
+/*!
+@brief
+    Sets the optional finalization method of the \bt_sink_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] component_class
+    Sink component class of which to set the finalization method to
+    \bt_p{method}.
+@param[in] method
+    New finalization method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern
+bt_component_class_set_method_status
+bt_component_class_sink_set_finalize_method(
+               bt_component_class_sink *component_class,
+               bt_component_class_sink_finalize_method method);
+
+/*!
+@brief
+    Sets the \"get supported \bt_mip versions\" method of the
+    \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+@param[in] component_class
+    Source component class of which to set the "get supported MIP
+    versions" method to \bt_p{method}.
+@param[in] method
+    New "get supported MIP versions" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_source_set_get_supported_mip_versions_method(
+               bt_component_class_source *component_class,
+               bt_component_class_source_get_supported_mip_versions_method method);
+
+/*!
+@brief
+    Sets the \"get supported \bt_mip versions\" method of the
+    \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+@param[in] component_class
+    Filter component class of which to set the "get supported MIP
+    versions" method to \bt_p{method}.
+@param[in] method
+    New "get supported MIP versions" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_filter_set_get_supported_mip_versions_method(
+               bt_component_class_filter *component_class,
+               bt_component_class_filter_get_supported_mip_versions_method method);
+
+/*!
+@brief
+    Sets the \"get supported \bt_mip versions\" method of the
+    \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+@param[in] component_class
+    Sink component class of which to set the "get supported MIP
+    versions" method to \bt_p{method}.
+@param[in] method
+    New "get supported MIP versions" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_sink_set_get_supported_mip_versions_method(
+               bt_component_class_sink *component_class,
+               bt_component_class_sink_get_supported_mip_versions_method method);
+
+/*!
+@brief
+    Sets the "graph is configured" method of the
+    \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the
+\ref api-comp-cls-dev-meth-graph-configured "graph is configured"
+method.
+
+@param[in] component_class
+    Sink component class of which to set the "graph is configured"
+    method to \bt_p{method}.
+@param[in] method
+    New "graph is configured" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern
+bt_component_class_set_method_status
+bt_component_class_sink_set_graph_is_configured_method(
+               bt_component_class_sink *component_class,
+               bt_component_class_sink_graph_is_configured_method method);
+
+/*!
+@brief
+    Sets the optional initialization method of the \bt_src_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+@param[in] component_class
+    Source component class of which to set the initialization method to
+    \bt_p{method}.
+@param[in] method
+    New initialization method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_source_set_initialize_method(
+               bt_component_class_source *component_class,
+               bt_component_class_source_initialize_method method);
+
+/*!
+@brief
+    Sets the optional initialization method of the \bt_flt_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+@param[in] component_class
+    Filter component class of which to set the initialization method to
+    \bt_p{method}.
+@param[in] method
+    New initialization method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_filter_set_initialize_method(
+               bt_component_class_filter *component_class,
+               bt_component_class_filter_initialize_method method);
+
+/*!
+@brief
+    Sets the optional initialization method of the \bt_sink_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+@param[in] component_class
+    Sink component class of which to set the initialization method to
+    \bt_p{method}.
+@param[in] method
+    New initialization method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern
+bt_component_class_set_method_status
+bt_component_class_sink_set_initialize_method(
+               bt_component_class_sink *component_class,
+               bt_component_class_sink_initialize_method method);
+
+/*!
+@brief
+    Sets the optional "output port connected" method of the
+    \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the
+\ref api-comp-cls-dev-meth-oport-connected "output port connected"
+method.
+
+@param[in] component_class
+    Source component class of which to set the "output port connected"
+    method to \bt_p{method}.
+@param[in] method
+    New "output port connected" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_source_set_output_port_connected_method(
+               bt_component_class_source *component_class,
+               bt_component_class_source_output_port_connected_method method);
+
+/*!
+@brief
+    Sets the optional "input port connected" method of the
+    \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the
+\ref api-comp-cls-dev-meth-iport-connected "input port connected"
+method.
+
+@param[in] component_class
+    Filter component class of which to set the "input port connected"
+    method to \bt_p{method}.
+@param[in] method
+    New "input port connected" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_filter_set_input_port_connected_method(
+               bt_component_class_filter *component_class,
+               bt_component_class_filter_input_port_connected_method method);
+
+/*!
+@brief
+    Sets the optional "output port connected" method of the
+    \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the
+\ref api-comp-cls-dev-meth-oport-connected "output port connected"
+method.
+
+@param[in] component_class
+    Filter component class of which to set the "output port connected"
+    method to \bt_p{method}.
+@param[in] method
+    New "output port connected" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_filter_set_output_port_connected_method(
+               bt_component_class_filter *component_class,
+               bt_component_class_filter_output_port_connected_method method);
+
+/*!
+@brief
+    Sets the optional "input port connected" method of the
+    \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}.
+
+See the
+\ref api-comp-cls-dev-meth-iport-connected "input port connected"
+method.
+
+@param[in] component_class
+    Sink component class of which to set the "input port connected"
+    method to \bt_p{method}.
+@param[in] method
+    New "input port connected" method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern
+bt_component_class_set_method_status
+bt_component_class_sink_set_input_port_connected_method(
+               bt_component_class_sink *component_class,
+               bt_component_class_sink_input_port_connected_method method);
+
+/*!
+@brief
+    Sets the optional query method of the \bt_src_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] component_class
+    Source component class of which to set the query method to
+    \bt_p{method}.
+@param[in] method
+    New query method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_source_set_query_method(
+               bt_component_class_source *component_class,
+               bt_component_class_source_query_method method);
+
+/*!
+@brief
+    Sets the optional query method of the \bt_flt_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] component_class
+    Filter component class of which to set the query method to
+    \bt_p{method}.
+@param[in] method
+    New query method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern bt_component_class_set_method_status
+bt_component_class_filter_set_query_method(
+               bt_component_class_filter *component_class,
+               bt_component_class_filter_query_method method);
+
+/*!
+@brief
+    Sets the optional query method of the \bt_sink_comp_cls
+    \bt_p{component_class} to \bt_p{method}.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] component_class
+    Sink component class of which to set the query method to
+    \bt_p{method}.
+@param[in] method
+    New query method of \bt_p{component_class}.
+
+@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{component_class}
+@bt_pre_hot{component_class}
+@bt_pre_not_null{method}
+*/
+extern
+bt_component_class_set_method_status
+bt_component_class_sink_set_query_method(
+               bt_component_class_sink *component_class,
+               bt_component_class_sink_query_method method);
+
+/*! @} */
+
+/*!
+@name Upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
+    \bt_p{component_class} to the common #bt_component_class type.
+
+@param[in] component_class
+    @parblock
+    Source component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component_class} as a common component class.
+*/
+static inline
+bt_component_class *bt_component_class_source_as_component_class(
+               bt_component_class_source *component_class)
+{
+       return __BT_UPCAST(bt_component_class, component_class);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
+    \bt_p{component_class} to the common #bt_component_class type.
+
+@param[in] component_class
+    @parblock
+    Filter component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component_class} as a common component class.
+*/
+static inline
+bt_component_class *bt_component_class_filter_as_component_class(
+               bt_component_class_filter *component_class)
+{
+       return __BT_UPCAST(bt_component_class, component_class);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
+    \bt_p{component_class} to the common #bt_component_class type.
+
+@param[in] component_class
+    @parblock
+    Sink component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component_class} as a common component class.
+*/
+static inline
+bt_component_class *bt_component_class_sink_as_component_class(
+               bt_component_class_sink *component_class)
+{
+       return __BT_UPCAST(bt_component_class, component_class);
+}
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H */

diff --git a/include/babeltrace2/graph/component-class-filter-const.h b/include/babeltrace2/graph/component-class-filter-const.h
deleted file mode 100644 (file)
index f620e03..0000000
--- a/include/babeltrace2/graph/component-class-filter-const.h
+++ /dev/null
@@ -1,67 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component_class *
-bt_component_class_filter_as_component_class_const(
-               const bt_component_class_filter *comp_cls_filter)
-{
-       return __BT_UPCAST_CONST(bt_component_class, comp_cls_filter);
-}
-
-extern void bt_component_class_filter_get_ref(
-               const bt_component_class_filter *component_class_filter);
-
-extern void bt_component_class_filter_put_ref(
-               const bt_component_class_filter *component_class_filter);
-
-#define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_var)      \
-       do {                                                    \
-               bt_component_class_filter_put_ref(_var);        \
-               (_var) = NULL;                                  \
-       } while (0)
-
-#define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_var_dst, _var_src) \
-       do {                                                    \
-               bt_component_class_filter_put_ref(_var_dst);    \
-               (_var_dst) = (_var_src);                        \
-               (_var_src) = NULL;                              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_CONST_H */

diff --git a/include/babeltrace2/graph/component-class-filter.h b/include/babeltrace2/graph/component-class-filter.h
deleted file mode 100644 (file)
index 9aa7a9c..0000000
--- a/include/babeltrace2/graph/component-class-filter.h
+++ /dev/null
@@ -1,121 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_H
-#define BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/types.h>
-#include <babeltrace2/logging.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef bt_component_class_get_supported_mip_versions_method_status
-(*bt_component_class_filter_get_supported_mip_versions_method)(
-               bt_self_component_class_filter *comp_class,
-               const bt_value *params, void *init_method_data,
-               bt_logging_level log_level,
-               bt_integer_range_set_unsigned *supported_versions);
-
-typedef bt_component_class_initialize_method_status
-(*bt_component_class_filter_initialize_method)(
-               bt_self_component_filter *self_component,
-               bt_self_component_filter_configuration *config,
-               const bt_value *params, void *init_method_data);
-
-typedef void (*bt_component_class_filter_finalize_method)(
-               bt_self_component_filter *self_component);
-
-typedef bt_component_class_query_method_status
-(*bt_component_class_filter_query_method)(
-               bt_self_component_class_filter *comp_class,
-               bt_private_query_executor *query_executor,
-               const char *object, const bt_value *params,
-               void *method_data, const bt_value **result);
-
-typedef bt_component_class_port_connected_method_status
-(*bt_component_class_filter_input_port_connected_method)(
-               bt_self_component_filter *self_component,
-               bt_self_component_port_input *self_port,
-               const bt_port_output *other_port);
-
-typedef bt_component_class_port_connected_method_status
-(*bt_component_class_filter_output_port_connected_method)(
-               bt_self_component_filter *self_component,
-               bt_self_component_port_output *self_port,
-               const bt_port_input *other_port);
-
-static inline
-bt_component_class *bt_component_class_filter_as_component_class(
-               bt_component_class_filter *comp_cls_filter)
-{
-       return __BT_UPCAST(bt_component_class, comp_cls_filter);
-}
-
-extern
-bt_component_class_filter *bt_component_class_filter_create(
-               const char *name,
-               bt_message_iterator_class *message_iterator_class);
-
-extern bt_component_class_set_method_status
-bt_component_class_filter_set_get_supported_mip_versions_method(
-               bt_component_class_filter *comp_class,
-               bt_component_class_filter_get_supported_mip_versions_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_filter_set_initialize_method(
-               bt_component_class_filter *comp_class,
-               bt_component_class_filter_initialize_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_filter_set_finalize_method(
-               bt_component_class_filter *comp_class,
-               bt_component_class_filter_finalize_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_filter_set_input_port_connected_method(
-               bt_component_class_filter *comp_class,
-               bt_component_class_filter_input_port_connected_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_filter_set_output_port_connected_method(
-               bt_component_class_filter *comp_class,
-               bt_component_class_filter_output_port_connected_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_filter_set_query_method(
-               bt_component_class_filter *comp_class,
-               bt_component_class_filter_query_method method);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_H */

diff --git a/include/babeltrace2/graph/component-class-sink-const.h b/include/babeltrace2/graph/component-class-sink-const.h
deleted file mode 100644 (file)
index c4879d0..0000000
--- a/include/babeltrace2/graph/component-class-sink-const.h
+++ /dev/null
@@ -1,67 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component_class *
-bt_component_class_sink_as_component_class_const(
-               const bt_component_class_sink *comp_cls_sink)
-{
-       return __BT_UPCAST_CONST(bt_component_class, comp_cls_sink);
-}
-
-extern void bt_component_class_sink_get_ref(
-               const bt_component_class_sink *component_class_sink);
-
-extern void bt_component_class_sink_put_ref(
-               const bt_component_class_sink *component_class_sink);
-
-#define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_var)                \
-       do {                                                    \
-               bt_component_class_sink_put_ref(_var);          \
-               (_var) = NULL;                                  \
-       } while (0)
-
-#define BT_COMPONENT_CLASS_SINK_MOVE_REF(_var_dst, _var_src)   \
-       do {                                                    \
-               bt_component_class_sink_put_ref(_var_dst);      \
-               (_var_dst) = (_var_src);                        \
-               (_var_src) = NULL;                              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_CONST_H */

diff --git a/include/babeltrace2/graph/component-class-sink.h b/include/babeltrace2/graph/component-class-sink.h
deleted file mode 100644 (file)
index aa56d26..0000000
--- a/include/babeltrace2/graph/component-class-sink.h
+++ /dev/null
@@ -1,142 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_H
-#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/types.h>
-#include <babeltrace2/logging.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef bt_component_class_get_supported_mip_versions_method_status
-(*bt_component_class_sink_get_supported_mip_versions_method)(
-               bt_self_component_class_sink *comp_class,
-               const bt_value *params, void *init_method_data,
-               bt_logging_level log_level,
-               bt_integer_range_set_unsigned *supported_versions);
-
-typedef bt_component_class_initialize_method_status
-(*bt_component_class_sink_initialize_method)(
-               bt_self_component_sink *self_component,
-               bt_self_component_sink_configuration *config,
-               const bt_value *params, void *init_method_data);
-
-typedef void (*bt_component_class_sink_finalize_method)(
-               bt_self_component_sink *self_component);
-
-typedef bt_component_class_query_method_status
-(*bt_component_class_sink_query_method)(
-               bt_self_component_class_sink *comp_class,
-               bt_private_query_executor *query_executor,
-               const char *object, const bt_value *params,
-               void *method_data, const bt_value **result);
-
-typedef bt_component_class_port_connected_method_status
-(*bt_component_class_sink_input_port_connected_method)(
-               bt_self_component_sink *self_component,
-               bt_self_component_port_input *self_port,
-               const bt_port_output *other_port);
-
-typedef enum bt_component_class_sink_graph_is_configured_method_status {
-       BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK            = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
-       BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_component_class_sink_graph_is_configured_method_status;
-
-typedef bt_component_class_sink_graph_is_configured_method_status
-(*bt_component_class_sink_graph_is_configured_method)(
-               bt_self_component_sink *self_component);
-
-typedef enum bt_component_class_sink_consume_method_status {
-       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK                = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
-       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN             = __BT_FUNC_STATUS_AGAIN,
-       BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END               = __BT_FUNC_STATUS_END,
-} bt_component_class_sink_consume_method_status;
-
-typedef bt_component_class_sink_consume_method_status
-(*bt_component_class_sink_consume_method)(
-               bt_self_component_sink *self_component);
-
-static inline
-bt_component_class *bt_component_class_sink_as_component_class(
-               bt_component_class_sink *comp_cls_sink)
-{
-       return __BT_UPCAST(bt_component_class, comp_cls_sink);
-}
-
-extern bt_component_class_set_method_status
-bt_component_class_sink_set_get_supported_mip_versions_method(
-               bt_component_class_sink *comp_class,
-               bt_component_class_sink_get_supported_mip_versions_method method);
-
-extern
-bt_component_class_sink *bt_component_class_sink_create(
-               const char *name,
-               bt_component_class_sink_consume_method method);
-
-extern
-bt_component_class_set_method_status
-bt_component_class_sink_set_initialize_method(
-               bt_component_class_sink *comp_class,
-               bt_component_class_sink_initialize_method method);
-
-extern
-bt_component_class_set_method_status
-bt_component_class_sink_set_finalize_method(
-               bt_component_class_sink *comp_class,
-               bt_component_class_sink_finalize_method method);
-
-extern
-bt_component_class_set_method_status
-bt_component_class_sink_set_input_port_connected_method(
-               bt_component_class_sink *comp_class,
-               bt_component_class_sink_input_port_connected_method method);
-
-extern
-bt_component_class_set_method_status
-bt_component_class_sink_set_graph_is_configured_method(
-               bt_component_class_sink *comp_class,
-               bt_component_class_sink_graph_is_configured_method method);
-
-extern
-bt_component_class_set_method_status
-bt_component_class_sink_set_query_method(
-               bt_component_class_sink *comp_class,
-               bt_component_class_sink_query_method method);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_H */

diff --git a/include/babeltrace2/graph/component-class-source-const.h b/include/babeltrace2/graph/component-class-source-const.h
deleted file mode 100644 (file)
index 163eb31..0000000
--- a/include/babeltrace2/graph/component-class-source-const.h
+++ /dev/null
@@ -1,67 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component_class *
-bt_component_class_source_as_component_class_const(
-               const bt_component_class_source *comp_cls_source)
-{
-       return __BT_UPCAST_CONST(bt_component_class, comp_cls_source);
-}
-
-extern void bt_component_class_source_get_ref(
-               const bt_component_class_source *component_class_source);
-
-extern void bt_component_class_source_put_ref(
-               const bt_component_class_source *component_class_source);
-
-#define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_var)      \
-       do {                                                    \
-               bt_component_class_source_put_ref(_var);        \
-               (_var) = NULL;                                  \
-       } while (0)
-
-#define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_var_dst, _var_src) \
-       do {                                                    \
-               bt_component_class_source_put_ref(_var_dst);    \
-               (_var_dst) = (_var_src);                        \
-               (_var_src) = NULL;                              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_CONST_H */

diff --git a/include/babeltrace2/graph/component-class-source.h b/include/babeltrace2/graph/component-class-source.h
deleted file mode 100644 (file)
index 10942f8..0000000
--- a/include/babeltrace2/graph/component-class-source.h
+++ /dev/null
@@ -1,110 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_H
-#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/types.h>
-#include <babeltrace2/logging.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef bt_component_class_get_supported_mip_versions_method_status
-(*bt_component_class_source_get_supported_mip_versions_method)(
-               bt_self_component_class_source *comp_class,
-               const bt_value *params, void *init_method_data,
-               bt_logging_level log_level,
-               bt_integer_range_set_unsigned *supported_versions);
-
-typedef bt_component_class_initialize_method_status
-(*bt_component_class_source_initialize_method)(
-               bt_self_component_source *self_component,
-               bt_self_component_source_configuration *config,
-               const bt_value *params, void *init_method_data);
-
-typedef void (*bt_component_class_source_finalize_method)(
-               bt_self_component_source *self_component);
-
-typedef bt_component_class_query_method_status
-(*bt_component_class_source_query_method)(
-               bt_self_component_class_source *comp_class,
-               bt_private_query_executor *query_executor,
-               const char *object, const bt_value *params,
-               void *method_data, const bt_value **result);
-
-typedef bt_component_class_port_connected_method_status
-(*bt_component_class_source_output_port_connected_method)(
-               bt_self_component_source *self_component,
-               bt_self_component_port_output *self_port,
-               const bt_port_input *other_port);
-
-static inline
-bt_component_class *bt_component_class_source_as_component_class(
-               bt_component_class_source *comp_cls_source)
-{
-       return __BT_UPCAST(bt_component_class, comp_cls_source);
-}
-
-extern
-bt_component_class_source *bt_component_class_source_create(
-               const char *name,
-               bt_message_iterator_class *message_iterator_class);
-
-extern bt_component_class_set_method_status
-bt_component_class_source_set_get_supported_mip_versions_method(
-               bt_component_class_source *comp_class,
-               bt_component_class_source_get_supported_mip_versions_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_source_set_initialize_method(
-               bt_component_class_source *comp_class,
-               bt_component_class_source_initialize_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_source_set_finalize_method(
-               bt_component_class_source *comp_class,
-               bt_component_class_source_finalize_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_source_set_output_port_connected_method(
-               bt_component_class_source *comp_class,
-               bt_component_class_source_output_port_connected_method method);
-
-extern bt_component_class_set_method_status
-bt_component_class_source_set_query_method(
-               bt_component_class_source *comp_class,
-               bt_component_class_source_query_method method);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_H */

diff --git a/include/babeltrace2/graph/component-class.h b/include/babeltrace2/graph/component-class.h
index b8495d45d0b0bcae7437e0cd58d9ff4ae20c0936..98f66fbb26c47f4fcd6e1d9ea7d6234ada6e5b64 100644 (file)
--- a/include/babeltrace2/graph/component-class.h
+++ b/include/babeltrace2/graph/component-class.h
@@ -33,53 +33,855 @@
 extern "C" {
 #endif
 
-typedef enum bt_component_class_get_supported_mip_versions_method_status {
-       BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK                  = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
-       BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_component_class_get_supported_mip_versions_method_status;
-
-typedef enum bt_component_class_initialize_method_status {
-       BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK                  = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
-       BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_component_class_initialize_method_status;
-
-typedef enum bt_component_class_port_connected_method_status {
-       BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK              = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
-       BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_component_class_port_connected_method_status;
-
-typedef enum bt_component_class_query_method_status {
-       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK               = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
-       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
-       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT   = __BT_FUNC_STATUS_UNKNOWN_OBJECT,
-} bt_component_class_query_method_status;
-
-typedef enum bt_component_class_set_method_status {
-       BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK =       __BT_FUNC_STATUS_OK,
-} bt_component_class_set_method_status;
-
-typedef enum bt_component_class_set_description_status {
-       BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK            = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_component_class_set_description_status;
-
-extern bt_component_class_set_description_status
-bt_component_class_set_description(bt_component_class *component_class,
-               const char *description);
-
-typedef enum bt_component_class_set_help_status {
-       BT_COMPONENT_CLASS_SET_HELP_STATUS_OK           = __BT_FUNC_STATUS_OK,
-       BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_component_class_set_help_status;
-
-extern bt_component_class_set_help_status bt_component_class_set_help(
-               bt_component_class *component_class,
-               const char *help);
+/*!
+@defgroup api-comp-cls Component classes
+@ingroup api-graph
+
+@brief
+    Source, filter, and sink component classes (non-development).
+
+A <strong><em>component class</em></strong> is the class of a \bt_comp:
+
+@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.
+
+You can instantiate a given component class many times, with different
+initialization parameters, to create many components with the
+<code>bt_graph_add_*_component*()</code> functions (see \ref api-graph).
+
+There are two ways to obtain a component class:
+
+- Create one programatically: see \ref api-comp-cls-dev.
+
+- Borrow one from a \bt_plugin.
+
+  Note that, as of \bt_name_version_min_maj, you cannot access a
+  component class's plugin, if any.
+
+A component class is a \ref api-fund-shared-object "shared object": get
+a new reference with bt_component_class_get_ref() and put an existing
+reference with bt_component_class_put_ref().
+
+The common C&nbsp;type of a component class is #bt_component_class.
+
+There are three types of component classes:
+
+<dl>
+  <dt>\anchor api-comp-cls-src Source component class</dt>
+  <dd>
+    A source component class instance (a \bt_src_comp) \bt_msg_iter
+    emits fresh \bt_p_msg.
+
+    A source component class's specific type is
+    #bt_component_class_source and its type enumerator is
+    #BT_COMPONENT_CLASS_TYPE_SOURCE.
+
+    \ref api-fund-c-typing "Upcast" the #bt_component_class_source type
+    to the #bt_component_class type with
+    bt_component_class_source_as_component_class_const().
+
+    Get a new source component class reference with Use
+    bt_component_class_source_get_ref() and put an existing one with
+    bt_component_class_source_put_ref().
+  </dd>
+
+  <dt>\anchor api-comp-cls-flt Filter component class</dt>
+  <dd>
+    A filter component class instance (a \bt_flt_comp) message iterator
+    emits fresh and transformed messages. It can also discard
+    existing messages.
+
+    A filter component class's specific type is
+    #bt_component_class_filter and its type enumerator is
+    #BT_COMPONENT_CLASS_TYPE_FILTER.
+
+    \ref api-fund-c-typing "Upcast" the #bt_component_class_filter type
+    to the #bt_component_class type with
+    bt_component_class_filter_as_component_class_const().
+
+    Get a new filter component class reference with
+    bt_component_class_filter_get_ref() and put an existing one with
+    bt_component_class_filter_put_ref().
+  </dd>
+
+  <dt>\anchor api-comp-cls-sink Sink component class</dt>
+  <dd>
+    A sink component class instance (a \bt_sink_comp) consumes messages
+    from a source or filter message iterator.
+
+    A filter component class's specific type is #bt_component_class_sink
+    and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK.
+
+    \ref api-fund-c-typing "Upcast" the #bt_component_class_sink type to
+    the #bt_component_class type with
+    bt_component_class_sink_as_component_class_const().
+
+    Get a new sink component class reference with
+    bt_component_class_sink_get_ref() and put an existing one with
+    bt_component_class_sink_put_ref().
+  </dd>
+</dl>
+
+Get a component's class type enumerator with
+bt_component_class_get_type(). You can also use the
+bt_component_class_is_source(), bt_component_class_is_filter(), and
+bt_component_class_is_sink() helper functions.
+
+<h1>Properties</h1>
+
+A component class has the following common properties:
+
+<dl>
+  <dt>
+    \anchor api-comp-cls-prop-name
+    Name
+  </dt>
+  <dd>
+    Name of the component class.
+
+    Within a \bt_plugin, for a given component class type, each
+    component class has a unique name.
+
+    Get a component class's name with bt_component_class_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-prop-descr
+    \bt_dt_opt Description
+  </dt>
+  <dd>
+    Textual description of the component class.
+
+    Get a component class's description with
+    bt_component_class_get_description().
+  </dd>
+
+  <dt>
+    \anchor api-comp-cls-prop-help
+    \bt_dt_opt Help text
+  </dt>
+  <dd>
+    Help text of the component class.
+
+    Get a component class's help text with
+    bt_component_class_get_help().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_component_class bt_component_class;
+
+@brief
+    Component class.
+
+@typedef struct bt_component_class_source bt_component_class_source;
+
+@brief
+    \bt_c_src_comp_cls.
+
+@typedef struct bt_component_class_filter bt_component_class_filter;
+
+@brief
+    \bt_c_flt_comp_cls.
+
+@typedef struct bt_component_class_sink bt_component_class_sink;
+
+@brief
+    \bt_c_sink_comp_cls.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+    Component class type enumerators.
+*/
+typedef enum bt_component_class_type {
+       /*!
+       @brief
+           \bt_c_src_comp_cls.
+       */
+       BT_COMPONENT_CLASS_TYPE_SOURCE  = 1 << 0,
+
+       /*!
+       @brief
+           \bt_c_flt_comp_cls.
+       */
+       BT_COMPONENT_CLASS_TYPE_FILTER  = 1 << 1,
+
+       /*!
+       @brief
+           \bt_c_sink_comp_cls.
+       */
+       BT_COMPONENT_CLASS_TYPE_SINK    = 1 << 2,
+} bt_component_class_type;
+
+/*!
+@brief
+    Returns the type enumerator of the component class
+    \bt_p{component_class}.
+
+@param[in] component_class
+    Component class of which to get the type enumerator.
+
+@returns
+    Type enumerator of \bt_p{component_class}.
+
+@bt_pre_not_null{component_class}
+
+@sa bt_component_class_is_source() &mdash;
+    Returns whether or not a component class is a \bt_src_comp_cls.
+@sa bt_component_class_is_filter() &mdash;
+    Returns whether or not a component class is a \bt_flt_comp_cls.
+@sa bt_component_class_is_sink() &mdash;
+    Returns whether or not a component class is a \bt_sink_comp_cls.
+*/
+extern bt_component_class_type bt_component_class_get_type(
+               const bt_component_class *component_class);
+
+/*!
+@brief
+    Returns whether or not the component class \bt_p{component_class}
+    is a \bt_src_comp_cls.
+
+@param[in] component_class
+    Component class to check.
+
+@returns
+    #BT_TRUE if \bt_p{component_class} is a source component class.
+
+@bt_pre_not_null{component_class}
+
+@sa bt_component_class_get_type() &mdash;
+    Returns the type enumerator of a component class.
+*/
+static inline
+bt_bool bt_component_class_is_source(
+               const bt_component_class *component_class)
+{
+       return bt_component_class_get_type(component_class) ==
+               BT_COMPONENT_CLASS_TYPE_SOURCE;
+}
+
+/*!
+@brief
+    Returns whether or not the component class \bt_p{component_class}
+    is a \bt_flt_comp_cls.
+
+@param[in] component_class
+    Component class to check.
+
+@returns
+    #BT_TRUE if \bt_p{component_class} is a filter component class.
+
+@bt_pre_not_null{component_class}
+
+@sa bt_component_class_get_type() &mdash;
+    Returns the type enumerator of a component class.
+*/
+static inline
+bt_bool bt_component_class_is_filter(
+               const bt_component_class *component_class)
+{
+       return bt_component_class_get_type(component_class) ==
+               BT_COMPONENT_CLASS_TYPE_FILTER;
+}
+
+/*!
+@brief
+    Returns whether or not the component class \bt_p{component_class}
+    is a \bt_sink_comp_cls.
+
+@param[in] component_class
+    Component class to check.
+
+@returns
+    #BT_TRUE if \bt_p{component_class} is a sink component class.
+
+@bt_pre_not_null{component_class}
+
+@sa bt_component_class_get_type() &mdash;
+    Returns the type enumerator of a component class.
+*/
+static inline
+bt_bool bt_component_class_is_sink(
+               const bt_component_class *component_class)
+{
+       return bt_component_class_get_type(component_class) ==
+               BT_COMPONENT_CLASS_TYPE_SINK;
+}
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Returns the name of the component class \bt_p{component_class}.
+
+See the \ref api-comp-cls-prop-name "name" property.
+
+@param[in] component_class
+    Component class of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{component_class}.
+
+    The returned pointer remains valid as long as \bt_p{component_class}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component_class}
+*/
+extern const char *bt_component_class_get_name(
+               const bt_component_class *component_class);
+
+/*!
+@brief
+    Returns the description of the component class
+    \bt_p{component_class}.
+
+See the \ref api-comp-cls-prop-descr "description" property.
+
+@param[in] component_class
+    Component class of which to get the description.
+
+@returns
+    @parblock
+    Description of \bt_p{component_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{component_class}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component_class}
+*/
+extern const char *bt_component_class_get_description(
+               const bt_component_class *component_class);
+
+/*!
+@brief
+    Returns the help text of the component class \bt_p{component_class}.
+
+See the \ref api-comp-cls-prop-help "help text" property.
+
+@param[in] component_class
+    Component class of which to get the help text.
+
+@returns
+    @parblock
+    Help text of \bt_p{component_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{component_class}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component_class}
+*/
+extern const char *bt_component_class_get_help(
+               const bt_component_class *component_class);
+
+/*! @} */
+
+/*!
+@name Common reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the component class \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Component class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_put_ref() &mdash;
+    Decrements the reference count of a component class.
+*/
+extern void bt_component_class_get_ref(
+               const bt_component_class *component_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the component class \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Component class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_get_ref() &mdash;
+    Increments the reference count of a component class.
+*/
+extern void bt_component_class_put_ref(
+               const bt_component_class *component_class);
+
+/*!
+@brief
+    Decrements the reference count of the component class
+    \bt_p{_component_class}, and then sets \bt_p{_component_class}
+    to \c NULL.
+
+@param _component_class
+    @parblock
+    Component class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component_class}
+*/
+#define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class) \
+       do {                                                    \
+               bt_component_class_put_ref(_component_class);   \
+               (_component_class) = NULL;                      \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the component class \bt_p{_dst},
+    sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src}
+    to \c NULL.
+
+This macro effectively moves a component class reference from the
+expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src)                \
+       do {                                            \
+               bt_component_class_put_ref(_dst);       \
+               (_dst) = (_src);                        \
+               (_src) = NULL;                          \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Source component class upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
+    \bt_p{component_class} to the common #bt_component_class type.
+
+@param[in] component_class
+    @parblock
+    Source component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component_class} as a common component class.
+*/
+static inline
+const bt_component_class *
+bt_component_class_source_as_component_class_const(
+               const bt_component_class_source *component_class)
+{
+       return __BT_UPCAST_CONST(bt_component_class, component_class);
+}
+
+/*! @} */
+
+/*!
+@name Source component class reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_src_comp_cls \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Source component class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_class_source_put_ref() &mdash;
+    Decrements the reference count of a source component class.
+*/
+extern void bt_component_class_source_get_ref(
+               const bt_component_class_source *component_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_src_comp_cls \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Source component class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_class_source_get_ref() &mdash;
+    Increments the reference count of a source component class.
+*/
+extern void bt_component_class_source_put_ref(
+               const bt_component_class_source *component_class);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_src_comp_cls
+    \bt_p{_component_class}, and then sets \bt_p{_component_class} to
+    \c NULL.
+
+@param _component_class
+    @parblock
+    Source component class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component_class}
+*/
+#define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class)  \
+       do {                                                            \
+               bt_component_class_source_put_ref(_component_class);    \
+               (_component_class) = NULL;                              \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_src_comp_cls \bt_p{_dst},
+    sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
+    \c NULL.
+
+This macro effectively moves a source component class reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src)         \
+       do {                                                    \
+               bt_component_class_source_put_ref(_dst);        \
+               (_dst) = (_src);                                \
+               (_src) = NULL;                                  \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Filter component class upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
+    \bt_p{component_class} to the common #bt_component_class type.
+
+@param[in] component_class
+    @parblock
+    Filter component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component_class} as a common component class.
+*/
+static inline
+const bt_component_class *
+bt_component_class_filter_as_component_class_const(
+               const bt_component_class_filter *component_class)
+{
+       return __BT_UPCAST_CONST(bt_component_class, component_class);
+}
+
+/*! @} */
+
+/*!
+@name Filter component class reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_flt_comp_cls \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Filter component class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_class_filter_put_ref() &mdash;
+    Decrements the reference count of a filter component class.
+*/
+extern void bt_component_class_filter_get_ref(
+               const bt_component_class_filter *component_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_flt_comp_cls \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Filter component class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_class_filter_get_ref() &mdash;
+    Increments the reference count of a filter component class.
+*/
+extern void bt_component_class_filter_put_ref(
+               const bt_component_class_filter *component_class);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_flt_comp_cls
+    \bt_p{_component_class}, and then sets \bt_p{_component_class} to
+    \c NULL.
+
+@param _component_class
+    @parblock
+    Filter component class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component_class}
+*/
+#define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class)  \
+       do {                                                            \
+               bt_component_class_filter_put_ref(_component_class);    \
+               (_component_class) = NULL;                              \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_flt_comp_cls \bt_p{_dst},
+    setsc \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
+    \c NULL.
+
+This macro effectively moves a filter component class reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src)         \
+       do {                                                    \
+               bt_component_class_filter_put_ref(_dst);        \
+               (_dst) = (_src);                                \
+               (_src) = NULL;                                  \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Sink component class upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
+    \bt_p{component_class} to the common #bt_component_class type.
+
+@param[in] component_class
+    @parblock
+    Sink component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component_class} as a common component class.
+*/
+static inline
+const bt_component_class *
+bt_component_class_sink_as_component_class_const(
+               const bt_component_class_sink *component_class)
+{
+       return __BT_UPCAST_CONST(bt_component_class, component_class);
+}
+
+/*! @} */
+
+/*!
+@name Sink component class reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_sink_comp_cls \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Sink component class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_class_sink_put_ref() &mdash;
+    Decrements the reference count of a sink component class.
+*/
+extern void bt_component_class_sink_get_ref(
+               const bt_component_class_sink *component_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_sink_comp_cls \bt_p{component_class}.
+
+@param[in] component_class
+    @parblock
+    Sink component class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_class_sink_get_ref() &mdash;
+    Increments the reference count of a sink component class.
+*/
+extern void bt_component_class_sink_put_ref(
+               const bt_component_class_sink *component_class);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_sink_comp_cls
+    \bt_p{_component_class}, and then sets \bt_p{_component_class} to
+    \c NULL.
+
+@param _component_class
+    @parblock
+    Sink component class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component_class}
+*/
+#define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class)    \
+       do {                                                            \
+               bt_component_class_sink_put_ref(_component_class);      \
+               (_component_class) = NULL;                              \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_sink_comp_cls \bt_p{_dst},
+    sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
+    \c NULL.
+
+This macro effectively moves a sink component class reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src)           \
+       do {                                                    \
+               bt_component_class_sink_put_ref(_dst);          \
+               (_dst) = (_src);                                \
+               (_src) = NULL;                                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/graph/component-const.h b/include/babeltrace2/graph/component-const.h
deleted file mode 100644 (file)
index 11554b5..0000000
--- a/include/babeltrace2/graph/component-const.h
+++ /dev/null
@@ -1,103 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/graph/component-class-const.h>
-#include <babeltrace2/types.h>
-#include <babeltrace2/logging.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/**
- * Get component's name.
- *
- * @param component    Component instance of which to get the name
- * @returns            Returns a pointer to the component's name
- */
-extern const char *bt_component_get_name(const bt_component *component);
-
-extern bt_logging_level bt_component_get_logging_level(
-               const bt_component *component);
-
-/**
- * Get component's class.
- *
- * @param component    Component instance of which to get the class
- * @returns            The component's class
- */
-extern const bt_component_class *bt_component_borrow_class_const(
-               const bt_component *component);
-
-extern bt_component_class_type bt_component_get_class_type(
-               const bt_component *component);
-
-static inline
-bt_bool bt_component_is_source(const bt_component *component)
-{
-       return bt_component_get_class_type(component) ==
-               BT_COMPONENT_CLASS_TYPE_SOURCE;
-}
-
-static inline
-bt_bool bt_component_is_filter(const bt_component *component)
-{
-       return bt_component_get_class_type(component) ==
-               BT_COMPONENT_CLASS_TYPE_FILTER;
-}
-
-static inline
-bt_bool bt_component_is_sink(const bt_component *component)
-{
-       return bt_component_get_class_type(component) ==
-               BT_COMPONENT_CLASS_TYPE_SINK;
-}
-
-extern void bt_component_get_ref(const bt_component *component);
-
-extern void bt_component_put_ref(const bt_component *component);
-
-#define BT_COMPONENT_PUT_REF_AND_RESET(_var)           \
-       do {                                            \
-               bt_component_put_ref(_var);             \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_COMPONENT_MOVE_REF(_var_dst, _var_src)      \
-       do {                                            \
-               bt_component_put_ref(_var_dst);         \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_CONST_H */

diff --git a/include/babeltrace2/graph/component-descriptor-set-const.h b/include/babeltrace2/graph/component-descriptor-set-const.h
deleted file mode 100644 (file)
index 4fdf49a..0000000
--- a/include/babeltrace2/graph/component-descriptor-set-const.h
+++ /dev/null
@@ -1,59 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern void bt_component_descriptor_set_get_ref(
-               const bt_component_descriptor_set *comp_descriptor_set);
-
-extern void bt_component_descriptor_set_put_ref(
-               const bt_component_descriptor_set *comp_descriptor_set);
-
-#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_var)            \
-       do {                                                            \
-               bt_component_descriptor_set_put_ref(_var);              \
-               (_var) = NULL;                                          \
-       } while (0)
-
-#define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_var_dst, _var_src)       \
-       do {                                                            \
-               bt_component_descriptor_set_put_ref(_var_dst);          \
-               (_var_dst) = (_var_src);                                \
-               (_var_src) = NULL;                                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_CONST_H */

diff --git a/include/babeltrace2/graph/component-descriptor-set.h b/include/babeltrace2/graph/component-descriptor-set.h
index e551a70b7ae01d1844829fcf69f546495ffd805f..b90572099f20eea7ff85c10f23dda809d9c80636 100644 (file)
--- a/include/babeltrace2/graph/component-descriptor-set.h
+++ b/include/babeltrace2/graph/component-descriptor-set.h
@@ -34,24 +34,269 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-comp-descr-set Component descriptor set
+@ingroup api-graph
+
+@brief
+    Set of descriptors of prospective \bt_p_comp to use with
+    bt_get_greatest_operative_mip_version().
+
+A <strong><em>component descriptor set</em></strong>
+is an \em unordered set of component descriptors.
+
+A <strong><em>component descriptor</em></strong> describes a
+prospective \bt_comp, that is, everything that is needed to
+\ref api-graph-lc-add "instantiate a component class" within a
+trace processing \bt_graph without actually doing it:
+
+- The <strong>component class</strong> to instantiate, which you would
+  pass as the \bt_p{component_class} parameter of one of the
+  <code>bt_graph_add_*_component*()</code> functions.
+
+- The <strong>initialization parameters</strong>, which you
+  would pass as the \bt_p{params} parameter of one of the
+  <code>bt_graph_add_*_component*()</code> functions.
+
+- The <strong>initialization method data</strong>, which you would pass
+  as the \bt_p{initialize_method_data} parameter of one of the
+  <code>bt_graph_add_*_component_with_initialize_method_data()</code>
+  functions.
+
+As of \bt_name_version_min_maj, the only use case of a component
+descriptor set is bt_get_greatest_operative_mip_version(). This
+function computes the greatest \bt_mip version which
+you can use to create a trace processing graph to which you intend
+to \ref api-graph-lc-add "add components" described by a set of
+component descriptors.
+
+A component descriptor set is a
+\ref api-fund-shared-object "shared object": get a new reference with
+bt_component_descriptor_set_get_ref() and put an existing reference with
+bt_component_descriptor_set_put_ref().
+
+Create an empty component descriptor set with
+bt_component_descriptor_set_create().
+
+Add a component descriptor to a component descriptor set with
+bt_component_descriptor_set_add_descriptor() and
+bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_component_descriptor_set bt_component_descriptor_set;
+
+@brief
+    Component descriptor set.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+
+/*!
+@brief
+    Creates an empty component descriptor set.
+
+@returns
+    New component descriptor set reference, or \c NULL on memory error.
+*/
 extern bt_component_descriptor_set *bt_component_descriptor_set_create(void);
 
+/*!
+@brief
+    Status codes for bt_component_descriptor_set_add_descriptor()
+    and
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data().
+*/
 typedef enum bt_component_descriptor_set_add_descriptor_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK            = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_component_descriptor_set_add_descriptor_status;
 
+/*! @} */
+
+/*!
+@name Component descriptor adding
+@{
+*/
+
+/*!
+@brief
+    Alias of
+    bt_component_descriptor_set_add_descriptor_with_initialize_method_data()
+    with the \bt_p{initialize_method_data} parameter set to \c NULL.
+*/
 extern bt_component_descriptor_set_add_descriptor_status
 bt_component_descriptor_set_add_descriptor(
-               bt_component_descriptor_set *comp_descriptor_set,
+               bt_component_descriptor_set *component_descriptor_set,
                const bt_component_class *component_class,
                const bt_value *params);
 
+/*!
+@brief
+    Adds a descriptor of a \bt_comp which would be an instance of the
+    \bt_comp_cls \bt_p{component_class}, would receive the parameters
+    \bt_p{params} and the method data \bt_p{initialize_method_data} at
+    initialization time, to the component descriptor set
+    \bt_p{component_descriptor_set}.
+
+@param[in] component_descriptor_set
+    Component descriptor set to which to add a component descriptor.
+@param[in] component_class
+    \bt_c_comp_cls which would be instantiated to create the
+    described component.
+@param[in] params
+    @parblock
+    Parameters which would be passed to the initialization method of
+    the described component as the \bt_p{params} parameter.
+
+    Can be \c NULL, in which case it is equivalent to passing an empty
+    \bt_map_val.
+    @endparblock
+@param[in] initialize_method_data
+    User data which would be passed to the initialization method of
+    the described component as the \bt_p{initialize_method_data}
+    parameter.
+
+@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_OK
+    Success.
+@retval #BT_COMPONENT_DESCRIPTOR_SET_ADD_DESCRIPTOR_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{component_descriptor_set}
+@bt_pre_not_null{component_class}
+@pre
+    \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
+    or is \c NULL.
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
 extern bt_component_descriptor_set_add_descriptor_status
 bt_component_descriptor_set_add_descriptor_with_initialize_method_data(
-               bt_component_descriptor_set *comp_descriptor_set,
+               bt_component_descriptor_set *component_descriptor_set,
                const bt_component_class *component_class,
-               const bt_value *params, void *init_method_data);
+               const bt_value *params, void *initialize_method_data);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the component descriptor set \bt_p{component_descriptor_set}.
+
+@param[in] component_descriptor_set
+    @parblock
+    Component descriptor set of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_descriptor_set_put_ref() &mdash;
+    Decrements the reference count of a component descriptor set.
+*/
+extern void bt_component_descriptor_set_get_ref(
+               const bt_component_descriptor_set *component_descriptor_set);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the component descriptor set \bt_p{component_descriptor_set}.
+
+@param[in] component_descriptor_set
+    @parblock
+    Component descriptor set of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_descriptor_set_get_ref() &mdash;
+    Increments the reference count of a component descriptor set.
+*/
+extern void bt_component_descriptor_set_put_ref(
+               const bt_component_descriptor_set *component_descriptor_set);
+
+/*!
+@brief
+    Decrements the reference count of the component descriptor set
+    \bt_p{_component_descriptor_set}, and then sets
+    \bt_p{_component_descriptor_set} to \c NULL.
+
+@param _component_descriptor_set
+    @parblock
+    Component descriptor set of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component_descriptor_set}
+*/
+#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_component_descriptor_set) \
+       do {                                                            \
+               bt_component_descriptor_set_put_ref(_component_descriptor_set); \
+               (_component_descriptor_set) = NULL;                     \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the component descriptor set
+    \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
+    \bt_p{_src} to \c NULL.
+
+This macro effectively moves a component descriptor set reference from
+the expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_dst, _src)       \
+       do {                                                    \
+               bt_component_descriptor_set_put_ref(_dst);      \
+               (_dst) = (_src);                                \
+               (_src) = NULL;                                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/graph/component-filter-const.h b/include/babeltrace2/graph/component-filter-const.h
deleted file mode 100644 (file)
index 55ddbd7..0000000
--- a/include/babeltrace2/graph/component-filter-const.h
+++ /dev/null
@@ -1,94 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_FILTER_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_FILTER_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component *bt_component_filter_as_component_const(
-               const bt_component_filter *component)
-{
-       return __BT_UPCAST_CONST(bt_component, component);
-}
-
-extern const bt_component_class_filter *
-bt_component_filter_borrow_class_const(
-               const bt_component_filter *component);
-
-extern uint64_t bt_component_filter_get_input_port_count(
-               const bt_component_filter *component);
-
-extern const bt_port_input *
-bt_component_filter_borrow_input_port_by_name_const(
-               const bt_component_filter *component, const char *name);
-
-extern const bt_port_input *
-bt_component_filter_borrow_input_port_by_index_const(
-               const bt_component_filter *component, uint64_t index);
-
-extern uint64_t bt_component_filter_get_output_port_count(
-               const bt_component_filter *component);
-
-extern const bt_port_output *
-bt_component_filter_borrow_output_port_by_name_const(
-               const bt_component_filter *component, const char *name);
-
-extern const bt_port_output *
-bt_component_filter_borrow_output_port_by_index_const(
-               const bt_component_filter *component, uint64_t index);
-
-extern void bt_component_filter_get_ref(
-               const bt_component_filter *component_filter);
-
-extern void bt_component_filter_put_ref(
-               const bt_component_filter *component_filter);
-
-#define BT_COMPONENT_FILTER_PUT_REF_AND_RESET(_var)            \
-       do {                                                    \
-               bt_component_filter_put_ref(_var);              \
-               (_var) = NULL;                                  \
-       } while (0)
-
-#define BT_COMPONENT_FILTER_MOVE_REF(_var_dst, _var_src)       \
-       do {                                                    \
-               bt_component_filter_put_ref(_var_dst);          \
-               (_var_dst) = (_var_src);                        \
-               (_var_src) = NULL;                              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_FILTER_CONST_H */

diff --git a/include/babeltrace2/graph/component-sink-const.h b/include/babeltrace2/graph/component-sink-const.h
deleted file mode 100644 (file)
index 64e8b05..0000000
--- a/include/babeltrace2/graph/component-sink-const.h
+++ /dev/null
@@ -1,83 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_SINK_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_SINK_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component *bt_component_sink_as_component_const(
-               const bt_component_sink *component)
-{
-       return __BT_UPCAST_CONST(bt_component, component);
-}
-
-extern const bt_component_class_sink *
-bt_component_sink_borrow_class_const(
-               const bt_component_sink *component);
-
-extern uint64_t bt_component_sink_get_input_port_count(
-               const bt_component_sink *component);
-
-extern const bt_port_input *
-bt_component_sink_borrow_input_port_by_name_const(
-               const bt_component_sink *component, const char *name);
-
-extern const bt_port_input *
-bt_component_sink_borrow_input_port_by_index_const(
-               const bt_component_sink *component, uint64_t index);
-
-extern void bt_component_sink_get_ref(
-               const bt_component_sink *component_sink);
-
-extern void bt_component_sink_put_ref(
-               const bt_component_sink *component_sink);
-
-#define BT_COMPONENT_SINK_PUT_REF_AND_RESET(_var)              \
-       do {                                                    \
-               bt_component_sink_put_ref(_var);                \
-               (_var) = NULL;                                  \
-       } while (0)
-
-#define BT_COMPONENT_SINK_MOVE_REF(_var_dst, _var_src)         \
-       do {                                                    \
-               bt_component_sink_put_ref(_var_dst);            \
-               (_var_dst) = (_var_src);                        \
-               (_var_src) = NULL;                              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_SINK_CONST_H */

diff --git a/include/babeltrace2/graph/component-source-const.h b/include/babeltrace2/graph/component-source-const.h
deleted file mode 100644 (file)
index 85f8923..0000000
--- a/include/babeltrace2/graph/component-source-const.h
+++ /dev/null
@@ -1,83 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_COMPONENT_SOURCE_CONST_H
-#define BABELTRACE2_GRAPH_COMPONENT_SOURCE_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component *bt_component_source_as_component_const(
-               const bt_component_source *component)
-{
-       return __BT_UPCAST_CONST(bt_component, component);
-}
-
-extern const bt_component_class_source *
-bt_component_source_borrow_class_const(
-               const bt_component_source *component);
-
-extern uint64_t bt_component_source_get_output_port_count(
-               const bt_component_source *component);
-
-extern const bt_port_output *
-bt_component_source_borrow_output_port_by_name_const(
-               const bt_component_source *component, const char *name);
-
-extern const bt_port_output *
-bt_component_source_borrow_output_port_by_index_const(
-               const bt_component_source *component, uint64_t index);
-
-extern void bt_component_source_get_ref(
-               const bt_component_source *component_source);
-
-extern void bt_component_source_put_ref(
-               const bt_component_source *component_source);
-
-#define BT_COMPONENT_SOURCE_PUT_REF_AND_RESET(_var)            \
-       do {                                                    \
-               bt_component_source_put_ref(_var);              \
-               (_var) = NULL;                                  \
-       } while (0)
-
-#define BT_COMPONENT_SOURCE_MOVE_REF(_var_dst, _var_src)       \
-       do {                                                    \
-               bt_component_source_put_ref(_var_dst);          \
-               (_var_dst) = (_var_src);                        \
-               (_var_src) = NULL;                              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_COMPONENT_SOURCE_CONST_H */

diff --git a/include/babeltrace2/graph/component.h b/include/babeltrace2/graph/component.h
new file mode 100644 (file)
index 0000000..82aee89
--- /dev/null
+++ b/include/babeltrace2/graph/component.h
@@ -0,0 +1,1280 @@
+#ifndef BABELTRACE2_GRAPH_COMPONENT_H
+#define BABELTRACE2_GRAPH_COMPONENT_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <babeltrace2/graph/component-class.h>
+#include <babeltrace2/types.h>
+#include <babeltrace2/logging.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-comp Components
+@ingroup api-graph
+
+@brief
+    Source, filter, and sink components: nodes in a trace processing
+    \bt_graph.
+
+A <strong><em>component</em></strong> is a node within a trace
+processing \bt_graph:
+
+@image html component.png
+
+A component is \bt_comp_cls instance. Borrow the class of a
+component with bt_component_borrow_class_const(),
+bt_component_source_borrow_class_const(),
+bt_component_filter_borrow_class_const(), and
+bt_component_sink_borrow_class_const().
+
+A component is a \ref api-fund-shared-object "shared object": get a new
+reference with bt_component_get_ref() and put an existing reference with
+bt_component_put_ref().
+
+The common C&nbsp;type of a port is #bt_component.
+
+There are three types of components, which come from the three types
+of component classes:
+
+<dl>
+  <dt>\anchor api-comp-src Source component</dt>
+  <dd>
+    A source component's \bt_msg_iter emits fresh \bt_p_msg.
+
+    A source component's specific type is #bt_component_source and its
+    class's type enumerator is #BT_COMPONENT_CLASS_TYPE_SOURCE.
+
+    \ref api-fund-c-typing "Upcast" the #bt_component_source type to the
+    #bt_component type with bt_component_source_as_component_const().
+
+    Get a new source component reference with
+    bt_component_source_get_ref() and put an existing one with
+    bt_component_source_put_ref().
+
+    A source component has \bt_p_oport only.
+
+    Get the number of output ports a source component has with
+    bt_component_source_get_output_port_count().
+
+    Borrow a source component's output port by index with
+    bt_component_source_borrow_output_port_by_index_const() or by name
+    with bt_component_source_borrow_output_port_by_name_const().
+  </dd>
+
+  <dt>\anchor api-comp-flt Filter component</dt>
+  <dd>
+    A filter component's message iterator emits fresh and transformed
+    messages. It can also discard existing messages.
+
+    A filter component's specific type is #bt_component_filter and its
+    class's type enumerator is #BT_COMPONENT_CLASS_TYPE_FILTER.
+
+    \ref api-fund-c-typing "Upcast" the #bt_component_filter type to the
+    #bt_component type with bt_component_filter_as_component_const().
+
+    Get a new filter component reference with
+    bt_component_filter_get_ref() and put an existing one with
+    bt_component_filter_put_ref().
+
+    A filter component has \bt_p_iport and \bt_p_oport.
+
+    Get the number of output ports a filter component has with
+    bt_component_filter_get_output_port_count().
+
+    Borrow a filter component's output port by index with
+    bt_component_filter_borrow_output_port_by_index_const() or by name
+    with bt_component_filter_borrow_output_port_by_name_const().
+
+    Get the number of input ports a filter component has with
+    bt_component_filter_get_input_port_count().
+
+    Borrow a filter component's input port by index with
+    bt_component_filter_borrow_input_port_by_index_const() or by name
+    with bt_component_filter_borrow_input_port_by_name_const().
+  </dd>
+
+  <dt>\anchor api-comp-sink Sink component</dt>
+  <dd>
+    A sink component consumes messages from a source or filter message
+    iterator.
+
+    A filter component's specific type is #bt_component_sink and its
+    class's type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK.
+
+    \ref api-fund-c-typing "Upcast" the #bt_component_sink type to the
+    #bt_component type with bt_component_sink_as_component_const().
+
+    Get a new sink component reference with bt_component_sink_get_ref()
+    and put an existing one with bt_component_sink_put_ref().
+
+    A sink component has \bt_p_iport only.
+
+    Get the number of input ports a sink component has with
+    bt_component_sink_get_input_port_count().
+
+    Borrow a sink component's input port by index with
+    bt_component_sink_borrow_input_port_by_index_const() or by name
+    with bt_component_sink_borrow_input_port_by_name_const().
+  </dd>
+</dl>
+
+Get a component's class type enumerator with
+bt_component_get_class_type(). You can also use the
+bt_component_is_source(), bt_component_is_filter(), and
+bt_component_is_sink() helper functions.
+
+You cannot directly create a component: there are no
+<code>bt_component_*_create()</code> functions. A trace processing
+\bt_graph creates a component from a \bt_comp_cls when you call one of
+the <code>bt_graph_add_*_component*()</code> functions. Those functions
+also return a borrowed reference of the created component through their
+\bt_p{component} parameter.
+
+<h1>Properties</h1>
+
+A component has the following common properties:
+
+<dl>
+  <dt>
+    \anchor api-comp-prop-name
+    Name
+  </dt>
+  <dd>
+    Name of the component.
+
+    Each component has a unique name within a given trace processing
+    \bt_graph.
+
+    A component's name is set when you
+    \ref api-graph-lc-add "add it to a graph" with one of the
+    <code>bt_graph_add_*_component*()</code> functions (\bt_p{name}
+    parameter); you cannot change it afterwards.
+
+    Get a component's name with bt_component_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-comp-prop-log-lvl
+    Logging level
+  </dt>
+  <dd>
+    Logging level of the component (and its message iterators, if any).
+
+    A component's logging level is set when you
+    \ref api-graph-lc-add "add it to a trace processing graph" with one
+    of the <code>bt_graph_add_*_component*()</code> functions
+    (\bt_p{logging_level} parameter); as of
+    \bt_name_version_min_maj, you cannot change it afterwards.
+
+    Get a component's logging level with
+    bt_component_get_logging_level().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_component bt_component;
+
+@brief
+    Component.
+
+@typedef struct bt_component_source bt_component_source;
+
+@brief
+    \bt_c_src_comp.
+
+@typedef struct bt_component_filter bt_component_filter;
+
+@brief
+    \bt_c_flt_comp.
+
+@typedef struct bt_component_sink bt_component_sink;
+
+@brief
+    \bt_c_sink_comp.
+
+@}
+*/
+
+/*!
+@name Class type query
+@{
+*/
+
+/*!
+@brief
+    Returns the type enumerator of the \ref api-comp-cls "class" of
+    the component \bt_p{component}.
+
+@param[in] component
+    Component of which to get the class's type enumerator.
+
+@returns
+    Type enumerator of the class of \bt_p{component}.
+
+@bt_pre_not_null{component}
+
+@sa bt_component_is_source() &mdash;
+    Returns whether or not a component is a \bt_src_comp.
+@sa bt_component_is_filter() &mdash;
+    Returns whether or not a component is a \bt_flt_comp.
+@sa bt_component_is_sink() &mdash;
+    Returns whether or not a component is a \bt_sink_comp.
+*/
+extern bt_component_class_type bt_component_get_class_type(
+               const bt_component *component);
+
+/*!
+@brief
+    Returns whether or not the component \bt_p{component} is a
+    \bt_src_comp.
+
+@param[in] component
+    Component to check.
+
+@returns
+    #BT_TRUE if \bt_p{component} is a source component.
+
+@bt_pre_not_null{component}
+
+@sa bt_component_get_class_type() &mdash;
+    Returns the type enumerator of a component's class.
+*/
+static inline
+bt_bool bt_component_is_source(const bt_component *component)
+{
+       return bt_component_get_class_type(component) ==
+               BT_COMPONENT_CLASS_TYPE_SOURCE;
+}
+
+/*!
+@brief
+    Returns whether or not the component \bt_p{component} is a
+    \bt_flt_comp.
+
+@param[in] component
+    Component to check.
+
+@returns
+    #BT_TRUE if \bt_p{component} is a filter component.
+
+@bt_pre_not_null{component}
+
+@sa bt_component_get_class_type() &mdash;
+    Returns the type enumerator of a component's class.
+*/
+static inline
+bt_bool bt_component_is_filter(const bt_component *component)
+{
+       return bt_component_get_class_type(component) ==
+               BT_COMPONENT_CLASS_TYPE_FILTER;
+}
+
+/*!
+@brief
+    Returns whether or not the component \bt_p{component} is a
+    \bt_sink_comp.
+
+@param[in] component
+    Component to check.
+
+@returns
+    #BT_TRUE if \bt_p{component} is a sink component.
+
+@bt_pre_not_null{component}
+
+@sa bt_component_get_class_type() &mdash;
+    Returns the type enumerator of a component's class.
+*/
+static inline
+bt_bool bt_component_is_sink(const bt_component *component)
+{
+       return bt_component_get_class_type(component) ==
+               BT_COMPONENT_CLASS_TYPE_SINK;
+}
+
+/*! @} */
+
+/*!
+@name Common class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-comp-cls "class" of the component
+    \bt_p{component}.
+
+@param[in] component
+    Component of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{component}.
+
+@bt_pre_not_null{component}
+*/
+extern const bt_component_class *bt_component_borrow_class_const(
+               const bt_component *component);
+
+/*! @} */
+
+/*!
+@name Common properties
+@{
+*/
+
+/*!
+@brief
+    Returns the name of the component \bt_p{component}.
+
+See the \ref api-comp-prop-name "name" property.
+
+@param[in] component
+    Component of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{component}.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+*/
+extern const char *bt_component_get_name(const bt_component *component);
+
+/*!
+@brief
+    Returns the logging level of the component \bt_p{component} and its
+    \bt_p_msg_iter, if any.
+
+See the \ref api-comp-prop-log-lvl "logging level" property.
+
+@param[in] component
+    Component of which to get the logging level.
+
+@returns
+    Logging level of \bt_p{component}.
+
+@bt_pre_not_null{component}
+*/
+extern bt_logging_level bt_component_get_logging_level(
+               const bt_component *component);
+
+/*! @} */
+
+/*!
+@name Common reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the component \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Component of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_put_ref() &mdash;
+    Decrements the reference count of a component.
+*/
+extern void bt_component_get_ref(const bt_component *component);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the component \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Component of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_get_ref() &mdash;
+    Increments the reference count of a component.
+*/
+extern void bt_component_put_ref(const bt_component *component);
+
+/*!
+@brief
+    Decrements the reference count of the component
+    \bt_p{_component}, and then sets \bt_p{_component} to \c NULL.
+
+@param _component
+    @parblock
+    Component of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component}
+*/
+#define BT_COMPONENT_PUT_REF_AND_RESET(_component)     \
+       do {                                            \
+               bt_component_put_ref(_component);       \
+               (_component) = NULL;                    \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the component \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a component reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_MOVE_REF(_dst, _src)      \
+       do {                                    \
+               bt_component_put_ref(_dst);     \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Source component class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-comp-cls "class" of the \bt_src_comp
+    \bt_p{component}.
+
+@param[in] component
+    Source component of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{component}.
+
+@bt_pre_not_null{component}
+*/
+extern const bt_component_class_source *
+bt_component_source_borrow_class_const(
+               const bt_component_source *component);
+
+/*! @} */
+
+/*!
+@name Source component upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_src_comp \bt_p{component}
+    to the common #bt_component type.
+
+@param[in] component
+    @parblock
+    Source component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component} as a common component.
+*/
+static inline
+const bt_component *bt_component_source_as_component_const(
+               const bt_component_source *component)
+{
+       return __BT_UPCAST_CONST(bt_component, component);
+}
+
+/*! @} */
+
+/*!
+@name Source component port access
+@{
+*/
+
+/*!
+@brief
+    Returns the number of \bt_p_oport that the \bt_src_comp
+    \bt_p{component} has.
+
+@param[in] component
+    Source component of which to get the number of output ports.
+
+@returns
+    Number of output ports that \bt_p{component} has.
+
+@bt_pre_not_null{component}
+*/
+extern uint64_t bt_component_source_get_output_port_count(
+               const bt_component_source *component);
+
+/*!
+@brief
+    Borrows the \bt_oport at index \bt_p{index} from the
+    \bt_src_comp \bt_p{component}.
+
+@param[in] component
+    Source component from which to borrow the output port at index
+    \bt_p{index}.
+@param[in] index
+    Index of the output port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@pre
+    \bt_p{index} is less than the number of output ports
+    \bt_p{component} has (as returned by
+    bt_component_source_get_output_port_count()).
+
+@sa bt_component_source_get_output_port_count() &mdash;
+    Returns the number of output ports that a source component has.
+*/
+extern const bt_port_output *
+bt_component_source_borrow_output_port_by_index_const(
+               const bt_component_source *component, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_oport named \bt_p{name} from the \bt_src_comp
+    \bt_p{component}.
+
+If \bt_p{component} has no output port named \bt_p{name}, this function
+returns \c NULL.
+
+@param[in] component
+    Source component from which to borrow the output port
+    named \bt_p{name}.
+@param[in] name
+    Name of the output port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{name}
+*/
+extern const bt_port_output *
+bt_component_source_borrow_output_port_by_name_const(
+               const bt_component_source *component, const char *name);
+
+/*! @} */
+
+/*!
+@name Source component reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_src_comp \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Source component of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_source_put_ref() &mdash;
+    Decrements the reference count of a source component.
+*/
+extern void bt_component_source_get_ref(
+               const bt_component_source *component);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_src_comp \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Source component of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_source_get_ref() &mdash;
+    Increments the reference count of a source component.
+*/
+extern void bt_component_source_put_ref(
+               const bt_component_source *component);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_src_comp
+    \bt_p{_component}, and then sets \bt_p{_component} to \c NULL.
+
+@param _component
+    @parblock
+    Source component of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component}
+*/
+#define BT_COMPONENT_SOURCE_PUT_REF_AND_RESET(_component)      \
+       do {                                                    \
+               bt_component_source_put_ref(_component);        \
+               (_component) = NULL;                            \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_src_comp \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a source component reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_SOURCE_MOVE_REF(_dst, _src)       \
+       do {                                            \
+               bt_component_source_put_ref(_dst);      \
+               (_dst) = (_src);                        \
+               (_src) = NULL;                          \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Filter component class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-comp-cls "class" of the \bt_flt_comp
+    \bt_p{component}.
+
+@param[in] component
+    Filter component of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{component}.
+
+@bt_pre_not_null{component}
+*/
+extern const bt_component_class_filter *
+bt_component_filter_borrow_class_const(
+               const bt_component_filter *component);
+
+/*! @} */
+
+/*!
+@name Filter component upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_flt_comp \bt_p{component}
+    to the common #bt_component type.
+
+@param[in] component
+    @parblock
+    Filter component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component} as a common component.
+*/
+static inline
+const bt_component *bt_component_filter_as_component_const(
+               const bt_component_filter *component)
+{
+       return __BT_UPCAST_CONST(bt_component, component);
+}
+
+/*! @} */
+
+/*!
+@name Filter component port access
+@{
+*/
+
+/*!
+@brief
+    Returns the number of \bt_p_iport that the \bt_flt_comp
+    \bt_p{component} has.
+
+@param[in] component
+    Filter component of which to get the number of input ports.
+
+@returns
+    Number of input ports that \bt_p{component} has.
+
+@bt_pre_not_null{component}
+*/
+extern uint64_t bt_component_filter_get_input_port_count(
+               const bt_component_filter *component);
+
+/*!
+@brief
+    Borrows the \bt_iport at index \bt_p{index} from the
+    \bt_flt_comp \bt_p{component}.
+
+@param[in] component
+    Filter component from which to borrow the input port at index
+    \bt_p{index}.
+@param[in] index
+    Index of the input port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the input port of
+    \bt_p{component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@pre
+    \bt_p{index} is less than the number of input ports
+    \bt_p{component} has (as returned by
+    bt_component_filter_get_input_port_count()).
+
+@sa bt_component_filter_get_input_port_count() &mdash;
+    Returns the number of input ports that a filter component has.
+*/
+extern const bt_port_input *
+bt_component_filter_borrow_input_port_by_index_const(
+               const bt_component_filter *component, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_iport named \bt_p{name} from the \bt_flt_comp
+    \bt_p{component}.
+
+If \bt_p{component} has no input port named \bt_p{name}, this function
+returns \c NULL.
+
+@param[in] component
+    Filter component from which to borrow the input port
+    named \bt_p{name}.
+@param[in] name
+    Name of the input port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the input port of
+    \bt_p{component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{name}
+*/
+extern const bt_port_input *
+bt_component_filter_borrow_input_port_by_name_const(
+               const bt_component_filter *component, const char *name);
+
+/*!
+@brief
+    Returns the number of \bt_p_oport that the \bt_flt_comp
+    \bt_p{component} has.
+
+@param[in] component
+    Filter component of which to get the number of output ports.
+
+@returns
+    Number of output ports that \bt_p{component} has.
+
+@bt_pre_not_null{component}
+*/
+extern uint64_t bt_component_filter_get_output_port_count(
+               const bt_component_filter *component);
+
+/*!
+@brief
+    Borrows the \bt_oport at index \bt_p{index} from the
+    \bt_flt_comp \bt_p{component}.
+
+@param[in] component
+    Filter component from which to borrow the output port at index
+    \bt_p{index}.
+@param[in] index
+    Index of the output port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@pre
+    \bt_p{index} is less than the number of output ports
+    \bt_p{component} has (as returned by
+    bt_component_filter_get_output_port_count()).
+
+@sa bt_component_filter_get_output_port_count() &mdash;
+    Returns the number of output ports that a filter component has.
+*/
+extern const bt_port_output *
+bt_component_filter_borrow_output_port_by_index_const(
+               const bt_component_filter *component, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_oport named \bt_p{name} from the \bt_flt_comp
+    \bt_p{component}.
+
+If \bt_p{component} has no output port named \bt_p{name}, this function
+returns \c NULL.
+
+@param[in] component
+    Filter component from which to borrow the output port
+    named \bt_p{name}.
+@param[in] name
+    Name of the output port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{name}
+*/
+extern const bt_port_output *
+bt_component_filter_borrow_output_port_by_name_const(
+               const bt_component_filter *component, const char *name);
+
+/*! @} */
+
+/*!
+@name Filter component reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_flt_comp \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Filter component of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_filter_put_ref() &mdash;
+    Decrements the reference count of a filter component.
+*/
+extern void bt_component_filter_get_ref(
+               const bt_component_filter *component);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_flt_comp \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Filter component of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_filter_get_ref() &mdash;
+    Increments the reference count of a filter component.
+*/
+extern void bt_component_filter_put_ref(
+               const bt_component_filter *component);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_flt_comp
+    \bt_p{_component}, and then sets \bt_p{_component} to \c NULL.
+
+@param _component
+    @parblock
+    Filter component of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component}
+*/
+#define BT_COMPONENT_FILTER_PUT_REF_AND_RESET(_component)      \
+       do {                                                    \
+               bt_component_filter_put_ref(_component);        \
+               (_component) = NULL;                            \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_flt_comp \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a filter component reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_FILTER_MOVE_REF(_dst, _src)       \
+       do {                                            \
+               bt_component_filter_put_ref(_dst);      \
+               (_dst) = (_src);                        \
+               (_src) = NULL;                          \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Sink component class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-comp-cls "class" of the \bt_sink_comp
+    \bt_p{component}.
+
+@param[in] component
+    Sink component of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{component}.
+
+@bt_pre_not_null{component}
+*/
+extern const bt_component_class_sink *
+bt_component_sink_borrow_class_const(
+               const bt_component_sink *component);
+
+/*! @} */
+
+/*!
+@name Sink component upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_sink_comp \bt_p{component}
+    to the common #bt_component type.
+
+@param[in] component
+    @parblock
+    Sink component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{component} as a common component.
+*/
+static inline
+const bt_component *bt_component_sink_as_component_const(
+               const bt_component_sink *component)
+{
+       return __BT_UPCAST_CONST(bt_component, component);
+}
+
+/*! @} */
+
+/*!
+@name Sink component port access
+@{
+*/
+
+/*!
+@brief
+    Returns the number of \bt_p_iport that the \bt_sink_comp
+    \bt_p{component} has.
+
+@param[in] component
+    Sink component of which to get the number of input ports.
+
+@returns
+    Number of input ports that \bt_p{component} has.
+
+@bt_pre_not_null{component}
+*/
+extern uint64_t bt_component_sink_get_input_port_count(
+               const bt_component_sink *component);
+
+/*!
+@brief
+    Borrows the \bt_iport at index \bt_p{index} from the
+    \bt_sink_comp \bt_p{component}.
+
+@param[in] component
+    Sink component from which to borrow the input port at index
+    \bt_p{index}.
+@param[in] index
+    Index of the input port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the input port of
+    \bt_p{component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@pre
+    \bt_p{index} is less than the number of input ports
+    \bt_p{component} has (as returned by
+    bt_component_sink_get_input_port_count()).
+
+@sa bt_component_sink_get_input_port_count() &mdash;
+    Returns the number of input ports that a sink component has.
+*/
+extern const bt_port_input *
+bt_component_sink_borrow_input_port_by_index_const(
+               const bt_component_sink *component, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_oport named \bt_p{name} from the \bt_sink_comp
+    \bt_p{component}.
+
+If \bt_p{component} has no output port named \bt_p{name}, this function
+returns \c NULL.
+
+@param[in] component
+    Sink component from which to borrow the output port
+    named \bt_p{name}.
+@param[in] name
+    Name of the output port to borrow from \bt_p{component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{name}
+*/
+extern const bt_port_input *
+bt_component_sink_borrow_input_port_by_name_const(
+               const bt_component_sink *component, const char *name);
+
+/*! @} */
+
+/*!
+@name Sink component reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_sink_comp \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Sink component of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_sink_put_ref() &mdash;
+    Decrements the reference count of a sink component.
+*/
+extern void bt_component_sink_get_ref(
+               const bt_component_sink *component);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_sink_comp \bt_p{component}.
+
+@param[in] component
+    @parblock
+    Sink component of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_sink_get_ref() &mdash;
+    Increments the reference count of a sink component.
+*/
+extern void bt_component_sink_put_ref(
+               const bt_component_sink *component);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_sink_comp
+    \bt_p{_component}, and then sets \bt_p{_component} to \c NULL.
+
+@param _component
+    @parblock
+    Sink component of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_component}
+*/
+#define BT_COMPONENT_SINK_PUT_REF_AND_RESET(_component)                \
+       do {                                                    \
+               bt_component_sink_put_ref(_component);          \
+               (_component) = NULL;                            \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_sink_comp \bt_p{_dst},
+    sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
+    \c NULL.
+
+This macro effectively moves a sink component reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_COMPONENT_SINK_MOVE_REF(_dst, _src)         \
+       do {                                            \
+               bt_component_sink_put_ref(_dst);        \
+               (_dst) = (_src);                        \
+               (_src) = NULL;                          \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_GRAPH_COMPONENT_H */

diff --git a/include/babeltrace2/graph/connection-const.h b/include/babeltrace2/graph/connection-const.h
deleted file mode 100644 (file)
index 9282c17..0000000
--- a/include/babeltrace2/graph/connection-const.h
+++ /dev/null
@@ -1,63 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_CONNECTION_CONST_H
-#define BABELTRACE2_GRAPH_CONNECTION_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_port_input *bt_connection_borrow_downstream_port_const(
-               const bt_connection *connection);
-
-extern const bt_port_output *bt_connection_borrow_upstream_port_const(
-               const bt_connection *connection);
-
-extern void bt_connection_get_ref(const bt_connection *connection);
-
-extern void bt_connection_put_ref(const bt_connection *connection);
-
-#define BT_CONNECTION_PUT_REF_AND_RESET(_var)          \
-       do {                                            \
-               bt_connection_put_ref(_var);            \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_CONNECTION_MOVE_REF(_var_dst, _var_src)     \
-       do {                                            \
-               bt_connection_put_ref(_var_dst);        \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_CONNECTION_CONST_H */

diff --git a/include/babeltrace2/graph/connection.h b/include/babeltrace2/graph/connection.h
new file mode 100644 (file)
index 0000000..68b5634
--- /dev/null
+++ b/include/babeltrace2/graph/connection.h
@@ -0,0 +1,210 @@
+#ifndef BABELTRACE2_GRAPH_CONNECTION_H
+#define BABELTRACE2_GRAPH_CONNECTION_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <babeltrace2/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-conn Connection
+@ingroup api-graph
+
+@brief
+    \bt_c_comp \bt_port connection.
+
+A <strong><em>connection</em></strong> is a link between an \bt_oport
+and an \bt_iport.
+
+@image html component-zoom.png
+
+A connection is a \ref api-fund-shared-object "shared object": get a new
+reference with bt_connection_get_ref() and put an existing reference with
+bt_connection_put_ref().
+
+The type of a connection is #bt_connection.
+
+Borrow the upstream (output) port and downstream (input) port of a
+connection with bt_connection_borrow_upstream_port_const() and
+bt_connection_borrow_downstream_port_const().
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_connection bt_connection;
+
+@brief
+    Connection.
+
+@}
+*/
+
+/*!
+@name Port access
+@{
+*/
+
+/*!
+@brief
+    Borrows the upstream \bt_iport of the connection \bt_p{connection}.
+
+@param[in] connection
+    Connection of which to borrow the upstream port.
+
+@returns
+    \em Borrowed reference of the upstream port of \bt_p{connection}.
+
+@bt_pre_not_null{connection}
+*/
+extern const bt_port_input *bt_connection_borrow_downstream_port_const(
+               const bt_connection *connection);
+
+/*!
+@brief
+    Borrows the downstream \bt_oport of the connection
+    \bt_p{connection}.
+
+@param[in] connection
+    Connection of which to borrow the downstream port.
+
+@returns
+    \em Borrowed reference of the downstream port of \bt_p{connection}.
+
+@bt_pre_not_null{connection}
+*/
+extern const bt_port_output *bt_connection_borrow_upstream_port_const(
+               const bt_connection *connection);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the connection \bt_p{connection}.
+
+@param[in] connection
+    @parblock
+    Connection of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_connection_put_ref() &mdash;
+    Decrements the reference count of a connection.
+*/
+extern void bt_connection_get_ref(const bt_connection *connection);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the connection \bt_p{connection}.
+
+@param[in] connection
+    @parblock
+    Connection of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_connection_get_ref() &mdash;
+    Increments the reference count of a connection.
+*/
+extern void bt_connection_put_ref(const bt_connection *connection);
+
+/*!
+@brief
+    Decrements the reference count of the connection
+    \bt_p{_connection}, and then sets \bt_p{_connection} to \c NULL.
+
+@param _connection
+    @parblock
+    Connection of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_connection}
+*/
+#define BT_CONNECTION_PUT_REF_AND_RESET(_connection)   \
+       do {                                            \
+               bt_connection_put_ref(_connection);     \
+               (_connection) = NULL;                   \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the connection \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a connection reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_CONNECTION_MOVE_REF(_dst, _src)     \
+       do {                                    \
+               bt_connection_put_ref(_dst);    \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_GRAPH_CONNECTION_H */

diff --git a/include/babeltrace2/graph/graph-const.h b/include/babeltrace2/graph/graph-const.h
deleted file mode 100644 (file)
index 168ed2b..0000000
--- a/include/babeltrace2/graph/graph-const.h
+++ /dev/null
@@ -1,57 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_GRAPH_CONST_H
-#define BABELTRACE2_GRAPH_GRAPH_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern void bt_graph_get_ref(const bt_graph *graph);
-
-extern void bt_graph_put_ref(const bt_graph *graph);
-
-#define BT_GRAPH_PUT_REF_AND_RESET(_var)       \
-       do {                                    \
-               bt_graph_put_ref(_var);         \
-               (_var) = NULL;                  \
-       } while (0)
-
-#define BT_GRAPH_MOVE_REF(_var_dst, _var_src)  \
-       do {                                    \
-               bt_graph_put_ref(_var_dst);     \
-               (_var_dst) = (_var_src);        \
-               (_var_src) = NULL;              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_GRAPH_CONST_H */

diff --git a/include/babeltrace2/graph/graph.h b/include/babeltrace2/graph/graph.h
index d562e366e41ace21e3efe49da982d8115eaf8e28..6c7b2d1b8cba495bb5ae7597e41c634fd2f14c59 100644 (file)
--- a/include/babeltrace2/graph/graph.h
+++ b/include/babeltrace2/graph/graph.h
@@ -34,213 +34,1981 @@
 extern "C" {
 #endif
 
-typedef enum bt_graph_listener_func_status {
-       BT_GRAPH_LISTENER_FUNC_STATUS_OK                = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_LISTENER_FUNC_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
-       BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_graph_listener_func_status;
+/*!
+@defgroup api-graph Graph
 
-typedef bt_graph_listener_func_status
-(*bt_graph_filter_component_input_port_added_listener_func)(
-               const bt_component_filter *component,
-               const bt_port_input *port, void *data);
+@brief
+    Trace processing graph.
 
-typedef bt_graph_listener_func_status
-(*bt_graph_sink_component_input_port_added_listener_func)(
-               const bt_component_sink *component,
-               const bt_port_input *port, void *data);
+A <strong><em>trace processing graph</em></strong> is a specialized
+<a href="https://en.wikipedia.org/wiki/Filter_graph">filter graph</a>
+to manipulate one or more traces.
 
-typedef bt_graph_listener_func_status
-(*bt_graph_source_component_output_port_added_listener_func)(
-               const bt_component_source *component,
-               const bt_port_output *port, void *data);
+Whereas the nodes of a multimedia filter graph typically exchange
+video frames and audio samples, the nodes, or \bt_p_comp, of a trace
+processing graph exchange immutable \bt_p_msg containing trace data.
 
-typedef bt_graph_listener_func_status
-(*bt_graph_filter_component_output_port_added_listener_func)(
-               const bt_component_filter *component,
-               const bt_port_output *port, void *data);
+The following illustration shows a basic trace processing graph which
+converts many traces to a single log of pretty-printed lines:
 
-typedef bt_graph_listener_func_status
-(*bt_graph_source_filter_component_ports_connected_listener_func)(
-               const bt_component_source *source_component,
-               const bt_component_filter *filter_component,
-               const bt_port_output *upstream_port,
-               const bt_port_input *downstream_port, void *data);
+@image html basic-convert-graph.png "Basic trace processing graph (conversion graph)."
 
-typedef bt_graph_listener_func_status
-(*bt_graph_source_sink_component_ports_connected_listener_func)(
-               const bt_component_source *source_component,
-               const bt_component_sink *sink_component,
-               const bt_port_output *upstream_port,
-               const bt_port_input *downstream_port, void *data);
+In the illustrations above, notice that:
 
-typedef bt_graph_listener_func_status
-(*bt_graph_filter_filter_component_ports_connected_listener_func)(
-               const bt_component_filter *filter_component_upstream,
-               const bt_component_filter *filter_component_downstream,
-               const bt_port_output *upstream_port,
-               const bt_port_input *downstream_port,
-               void *data);
+- The graph (blue) contains five components.
 
-typedef bt_graph_listener_func_status
-(*bt_graph_filter_sink_component_ports_connected_listener_func)(
-               const bt_component_filter *filter_component,
-               const bt_component_sink *sink_component,
-               const bt_port_output *upstream_port,
-               const bt_port_input *downstream_port, void *data);
+- Three source components (green) are connected to a single filter
+  component (yellow).
 
-typedef enum bt_graph_simple_sink_component_initialize_func_status {
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK                = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_graph_simple_sink_component_initialize_func_status;
+  There are five \bt_p_conn, from five \bt_p_oport
+  to five \bt_p_iport.
 
-typedef bt_graph_simple_sink_component_initialize_func_status
-(*bt_graph_simple_sink_component_initialize_func)(
-               bt_message_iterator *iterator,
-               void *data);
+- The filter component is connected to a single sink component (red).
 
-typedef enum bt_graph_simple_sink_component_consume_func_status {
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK                   = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR                = __BT_FUNC_STATUS_ERROR,
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR         = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN                = __BT_FUNC_STATUS_AGAIN,
-       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END                  = __BT_FUNC_STATUS_END,
-} bt_graph_simple_sink_component_consume_func_status;
+  There's a single connection.
 
-typedef bt_graph_simple_sink_component_consume_func_status
-(*bt_graph_simple_sink_component_consume_func)(
-               bt_message_iterator *iterator,
-               void *data);
+- Source components read external resources while the sink component
+  writes to the standard output or to a file.
+
+- There are two source components having the same
+  \ref api-tir-comp-cls "class": <code>source.ctf.fs</code>.
+
+- All components are instances of \bt_plugin-provided classes:
+  <code>babeltrace2-plugin-ctf.so</code>,
+  <code>user-plugin.so</code>,
+  <code>babeltrace2-plugin-utils.so</code>, and
+  <code>babeltrace2-plugin-text.so</code>.
+
+Of course the topology can be much more complex if needed:
+
+@image html complex-graph.png "Complex trace processing graph."
+
+In a trace processing graph, \bt_p_comp are instances of \bt_p_comp_cls.
+
+A \bt_plugin can provide a component class, but you can also create one
+dynamically (see \ref api-comp-cls-dev).
+
+The connections between component ports in a trace processing graph
+indicate the needed topology to achieve a trace processing task. That
+being said,
+\bt_p_msg do not flow within connections. Instead, a source-to-sink
+or filter-to-sink connection makes it
+possible for a sink component to create a \bt_msg_iter on its end of
+the connection (an \bt_iport). In turn, a filter component message
+iterator can create other message iterators on one or more of the
+component's input ports. For a single connection, there can exist
+multiple message iterators.
+
+A trace processing graph is a
+\ref api-fund-shared-object "shared object": get a new reference with
+bt_graph_get_ref() and put an existing reference with
+bt_graph_put_ref().
+
+The type of a trace processing graph is #bt_graph.
+
+Create a default trace processing graph with bt_graph_create(). You need
+to pass a \bt_mip (MIP) version number when you call this function.
+Then, see
+\ref api-graph-lc "Trace processing graph life cycle"
+to learn how to add components to the graph, connect their ports, and
+run it.
+
+To interrupt a \ref api-graph-lc-run "running" trace processing graph,
+either:
+
+- Borrow the graph's default \bt_intr with
+  bt_graph_borrow_default_interrupter() and set it with
+  bt_interrupter_set().
+
+  When you call bt_graph_create(), the returned trace processing
+  graph has a default interrupter.
+
+- Add your own interrupter with bt_graph_add_interrupter() \em before
+  you run the graph with bt_graph_run() or bt_graph_run_once().
+
+  Then, set the interrupter with bt_interrupter_set().
+
+<h1>\anchor api-graph-lc Trace processing graph life cycle</h1>
+
+The following diagram shows the life cycle of a trace processing
+graph:
+
+@image html graph-lifetime.png "Trace processing graph lifecycle."
+
+After you create a default (empty) trace processing  graph with
+bt_graph_create(), there are three steps to make the trace processing
+task execute:
+
+-# \ref api-graph-lc-add "Add components" to the graph.
+-# \ref api-graph-lc-connect "Connect component ports".
+-# \ref api-graph-lc-run "Run the graph".
+
+You can repeat steps 1 and 2 before step 3, as connecting a
+component \bt_port can make this \bt_comp create a new port:
+you might want to add a component in reaction to this event
+(see \ref api-graph-listeners "Listeners").
+
+Steps 1 and 2 constitute the \em configuration phase of the trace
+processing graph. The first time you call bt_graph_run() or
+bt_graph_run_once() for a given graph (step&nbsp;3), the graph becomes
+<em>configured</em>, and it notifies the sink components as such so that
+they can create their \bt_p_msg_iter.
+
+Once a trace processing graph becomes configured:
+
+- You cannot \ref api-graph-lc-add "add a component" to it.
+
+- You cannot \ref api-graph-lc-connect "connect component ports".
+
+- Components cannot add ports.
+
+In general, as of \bt_name_version_min_maj:
+
+- You cannot remove a component from a trace processing graph.
+
+- You cannot end (remove) a port \bt_conn.
+
+- Components cannot remove ports.
+
+If \em any error occurs (a function returns a status code which ends
+with <code>ERROR</code>) during step 1 or 2, the trace processing
+graph is considered <strong>faulty</strong>: you cannot use it anymore.
+The only functions you can call with a faulty graph are
+bt_graph_get_ref() and bt_graph_put_ref().
+
+<h2>\anchor api-graph-lc-add Add components</h2>
+
+Adding a \bt_comp to a trace processing graph is also known as
+<em>instantiating a \bt_comp_cls</em> because the graph must first
+create the component from its class before adding it.
+
+Because component and component class C&nbsp;types are
+\ref api-fund-c-typing "highly specific", there are six functions
+to add a component to a trace processing graph:
+
+<dl>
+  <dt>Source component</dt>
+  <dd>
+    <dl>
+      <dt>Without initialization method data</dt>
+      <dd>bt_graph_add_source_component()</dd>
+
+      <dt>With initialization method data</dt>
+      <dd>bt_graph_add_source_component_with_initialize_method_data()</dd>
+    </dl>
+  </dd>
+
+  <dt>Filter component</dt>
+  <dd>
+    <dl>
+      <dt>Without initialization method data</dt>
+      <dd>bt_graph_add_filter_component()</dd>
+
+      <dt>With initialization method data</dt>
+      <dd>bt_graph_add_filter_component_with_initialize_method_data()</dd>
+    </dl>
+  </dd>
+
+  <dt>Sink component</dt>
+  <dd>
+    <dl>
+      <dt>Without initialization method data</dt>
+      <dd>bt_graph_add_sink_component()</dd>
+
+      <dt>With initialization method data</dt>
+      <dd>bt_graph_add_sink_component_with_initialize_method_data()</dd>
+    </dl>
+  </dd>
+</dl>
+
+The <code>*_with_initialize_method_data()</code> versions can pass a
+custom, \bt_voidp pointer to the component's
+\ref api-comp-cls-dev-meth-init "initialization method".
+The other versions pass \c NULL as this parameter.
+
+All the functions above accept the same parameters:
+
+@param[in] graph
+    Trace processing graph to which to add the created component.
+@param[in] component_class
+    Class to instantiate within \bt_p{graph}.
+@param[in] name
+    Unique name of the component to add within \bt_p{graph}.
+@param[in] params
+    Initialization parameters to use when creating the component.
+@param[in] logging_level
+    Initial logging level of the component to create.
+@param[out] component
+    <strong>On success</strong>, \bt_p{*component} is the created
+    component.
+
+Once you have the created and added component (\bt_p{*component}),
+you can borrow its \bt_p_port to
+\ref api-graph-lc-connect "connect them".
+
+You can add as many components as needed to a trace processing graph,
+but they must all have a unique name.
+
+<h3>\anchor api-graph-lc-add-ss Add a simple sink component</h3>
+
+To add a very basic \bt_sink_comp which has a single \bt_iport and
+creates a single \bt_msg_iter when the trace processing graph becomes
+configured, use bt_graph_add_simple_sink_component(). When you call
+this function, you pass three user functions:
+
+<dl>
+  <dt>\bt_dt_opt Initialization</dt>
+  <dd>
+    Called when the trace processing graph becomes
+    configured and when the sink component created its single
+    message iterator.
+
+    You can do an initial action with the message iterator such as
+    making it seek a specific point in time or getting messages.
+  </dd>
+
+  <dt>Consume</dt>
+  <dd>
+    Called every time the sink component's
+    \ref api-comp-cls-dev-meth-consume "consuming method" is called.
+
+    You can get the next messages from the component's message
+    iterator and process them.
+  </dd>
+
+  <dt>\bt_dt_opt Finalization</dt>
+  <dd>
+    Called when the sink component is finalized.
+  </dd>
+</dl>
+
+The three functions above receive, as their last parameter, the user
+data you passed to bt_graph_add_simple_sink_component() .
+
+<h2>\anchor api-graph-lc-connect Connect component ports</h2>
+
+When you \ref api-graph-lc-add "add a component" to a trace processing
+graph with one of the <code>bt_graph_add_*_component*()</code>
+functions, the function sets \bt_p{*component} to the
+created and added component.
+
+With such a \bt_comp, you can borrow one of its \bt_p_port by index or
+by name.
+
+Connect two component ports within a trace processing graph with
+bt_graph_connect_ports().
+
+After you connect component ports, you can still
+\ref api-graph-lc-add "add" more components to the graph, and then
+connect more ports.
+
+You don't need to connect all the available ports of a given component,
+depending on the trace processing task you need to perform. However,
+when you \ref api-graph-lc-run "run" the trace processing graph:
+
+- At least one \bt_oport of any \bt_src_comp must be connected.
+- At least one \bt_iport and one output port of any \bt_flt_comp must
+  be connected.
+- At least one input port of any \bt_sink_comp must be connected.
+
+<h2>\anchor api-graph-lc-run Run</h2>
+
+When you are done configuring a trace processing graph, you can run it
+with bt_graph_run().
+
+bt_graph_run() does \em not return until one of:
+
+- All the sink components are ended: bt_graph_run() returns
+  #BT_GRAPH_RUN_STATUS_OK.
+
+- One of the sink component returns an error:
+  bt_graph_run() returns #BT_GRAPH_RUN_STATUS_ERROR or
+  #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
+
+- One of the sink component returns "try again":
+  bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
+
+  In that case, you can call bt_graph_run() again later, usually after
+  waiting for some time.
+
+  This feature exists to allow blocking operations within components
+  to be postponed until they don't block. The graph user can perform
+  other tasks instead of the graph's thread blocking.
+
+- The trace processing graph is interrupted (see
+  bt_graph_borrow_default_interrupter() and bt_graph_add_interrupter()):
+  bt_graph_run() returns #BT_GRAPH_RUN_STATUS_AGAIN.
+
+  Check the \bt_intr's state with bt_interrupter_is_set() to
+  distinguish between a sink component returning "try again" and
+  the trace processing graph getting interrupted.
+
+If you want to make a single sink component consume and process a few
+\bt_p_msg before controlling the thread again, use bt_graph_run_once()
+instead of bt_graph_run().
+
+<h1>Standard \bt_name component classes</h1>
 
-typedef void (*bt_graph_simple_sink_component_finalize_func)(void *data);
+The \bt_name project ships with project \bt_p_plugin which provide
+"standard" \bt_p_comp_cls.
 
+Those standard component classes can be useful in many trace processing
+graph topologies. They are:
+
+<dl>
+  <dt>\c ctf plugin</dt>
+  <dd>
+    <dl>
+      <dt>\c fs source component class</dt>
+      <dd>
+        Opens a
+        <a href="https://diamon.org/ctf/">CTF</a> trace on the file
+        system and emits the \bt_p_msg of their data stream files.
+
+        See \bt_man{babeltrace2-source.ctf.fs,7}.
+      </dd>
+
+      <dt>\c lttng-live source component class</dt>
+      <dd>
+        Connects to an <a href="https://lttng.org/">LTTng</a> relay
+        daemon and emits the messages of the received CTF data streams.
+
+        See \bt_man{babeltrace2-source.ctf.lttng-live,7}.
+      </dd>
+
+      <dt>\c fs sink component class</dt>
+      <dd>
+        Writes the consumed messages as one or more CTF traces on the
+        file system.
+
+        See \bt_man{babeltrace2-sink.ctf.fs,7}.
+      </dd>
+    </dl>
+  </dd>
+
+  <dt>\c lttng-utils plugin</dt>
+  <dd>
+    <dl>
+      <dt>\c debug-info filter component class</dt>
+      <dd>
+        Adds debugging information to compatible LTTng event messages.
+
+        This component class is only available if the project was
+        built with the <code>\-\-enable-debug-info</code>
+        configuration option.
+
+        See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}.
+      </dd>
+    </dl>
+  </dd>
+
+  <dt>\c text plugin</dt>
+  <dd>
+    <dl>
+      <dt>\c dmesg source component class</dt>
+      <dd>
+        Reads the lines of a Linux kernel ring buffer, that is, the
+        output of the
+        <a href="http://man7.org/linux/man-pages/man1/dmesg.1.html"><code>dmesg</code></a>
+        tool, and emits each line as an \bt_ev_msg.
+
+        See \bt_man{babeltrace2-source.text.dmesg,7}.
+      </dd>
+
+      <dt>\c details sink component class</dt>
+      <dd>
+        Deterministically prints the messages it consumes with details
+        to the standard output.
+
+        See \bt_man{babeltrace2-sink.text.details,7}.
+      </dd>
+
+      <dt>\c pretty sink component class</dt>
+      <dd>
+        Pretty-prints the messages it consumes to the standard output or
+        to a file.
+
+        This is equivalent to the \c text output format of the
+        <a href="http://man7.org/linux/man-pages/man1/babeltrace.1.html">Babeltrace&nbsp;1
+        command-line tool</a>.
+
+        See \bt_man{babeltrace2-sink.text.pretty,7}.
+      </dd>
+    </dl>
+  </dd>
+
+  <dt>\c utils plugin</dt>
+  <dd>
+    <dl>
+      <dt>\c muxer filter component class</dt>
+      <dd>
+        Muxes messages by time.
+
+        See \bt_man{babeltrace2-filter.utils.muxer,7}.
+      </dd>
+
+      <dt>\c trimmer filter component class</dt>
+      <dd>
+        Discards all the consumed messages with a time outside a given
+        time range, effectively "cutting" \bt_p_stream.
+
+        See \bt_man{babeltrace2-filter.utils.trimmer,7}.
+      </dd>
+
+      <dt>\c counter sink component class</dt>
+      <dd>
+        Prints the number of consumed messages, either once at the end
+        or periodically, to the standard output.
+
+        See \bt_man{babeltrace2-sink.utils.counter,7}.
+      </dd>
+
+      <dt>\c dummy sink component class</dt>
+      <dd>
+        Consumes messages and discards them (does nothing with them).
+
+        This is useful for testing and benchmarking a trace processing
+        graph application, for example.
+
+        See \bt_man{babeltrace2-sink.utils.dummy,7}.
+      </dd>
+    </dl>
+  </dd>
+</dl>
+
+To access such a component class, get its plugin by name with
+bt_plugin_find() and then borrow the component class by name
+with bt_plugin_borrow_source_component_class_by_name_const(),
+bt_plugin_borrow_filter_component_class_by_name_const(), or
+bt_plugin_borrow_sink_component_class_by_name_const().
+
+For example:
+
+@code
+const bt_plugin *plugin;
+
+if (bt_plugin_find("utils", BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE, BT_TRUE,
+                   &plugin) != BT_PLUGIN_FIND_STATUS_OK) {
+    // handle error
+}
+
+const bt_component_class_filter *muxer_component_class =
+    bt_plugin_borrow_filter_component_class_by_name_const(plugin, "muxer");
+
+if (!muxer_component_class) {
+    // handle error
+}
+@endcode
+
+<h1>\anchor api-graph-listeners Listeners</h1>
+
+A \bt_comp can add a \bt_port:
+
+- At initialization time, that is, when you call one of the
+  <code>bt_graph_add_*_component*()</code> functions.
+
+- When one of its ports gets connected, that is, when you call
+  bt_graph_connect_ports().
+
+To get notified when any component of a given trace processing
+graph adds a port, add one or more "port
+added" listeners to the graph with:
+
+- bt_graph_add_source_component_output_port_added_listener()
+- bt_graph_add_filter_component_input_port_added_listener()
+- bt_graph_add_filter_component_output_port_added_listener()
+- bt_graph_add_sink_component_input_port_added_listener()
+
+Within a "port added" listener function, you can
+\ref api-graph-lc-add "add more components"
+and \ref api-graph-lc-connect "connect more component ports".
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_graph bt_graph;
+
+@brief
+    Trace processing graph.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a default, empty trace processing graph honouring version
+    \bt_p{mip_version} of the \bt_mip.
+
+On success, the returned graph contains no components (see
+\ref api-graph-lc-add "Add components").
+
+The graph is configured as operating following version
+\bt_p{mip_version} of the Message Interchange Protocol, so that
+bt_self_component_get_graph_mip_version() returns this version when
+components call it.
+
+@note
+    As of \bt_name_version_min_maj, the only available MIP version is 0.
+
+The returned graph has a default \bt_intr. Any \bt_comp you add with the
+<code>bt_graph_add_*_component*()</code> functions and all their
+\bt_p_msg_iter also have this same default interrupter. Borrow the graph's
+default interrupter with bt_graph_borrow_default_interrupter().
+
+@param[in] mip_version
+    Version of the Message Interchange Protocol to use within the
+    graph to create.
+
+@returns
+    New trace processing graph reference, or \c NULL on memory error.
+
+@pre
+    \bt_p{mip_version} is 0.
+*/
 extern bt_graph *bt_graph_create(uint64_t mip_version);
 
+/*! @} */
+
+/*!
+@name Component adding
+@{
+*/
+
+/*!
+@brief
+    Status codes for the
+    <code>bt_graph_add_*_component*()</code> functions.
+*/
 typedef enum bt_graph_add_component_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_GRAPH_ADD_COMPONENT_STATUS_OK                = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_ADD_COMPONENT_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GRAPH_ADD_COMPONENT_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
 } bt_graph_add_component_status;
 
+/*!
+@brief
+    Alias of bt_graph_add_source_component_with_initialize_method_data()
+    with the \bt_p{initialize_method_data} parameter set to \c NULL.
+*/
 extern bt_graph_add_component_status
 bt_graph_add_source_component(bt_graph *graph,
                const bt_component_class_source *component_class,
                const char *name, const bt_value *params,
-               bt_logging_level log_level, const bt_component_source **component);
+               bt_logging_level logging_level,
+               const bt_component_source **component);
+
+/*!
+@brief
+    Creates a \bt_src_comp from the
+    \ref api-tir-comp-cls "class" \bt_p{component_class}
+    with the initialization parameters \bt_p{params}, the initialization
+    user data \bt_p{initialize_method_data}, and the initial
+    logging level \bt_p{logging_level}, adds it to the trace processing
+    graph \bt_p{graph} with the name \bt_p{name}, and sets
+    \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add "Add components" to learn more about adding
+components to a trace processing graph.
+
+This function calls the source component's
+\ref api-comp-cls-dev-meth-init "initialization method" after
+creating it.
+
+The created source component's initialization method receives:
+
+- \bt_p{params} as its own \bt_p{params} parameter (or an empty
+  \bt_map_val if \bt_p{params} is \c NULL).
+
+- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
+  parameter.
+
+The created source component can get its logging level
+(\bt_p{logging_level}) with bt_component_get_logging_level().
+
+@param[in] graph
+    Trace processing graph to which to add the created source component.
+@param[in] component_class
+    Class to instantiate within \bt_p{graph}.
+@param[in] name
+    Unique name, within \bt_p{graph}, of the component to create.
+@param[in] params
+    @parblock
+    Initialization parameters to use when creating the source component.
+
+    Can be \c NULL, in which case the created source component's
+    initialization method receives an empty \bt_map_val as its
+    \bt_p{params} parameter.
+    @endparblock
+@param[in] initialize_method_data
+    User data passed as is to the created source component's
+    initialization method.
+@param[in] logging_level
+    Initial logging level of the source component to create.
+@param[out] component
+    <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+    a \em borrowed reference of the created source component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+    Other error, for example, the created source component's
+    initialization method failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{name}
+@pre
+    No other component within \bt_p{graph} has the name \bt_p{name}.
+@pre
+    \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
+    or is \c NULL.
 
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
 extern bt_graph_add_component_status
 bt_graph_add_source_component_with_initialize_method_data(
                bt_graph *graph,
                const bt_component_class_source *component_class,
                const char *name, const bt_value *params,
-               void *init_method_data, bt_logging_level log_level,
+               void *initialize_method_data, bt_logging_level logging_level,
                const bt_component_source **component);
 
+/*!
+@brief
+    Alias of bt_graph_add_filter_component_with_initialize_method_data()
+    with the \bt_p{initialize_method_data} parameter set to \c NULL.
+*/
 extern bt_graph_add_component_status
 bt_graph_add_filter_component(bt_graph *graph,
                const bt_component_class_filter *component_class,
                const char *name, const bt_value *params,
-               bt_logging_level log_level,
+               bt_logging_level logging_level,
                const bt_component_filter **component);
 
+/*!
+@brief
+    Creates a \bt_flt_comp from the
+    \ref api-tir-comp-cls "class" \bt_p{component_class}
+    with the initialization parameters \bt_p{params}, the initialization
+    user data \bt_p{initialize_method_data}, and the initial
+    logging level \bt_p{logging_level}, adds it to the trace processing
+    graph \bt_p{graph} with the name \bt_p{name}, and sets
+    \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add "Add components" to learn more about adding
+components to a trace processing graph.
+
+This function calls the filter component's
+\ref api-comp-cls-dev-meth-init "initialization method" after
+creating it.
+
+The created filter component's initialization method receives:
+
+- \bt_p{params} as its own \bt_p{params} parameter (or an empty
+  \bt_map_val if \bt_p{params} is \c NULL).
+
+- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
+  parameter.
+
+The created filter component can get its logging level
+(\bt_p{logging_level}) with bt_component_get_logging_level().
+
+@param[in] graph
+    Trace processing graph to which to add the created filter component.
+@param[in] component_class
+    Class to instantiate within \bt_p{graph}.
+@param[in] name
+    Unique name, within \bt_p{graph}, of the component to create.
+@param[in] params
+    @parblock
+    Initialization parameters to use when creating the filter component.
+
+    Can be \c NULL, in which case the created filter component's
+    initialization method receives an empty \bt_map_val as its
+    \bt_p{params} parameter.
+    @endparblock
+@param[in] initialize_method_data
+    User data passed as is to the created filter component's
+    initialization method.
+@param[in] logging_level
+    Initial logging level of the filter component to create.
+@param[out] component
+    <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+    a \em borrowed reference of the created filter component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+    Other error, for example, the created filter component's
+    initialization method failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{name}
+@pre
+    No other component within \bt_p{graph} has the name \bt_p{name}.
+@pre
+    \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
+    or is \c NULL.
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
 extern bt_graph_add_component_status
 bt_graph_add_filter_component_with_initialize_method_data(
                bt_graph *graph,
                const bt_component_class_filter *component_class,
                const char *name, const bt_value *params,
-               void *init_method_data, bt_logging_level log_level,
+               void *initialize_method_data, bt_logging_level logging_level,
                const bt_component_filter **component);
 
+/*!
+@brief
+    Alias of bt_graph_add_sink_component_with_initialize_method_data()
+    with the \bt_p{initialize_method_data} parameter set to \c NULL.
+*/
 extern bt_graph_add_component_status
 bt_graph_add_sink_component(
                bt_graph *graph, const bt_component_class_sink *component_class,
                const char *name, const bt_value *params,
-               bt_logging_level log_level,
+               bt_logging_level logging_level,
                const bt_component_sink **component);
 
+/*!
+@brief
+    Creates a \bt_sink_comp from the
+    \ref api-tir-comp-cls "class" \bt_p{component_class}
+    with the initialization parameters \bt_p{params}, the initialization
+    user data \bt_p{initialize_method_data}, and the initial
+    logging level \bt_p{logging_level}, adds it to the trace processing
+    graph \bt_p{graph} with the name \bt_p{name}, and sets
+    \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add "Add components" to learn more about adding
+components to a trace processing graph.
+
+This function calls the sink component's
+\ref api-comp-cls-dev-meth-init "initialization method" after
+creating it.
+
+The created sink component's initialization method receives:
+
+- \bt_p{params} as its own \bt_p{params} parameter (or an empty
+  \bt_map_val if \bt_p{params} is \c NULL).
+
+- \bt_p{initialize_method_data} as its own \bt_p{initialize_method_data}
+  parameter.
+
+The created sink component can get its logging level
+(\bt_p{logging_level}) with bt_component_get_logging_level().
+
+@param[in] graph
+    Trace processing graph to which to add the created sink component.
+@param[in] component_class
+    Class to instantiate within \bt_p{graph}.
+@param[in] name
+    Unique name, within \bt_p{graph}, of the component to create.
+@param[in] params
+    @parblock
+    Initialization parameters to use when creating the sink component.
+
+    Can be \c NULL, in which case the created sink component's
+    initialization method receives an empty \bt_map_val as its
+    \bt_p{params} parameter.
+    @endparblock
+@param[in] initialize_method_data
+    User data passed as is to the created sink component's
+    initialization method.
+@param[in] logging_level
+    Initial logging level of the sink component to create.
+@param[out] component
+    <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+    a \em borrowed reference of the created sink component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+    Other error, for example, the created sink component's
+    initialization method failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{name}
+@pre
+    No other component within \bt_p{graph} has the name \bt_p{name}.
+@pre
+    \bt_p{params} is a \bt_map_val (bt_value_is_map() returns #BT_TRUE)
+    or is \c NULL.
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
 extern bt_graph_add_component_status
 bt_graph_add_sink_component_with_initialize_method_data(
                bt_graph *graph, const bt_component_class_sink *component_class,
                const char *name, const bt_value *params,
-               void *init_method_data, bt_logging_level log_level,
+               void *initialize_method_data, bt_logging_level logging_level,
                const bt_component_sink **component);
 
+/*! @} */
+
+/*!
+@name Simple sink component adding
+@{
+*/
+
+/*!
+@brief
+    Status codes for the #bt_graph_simple_sink_component_initialize_func
+    type.
+*/
+typedef enum bt_graph_simple_sink_component_initialize_func_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+} bt_graph_simple_sink_component_initialize_func_status;
+
+/*!
+@brief
+    User initialization function for
+    bt_graph_add_simple_sink_component().
+
+Such an initialization function is called when the trace processing
+graph becomes configured and when the simple sink component has created
+its single \bt_msg_iter. This occurs the first time you call
+bt_graph_run() or bt_graph_run_once() on the trace processing graph.
+
+See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
+about adding a simple component to a trace processing graph.
+
+@param[in] message_iterator
+    @parblock
+    Simple sink component's upstream message iterator.
+
+    This user function is free to get the message iterator's next
+    message or to make it seek.
+    @endparblock
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_graph_add_simple_sink_component().
+
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_OK
+    Success.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_INITIALIZE_FUNC_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{message_iterator}
+
+@post
+    The reference count of \bt_p{message_iterator} is not changed.
+
+@sa bt_graph_add_simple_sink_component() &mdash;
+    Creates and adds a simple sink component to a trace processing
+    graph.
+*/
+typedef bt_graph_simple_sink_component_initialize_func_status
+(*bt_graph_simple_sink_component_initialize_func)(
+               bt_message_iterator *message_iterator,
+               void *user_data);
+
+/*!
+@brief
+    Status codes for the #bt_graph_simple_sink_component_consume_func
+    type.
+*/
+typedef enum bt_graph_simple_sink_component_consume_func_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK                   = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           End of processing.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END                  = __BT_FUNC_STATUS_END,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN                = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR         = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR                = __BT_FUNC_STATUS_ERROR,
+} bt_graph_simple_sink_component_consume_func_status;
+
+/*!
+@brief
+    User consuming function for bt_graph_add_simple_sink_component().
+
+Such a consuming function is called when the simple sink component's own
+\ref api-comp-cls-dev-meth-consume "consuming method" is called. This
+occurs in a loop within bt_graph_run() or when it's this sink
+component's turn to consume in
+bt_graph_run_once().
+
+See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
+about adding a simple component to a trace processing graph.
+
+If you are not done consuming messages, return
+#BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK.
+
+If you are done consuming messages, return
+#BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END.
+
+If you wish to avoid a blocking operation and make
+bt_graph_run() or bt_graph_run_once() aware, return
+#BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN.
+
+@param[in] message_iterator
+    @parblock
+    Simple sink component's upstream message iterator.
+
+    This user function is free to get the message iterator's next
+    message or to make it seek.
+    @endparblock
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_graph_add_simple_sink_component().
+
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_OK
+    Success.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_END
+    End of processing.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_AGAIN
+    Try again.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_SIMPLE_SINK_COMPONENT_CONSUME_FUNC_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{message_iterator}
+
+@post
+    The reference count of \bt_p{message_iterator} is not changed.
+
+@sa bt_graph_add_simple_sink_component() &mdash;
+    Creates and adds a simple sink component to a trace processing
+    graph.
+*/
+typedef bt_graph_simple_sink_component_consume_func_status
+(*bt_graph_simple_sink_component_consume_func)(
+               bt_message_iterator *message_iterator,
+               void *user_data);
+
+/*!
+@brief
+    User finalization function for bt_graph_add_simple_sink_component().
+
+Such a finalization function is called when the simple sink component
+is finalized. This occurs when the trace processing graph is destroyed
+(you put its last strong \ref api-fund-shared-object "reference"
+with bt_graph_put_ref()).
+
+See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
+about adding a simple component to a trace processing graph.
+
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_graph_add_simple_sink_component().
+
+@bt_post_no_error
+
+@sa bt_graph_add_simple_sink_component() &mdash;
+    Creates and adds a simple sink component to a trace processing
+    graph.
+*/
+typedef void (*bt_graph_simple_sink_component_finalize_func)(void *user_data);
+
+/*!
+@brief
+    Creates a simple \bt_sink_comp, adds it to the trace processing
+    graph \bt_p{graph} with the name \bt_p{name}, and sets
+    \bt_p{*component} to the resulting component.
+
+See \ref api-graph-lc-add-ss "Add a simple sink component" to learn more
+about adding a simple component to a trace processing graph.
+
+\bt_p{initialize_func} (if not \c NULL), \bt_p{consume_func},
+and \bt_p{finalize_func} (if not \c NULL) receive \bt_p{user_data}
+as their own \bt_p{user_data} parameter.
+
+@param[in] graph
+    Trace processing graph to which to add the created simple sink
+    component.
+@param[in] name
+    Unique name, within \bt_p{graph}, of the component to create.
+@param[in] initialize_func
+    @parblock
+    User initialization function.
+
+    Can be \c NULL.
+    @endparblock
+@param[in] consume_func
+    User consuming function.
+@param[in] finalize_func
+    @parblock
+    User finalization function.
+
+    Can be \c NULL.
+    @endparblock
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of
+    \bt_p{initialize_func}, \bt_p{consume_func}, and
+    \bt_p{finalize_func}.
+@param[out] component
+    <strong>On success, if not \c NULL</strong>, \bt_p{*component} is
+    a \em borrowed reference of the created simple sink component.
+
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_ADD_COMPONENT_STATUS_ERROR
+    Other error, for example, the created sink component's
+    \ref api-comp-cls-dev-meth-init "initialization method" failed.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{name}
+@pre
+    No other component within \bt_p{graph} has the name \bt_p{name}.
+@bt_pre_not_null{consume_func}
+*/
 extern bt_graph_add_component_status
 bt_graph_add_simple_sink_component(bt_graph *graph, const char *name,
-               bt_graph_simple_sink_component_initialize_func init_func,
+               bt_graph_simple_sink_component_initialize_func initialize_func,
                bt_graph_simple_sink_component_consume_func consume_func,
                bt_graph_simple_sink_component_finalize_func finalize_func,
                void *user_data, const bt_component_sink **component);
 
+/*! @} */
+
+/*!
+@name Component port connection
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_graph_connect_ports().
+*/
 typedef enum bt_graph_connect_ports_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_GRAPH_CONNECT_PORTS_STATUS_OK                = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_CONNECT_PORTS_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GRAPH_CONNECT_PORTS_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
 } bt_graph_connect_ports_status;
 
+/*!
+@brief
+    Connects the \bt_oport \bt_p{upstream_port} to the \bt_iport
+    \bt_p{downstream_port} within the trace processing graph
+    \bt_p{graph}, and sets \bt_p{*connection} to the resulting
+    \bt_conn.
+
+See \ref api-graph-lc-connect "Connect component ports" to learn more
+about connecting ports within a trace processing graph.
+
+Both \bt_p{upstream_port} and \bt_p{downstream_port} must be
+unconnected (bt_port_is_connected() returns #BT_FALSE) when you call
+this function.
+
+@param[in] graph
+    Trace processing graph containing the \bt_p_comp to which belong
+    \bt_p{upstream_port} and \bt_p{downstream_port}.
+@param[in] upstream_port
+    \bt_c_oport to connect to \bt_p{downstream_port}.
+@param[in] downstream_port
+    \bt_c_iport to connect to \bt_p{upstream_port}.
+@param[in] connection
+    <strong>On success, if not \c NULL</strong>, \bt_p{*connection} is
+    a \em borrowed reference of the resulting \bt_conn.
+
+@retval #BT_GRAPH_CONNECT_PORTS_STATUS_OK
+    Success.
+@retval #BT_GRAPH_CONNECT_PORTS_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_CONNECT_PORTS_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_configured{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{upstream_port}
+@pre
+    \bt_p{graph} contains the component of \bt_p{upstream_port},
+    as returned by bt_port_borrow_component_const().
+@pre
+    \bt_p{upstream_port} is unconnected
+    (bt_port_is_connected() returns #BT_FALSE).
+@bt_pre_not_null{downstream_port}
+@pre
+    \bt_p{graph} contains the component of \bt_p{downstream_port},
+    as returned by bt_port_borrow_component_const().
+@pre
+    \bt_p{downstream_port} is unconnected
+    (bt_port_is_connected() returns #BT_FALSE).
+@pre
+    Connecting \bt_p{upstream_port} to \bt_p{downstream_port} does not
+    form a connection cycle within \bt_p{graph}.
+*/
 extern bt_graph_connect_ports_status bt_graph_connect_ports(bt_graph *graph,
-               const bt_port_output *upstream,
-               const bt_port_input *downstream,
+               const bt_port_output *upstream_port,
+               const bt_port_input *downstream_port,
                const bt_connection **connection);
 
+/*! @} */
+
+/*!
+@name Running
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_graph_run().
+*/
 typedef enum bt_graph_run_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_GRAPH_RUN_STATUS_OK                  = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_RUN_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
-       BT_GRAPH_RUN_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Try again.
+       */
        BT_GRAPH_RUN_STATUS_AGAIN               = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_GRAPH_RUN_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GRAPH_RUN_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
 } bt_graph_run_status;
 
+/*!
+@brief
+    Runs the trace processing graph \bt_p{graph}, calling each
+    \bt_sink_comp's
+    \ref api-comp-cls-dev-meth-consume "consuming method" in a round
+    robin fashion until they are all done consuming or an exception
+    occurs.
+
+See \ref api-graph-lc-run "Run" to learn more about running a trace
+processing graph.
+
+This function does \em not return until one of:
+
+- All the sink components are ended, in which case this function
+  returns #BT_GRAPH_RUN_STATUS_OK.
+
+- One of the sink component returns an error, in which case this
+  function returns #BT_GRAPH_RUN_STATUS_ERROR or
+  #BT_GRAPH_RUN_STATUS_MEMORY_ERROR.
+
+- One of the sink component returns "try again", in which case
+  this function returns #BT_GRAPH_RUN_STATUS_AGAIN.
+
+  In that case, you can call this function again later, usually after
+  waiting for some time.
+
+  This feature exists to allow blocking operations within components
+  to be postponed until they don't block. The graph user can perform
+  other tasks instead of the graph's thread blocking.
+
+- \bt_p{graph} is interrupted (see bt_graph_borrow_default_interrupter()
+  and bt_graph_add_interrupter()), in which case this function returns
+  #BT_GRAPH_RUN_STATUS_AGAIN.
+
+  Check the \bt_intr's state with bt_interrupter_is_set() to
+  distinguish between a sink component returning "try again" and
+  \bt_p{graph} getting interrupted.
+
+To make a single sink component consume, then get the thread's control
+back, use bt_graph_run_once().
+
+When you call this function or bt_graph_run_once() for the first time,
+\bt_p{graph} becomes <em>configured</em>. See
+\ref api-graph-lc "Trace processing graph life cycle"
+to learn what happens when a trace processing graph becomes configured,
+and what you can and cannot do with a configured graph.
+
+@param[in] graph
+    Trace processing graph to run.
+
+@retval #BT_GRAPH_RUN_STATUS_OK
+    Success.
+@retval #BT_GRAPH_RUN_STATUS_AGAIN
+    Try again.
+@retval #BT_GRAPH_RUN_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_RUN_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@pre
+    For each \bt_src_comp within \bt_p{graph}, at least one \bt_oport
+    is connected.
+@pre
+    For each \bt_flt_comp within \bt_p{graph}, at least one \bt_iport
+    and one \bt_iport are connected.
+@pre
+    For each \bt_sink_comp within \bt_p{graph}, at least one \bt_iport
+    is connected.
+@pre
+    \bt_p{graph} contains at least one sink component.
+
+@sa bt_graph_run_once() &mdash;
+    Calls a single trace processing graph's sink component's consuming
+    method once.
+*/
 extern bt_graph_run_status bt_graph_run(bt_graph *graph);
 
+/*!
+@brief
+    Status codes for bt_graph_run().
+*/
 typedef enum bt_graph_run_once_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_GRAPH_RUN_ONCE_STATUS_OK             = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_RUN_ONCE_STATUS_ERROR          = __BT_FUNC_STATUS_ERROR,
-       BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_GRAPH_RUN_ONCE_STATUS_AGAIN          = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           All sink components are finished processing.
+       */
        BT_GRAPH_RUN_ONCE_STATUS_END            = __BT_FUNC_STATUS_END,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_GRAPH_RUN_ONCE_STATUS_AGAIN          = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GRAPH_RUN_ONCE_STATUS_ERROR          = __BT_FUNC_STATUS_ERROR,
 } bt_graph_run_once_status;
 
+/*!
+@brief
+    Calls the \ref api-comp-cls-dev-meth-consume "consuming method" of
+    the next non-ended \bt_sink_comp to make consume within the trace
+    processing graph \bt_p{graph}.
+
+See \ref api-graph-lc-run "Run" to learn more about running a trace
+processing graph.
+
+This function makes the \em next non-ended sink component consume. For
+example, if \bt_p{graph} has two non-ended sink components A and B:
+
+- Calling bt_graph_run_once() makes sink component A consume.
+- Calling bt_graph_run_once() again makes sink component B consume.
+- Calling bt_graph_run_once() again makes sink component A consume.
+- ...
+
+Considering this, if \bt_p{graph} contains a single non-ended sink
+component, this function \em always makes this sink component consume.
+
+If the sink component's consuming method:
+
+<dl>
+  <dt>Succeeds</dt>
+  <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.</dd>
+
+  <dt>Returns "try again"</dt>
+  <dd>This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.</dd>
+
+  <dt>Fails</dt>
+  <dd>
+    This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
+    or #BT_GRAPH_RUN_ONCE_STATUS_ERROR.
+  </dd>
+</dl>
+
+When all the sink components of \bt_p{graph} are finished processing
+(ended), this function returns #BT_GRAPH_RUN_ONCE_STATUS_END.
+
+bt_graph_run() calls this function in a loop until are the sink
+components are ended or an exception occurs.
+
+When you call this function or bt_graph_run() for the first time,
+\bt_p{graph} becomes <em>configured</em>. See
+\ref api-graph-lc "Trace processing graph life cycle"
+to learn what happens when a trace processing graph becomes configured,
+and what you can and cannot do with a configured graph.
+
+@param[in] graph
+    Trace processing graph of which to make the next sink component
+    consume.
+
+@retval #BT_GRAPH_RUN_ONCE_STATUS_OK
+    Success.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_END
+    All sink components are finished processing.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_AGAIN
+    Try again.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_RUN_ONCE_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+
+@sa bt_graph_run() &mdash;
+    Runs a trace processing graph, making all its sink components
+    consume in a round robin fashion.
+*/
 extern bt_graph_run_once_status bt_graph_run_once(bt_graph *graph);
 
+/*! @} */
+
+/*!
+@name Interruption
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_graph_add_interrupter().
+*/
+typedef enum bt_graph_add_interrupter_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_GRAPH_ADD_INTERRUPTER_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_graph_add_interrupter_status;
+
+/*!
+@brief
+    Adds the \bt_intr \bt_p{interrupter} to all the current and future
+    \bt_p_sink_comp and \bt_p_msg_iter of the trace processing graph
+    \bt_p{graph}, as well as to the graph itself.
+
+Sink components can check whether or not they are interrupted
+with bt_self_component_sink_is_interrupted().
+
+Message iterators can check whether or not they are interrupted
+with bt_self_message_iterator_is_interrupted().
+
+The bt_graph_run() loop intermittently checks whether or not any of the
+graph's interrupters is set. If so, bt_graph_run() returns
+#BT_GRAPH_RUN_STATUS_AGAIN.
+
+@note
+    @parblock
+    bt_graph_create() returns a trace processing graph which comes
+    with its own <em>default interrupter</em>.
+
+    Instead of adding your own interrupter to \bt_p{graph}, you can
+    set its default interrupter with
+
+    @code
+    bt_interrupter_set(bt_graph_borrow_default_interrupter());
+    @endcode
+    @endparblock
+
+@param[in] graph
+    Trace processing graph to which to add \bt_p{interrupter}.
+@param[in] interrupter
+    Interrupter to add to \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{interrupter}
+
+@sa bt_graph_borrow_default_interrupter() &mdash;
+    Borrows the default interrupter from a trace processing graph.
+*/
+extern bt_graph_add_interrupter_status bt_graph_add_interrupter(bt_graph *graph,
+               const bt_interrupter *interrupter);
+
+/*!
+@brief
+    Borrows the default \bt_intr from the trace processing graph
+    \bt_p{graph}.
+
+@param[in] graph
+    Trace processing graph from which to borrow the default interrupter.
+
+@returns
+    @parblock
+    \em Borrowed reference of the default interrupter of \bt_p{graph}.
+
+    The returned pointer remains valid as long as \bt_p{graph} exists.
+    @endparblock
+
+@bt_pre_not_null{graph}
+
+@sa bt_graph_add_interrupter() &mdash;
+    Adds an interrupter to a trace processing graph.
+*/
+extern bt_interrupter *bt_graph_borrow_default_interrupter(bt_graph *graph);
+
+/*! @} */
+
+/*!
+@name Listeners
+@{
+*/
+
+/*!
+@brief
+    Status codes for the
+    <code>bt_graph_add_*_component_*_port_added_listener()</code>
+    functions.
+*/
 typedef enum bt_graph_add_listener_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_GRAPH_ADD_LISTENER_STATUS_OK                 = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_graph_add_listener_status;
 
+/*!
+@brief
+    Status codes for the
+    <code>bt_graph_*_component_*_port_added_listener_func()</code>
+    types.
+*/
+typedef enum bt_graph_listener_func_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_GRAPH_LISTENER_FUNC_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GRAPH_LISTENER_FUNC_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+} bt_graph_listener_func_status;
+
+/*!
+@brief
+    User function for
+    bt_graph_add_filter_component_input_port_added_listener().
+
+Such a function is called whenever a \bt_flt_comp within a trace
+processing graph adds an \bt_iport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+    Filter component which added \bt_p{port}.
+@param[in] port
+    Input port added by \bt_p{component}.
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_graph_add_filter_component_input_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+    Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_filter_component_input_port_added_listener() &mdash;
+    Adds a "filter component input port added" listener to a trace
+    processing graph.
+*/
+typedef bt_graph_listener_func_status
+(*bt_graph_filter_component_input_port_added_listener_func)(
+               const bt_component_filter *component,
+               const bt_port_input *port, void *user_data);
+
+/*!
+@brief
+    Adds a \"\bt_flt_comp \bt_iport added\" listener to the trace
+    processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+filter component adds an input port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] graph
+    Trace processing graph to add the "filter component input port
+    added" listener to.
+@param[in] user_func
+    User function of the "filter component input port added" listener to
+    add to \bt_p{graph}.
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of
+    \bt_p{user_func}.
+@param[out] listener_id
+    <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+    is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
 extern bt_graph_add_listener_status
 bt_graph_add_filter_component_input_port_added_listener(
                bt_graph *graph,
-               bt_graph_filter_component_input_port_added_listener_func listener,
-               void *data, bt_listener_id *listener_id);
+               bt_graph_filter_component_input_port_added_listener_func user_func,
+               void *user_data, bt_listener_id *listener_id);
+
+/*!
+@brief
+    User function for
+    bt_graph_add_sink_component_input_port_added_listener().
+
+Such a function is called whenever a \bt_sink_comp within a trace
+processing graph adds an \bt_iport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+    Filter component which added \bt_p{port}.
+@param[in] port
+    Input port added by \bt_p{component}.
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_graph_add_sink_component_input_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+    Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_sink_component_input_port_added_listener() &mdash;
+    Adds a "sink component input port added" listener to a trace
+    processing graph.
+*/
+typedef bt_graph_listener_func_status
+(*bt_graph_sink_component_input_port_added_listener_func)(
+               const bt_component_sink *component,
+               const bt_port_input *port, void *user_data);
+
+/*!
+@brief
+    Adds a \"\bt_sink_comp \bt_iport added\" listener to the trace
+    processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+sink component adds an input port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] graph
+    Trace processing graph to add the "sink component input port
+    added" listener to.
+@param[in] user_func
+    User function of the "sink component input port added" listener to
+    add to \bt_p{graph}.
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of
+    \bt_p{user_func}.
+@param[out] listener_id
+    <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+    is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
 
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
 extern bt_graph_add_listener_status
 bt_graph_add_sink_component_input_port_added_listener(
                bt_graph *graph,
-               bt_graph_sink_component_input_port_added_listener_func listener,
-               void *data, bt_listener_id *listener_id);
+               bt_graph_sink_component_input_port_added_listener_func user_func,
+               void *user_data, bt_listener_id *listener_id);
 
+/*!
+@brief
+    User function for
+    bt_graph_add_source_component_output_port_added_listener().
+
+Such a function is called whenever a \bt_src_comp within a trace
+processing graph adds an \bt_oport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+    Filter component which added \bt_p{port}.
+@param[in] port
+    Input port added by \bt_p{component}.
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_graph_add_source_component_output_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+    Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_source_component_output_port_added_listener() &mdash;
+    Adds a "source component output port added" listener to a trace
+    processing graph.
+*/
+typedef bt_graph_listener_func_status
+(*bt_graph_source_component_output_port_added_listener_func)(
+               const bt_component_source *component,
+               const bt_port_output *port, void *user_data);
+
+/*!
+@brief
+    Adds a \"\bt_src_comp \bt_oport added\" listener to the trace
+    processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+source component adds an output port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] graph
+    Trace processing graph to add the "source component output port
+    added" listener to.
+@param[in] user_func
+    User function of the "source component output port added" listener
+    to add to \bt_p{graph}.
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of
+    \bt_p{user_func}.
+@param[out] listener_id
+    <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+    is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
 extern bt_graph_add_listener_status
 bt_graph_add_source_component_output_port_added_listener(
                bt_graph *graph,
-               bt_graph_source_component_output_port_added_listener_func listener,
-               void *data, bt_listener_id *listener_id);
+               bt_graph_source_component_output_port_added_listener_func user_func,
+               void *user_data, bt_listener_id *listener_id);
+
+/*!
+@brief
+    User function for
+    bt_graph_add_filter_component_output_port_added_listener().
+
+Such a function is called whenever a \bt_flt_comp within a trace
+processing graph adds an \bt_oport during the graph
+\ref api-graph-lc "configuration" phase.
+
+See \ref api-graph-listeners "Listeners" to learn more.
+
+@param[in] component
+    Filter component which added \bt_p{port}.
+@param[in] port
+    Input port added by \bt_p{component}.
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_graph_add_filter_component_output_port_added_listener().
+
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_OK
+    Success.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GRAPH_LISTENER_FUNC_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{component}
+@bt_pre_not_null{port}
+
+@sa bt_graph_add_filter_component_output_port_added_listener() &mdash;
+    Adds a "filter component output port added" listener to a trace
+    processing graph.
+*/
+typedef bt_graph_listener_func_status
+(*bt_graph_filter_component_output_port_added_listener_func)(
+               const bt_component_filter *component,
+               const bt_port_output *port, void *user_data);
+
+/*!
+@brief
+    Adds a \"\bt_flt_comp \bt_oport added\" listener to the trace
+    processing graph \bt_p{graph}.
+
+Once this function returns, \bt_p{user_func} is called whenever a
+filter component adds an output port within \bt_p{graph}.
+
+See \ref api-graph-listeners "Listeners" to learn more.
 
+@param[in] graph
+    Trace processing graph to add the "filter component output port
+    added" listener to.
+@param[in] user_func
+    User function of the "filter component output port added" listener
+    to add to \bt_p{graph}.
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of
+    \bt_p{user_func}.
+@param[out] listener_id
+    <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+    is the ID of the added listener within \bt_p{graph}.
+
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_OK
+    Success.
+@retval #BT_GRAPH_ADD_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{graph}
+@bt_pre_graph_not_faulty{graph}
+@bt_pre_not_null{user_func}
+*/
 extern bt_graph_add_listener_status
 bt_graph_add_filter_component_output_port_added_listener(
                bt_graph *graph,
-               bt_graph_filter_component_output_port_added_listener_func listener,
-               void *data, bt_listener_id *listener_id);
+               bt_graph_filter_component_output_port_added_listener_func user_func,
+               void *user_data, bt_listener_id *listener_id);
 
-typedef enum bt_graph_add_interrupter_status {
-       BT_GRAPH_ADD_INTERRUPTER_STATUS_OK              = __BT_FUNC_STATUS_OK,
-       BT_GRAPH_ADD_INTERRUPTER_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_graph_add_interrupter_status;
+/*! @} */
 
-extern bt_graph_add_interrupter_status bt_graph_add_interrupter(bt_graph *graph,
-               const bt_interrupter *interrupter);
+/*!
+@name Reference count
+@{
+*/
 
-extern bt_interrupter *bt_graph_borrow_default_interrupter(bt_graph *graph);
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the trace processing graph \bt_p{graph}.
+
+@param[in] graph
+    @parblock
+    Trace processing graph of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_graph_put_ref() &mdash;
+    Decrements the reference count of a trace processing graph.
+*/
+extern void bt_graph_get_ref(const bt_graph *graph);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the trace processing graph \bt_p{graph}.
+
+@param[in] graph
+    @parblock
+    Trace processing graph of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_graph_get_ref() &mdash;
+    Increments the reference count of a trace processing graph.
+*/
+extern void bt_graph_put_ref(const bt_graph *graph);
+
+/*!
+@brief
+    Decrements the reference count of the trace processing graph
+    \bt_p{_graph}, and then sets \bt_p{_graph} to \c NULL.
+
+@param _graph
+    @parblock
+    Trace processing graph of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_graph}
+*/
+#define BT_GRAPH_PUT_REF_AND_RESET(_graph)     \
+       do {                                    \
+               bt_graph_put_ref(_graph);       \
+               (_graph) = NULL;                \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the trace processing graph
+    \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
+    \bt_p{_src} to \c NULL.
+
+This macro effectively moves a trace processing graph reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_GRAPH_MOVE_REF(_dst, _src)          \
+       do {                                    \
+               bt_graph_put_ref(_dst);         \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/graph/interrupter-const.h b/include/babeltrace2/graph/interrupter-const.h
deleted file mode 100644 (file)
index 8a85dcc..0000000
--- a/include/babeltrace2/graph/interrupter-const.h
+++ /dev/null
@@ -1,59 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_INTERRUPTER_CONST_H
-#define BABELTRACE2_GRAPH_INTERRUPTER_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern bt_bool bt_interrupter_is_set(const bt_interrupter *interrupter);
-
-extern void bt_interrupter_get_ref(const bt_interrupter *interrupter);
-
-extern void bt_interrupter_put_ref(const bt_interrupter *interrupter);
-
-#define BT_INTERRUPTER_PUT_REF_AND_RESET(_var)         \
-       do {                                            \
-               bt_interrupter_put_ref(_var);           \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_INTERRUPTER_MOVE_REF(_var_dst, _var_src)    \
-       do {                                            \
-               bt_interrupter_put_ref(_var_dst);       \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_INTERRUPTER_CONST_H */

diff --git a/include/babeltrace2/graph/interrupter.h b/include/babeltrace2/graph/interrupter.h
index 953775329165435d50f37718340c2d4642d8e9a6..56c022e2ce2a7772e7222e4c83afeb7fa9f7ee7b 100644 (file)
--- a/include/babeltrace2/graph/interrupter.h
+++ b/include/babeltrace2/graph/interrupter.h
@@ -33,12 +33,258 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-intr Interrupter
+@ingroup api-graph
+
+@brief
+    Interrupter.
+
+An <strong><em>interrupter</em></strong> is a simple object which has
+a single boolean state: set or not set.
+
+You can use an interrupter to interrupt a running trace processing
+\bt_graph or \ref api-qexec "query". The user and library functions periodically
+check if they are interrupted (with
+bt_self_component_sink_is_interrupted(),
+bt_self_message_iterator_is_interrupted(), or
+bt_query_executor_is_interrupted()); meanwhile, another thread or
+a signal handler sets the shared interrupter with bt_interrupter_set().
+
+To interrupt a running trace processing graph or query:
+
+-# Create an interrupter with bt_interrupter_create().
+
+-# Before running a trace processing graph with bt_graph_run() or
+   performing a query with bt_query_executor_query(), add
+   the created interrupter to the object with bt_graph_add_interrupter()
+   or bt_query_executor_add_interrupter().
+
+   Alternatively, you can borrow the existing, default interrupter from
+   those objects with bt_graph_borrow_default_interrupter() and
+   bt_query_executor_borrow_default_interrupter().
+
+-# Run the graph with bt_graph_run() or perform the query with
+   bt_query_executor_query().
+
+-# From a signal handler or another thread, call bt_interrupter_set() to
+   set the shared interrupter.
+
+Eventually, the trace processing graph or query thread checks if it's
+interrupted and stops processing, usually returning a status code which
+ends with \c _AGAIN.
+
+You can add more than one interrupter to a trace processing graph and
+to a query executor. The bt_self_component_sink_is_interrupted(),
+bt_self_message_iterator_is_interrupted(), and
+bt_query_executor_is_interrupted() functions return the logical
+disjunction of all the added interrupters's states, so that \em any
+interrupter can interrupt the thread.
+
+Once a trace processing graph or a query executor is interrupted and
+you get the thread's control back, you can reset the interrupter
+with bt_interrupter_reset() and continue the previous operation,
+calling bt_graph_run() or bt_query_executor_query() again.
+
+An interrupter is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_interrupter_get_ref() and put an existing
+reference with bt_interrupter_put_ref().
+
+The type of an interrupter is #bt_interrupter.
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_interrupter bt_interrupter;
+
+@brief
+    Interrupter.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a default interrupter.
+
+On success, the returned interrupter is \em not set
+(bt_interrupter_is_set() returns #BT_FALSE).
+
+@returns
+    New interrupter reference, or \c NULL on memory error.
+*/
 extern bt_interrupter *bt_interrupter_create(void);
 
+/*! @} */
+
+/*!
+@name State
+@{
+*/
+
+/*!
+@brief
+    Sets the interrupter \bt_p{interrupter}.
+
+After you call this function, bt_interrupter_is_set() returns
+#BT_TRUE.
+
+@param[in] interrupter
+    Interrupter to set.
+
+@bt_pre_not_null{interrupter}
+
+@sa bt_interrupter_reset() &mdash;
+    Resets an interrupter.
+@sa bt_interrupter_is_set() &mdash;
+    Returns whether or not an interrupter is set.
+*/
 extern void bt_interrupter_set(bt_interrupter *interrupter);
 
+/*!
+@brief
+    Resets the interrupter \bt_p{interrupter}.
+
+After you call this function, bt_interrupter_is_set() returns
+#BT_FALSE.
+
+@param[in] interrupter
+    Interrupter to reset.
+
+@bt_pre_not_null{interrupter}
+
+@sa bt_interrupter_set() &mdash;
+    Sets an interrupter.
+@sa bt_interrupter_is_set() &mdash;
+    Returns whether or not an interrupter is set.
+*/
 extern void bt_interrupter_reset(bt_interrupter *interrupter);
 
+/*!
+@brief
+    Returns whether or not the interrupter \bt_p{interrupter} is set.
+
+@param[in] interrupter
+    Interrupter to reset.
+
+@returns
+    #BT_TRUE if \bt_p{interrupter} is set.
+
+@bt_pre_not_null{interrupter}
+
+@sa bt_interrupter_set() &mdash;
+    Sets an interrupter.
+@sa bt_interrupter_reset() &mdash;
+    Resets an interrupter.
+*/
+extern bt_bool bt_interrupter_is_set(const bt_interrupter *interrupter);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the interrupter \bt_p{interrupter}.
+
+@param[in] interrupter
+    @parblock
+    Interrupter of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_interrupter_put_ref() &mdash;
+    Decrements the reference count of an interrupter.
+*/
+extern void bt_interrupter_get_ref(const bt_interrupter *interrupter);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the interrupter \bt_p{interrupter}.
+
+@param[in] interrupter
+    @parblock
+    Interrupter of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_interrupter_get_ref() &mdash;
+    Increments the reference count of an interrupter.
+*/
+extern void bt_interrupter_put_ref(const bt_interrupter *interrupter);
+
+/*!
+@brief
+    Decrements the reference count of the interrupter
+    \bt_p{_interrupter}, and then sets \bt_p{_interrupter} to \c NULL.
+
+@param _interrupter
+    @parblock
+    Interrupter of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_interrupter}
+*/
+#define BT_INTERRUPTER_PUT_REF_AND_RESET(_interrupter) \
+       do {                                            \
+               bt_interrupter_put_ref(_interrupter);   \
+               (_interrupter) = NULL;                  \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the interrupter \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves an interrupter reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_INTERRUPTER_MOVE_REF(_dst, _src)    \
+       do {                                    \
+               bt_interrupter_put_ref(_dst);   \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/graph/message-const.h b/include/babeltrace2/graph/message-const.h
deleted file mode 100644 (file)
index 0612b3c..0000000
--- a/include/babeltrace2/graph/message-const.h
+++ /dev/null
@@ -1,79 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/**
- * Message types. Unhandled message types should be ignored.
- */
-typedef enum bt_message_type {
-       BT_MESSAGE_TYPE_EVENT                           = 1 << 0,
-       BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY     = 1 << 1,
-       BT_MESSAGE_TYPE_STREAM_BEGINNING                = 1 << 2,
-       BT_MESSAGE_TYPE_STREAM_END                      = 1 << 3,
-       BT_MESSAGE_TYPE_PACKET_BEGINNING                = 1 << 4,
-       BT_MESSAGE_TYPE_PACKET_END                      = 1 << 5,
-       BT_MESSAGE_TYPE_DISCARDED_EVENTS                = 1 << 6,
-       BT_MESSAGE_TYPE_DISCARDED_PACKETS               = 1 << 7,
-} bt_message_type;
-
-/**
- * Get a message's type.
- *
- * @param message      Message instance
- * @returns            One of #bt_message_type
- */
-extern bt_message_type bt_message_get_type(const bt_message *message);
-
-extern void bt_message_get_ref(const bt_message *message);
-
-extern void bt_message_put_ref(const bt_message *message);
-
-#define BT_MESSAGE_PUT_REF_AND_RESET(_var)             \
-       do {                                            \
-               bt_message_put_ref(_var);               \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_MESSAGE_MOVE_REF(_var_dst, _var_src)        \
-       do {                                            \
-               bt_message_put_ref(_var_dst);   \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_CONST_H */

diff --git a/include/babeltrace2/graph/message-discarded-events-const.h b/include/babeltrace2/graph/message-discarded-events-const.h
deleted file mode 100644 (file)
index 87508e2..0000000
--- a/include/babeltrace2/graph/message-discarded-events-const.h
+++ /dev/null
@@ -1,58 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_clock_snapshot *
-bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
-               const bt_message *msg);
-
-extern const bt_clock_snapshot *
-bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
-               const bt_message *msg);
-
-extern const bt_clock_class *
-bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
-               const bt_message *msg);
-
-extern const bt_stream *
-bt_message_discarded_events_borrow_stream_const(const bt_message *message);
-
-extern bt_property_availability bt_message_discarded_events_get_count(
-               const bt_message *message, uint64_t *count);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_CONST_H */

diff --git a/include/babeltrace2/graph/message-discarded-events.h b/include/babeltrace2/graph/message-discarded-events.h
deleted file mode 100644 (file)
index 0b102fa..0000000
--- a/include/babeltrace2/graph/message-discarded-events.h
+++ /dev/null
@@ -1,57 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_H
-#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern bt_message *bt_message_discarded_events_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_stream *stream);
-
-extern bt_message *bt_message_discarded_events_create_with_default_clock_snapshots(
-               bt_self_message_iterator *message_iterator,
-               const bt_stream *stream, uint64_t beginning_raw_value,
-               uint64_t end_raw_value);
-
-extern bt_stream *bt_message_discarded_events_borrow_stream(
-               bt_message *message);
-
-extern void bt_message_discarded_events_set_count(bt_message *message,
-               uint64_t count);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_H */

diff --git a/include/babeltrace2/graph/message-discarded-packets-const.h b/include/babeltrace2/graph/message-discarded-packets-const.h
deleted file mode 100644 (file)
index a528b76..0000000
--- a/include/babeltrace2/graph/message-discarded-packets-const.h
+++ /dev/null
@@ -1,58 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_clock_snapshot *
-bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
-               const bt_message *msg);
-
-extern const bt_clock_snapshot *
-bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
-               const bt_message *msg);
-
-extern const bt_clock_class *
-bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
-               const bt_message *msg);
-
-extern const bt_stream *
-bt_message_discarded_packets_borrow_stream_const(const bt_message *message);
-
-extern bt_property_availability bt_message_discarded_packets_get_count(
-               const bt_message *message, uint64_t *count);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_CONST_H */

diff --git a/include/babeltrace2/graph/message-discarded-packets.h b/include/babeltrace2/graph/message-discarded-packets.h
deleted file mode 100644 (file)
index c268d54..0000000
--- a/include/babeltrace2/graph/message-discarded-packets.h
+++ /dev/null
@@ -1,57 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_H
-#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern bt_message *bt_message_discarded_packets_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_stream *stream);
-
-extern bt_message *bt_message_discarded_packets_create_with_default_clock_snapshots(
-               bt_self_message_iterator *message_iterator,
-               const bt_stream *stream, uint64_t beginning_raw_value,
-               uint64_t end_raw_value);
-
-extern bt_stream *bt_message_discarded_packets_borrow_stream(
-               bt_message *message);
-
-extern void bt_message_discarded_packets_set_count(bt_message *message,
-               uint64_t count);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_H */

diff --git a/include/babeltrace2/graph/message-event-const.h b/include/babeltrace2/graph/message-event-const.h
deleted file mode 100644 (file)
index 3cb886c..0000000
--- a/include/babeltrace2/graph/message-event-const.h
+++ /dev/null
@@ -1,50 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_EVENT_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_EVENT_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_event *bt_message_event_borrow_event_const(
-               const bt_message *message);
-
-extern const bt_clock_snapshot *
-bt_message_event_borrow_default_clock_snapshot_const(const bt_message *msg);
-
-extern const bt_clock_class *
-bt_message_event_borrow_stream_class_default_clock_class_const(
-               const bt_message *msg);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_EVENT_CONST_H */

diff --git a/include/babeltrace2/graph/message-event.h b/include/babeltrace2/graph/message-event.h
deleted file mode 100644 (file)
index 739a684..0000000
--- a/include/babeltrace2/graph/message-event.h
+++ /dev/null
@@ -1,69 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_EVENT_H
-#define BABELTRACE2_GRAPH_MESSAGE_EVENT_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-bt_message *bt_message_event_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_event_class *event_class,
-               const bt_stream *stream);
-
-extern
-bt_message *bt_message_event_create_with_packet(
-               bt_self_message_iterator *message_iterator,
-               const bt_event_class *event_class,
-               const bt_packet *packet);
-
-extern
-bt_message *bt_message_event_create_with_default_clock_snapshot(
-               bt_self_message_iterator *message_iterator,
-               const bt_event_class *event_class,
-               const bt_stream *stream, uint64_t raw_clock_value);
-
-extern
-bt_message *bt_message_event_create_with_packet_and_default_clock_snapshot(
-               bt_self_message_iterator *message_iterator,
-               const bt_event_class *event_class,
-               const bt_packet *packet, uint64_t raw_clock_value);
-
-extern bt_event *bt_message_event_borrow_event(
-               bt_message *message);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_EVENT_H */

diff --git a/include/babeltrace2/graph/message-iterator-class.h b/include/babeltrace2/graph/message-iterator-class.h
index 3ee9c0da5ed2d161efc40446831b60859d580fe0..e668a515d4f28c6af3bf27d9f094b01c9a773b05 100644 (file)
--- a/include/babeltrace2/graph/message-iterator-class.h
+++ b/include/babeltrace2/graph/message-iterator-class.h
@@ -31,131 +31,1216 @@
 extern "C" {
 #endif
 
-typedef enum bt_message_iterator_class_set_method_status {
-       BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK  = __BT_FUNC_STATUS_OK,
-} bt_message_iterator_class_set_method_status;
 
+/*!
+@defgroup api-msg-iter-cls Message iterator class
+@ingroup api-comp-cls-dev
+
+@brief
+    \bt_c_msg_iter class.
+
+A <strong><em>message iterator class</em></strong> is the class of a
+\bt_msg_iter.
+
+@image html msg-iter-cls.png
+
+\bt_cp_src_comp_cls and \bt_p_flt_comp_cls contain a message iterator
+class. For such a component class, its message iterator class is the
+class of any message iterator created for any \bt_oport of the
+component class's instances (\bt_p_comp).
+
+Therefore, the only thing you can do with a message iterator class is to
+pass it to bt_component_class_source_create() or
+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:
+
+- Message iterator class method type definitions.
+
+- A message iterator class creation function, to which you must pass
+  the mandatory \link api-msg-iter-cls-meth-next "next" method\endlink.
+
+- Functions to set optional message iterator class methods.
+
+A message iterator class method is a user function. All message iterator
+class methods operate on an instance (a \bt_msg_iter). The type of the
+method's first parameter is #bt_self_message_iterator. This is similar
+to an instance method in Python (where the instance object name is
+generally <code>self</code>) or a member function in C++ (where the
+instance pointer is named <code>this</code>), for example.
+
+See \ref api-msg-iter-cls-methods "Methods" to learn more about the
+different types of message iterator class methods.
+
+A message iterator class is a
+\ref api-fund-shared-object "shared object": get a new reference with
+bt_message_iterator_class_get_ref() and put an existing reference with
+bt_message_iterator_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" message iterator
+classes on success. The documentation of those functions indicate this
+postcondition.
+
+The type of a message iterator class is #bt_message_iterator_class.
+
+Create a message iterator class with bt_message_iterator_class_create().
+When you call this function, you must pass the message iterator
+class's mandatory
+\link api-msg-iter-cls-meth-next "next" method\endlink.
+
+<h1>\anchor api-msg-iter-cls-methods Methods</h1>
+
+To learn when exactly the methods below are called, see
+\ref api-graph-lc "Trace processing graph life cycle" and
+\ref api-msg-iter.
+
+The available message iterator class methods to implement are:
+
+<table>
+  <tr>
+    <th>Name
+    <th>Requirement
+    <th>C type
+  <tr>
+    <td>Can seek beginning?
+    <td>Optional
+    <td>#bt_message_iterator_class_can_seek_beginning_method
+  <tr>
+    <td>Can seek ns from origin?
+    <td>Optional
+    <td>#bt_message_iterator_class_can_seek_ns_from_origin_method
+  <tr>
+    <td>Finalize
+    <td>Optional
+    <td>#bt_message_iterator_class_finalize_method
+  <tr>
+    <td>Initialize
+    <td>Optional
+    <td>#bt_message_iterator_class_initialize_method
+  <tr>
+    <td>Next
+    <td>Mandatory
+    <td>#bt_message_iterator_class_next_method
+  <tr>
+    <td>Seek beginning
+    <td>Optional
+    <td>#bt_message_iterator_class_seek_beginning_method
+  <tr>
+    <td>Seek ns from origin
+    <td>Optional
+    <td>#bt_message_iterator_class_seek_ns_from_origin_method
+</table>
+
+<dl>
+  <dt>
+    \anchor api-msg-iter-cls-meth-can-seek-beg
+    Can seek beginning?
+  </dt>
+  <dd>
+    Called to check whether or not your \bt_msg_iter can currently
+    seek its beginning (the very first message of its
+    \ref api-msg-seq "sequence").
+
+    There are some use cases in which a message iterator cannot always
+    seek its beginning, depending on its state.
+
+    If you don't implement this method, then, if you implement the
+    \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method, the
+    library assumes that your message iterator can always seek its
+    beginning.
+
+    The message iterator of a \bt_flt_comp will typically consider
+    the beginning seeking capability of its own upstream message
+    iterator(s) (with bt_message_iterator_can_seek_beginning()) in this
+    method's implementation.
+
+    If you need to block the thread to compute whether or not your
+    message iterator can seek its beginning, you can instead report to
+    try again later to the caller by returning
+    #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
+
+    Set this optional method with the \bt_p{can_seek_method} parameter
+    of bt_message_iterator_class_set_seek_beginning_methods().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-cls-meth-can-seek-ns
+    Can seek ns from origin?
+  </dt>
+  <dd>
+    Called to check whether or not your \bt_msg_iter can currently
+    seek a message occuring at or after a specific time given in
+    nanoseconds from its
+    \ref api-tir-clock-cls-origin "clock class origin".
+
+    There are some use cases in which a message iterator cannot always
+    seek some specific time, depending on its state.
+
+    Within this method, your receive the specific time to seek as the
+    \bt_p{ns_from_origin} parameter. You don't receive any
+    \bt_clock_cls: the method operates at the nanosecond from some
+    origin level and it is left to the implementation to decide whether
+    or not the message iterator can seek this point in time.
+
+    If you don't implement this method, then, if you implement the
+    \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method, the
+    library assumes that your message iterator can always seek any
+    message occuring at or after any time.
+
+    The message iterator of a \bt_flt_comp will typically consider
+    the time seeking capability of its own upstream message
+    iterator(s) (with bt_message_iterator_can_seek_ns_from_origin()) in
+    this method's implementation.
+
+    If you need to block the thread to compute whether or not your
+    message iterator can seek a message occuring at or after a given
+    time, you can instead report to try again later to the caller by
+    returning
+    #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
+
+    Set this optional method with the \bt_p{can_seek_method} parameter
+    of bt_message_iterator_class_set_seek_ns_from_origin_methods().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-cls-meth-fini
+    Finalize
+  </dt>
+  <dd>
+    Called to finalize your \bt_msg_iter, that is, to let you
+    destroy/free/finalize any user data you have (retrieved with
+    bt_self_message_iterator_get_data()).
+
+    The \bt_name library does not specify exactly when this method is
+    called, but guarantees that it's called before the message iterator
+    is destroyed.
+
+    The library guarantees that all message iterators are destroyed
+    before their component is destroyed.
+
+    This method is \em not called if the message iterator's
+    \ref api-msg-iter-cls-meth-init "initialization method"
+    previously returned an error status code.
+
+    Set this optional method with
+    bt_message_iterator_class_set_finalize_method().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-cls-meth-init
+    Initialize
+  </dt>
+  <dd>
+    Called within bt_message_iterator_create_from_message_iterator()
+    or bt_message_iterator_create_from_sink_component() to initialize
+    your \bt_msg_iter.
+
+    Within this method, you can access your \bt_comp's user data
+    by first borrowing it with
+    bt_self_message_iterator_borrow_component() and then using
+    bt_self_component_get_data().
+
+    For the message iterator of a \bt_flt_comp, this method is
+    typically where you create an upstream \bt_msg_iter
+    with bt_message_iterator_create_from_message_iterator().
+
+    You can create user data and set it as the \bt_self_msg_iter's user
+    data with bt_self_message_iterator_set_data().
+
+    If you return #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
+    from this method, then your message iterator's
+    \ref api-msg-iter-cls-meth-fini "finalization method" will be
+    called, if it exists, when your message iterator is finalized.
+
+    This method receives a message iterator configuration object
+    (#bt_self_message_iterator_configuration type). As of
+    \bt_name_version_min_maj, you can use
+    bt_self_message_iterator_configuration_set_can_seek_forward()
+    during, and only during, this method's execution to set whether or
+    not your message iterator can <em>seek forward</em>.
+
+    For a message iterator to be able to seek forward, all the \bt_p_msg
+    of its message sequence must have some \bt_cs.
+    bt_message_iterator_seek_ns_from_origin() uses this configuration
+    option and the beginning seeking capability of a message iterator
+    (bt_message_iterator_can_seek_beginning())
+    to make it seek a message occuring at or after a specific time even
+    when the message iterator does not implement the
+    \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
+
+    Set this optional method with
+    bt_message_iterator_class_set_initialize_method().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-cls-meth-next
+    "Next" (get next messages)
+  </dt>
+  <dd>
+    Called within bt_message_iterator_next()
+    to "advance" your \bt_msg_iter, that is, to get its next
+    messages.
+
+    Within this method, you receive:
+
+    - An array of \bt_p_msg to fill (\bt_p{messages} parameter)
+      with your message iterator's next messages, if any.
+
+      Note that this array needs its own message
+      \ref api-fund-shared-object "references". In other
+      words, if you have a message reference and you put this message
+      into the array without calling bt_message_get_ref(), then you just
+      \em moved the message reference to the array (the array owns the
+      message now).
+
+    - The capacity of the message array (\bt_p{capacity} parameter),
+      that is, the maximum number of messages you can put in it.
+
+    - A message count output parameter (\bt_p{count}) which, on success,
+      you must set to the number of messages you put in the message
+      array.
+
+    If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
+    from this method, then you must put at least one message in the
+    message array. In other words, \bt_p{*count} must be greater than
+    zero.
+
+    You must honour the \ref api-msg-seq "message sequence rules" when
+    you put new or existing messages in the message array.
+
+    If you return #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
+    then all the messages of the message array become
+    \ref api-fund-freezing "frozen".
+
+    This method typically:
+
+    <dl>
+      <dt>For a \bt_src_comp's message iterator</dt>
+      <dd>
+        Creates brand new \bt_p_msg to represent one or more input
+        traces.
+      </dd>
+
+      <dt>For a \bt_flt_comp's message iterator</dt>
+      <dd>
+        Gets \em one message batch from one (or more) upstream
+        \bt_msg_iter and filters them.
+      </dd>
+    </dl>
+
+    For a source component's message iterator, you are free to create
+    as many as \bt_p{capacity} messages. For a filter component's
+    message iterator, you are free to get more than one batch of
+    messages from upstream message iterators if needed. However, in both
+    cases, keep in mind that the \bt_name project recommends that this
+    method executes fast enough so as not to block an interactive
+    application running on the same thread.
+
+    During what you consider to be a long, blocking operation, the
+    project recommends that you periodically check whether or not you
+    are interrupted with bt_self_message_iterator_is_interrupted(). When
+    you are, you can return either
+    #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN or
+    #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR, depending on
+    your capability to continue the current operation later.
+
+    If you need to block the thread to insert messages into the message
+    array, you can instead report to try again later to the caller by
+    returning #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN.
+    When you return this status code, you must \em not put any message
+    into the message array.
+
+    If your message iterator's iteration process is done (you have no
+    more messages to emit), then return
+    #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END. When you return
+    this status code, you must \em not put any message into the message
+    array.
+
+    Set this mandatory method at message iterator class creation time
+    with bt_message_iterator_class_create().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-cls-meth-seek-beg
+    Seek beginning
+  </dt>
+  <dd>
+    Called within bt_message_iterator_seek_beginning() to make
+    your message iterator seek its beginning, that is, the very first
+    message of its \ref api-msg-seq "sequence".
+
+    The sequence of messages of a given message iterator must always be
+    the same, in that, if your message iterator emitted the messages A,
+    B, C, D, and E, and then this "seek beginning" method is called
+    successfully
+    (it returns
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK),
+    then your message iterator's next messages (the next time your
+    \link api-msg-iter-cls-meth-next "next" method\endlink
+    is called) must be A, B, C, D, and E.
+
+    The \bt_name project recommends that this method executes fast
+    enough so as not to block an interactive application running on the
+    same thread.
+
+    During what you consider to be a long, blocking operation, the
+    project recommends that you periodically check whether or not you
+    are interrupted with bt_self_message_iterator_is_interrupted(). When
+    you are, you can return either
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN or
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR,
+    depending on your capability to continue the current operation
+    later.
+
+    If you need to block the thread to make your message iterator seek
+    its beginning, you can instead report to try again later to the
+    caller by returning
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN.
+
+    The optional
+    \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
+    method can indicate whether or not your message iterator can
+    currently seek its beginning. If you implement it, the library
+    guarantees that it is called and returns #BT_TRUE before this "seek
+    beginning" is called, without any other message iterator methods
+    being called in between.
+
+    Set this optional method with the \bt_p{seek_method} parameter
+    of bt_message_iterator_class_set_seek_beginning_methods().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-cls-meth-seek-ns
+    Seek ns from origin
+  </dt>
+  <dd>
+    Called within bt_message_iterator_seek_ns_from_origin() to make
+    your message iterator seek a message occuring at or after a specific
+    time given in nanoseconds from its
+    \ref api-tir-clock-cls-origin "clock class origin".
+
+    Within this method, your receive the specific time to seek as the
+    \bt_p{ns_from_origin} parameter. You don't receive any
+    \bt_clock_cls: the method operates at the nanosecond from some
+    origin level and it is left to the implementation to seek a message
+    having at least this time while still honouring the
+    \ref api-msg-seq "message sequence rules" the next time your
+    \link api-msg-iter-cls-meth-next "next" method\endlink is called.
+
+    If you return
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK from
+    this method, then the next time your
+    \link api-msg-iter-cls-meth-next "next" method\endlink is called:
+
+    - For each "active" \bt_stream at the seeked time point, you must
+      emit a \bt_sb_msg for this stream before you emit any other
+      message for this stream.
+
+      The stream beginning message must have a
+      \ref api-msg-sb-prop-cs "default clock snapshot" which corresponds
+      to the seeked time point.
+
+    - For each "active" \bt_pkt at the seeked time point, you must
+      emit a \bt_pb_msg for this packet before you emit any other
+      message for this packet.
+
+      The packet beginning message must have a
+      \ref api-msg-pb-prop-cs "default clock snapshot" which corresponds
+      to the seeked time point.
+
+    The \bt_name project recommends that this method executes fast
+    enough so as not to block an interactive application running on the
+    same thread.
+
+    During what you consider to be a long, blocking operation, the
+    project recommends that you periodically check whether or not you
+    are interrupted with bt_self_message_iterator_is_interrupted(). When
+    you are, you can return either
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
+    or
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR,
+    depending on your capability to continue the current operation
+    later.
+
+    If you need to block the thread to make your message iterator seek a
+    message occuring at or after a given time, you can instead report to
+    try again later to the caller by returning
+    #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN.
+
+    The optional
+    \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+    method can indicate whether or not your message iterator can
+    currently seek a specific time. If you implement it, the library
+    guarantees that it is called and returns #BT_TRUE before this "seek
+    ns from origin" is called, without any other message iterator
+    methods being called in between.
+
+    Set this optional method with the \bt_p{seek_method} parameter
+    of bt_message_iterator_class_set_seek_ns_from_origin_methods().
+  </dd>
+</dl>
+
+Within any method, you can access the \bt_msg_iter's \bt_comp's
+configured \ref #bt_logging_level "logging level" by first upcasting the
+\bt_self_comp to the #bt_component type with
+bt_self_component_as_component(), and then with
+bt_component_get_logging_level().
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_message_iterator_class bt_message_iterator_class;
+
+@brief
+    Message iterator class.
+
+@}
+*/
+
+/*!
+@name Method types
+@{
+*/
+
+/*!
+@brief
+    Status codes for #bt_message_iterator_class_can_seek_beginning_method.
+*/
+typedef enum bt_message_iterator_class_can_seek_beginning_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK           = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN        = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_class_can_seek_beginning_method_status;
+
+/*!
+@brief
+    \bt_c_msg_iter "can seek beginning?" method.
+
+See the \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
+method.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+@param[out] can_seek_beginning
+    <strong>On success</strong>, \bt_p{*can_seek_beginning} is
+    #BT_TRUE if \bt_p{self_message_iterator} can currently seek its
+    beginning.
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{can_seek_beginning}
+
+@post
+    <strong>On success</strong>, \bt_p{*can_seek_beginning} is set.
+
+@sa bt_message_iterator_class_set_seek_beginning_methods() &mdash;
+    Sets the "seek beginning" and "can seek beginning?" methods of a
+    message iterator class.
+*/
+typedef bt_message_iterator_class_can_seek_beginning_method_status
+(*bt_message_iterator_class_can_seek_beginning_method)(
+               bt_self_message_iterator *self_message_iterator,
+               bt_bool *can_seek_beginning);
+
+/*!
+@brief
+    Status codes for #bt_message_iterator_class_can_seek_ns_from_origin_method.
+*/
+typedef enum bt_message_iterator_class_can_seek_ns_from_origin_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN           = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_class_can_seek_ns_from_origin_method_status;
+
+/*!
+@brief
+    \bt_c_msg_iter "can seek ns from origin?" method.
+
+See the \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+method.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+@param[in] ns_from_origin
+    Requested time point to seek.
+@param[out] can_seek_ns_from_origin
+    <strong>On success</strong>, set \bt_p{*can_seek_ns_from_origin} to
+    #BT_TRUE if \bt_p{self_message_iterator} can currently seek a
+    message occuring at or after \bt_p{ns_from_origin} nanoseconds from
+    its \ref api-tir-clock-cls-origin "clock class origin".
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{can_seek_ns_from_origin}
+
+@post
+    <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is set.
+
+@sa bt_message_iterator_class_set_seek_ns_from_origin_methods() &mdash;
+    Sets the "seek ns from origin" and "can seek ns from origin?"
+    methods of a message iterator class.
+*/
+typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status
+(*bt_message_iterator_class_can_seek_ns_from_origin_method)(
+               bt_self_message_iterator *self_message_iterator,
+               int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
+
+/*!
+@brief
+    \bt_c_msg_iter finalization method.
+
+See the \ref api-msg-iter-cls-meth-fini "finalize" method.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@bt_pre_not_null{self_message_iterator}
+
+@bt_post_no_error
+
+@sa bt_message_iterator_class_set_finalize_method() &mdash;
+    Sets the finalization method of a message iterator class.
+*/
+typedef void
+(*bt_message_iterator_class_finalize_method)(
+               bt_self_message_iterator *self_message_iterator);
+
+/*!
+@brief
+    Status codes for #bt_message_iterator_class_initialize_method.
+*/
 typedef enum bt_message_iterator_class_initialize_method_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK           = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
 } bt_message_iterator_class_initialize_method_status;
 
+/*!
+@brief
+    \bt_c_msg_iter initialization method.
+
+See the \ref api-msg-iter-cls-meth-init "initialize" method.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+@param[in] configuration
+    Message iterator's configuration.
+@param[in] port
+    \bt_c_oport for which \bt_p{self_message_iterator} was created.
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{configuration}
+@bt_pre_not_null{port}
+
+@sa bt_message_iterator_class_set_initialize_method() &mdash;
+    Sets the initialization method of a message iterator class.
+*/
+typedef bt_message_iterator_class_initialize_method_status
+(*bt_message_iterator_class_initialize_method)(
+               bt_self_message_iterator *self_message_iterator,
+               bt_self_message_iterator_configuration *configuration,
+               bt_self_component_port_output *port);
+
+/*!
+@brief
+    Status codes for #bt_message_iterator_class_next_method.
+*/
 typedef enum bt_message_iterator_class_next_method_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK                 = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           End of iteration.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END                = __BT_FUNC_STATUS_END,
+
+       /*!
+       @brief
+           Try again.
+       */
        BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN              = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR              = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END                = __BT_FUNC_STATUS_END,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR              = __BT_FUNC_STATUS_ERROR,
 } bt_message_iterator_class_next_method_status;
 
-typedef enum bt_message_iterator_class_seek_ns_from_origin_method_status {
-       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK                  = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN               = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
-       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_class_seek_ns_from_origin_method_status;
+/*!
+@brief
+    \bt_c_msg_iter "next" (get next messages) method.
 
-typedef enum bt_message_iterator_class_can_seek_ns_from_origin_method_status {
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK              = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN           = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_class_can_seek_ns_from_origin_method_status;
+See the \link api-msg-iter-cls-meth-next "next"\endlink method.
 
+If this method returns #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK,
+then all the messages of the message array become
+\ref api-fund-freezing "frozen".
+
+@param[in] self_message_iterator
+    Message iterator instance.
+@param[out] messages
+    @parblock
+    Message array to fill, on success, with the \bt_p_msg to emit.
+
+    This array needs its own message
+    \ref api-fund-shared-object "references". In other
+    words, if you have a message reference and you put this message
+    into the array without calling bt_message_get_ref(), then you just
+    \em moved the message reference to the array (the array owns the
+    message now).
+
+    The capacity of this array (maximum number of messages you can put
+    in it) is \bt_p{capacity}.
+    @endparblock
+@param[in] capacity
+    Capacity of the \bt_p{messages} array (maximum number of messages
+    you can put in it).
+@param[out] count
+    <strong>On success</strong>, \bt_p{*count} is the number of messages
+    you put in \bt_p{messages}.
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END
+    End of iteration.
+@retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{messages}
+@pre
+    \bt_p{capacity} ≥ 1.
+@bt_pre_not_null{count}
+
+@post
+    <strong>On success</strong>, \bt_p{messages} contains \bt_p{*count}
+    message references as its first \bt_p{*count} elements.
+@post
+    <strong>On success</strong>, the \bt_p_msg in \bt_p{messages} honour
+    the \ref api-msg-seq "message sequence rules".
+@post
+    <strong>On success</strong>, for any \bt_ev_msg in
+    \bt_p{messages}, its
+    \ref api-tir-ev-prop-payload "payload field",
+    \ref api-tir-ev-prop-spec-ctx "specific context field",
+    \ref api-tir-ev-prop-common-ctx "common context field", and all
+    their inner \bt_p_field, recursively, are set.
+@post
+    <strong>On success</strong>, \bt_p{*count}&nbsp;≥&nbsp;1.
+@post
+    <strong>On success</strong>,
+    \bt_p{*count}&nbsp;≤&nbsp;\bt_p{capacity}.
+
+@sa bt_message_iterator_class_create() &mdash;
+    Creates a message iterator class.
+*/
+typedef bt_message_iterator_class_next_method_status
+(*bt_message_iterator_class_next_method)(
+               bt_self_message_iterator *self_message_iterator,
+               bt_message_array_const messages, uint64_t capacity,
+               uint64_t *count);
+
+/*!
+@brief
+    Status codes for #bt_message_iterator_class_seek_beginning_method.
+*/
 typedef enum bt_message_iterator_class_seek_beginning_method_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Try again.
+       */
        BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_class_seek_beginning_method_status;
 
-typedef enum bt_message_iterator_class_can_seek_beginning_method_status {
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_OK           = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_AGAIN        = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
-       BT_MESSAGE_ITERATOR_CLASS_CAN_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_class_can_seek_beginning_method_status;
+       /*!
+       @brief
+           User error.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_class_seek_beginning_method_status;
 
-typedef bt_message_iterator_class_initialize_method_status
-(*bt_message_iterator_class_initialize_method)(
-               bt_self_message_iterator *message_iterator,
-               bt_self_message_iterator_configuration *config,
-               bt_self_component_port_output *port);
+/*!
+@brief
+    \bt_c_msg_iter "seek beginning" method.
 
-typedef void
-(*bt_message_iterator_class_finalize_method)(
-               bt_self_message_iterator *message_iterator);
+See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning" method.
 
-typedef bt_message_iterator_class_next_method_status
-(*bt_message_iterator_class_next_method)(
-               bt_self_message_iterator *message_iterator,
-               bt_message_array_const msgs, uint64_t capacity,
-               uint64_t *count);
+@param[in] self_message_iterator
+    Message iterator instance.
 
-typedef bt_message_iterator_class_seek_ns_from_origin_method_status
-(*bt_message_iterator_class_seek_ns_from_origin_method)(
-               bt_self_message_iterator *message_iterator,
-               int64_t ns_from_origin);
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHOD_STATUS_ERROR
+    User error.
 
-typedef bt_message_iterator_class_can_seek_ns_from_origin_method_status
-(*bt_message_iterator_class_can_seek_ns_from_origin_method)(
-               bt_self_message_iterator *message_iterator,
-               int64_t ns_from_origin, bt_bool *can_seek);
+@bt_pre_not_null{self_message_iterator}
+@pre
+    <strong>If \bt_p{self_message_iterator} has a
+    \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
+    method</strong>, then it was called and returned #BT_TRUE before
+    this "seek beginning" method is called, without any other method of
+    \bt_p{self_message_iterator} called in between.
 
+@sa bt_message_iterator_class_set_seek_beginning_methods() &mdash;
+    Sets the "seek beginning" and "can seek beginning?" methods of a
+    message iterator class.
+*/
 typedef bt_message_iterator_class_seek_beginning_method_status
 (*bt_message_iterator_class_seek_beginning_method)(
-               bt_self_message_iterator *message_iterator);
+               bt_self_message_iterator *self_message_iterator);
 
-typedef bt_message_iterator_class_can_seek_beginning_method_status
-(*bt_message_iterator_class_can_seek_beginning_method)(
-               bt_self_message_iterator *message_iterator, bt_bool *can_seek);
+/*!
+@brief
+    Status codes for #bt_message_iterator_class_seek_ns_from_origin_method.
+*/
+typedef enum bt_message_iterator_class_seek_ns_from_origin_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK                  = __BT_FUNC_STATUS_OK,
 
-extern void bt_message_iterator_class_get_ref(
-               const bt_message_iterator_class *message_iterator_class);
+       /*!
+       @brief
+           Try again.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN               = __BT_FUNC_STATUS_AGAIN,
 
-extern void bt_message_iterator_class_put_ref(
-               const bt_message_iterator_class *message_iterator_class);
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
 
-#define BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET(_var)      \
-       do {                                                    \
-               bt_message_iterator_class_put_ref(_var);        \
-               (_var) = NULL;                                  \
-       } while (0)
+       /*!
+       @brief
+           User error.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_class_seek_ns_from_origin_method_status;
 
-#define BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF(_var_dst, _var_src)    \
-       do {                                                            \
-               bt_message_iterator_class_put_ref(_var_dst);            \
-               (_var_dst) = (_var_src);                                \
-               (_var_src) = NULL;                                      \
-       } while (0)
+/*!
+@brief
+    \bt_c_msg_iter "seek ns from origin" method.
+
+See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" method.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+@param[in] ns_from_origin
+    Time point to seek.
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHOD_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{self_message_iterator}
+@pre
+    <strong>If \bt_p{self_message_iterator} has a
+    \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+    method</strong>, then it was called and returned #BT_TRUE before
+    this "seek ns from origin" method is called, without any other
+    method of \bt_p{self_message_iterator} called in between.
+
+@sa bt_message_iterator_class_set_seek_ns_from_origin_methods() &mdash;
+    Sets the "seek ns from origin" and "can seek ns from origin?"
+    methods of a message iterator class.
+*/
+typedef bt_message_iterator_class_seek_ns_from_origin_method_status
+(*bt_message_iterator_class_seek_ns_from_origin_method)(
+               bt_self_message_iterator *self_message_iterator,
+               int64_t ns_from_origin);
+
+/*! @} */
+
+/*!
+@name Creation
+@{
+*/
 
+/*!
+@brief
+    Creates a message iterator class having the
+    \link api-msg-iter-cls-meth-next "next" method\endlink method
+    \bt_p{next_method}.
+
+@param[in] next_method
+    "Next" method of the message iterator class to create.
+
+@returns
+    New message iterator class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{next_method}
+*/
 extern bt_message_iterator_class *
 bt_message_iterator_class_create(
                bt_message_iterator_class_next_method next_method);
 
-extern bt_message_iterator_class_set_method_status
-bt_message_iterator_class_set_initialize_method(
-               bt_message_iterator_class *message_iterator_class,
-               bt_message_iterator_class_initialize_method method);
+/*! @} */
+
+/*!
+@name Method setting
+@{
+*/
+
+/*!
+@brief
+    Status code for the
+    <code>bt_message_iterator_class_set_*_method()</code> functions.
+*/
+typedef enum bt_message_iterator_class_set_method_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK  = __BT_FUNC_STATUS_OK,
+} bt_message_iterator_class_set_method_status;
+
+/*!
+@brief
+    Sets the optional finalization method of the message iterator class
+    \bt_p{message_iterator_class} to \bt_p{method}.
+
+See the \ref api-msg-iter-cls-meth-fini "finalize" method.
 
+@param[in] message_iterator_class
+    Message iterator class of which to set the finalization method to
+    \bt_p{method}.
+@param[in] method
+    New finalization method of \bt_p{message_iterator_class}.
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{message_iterator_class}
+@bt_pre_hot{message_iterator_class}
+@bt_pre_not_null{method}
+*/
 extern bt_message_iterator_class_set_method_status
 bt_message_iterator_class_set_finalize_method(
                bt_message_iterator_class *message_iterator_class,
                bt_message_iterator_class_finalize_method method);
 
+/*!
+@brief
+    Sets the optional initialization method of the message iterator
+    class \bt_p{message_iterator_class} to \bt_p{method}.
+
+See the \ref api-msg-iter-cls-meth-init "initialize" method.
+
+@param[in] message_iterator_class
+    Message iterator class of which to set the initialization method to
+    \bt_p{method}.
+@param[in] method
+    New initialization method of \bt_p{message_iterator_class}.
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{message_iterator_class}
+@bt_pre_hot{message_iterator_class}
+@bt_pre_not_null{method}
+*/
 extern bt_message_iterator_class_set_method_status
-bt_message_iterator_class_set_seek_ns_from_origin_methods(
+bt_message_iterator_class_set_initialize_method(
                bt_message_iterator_class *message_iterator_class,
-               bt_message_iterator_class_seek_ns_from_origin_method seek_method,
-               bt_message_iterator_class_can_seek_ns_from_origin_method can_seek_method);
+               bt_message_iterator_class_initialize_method method);
+
+/*!
+@brief
+    Sets the optional "seek beginning" and
+    "can seek beginning?" methods of the message iterator class
+    \bt_p{message_iterator_class} to \bt_p{seek_method} and
+    \bt_p{can_seek_method}.
+
+See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning"
+and \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?"
+methods.
+
+@param[in] message_iterator_class
+    Message iterator class of which to set the "seek beginning"
+    and "can seek beginning?" methods.
+@param[in] seek_method
+    New "seek beginning" method of \bt_p{message_iterator_class}.
+@param[in] can_seek_method
+    @parblock
+    New "can seek beginning?" method of \bt_p{message_iterator_class}.
+
+    Can be \c NULL, in which case it is equivalent to setting a method
+    which always returns #BT_TRUE.
+    @endparblock
 
+@retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{message_iterator_class}
+@bt_pre_hot{message_iterator_class}
+@bt_pre_not_null{seek_method}
+*/
 extern bt_message_iterator_class_set_method_status
 bt_message_iterator_class_set_seek_beginning_methods(
                bt_message_iterator_class *message_iterator_class,
                bt_message_iterator_class_seek_beginning_method seek_method,
                bt_message_iterator_class_can_seek_beginning_method can_seek_method);
 
+/*!
+@brief
+    Sets the optional "seek ns from origin" and
+    "can seek ns from origin?" methods of the message iterator class
+    \bt_p{message_iterator_class} to \bt_p{seek_method} and
+    \bt_p{can_seek_method}.
+
+See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin"
+and
+\ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+methods.
+
+@param[in] message_iterator_class
+    Message iterator class of which to set the "seek ns from origin"
+    and "can seek ns from origin?" methods.
+@param[in] seek_method
+    New "seek ns from origin" method of \bt_p{message_iterator_class}.
+@param[in] can_seek_method
+    @parblock
+    New "can seek ns from origin?" method of
+    \bt_p{message_iterator_class}.
+
+    Can be \c NULL, in which case it is equivalent to setting a method
+    which always returns #BT_TRUE.
+    @endparblock
+
+@retval #BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK
+    Success.
+
+@bt_pre_not_null{message_iterator_class}
+@bt_pre_hot{message_iterator_class}
+@bt_pre_not_null{seek_method}
+*/
+extern bt_message_iterator_class_set_method_status
+bt_message_iterator_class_set_seek_ns_from_origin_methods(
+               bt_message_iterator_class *message_iterator_class,
+               bt_message_iterator_class_seek_ns_from_origin_method seek_method,
+               bt_message_iterator_class_can_seek_ns_from_origin_method can_seek_method);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the message iterator class \bt_p{message_iterator_class}.
+
+@param[in] message_iterator_class
+    @parblock
+    Message iterator class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_put_ref() &mdash;
+    Decrements the reference count of a message iterator class.
+*/
+extern void bt_message_iterator_class_get_ref(
+               const bt_message_iterator_class *message_iterator_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the message iterator class \bt_p{message_iterator_class}.
+
+@param[in] message_iterator_class
+    @parblock
+    Message iterator class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_component_get_ref() &mdash;
+    Increments the reference count of a message iterator class.
+*/
+extern void bt_message_iterator_class_put_ref(
+               const bt_message_iterator_class *message_iterator_class);
+
+/*!
+@brief
+    Decrements the reference count of the message iterator class
+    \bt_p{_message_iterator_class}, and then sets
+    \bt_p{_message_iterator_class} to \c NULL.
+
+@param _message_iterator_class
+    @parblock
+    Message iterator class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_message_iterator_class}
+*/
+#define BT_MESSAGE_ITERATOR_CLASS_PUT_REF_AND_RESET(_message_iterator_class) \
+       do {                                                            \
+               bt_message_iterator_class_put_ref(_message_iterator_class); \
+               (_message_iterator_class) = NULL;                       \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the message iterator class \bt_p{_dst},
+    sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src}
+    to \c NULL.
+
+This macro effectively moves a message iterator class reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_MESSAGE_ITERATOR_CLASS_MOVE_MOVE_REF(_dst, _src)    \
+       do {                                                    \
+               bt_message_iterator_class_put_ref(_dst);        \
+               (_dst) = (_src);                                \
+               (_src) = NULL;                                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/graph/message-iterator.h b/include/babeltrace2/graph/message-iterator.h
index 228b40d1ab15b70d81f27edb96b042776a90be62..cda5040ae0c6fa819d3fd50488f6f076b18ef423 100644 (file)
--- a/include/babeltrace2/graph/message-iterator.h
+++ b/include/babeltrace2/graph/message-iterator.h
@@ -31,125 +31,865 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-msg-iter Message iterator
+@ingroup api-comp-cls-dev
+
+@brief
+    Iterator of a \bt_msg sequence.
+
+A <strong><em>message iterator</em></strong> iterates a sequence of
+\bt_p_msg.
+
+A message iterator is the \bt_name mechanism for the \bt_p_comp of a
+trace processing \bt_graph to exchange information. This information
+takes the form of a sequence of individual messages which contain
+trace data (\bt_p_ev, for example).
+
+A message iterator is a \bt_msg_iter_cls instance. Because a message
+iterator class is part of a \bt_src_comp_cls or \bt_flt_comp_cls, a
+message iterator is part of a \bt_src_comp or \bt_flt_comp. Borrow
+a message iterator's component with
+bt_message_iterator_borrow_component().
+
+A message iterator is a \ref api-fund-shared-object "shared object": get
+a new reference with bt_component_get_ref() and put an existing
+reference with bt_component_put_ref().
+
+The type of a message iterator is #bt_message_iterator.
+
+There are two contexts from which you can create a message iterator:
+
+<dl>
+  <dt>From another message iterator</dt>
+  <dd>
+    This is the case for a \bt_flt_comp's message iterator.
+
+    Use bt_message_iterator_create_from_message_iterator().
+
+    You can call this function from any message iterator
+    \ref api-msg-iter-cls-methods "method" except the
+    \ref api-msg-iter-cls-meth-fini "finalization method".
+  </dd>
+
+  <dt>From a \bt_sink_comp</dt>
+  <dd>
+    Use bt_message_iterator_create_from_sink_component().
+
+    You can call this function from a sink component
+    \ref api-comp-cls-dev-methods "method" once the trace processing
+    graph which contains the component is
+    \ref api-graph-lc "configured", that is:
+
+    - \ref api-comp-cls-dev-meth-graph-configured "Graph is configured"
+      method (typical).
+
+    - \ref api-comp-cls-dev-meth-consume "Consume" method.
+  </dd>
+</dl>
+
+When you call one of the creation functions above, you pass an \bt_iport
+on which to create the message iterator.
+
+You can create more than one message iterator on a given
+<em>\ref api-port-prop-is-connected "connected"</em> input port. The
+\bt_p_conn between \bt_p_port in a trace processing \bt_graph establish
+which \bt_p_comp and message iterators can create message iterators of
+other \bt_p_comp. Then:
+
+- Any \bt_sink_comp is free to create one or more message iterators
+  on any of its connected input ports.
+
+- Any message iterator is free to create one or more message iterators
+  on any of its component's connected input ports.
+
+The following illustration shows a very simple use case where the
+\ref api-comp-cls-dev-meth-consume "consuming method" of a sink
+component uses a single \bt_flt_comp's message iterator which itself
+uses a single \bt_src_comp's message iterator:
+
+@image html msg-iter.png
+
+Many message iterator relations are possible, for example:
+
+@image html msg-iter-complex.png
+
+<h1>\anchor api-msg-iter-ops Operations</h1>
+
+Once you have created a message iterator, there are three possible
+operations:
+
+<dl>
+  <dt>
+    \anchor api-msg-iter-op-next
+    Get the message iterator's next messages
+  </dt>
+  <dd>
+    This operation returns a batch of the message iterator's next
+    \bt_p_msg considering its current state.
+
+    This operation returns a batch of messages instead of a single
+    message for performance reasons.
+
+    This operation is said to \em advance the message iterator.
+
+    Get the next messages of a message iterator with
+    bt_message_iterator_next().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-op-seek-beg
+    Make the message iterator seek its beginning
+  </dt>
+  <dd>
+    This operation resets the message iterator's position to the
+    beginning of its \ref api-msg-seq "message sequence".
+
+    If the operation is successful, then the next call to
+    bt_message_iterator_next() returns the first \bt_p_msg of the
+    message iterator's sequence.
+
+    If bt_message_iterator_seek_ns_from_origin() returns something
+    else than #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK, you
+    \em cannot call bt_message_iterator_next() afterwards. In that case,
+    you can only call bt_message_iterator_seek_beginning() again or
+    bt_message_iterator_seek_ns_from_origin().
+
+    Before you call bt_message_iterator_seek_beginning() to make
+    the message iterator seek its beginning, check if it can currently
+    do it with bt_message_iterator_can_seek_beginning().
+  </dd>
+
+  <dt>
+    \anchor api-msg-iter-op-seek-ns
+    Make the message iterator seek a message occuring at or after a
+    given time (in nanoseconds) from its clock class origin
+  </dt>
+  <dd>
+    This operation changes the position of the message iterator within
+    its \ref api-msg-seq "sequence" so that the next call to
+    bt_message_iterator_next() returns \bt_p_msg which occur at or after
+    a given time (in nanoseconds) from its
+    \ref api-tir-clock-cls-origin "clock class origin".
+
+    When you call bt_message_iterator_seek_ns_from_origin() to perform
+    the operation, your pass the specific time to seek as the
+    \bt_p{ns_from_origin} parameter. You don't pass any
+    \bt_clock_cls: the function operates at the nanosecond from some
+    origin level and it is left to the message iterator's implementation
+    to seek a message having at least this time.
+
+    If the requested time point is \em after the message iterator's
+    sequence's last message, then the next call to
+    bt_message_iterator_next() returns
+    #BT_MESSAGE_ITERATOR_NEXT_STATUS_END.
+
+    If bt_message_iterator_seek_ns_from_origin() returns something
+    else than #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK, you
+    \em cannot call bt_message_iterator_next() afterwards. In that case,
+    you can only call bt_message_iterator_seek_ns_from_origin() again
+    or bt_message_iterator_seek_beginning().
+
+    Before you call bt_message_iterator_seek_ns_from_origin() to make
+    the message iterator seek a specific point in time, check if it can
+    currently do it with bt_message_iterator_can_seek_ns_from_origin().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_message_iterator bt_message_iterator;
+
+@brief
+    Message iterator.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Status code for bt_message_iterator_create_from_message_iterator().
+*/
+typedef enum bt_message_iterator_create_from_message_iterator_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_create_from_message_iterator_status;
+
+/*!
+@brief
+    Creates a message iterator on the \bt_iport \bt_p{port} from
+    another message iterator \bt_p{self_message_iterator}, and sets
+    \bt_p{*message_iterator} to the resulting message iterator.
+
+On success, the message iterator's position is at the beginning
+of its \ref api-msg-seq "message sequence".
+
+@param[in] self_message_iterator
+    Other message iterator from which to create the message iterator.
+@param[in] port
+    Input port on which to create the message iterator.
+@param[out] message_iterator
+    <strong>On success</strong>, \bt_p{*message_iterator} is a new
+    message iterator reference.
+
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
+    Other error, for example, the created message iterator's
+    \ref api-msg-iter-cls-meth-init "initialization method" failed.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{port}
+@pre
+    <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
+@bt_pre_not_null{message_iterator}
+
+@sa bt_message_iterator_create_from_sink_component() &mdash;
+    Creates a message iterator from a \bt_sink_comp.
+*/
+extern bt_message_iterator_create_from_message_iterator_status
+bt_message_iterator_create_from_message_iterator(
+               bt_self_message_iterator *self_message_iterator,
+               bt_self_component_port_input *port,
+               bt_message_iterator **message_iterator);
+
+/*!
+@brief
+    Status code for bt_message_iterator_create_from_sink_component().
+*/
+typedef enum bt_message_iterator_create_from_sink_component_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_create_from_sink_component_status;
+
+/*!
+@brief
+    Creates a message iterator on the \bt_iport \bt_p{port} from the
+    \bt_sink_comp \bt_p{self_component_sink}, and sets
+    \bt_p{*message_iterator} to the resulting message iterator.
+
+On success, the message iterator's position is at the beginning
+of its \ref api-msg-seq "message sequence".
+
+@param[in] self_component_sink
+    Sink component from which to create the message iterator.
+@param[in] port
+    Input port on which to create the message iterator.
+@param[out] message_iterator
+    <strong>On success</strong>, \bt_p{*message_iterator} is a new
+    message iterator reference.
+
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR
+    Other error, for example, the created message iterator's
+    \ref api-msg-iter-cls-meth-init "initialization method" failed.
+
+@bt_pre_not_null{self_component_sink}
+@bt_pre_not_null{port}
+@pre
+    <code>bt_port_is_connected(port)</code> returns #BT_TRUE.
+@bt_pre_not_null{message_iterator}
+
+@sa bt_message_iterator_create_from_message_iterator() &mdash;
+    Creates a message iterator from another message iterator.
+*/
+extern bt_message_iterator_create_from_sink_component_status
+bt_message_iterator_create_from_sink_component(
+               bt_self_component_sink *self_component_sink,
+               bt_self_component_port_input *port,
+               bt_message_iterator **message_iterator);
+
+/*! @} */
+
+/*!
+@name Component access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_comp which provides the \bt_msg_iter
+    \bt_p{message_iterator}.
+
+@param[in] message_iterator
+    Message iterator from which to borrow the component which provides
+    it.
+
+@returns
+    Component which provides \bt_p{message_iterator}.
+
+@bt_pre_not_null{message_iterator}
+*/
+extern bt_component *
+bt_message_iterator_borrow_component(
+               bt_message_iterator *message_iterator);
+
+/*! @} */
+
+/*!
+@name "Next" operation (get next messages)
+@{
+*/
+
+/*!
+@brief
+    Status code for bt_message_iterator_next().
+*/
 typedef enum bt_message_iterator_next_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_MESSAGE_ITERATOR_NEXT_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           End of iteration.
+       */
        BT_MESSAGE_ITERATOR_NEXT_STATUS_END             = __BT_FUNC_STATUS_END,
+
+       /*!
+       @brief
+           Try again.
+       */
        BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN           = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
 } bt_message_iterator_next_status;
 
-typedef enum bt_message_iterator_seek_beginning_status {
-       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK            = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN         = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
-       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_seek_beginning_status;
+/*!
+@brief
+    Returns the next \bt_p_msg of the message iterator
+    \bt_p{message_iterator} into the \bt_p{*messages} array of size
+    \bt_p{*count}, effectively advancing \bt_p{message_iterator}.
 
-typedef enum bt_message_iterator_seek_ns_from_origin_status {
-       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK               = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
-       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_seek_ns_from_origin_status;
+See \ref api-msg-iter-op-next "this operation's documentation".
+
+On success, the message iterator's position is advanced by \bt_p{*count}
+messages.
+
+@param[in] message_iterator
+    Message iterator from which to get the next messages.
+@param[out] messages
+    @parblock
+    <strong>On success</strong>, \bt_p{*messages} is an array containing
+    the next messages of \bt_p{message_iterator} as its first elements.
+
+    \bt_p{*count} is the number of messages in \bt_p{*messages}.
 
+    The library allocates and manages this array, but until you
+    perform another \ref api-msg-iter-ops "operation" on
+    \bt_p{message_iterator}, you are free to modify it. For example,
+    you can set its elements to \c NULL if your use case needs it.
+
+    You own the references of the messages this array contains. In
+    other words, you must put them with bt_message_put_ref() or move
+    them to another message array (from a
+    \link api-msg-iter-cls-meth-next "next" method\endlink)
+    before you perform another operation on \bt_p{message_iterator} or
+    before \bt_p{message_iterator} is destroyed.
+    @endparblock
+@param[out] count
+    <strong>On success</strong>, \bt_p{*count} is the number of messages
+    in \bt_p{*messages}.
+
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_END
+    End of iteration.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{message_iterator}
+@bt_pre_not_null{messages}
+@bt_pre_not_null{count}
+
+@post
+    <strong>On success</strong>, \bt_p{*count}&nbsp;≥&nbsp;1.
+*/
+extern bt_message_iterator_next_status
+bt_message_iterator_next(bt_message_iterator *message_iterator,
+               bt_message_array_const *messages, uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Seeking
+@{
+*/
+
+/*!
+@brief
+    Status code for bt_message_iterator_can_seek_beginning().
+*/
 typedef enum bt_message_iterator_can_seek_beginning_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Try again.
+       */
        BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN             = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
 } bt_message_iterator_can_seek_beginning_status;
 
+/*!
+@brief
+    Returns whether or not the message iterator \bt_p{message_iterator}
+    can currently seek its beginning (first \bt_msg).
+
+See the \link api-msg-iter-op-seek-beg "seek beginning"
+operation\endlink.
+
+Make sure to call this function, without performing any other
+\ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you
+call bt_message_iterator_seek_beginning().
+
+@param[in] message_iterator
+    Message iterator from which to to get whether or not it can seek
+    its beginning.
+@param[out] can_seek_beginning
+    <strong>On success</strong>, \bt_p{*can_seek_beginning} is #BT_TRUE
+    if \bt_p{message_iterator} can seek its beginning.
+
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_BEGINNING_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{message_iterator}
+@bt_pre_not_null{can_seek_beginning}
+
+@sa bt_message_iterator_seek_beginning() &mdash;
+    Makes a message iterator seek its beginning.
+*/
+extern bt_message_iterator_can_seek_beginning_status
+bt_message_iterator_can_seek_beginning(
+               bt_message_iterator *message_iterator,
+               bt_bool *can_seek_beginning);
+
+/*!
+@brief
+    Status code for bt_message_iterator_seek_beginning().
+*/
+typedef enum bt_message_iterator_seek_beginning_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK            = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN         = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_seek_beginning_status;
+
+/*!
+@brief
+    Makes the message iterator \bt_p{message_iterator} seek its
+    beginning (first \bt_msg).
+
+See \ref api-msg-iter-op-seek-beg "this operation's documentation".
+
+Make sure to call bt_message_iterator_can_seek_beginning(),
+without performing any other \ref api-msg-iter-ops "operation" on
+\bt_p{message_iterator}, before you call this function.
+
+@param[in] message_iterator
+    Message iterator to seek to its beginning.
+
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_SEEK_BEGINNING_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{message_iterator}
+@pre
+    <code>bt_message_iterator_can_seek_beginning(message_iterator)</code>
+    returns #BT_TRUE.
+
+@sa bt_message_iterator_can_seek_beginning() &mdash;
+    Returns whether or not a message iterator can currently seek its
+    beginning.
+*/
+extern bt_message_iterator_seek_beginning_status
+bt_message_iterator_seek_beginning(
+               bt_message_iterator *message_iterator);
+
+/*!
+@brief
+    Status code for bt_message_iterator_can_seek_ns_from_origin().
+*/
 typedef enum bt_message_iterator_can_seek_ns_from_origin_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK           = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Try again.
+       */
        BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN        = __BT_FUNC_STATUS_AGAIN,
-       BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR        = __BT_FUNC_STATUS_ERROR,
 } bt_message_iterator_can_seek_ns_from_origin_status;
 
-typedef enum bt_message_iterator_create_from_message_iterator_status {
-       BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_OK              = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
-       BT_MESSAGE_ITERATOR_CREATE_FROM_MESSAGE_ITERATOR_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_create_from_message_iterator_status;
+/*!
+@brief
+    Returns whether or not the message iterator \bt_p{message_iterator}
+    can currently seek a \bt_msg occuring at or after
+    \bt_p{ns_from_origin} nanoseconds from its
+    \ref api-tir-clock-cls-origin "clock class origin".
 
-typedef enum bt_message_iterator_create_from_sink_component_status {
-       BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_OK                = __BT_FUNC_STATUS_OK,
-       BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
-       BT_MESSAGE_ITERATOR_CREATE_FROM_SINK_COMPONENT_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_message_iterator_create_from_sink_component_status;
+See the \link api-msg-iter-op-seek-ns "seek ns from origin"
+operation\endlink.
 
-static inline
-bt_message_iterator *
-bt_message_iterator_as_message_iterator(
-               bt_message_iterator *iterator)
-{
-       return __BT_UPCAST(bt_message_iterator, iterator);
-}
+Make sure to call this function, without performing any other
+\ref api-msg-iter-ops "operation" on \bt_p{message_iterator}, before you
+call bt_message_iterator_seek_ns_from_origin().
 
-extern bt_message_iterator_create_from_message_iterator_status
-bt_message_iterator_create_from_message_iterator(
-               bt_self_message_iterator *self_msg_iter,
-               bt_self_component_port_input *input_port,
-               bt_message_iterator **message_iterator);
+@param[in] message_iterator
+    Message iterator from which to to get whether or not it can seek
+    its beginning.
+@param[in] ns_from_origin
+    Requested time point to seek.
+@param[out] can_seek_ns_from_origin
+    <strong>On success</strong>, \bt_p{*can_seek_ns_from_origin} is
+    #BT_TRUE if \bt_p{message_iterator} can seek a message occuring at
+    or after \bt_p{ns_from_origin} nanoseconds from its clock class
+    origin.
 
-extern bt_message_iterator_create_from_sink_component_status
-bt_message_iterator_create_from_sink_component(
-               bt_self_component_sink *self_comp,
-               bt_self_component_port_input *input_port,
-               bt_message_iterator **message_iterator);
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_CAN_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
+    Other error.
 
-extern bt_component *
-bt_message_iterator_borrow_component(
-               bt_message_iterator *iterator);
+@bt_pre_not_null{message_iterator}
+@bt_pre_not_null{can_seek_ns_from_origin}
 
-extern bt_message_iterator_next_status
-bt_message_iterator_next(
-               bt_message_iterator *iterator,
-               bt_message_array_const *msgs, uint64_t *count);
+@sa bt_message_iterator_seek_ns_from_origin() &mdash;
+    Makes a message iterator seek a message occuring at or after
+    a given time from its clock class origin.
+*/
 
 extern bt_message_iterator_can_seek_ns_from_origin_status
 bt_message_iterator_can_seek_ns_from_origin(
-               bt_message_iterator *iterator,
-               int64_t ns_from_origin, bt_bool *can_seek);
+               bt_message_iterator *message_iterator,
+               int64_t ns_from_origin, bt_bool *can_seek_ns_from_origin);
 
-extern bt_message_iterator_can_seek_beginning_status
-bt_message_iterator_can_seek_beginning(
-               bt_message_iterator *iterator,
-               bt_bool *can_seek);
+/*!
+@brief
+    Status code for bt_message_iterator_seek_ns_from_origin().
+*/
+typedef enum bt_message_iterator_seek_ns_from_origin_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Try again.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
+} bt_message_iterator_seek_ns_from_origin_status;
+
+/*!
+@brief
+    Makes the message iterator \bt_p{message_iterator} seek a \bt_msg
+    occuring at or after \bt_p{ns_from_origin} nanoseconds from its
+    \ref api-tir-clock-cls-origin "clock class origin".
+
+See \ref api-msg-iter-op-seek-ns "this operation's documentation".
+
+Make sure to call bt_message_iterator_can_seek_ns_from_origin(),
+without performing any other \ref api-msg-iter-ops "operation" on
+\bt_p{message_iterator}, before you call this function.
+
+@param[in] message_iterator
+    Message iterator to seek to a message occuring at or after
+    \bt_p{ns_from_origin} nanoseconds from its clock class origin.
+@param[in] ns_from_origin
+    Time point to seek.
+
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_OK
+    Success.
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_AGAIN
+    Try again.
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_MESSAGE_ITERATOR_SEEK_NS_FROM_ORIGIN_STATUS_ERROR
+    Other error.
 
+@bt_pre_not_null{message_iterator}
+@pre
+    <code>bt_message_iterator_can_seek_ns_from_origin(message_iterator,&nbsp;ns_from_origin)</code>
+    returns #BT_TRUE.
+
+@sa bt_message_iterator_can_seek_ns_from_origin() &mdash;
+    Returns whether or not a message iterator can currently seek a
+    message occuring at or after a given time from its clock class
+    origin.
+*/
 extern bt_message_iterator_seek_ns_from_origin_status
 bt_message_iterator_seek_ns_from_origin(
-               bt_message_iterator *iterator,
+               bt_message_iterator *message_iterator,
                int64_t ns_from_origin);
 
-extern bt_message_iterator_seek_beginning_status
-bt_message_iterator_seek_beginning(
-               bt_message_iterator *iterator);
+/*! @} */
+
+/*!
+@name Configuration
+@{
+*/
+
+/*!
+@brief
+    Returns whether or not the message iterator \bt_p{message_iterator}
+    can seek forward.
+
+A message iterator can seek forward if all the \bt_p_msg of its
+message sequence have some \bt_cs.
+
+@param[in] message_iterator
+    Message iterator of which to get whether or not it can seek forward.
 
+@returns
+    #BT_TRUE if \bt_p{message_iterator} can seek forward.
+
+@sa bt_self_message_iterator_configuration_set_can_seek_forward() &mdash;
+    Sets whether or not a message iterator can seek forward.
+*/
 extern bt_bool
 bt_message_iterator_can_seek_forward(
-               bt_message_iterator *iterator);
+               bt_message_iterator *message_iterator);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the message iterator \bt_p{message_iterator}.
 
+@param[in] message_iterator
+    @parblock
+    Message iterator of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_message_iterator_put_ref() &mdash;
+    Decrements the reference count of a message iterator.
+*/
 extern void bt_message_iterator_get_ref(
                const bt_message_iterator *message_iterator);
 
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the message iterator \bt_p{message_iterator}.
+
+@param[in] message_iterator
+    @parblock
+    Message iterator of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_message_iterator_get_ref() &mdash;
+    Increments the reference count of a message iterator.
+*/
 extern void bt_message_iterator_put_ref(
                const bt_message_iterator *message_iterator);
 
-#define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_var) \
+/*!
+@brief
+    Decrements the reference count of the message iterator
+    \bt_p{_message_iterator}, and then sets \bt_p{_message_iterator}
+    to \c NULL.
+
+@param _message_iterator
+    @parblock
+    Message iterator of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_message_iterator}
+*/
+#define BT_MESSAGE_ITERATOR_PUT_REF_AND_RESET(_message_iterator)       \
        do {                                                            \
-               bt_message_iterator_put_ref(_var); \
-               (_var) = NULL;                                          \
+               bt_message_iterator_put_ref(_message_iterator);         \
+               (_message_iterator) = NULL;                             \
        } while (0)
 
-#define BT_MESSAGE_ITERATOR_MOVE_REF(_var_dst, _var_src) \
-       do {                                                            \
-               bt_message_iterator_put_ref(_var_dst); \
-               (_var_dst) = (_var_src);                                \
-               (_var_src) = NULL;                                      \
+/*!
+@brief
+    Decrements the reference count of the message iterator \bt_p{_dst},
+    sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
+    \c NULL.
+
+This macro effectively moves a message iterator reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_MESSAGE_ITERATOR_MOVE_REF(_dst, _src)       \
+       do {                                            \
+               bt_message_iterator_put_ref(_dst);      \
+               (_dst) = (_src);                        \
+               (_src) = NULL;                          \
        } while (0)
 
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/graph/message-message-iterator-inactivity-const.h b/include/babeltrace2/graph/message-message-iterator-inactivity-const.h
deleted file mode 100644 (file)
index ce5ed33..0000000
--- a/include/babeltrace2/graph/message-message-iterator-inactivity-const.h
+++ /dev/null
@@ -1,44 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_clock_snapshot *
-bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
-               const bt_message *msg);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_CONST_H */

diff --git a/include/babeltrace2/graph/message-message-iterator-inactivity.h b/include/babeltrace2/graph/message-message-iterator-inactivity.h
deleted file mode 100644 (file)
index dba7c4a..0000000
--- a/include/babeltrace2/graph/message-message-iterator-inactivity.h
+++ /dev/null
@@ -1,47 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_H
-#define BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-bt_message *bt_message_message_iterator_inactivity_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_clock_class *clock_class, uint64_t raw_value);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_H */

diff --git a/include/babeltrace2/graph/message-packet-beginning-const.h b/include/babeltrace2/graph/message-packet-beginning-const.h
deleted file mode 100644 (file)
index af2f747..0000000
--- a/include/babeltrace2/graph/message-packet-beginning-const.h
+++ /dev/null
@@ -1,51 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_packet *bt_message_packet_beginning_borrow_packet_const(
-               const bt_message *message);
-
-extern const bt_clock_snapshot *
-bt_message_packet_beginning_borrow_default_clock_snapshot_const(
-               const bt_message *msg);
-
-extern const bt_clock_class *
-bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
-               const bt_message *msg);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_CONST_H */

diff --git a/include/babeltrace2/graph/message-packet-beginning.h b/include/babeltrace2/graph/message-packet-beginning.h
deleted file mode 100644 (file)
index 93a9785..0000000
--- a/include/babeltrace2/graph/message-packet-beginning.h
+++ /dev/null
@@ -1,55 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_H
-#define BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-bt_message *bt_message_packet_beginning_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_packet *packet);
-
-extern
-bt_message *bt_message_packet_beginning_create_with_default_clock_snapshot(
-               bt_self_message_iterator *message_iterator,
-               const bt_packet *packet, uint64_t raw_value);
-
-extern bt_packet *bt_message_packet_beginning_borrow_packet(
-               bt_message *message);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_H */

diff --git a/include/babeltrace2/graph/message-packet-end-const.h b/include/babeltrace2/graph/message-packet-end-const.h
deleted file mode 100644 (file)
index 82e2bbd..0000000
--- a/include/babeltrace2/graph/message-packet-end-const.h
+++ /dev/null
@@ -1,51 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_END_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_PACKET_END_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_packet *bt_message_packet_end_borrow_packet_const(
-               const bt_message *message);
-
-extern const bt_clock_snapshot *
-bt_message_packet_end_borrow_default_clock_snapshot_const(
-               const bt_message *msg);
-
-extern const bt_clock_class *
-bt_message_packet_end_borrow_stream_class_default_clock_class_const(
-               const bt_message *msg);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_END_CONST_H */

diff --git a/include/babeltrace2/graph/message-packet-end.h b/include/babeltrace2/graph/message-packet-end.h
deleted file mode 100644 (file)
index a020179..0000000
--- a/include/babeltrace2/graph/message-packet-end.h
+++ /dev/null
@@ -1,55 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_END_H
-#define BABELTRACE2_GRAPH_MESSAGE_PACKET_END_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-bt_message *bt_message_packet_end_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_packet *packet);
-
-extern
-bt_message *bt_message_packet_end_create_with_default_clock_snapshot(
-               bt_self_message_iterator *message_iterator,
-               const bt_packet *packet, uint64_t raw_value);
-
-extern bt_packet *bt_message_packet_end_borrow_packet(
-               bt_message *message);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_END_H */

diff --git a/include/babeltrace2/graph/message-stream-beginning-const.h b/include/babeltrace2/graph/message-stream-beginning-const.h
deleted file mode 100644 (file)
index 69fdaa4..0000000
--- a/include/babeltrace2/graph/message-stream-beginning-const.h
+++ /dev/null
@@ -1,52 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-#include <babeltrace2/graph/message-stream-const.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_stream *bt_message_stream_beginning_borrow_stream_const(
-               const bt_message *message);
-
-extern bt_message_stream_clock_snapshot_state
-bt_message_stream_beginning_borrow_default_clock_snapshot_const(
-               const bt_message *message, const bt_clock_snapshot **snapshot);
-
-extern const bt_clock_class *
-bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
-               const bt_message *msg);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_CONST_H */

diff --git a/include/babeltrace2/graph/message-stream-beginning.h b/include/babeltrace2/graph/message-stream-beginning.h
deleted file mode 100644 (file)
index e7385c5..0000000
--- a/include/babeltrace2/graph/message-stream-beginning.h
+++ /dev/null
@@ -1,52 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_H
-#define BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-bt_message *bt_message_stream_beginning_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_stream *stream);
-
-extern bt_stream *bt_message_stream_beginning_borrow_stream(
-               bt_message *message);
-
-extern
-void bt_message_stream_beginning_set_default_clock_snapshot(
-               bt_message *message, uint64_t raw_value);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_H */

diff --git a/include/babeltrace2/graph/message-stream-const.h b/include/babeltrace2/graph/message-stream-const.h
deleted file mode 100644 (file)
index 8ecdfe7..0000000
--- a/include/babeltrace2/graph/message-stream-const.h
+++ /dev/null
@@ -1,43 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_STREAM_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_message_stream_clock_snapshot_state {
-       BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN = 0,
-       BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN = 1,
-} bt_message_stream_clock_snapshot_state;
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_CONST_H */

diff --git a/include/babeltrace2/graph/message-stream-end-const.h b/include/babeltrace2/graph/message-stream-end-const.h
deleted file mode 100644 (file)
index b822e3b..0000000
--- a/include/babeltrace2/graph/message-stream-end-const.h
+++ /dev/null
@@ -1,52 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_END_CONST_H
-#define BABELTRACE2_GRAPH_MESSAGE_STREAM_END_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-#include <babeltrace2/graph/message-stream-const.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_stream *bt_message_stream_end_borrow_stream_const(
-               const bt_message *message);
-
-extern bt_message_stream_clock_snapshot_state
-bt_message_stream_end_borrow_default_clock_snapshot_const(
-               const bt_message *message, const bt_clock_snapshot **snapshot);
-
-extern const bt_clock_class *
-bt_message_stream_end_borrow_stream_class_default_clock_class_const(
-               const bt_message *msg);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_END_CONST_H */

diff --git a/include/babeltrace2/graph/message-stream-end.h b/include/babeltrace2/graph/message-stream-end.h
deleted file mode 100644 (file)
index 34b98b8..0000000
--- a/include/babeltrace2/graph/message-stream-end.h
+++ /dev/null
@@ -1,52 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_END_H
-#define BABELTRACE2_GRAPH_MESSAGE_STREAM_END_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern
-bt_message *bt_message_stream_end_create(
-               bt_self_message_iterator *message_iterator,
-               const bt_stream *stream);
-
-extern bt_stream *bt_message_stream_end_borrow_stream(
-               bt_message *message);
-
-extern
-void bt_message_stream_end_set_default_clock_snapshot(
-               bt_message *message, uint64_t raw_value);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_END_H */

diff --git a/include/babeltrace2/graph/message.h b/include/babeltrace2/graph/message.h
new file mode 100644 (file)
index 0000000..34b98bc
--- /dev/null
+++ b/include/babeltrace2/graph/message.h
@@ -0,0 +1,3223 @@
+#ifndef BABELTRACE2_GRAPH_MESSAGE_H
+#define BABELTRACE2_GRAPH_MESSAGE_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <babeltrace2/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-msg Messages
+@ingroup api-comp-cls-dev
+
+@brief
+    Elements exchanged between \bt_p_comp.
+
+<strong><em>Messages</em></strong> are the objects which are exchanged
+between \bt_p_comp in a trace processing \bt_graph to accomplish a
+trace processing job.
+
+\bt_cp_msg_iter create messages while message iterators \em and
+\bt_p_sink_comp consume messages.
+
+There are eight types of messages:
+
+- \bt_c_sb_msg
+- \bt_c_se_msg
+- \bt_c_ev_msg
+- \bt_c_pb_msg
+- \bt_c_pe_msg
+- \bt_c_disc_ev_msg
+- \bt_c_disc_pkt_msg
+- \bt_c_inac_msg
+
+The type of a message is #bt_message.
+
+Get the type enumerator of a message with bt_message_get_type().
+
+A message is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_message_get_ref() and put an existing
+reference with bt_message_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" messages on
+success. The documentation of those functions indicate this
+postcondition.
+
+Messages transport objects of the \ref api-tir API, which is an
+intermediate representation of the tracing domain concepts.
+
+All types of messages, except the \bt_inac_msg type, are related to a
+specific <em>\bt_stream</em>, which represents a conceptual
+\ref api-msg-seq "sequence of messages".
+
+Some types of messages can have a default \bt_cs, depending on whether
+or not their stream has a conceptual default clock, that is, whether or
+not the stream's \ref api-tir-stream-cls "class" has a
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+The creation functions for those types of messages contain
+<code>_with_default_clock_snapshot</code> (for example,
+bt_message_event_create_with_default_clock_snapshot()).
+
+For the \bt_sb_msg and \bt_se_msg, the default clock snapshot property
+is optional, therefore they have dedicated
+bt_message_stream_beginning_set_default_clock_snapshot() and
+bt_message_stream_end_set_default_clock_snapshot() functions.
+
+All the message creation functions take a \bt_self_msg_iter as their
+first parameter. This is because a message iterator method is the only
+valid context to create a message.
+
+<h1>Message types</h1>
+
+This section details each type of message.
+
+The following table shows the creation functions and types for each type
+of message:
+
+<table>
+  <tr>
+    <th>Name
+    <th>Type enumerator
+    <th>Creation functions
+  <tr>
+    <td>\ref api-msg-sb "Stream beginning"
+    <td>#BT_MESSAGE_TYPE_STREAM_BEGINNING
+    <td>bt_message_stream_beginning_create()
+  <tr>
+    <td>\ref api-msg-se "Stream end"
+    <td>#BT_MESSAGE_TYPE_STREAM_END
+    <td>bt_message_stream_end_create()
+  <tr>
+    <td>\ref api-msg-ev "Event"
+    <td>#BT_MESSAGE_TYPE_EVENT
+    <td>
+      bt_message_event_create()<br>
+      bt_message_event_create_with_default_clock_snapshot()<br>
+      bt_message_event_create_with_packet()<br>
+      bt_message_event_create_with_packet_and_default_clock_snapshot()
+  <tr>
+    <td>\ref api-msg-pb "Packet beginning"
+    <td>#BT_MESSAGE_TYPE_PACKET_BEGINNING
+    <td>
+      bt_message_packet_beginning_create()<br>
+      bt_message_packet_beginning_create_with_default_clock_snapshot()
+  <tr>
+    <td>\ref api-msg-pe "Packet end"
+    <td>#BT_MESSAGE_TYPE_PACKET_END
+    <td>
+      bt_message_packet_end_create()<br>
+      bt_message_packet_end_create_with_default_clock_snapshot()
+  <tr>
+    <td>\ref api-msg-disc-ev "Discarded events"
+    <td>#BT_MESSAGE_TYPE_DISCARDED_EVENTS
+    <td>
+      bt_message_discarded_events_create()<br>
+      bt_message_discarded_events_create_with_default_clock_snapshots()
+  <tr>
+    <td>\ref api-msg-disc-pkt "Discarded packets"
+    <td>#BT_MESSAGE_TYPE_DISCARDED_PACKETS
+    <td>
+      bt_message_discarded_packets_create()<br>
+      bt_message_discarded_packets_create_with_default_clock_snapshots()
+  <tr>
+    <td>\ref api-msg-inac "Message iterator inactivity"
+    <td>#BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY
+    <td>bt_message_message_iterator_inactivity_create()
+</table>
+
+<h2>\anchor api-msg-sb Stream beginning message</h2>
+
+A <strong><em>stream beginning message</em></strong> indicates the
+beginning of a \bt_stream.
+
+For a given stream:
+
+- A stream beginning message is always the first one in the
+  \ref api-msg-seq "message sequence".
+
+- There can be only one stream beginning message.
+
+Create a stream beginning message with
+bt_message_stream_beginning_create().
+
+A stream beginning message has the following properties:
+
+<dl>
+  <dt>\anchor api-msg-sb-prop-stream Stream</dt>
+  <dd>
+    \bt_c_stream of which the message indicates the beginning.
+
+    You cannot change the stream once the message is created.
+
+    Borrow a stream beginning message's stream with
+    bt_message_stream_beginning_borrow_stream() and
+    bt_message_stream_beginning_borrow_stream_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-sb-prop-cs
+    \bt_dt_opt Default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock when the
+    stream begins.
+
+    A stream beginning message can only have a default clock snapshot
+    if its stream's \ref api-tir-stream-cls "class" has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    When a stream beginning message has no default clock snapshot,
+    then its time is <em>unknown</em>.
+
+    Set a stream beginning message's default clock snapshot with
+    bt_message_stream_beginning_set_default_clock_snapshot().
+
+    Borrow a stream beginning message's default clock snapshot with
+    bt_message_stream_beginning_borrow_default_clock_snapshot_const().
+  </dd>
+</dl>
+
+<h2>\anchor api-msg-se Stream end message</h2>
+
+A <strong><em>stream end message</em></strong> indicates the
+end of a \bt_stream.
+
+For a given stream:
+
+- A stream end message is always the last one in the
+  \ref api-msg-seq "message sequence".
+
+- There can be only one stream end message.
+
+Create a stream end message with bt_message_stream_end_create().
+
+A stream end message has the following properties:
+
+<dl>
+  <dt>\anchor api-msg-se-prop-stream Stream</dt>
+  <dd>
+    \bt_c_stream of which the message indicates the end.
+
+    You cannot change the stream once the message is created.
+
+    Borrow a stream end message's stream with
+    bt_message_stream_end_borrow_stream() and
+    bt_message_stream_end_borrow_stream_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-se-prop-cs
+    \bt_dt_opt Default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock when the
+    stream ends.
+
+    A stream end message can only have a default clock snapshot
+    if its stream's \ref api-tir-stream-cls "class" has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    When a stream end message has no default clock snapshot, then its
+    time is <em>unknown</em>.
+
+    Set a stream end message's default clock snapshot with
+    bt_message_stream_end_set_default_clock_snapshot().
+
+    Borrow a stream end message's default clock snapshot with
+    bt_message_stream_end_borrow_default_clock_snapshot_const().
+  </dd>
+</dl>
+
+<h2>\anchor api-msg-ev Event message</h2>
+
+An <strong><em>event message</em></strong> transports an \bt_ev and has,
+possibly, a default \bt_cs.
+
+Within its \bt_stream's \ref api-msg-seq "message sequence", an event
+message can only occur:
+
+<dl>
+  <dt>
+    If the stream's \ref api-tir-stream-cls "class"
+    \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
+  </dt>
+  <dd>After a \bt_pb_msg and before a \bt_pe_msg.</dd>
+
+  <dt>
+    If the stream's class does not support packets
+  </dt>
+  <dd>After the \bt_sb_msg and before the \bt_se_msg.</dd>
+</dl>
+
+To create an event message for a given stream, use:
+
+<dl>
+  <dt>
+    If the stream's \ref api-tir-stream-cls "class"
+    \ref api-tir-stream-cls-prop-supports-pkt "supports packets"
+  </dt>
+  <dd>
+    <dl>
+      <dt>
+        If the stream's class has a
+        \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+      </dt>
+      <dd>bt_message_event_create_with_packet_and_default_clock_snapshot()</dd>
+
+      <dt>
+        If the stream's class does not have a
+        \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+      </dt>
+      <dd>bt_message_event_create_with_packet()</dd>
+    </dl>
+
+    Those two creation functions accept a \bt_pkt parameter which is
+    the packet logically containing the message's event. A packet is
+    part of a stream.
+  </dd>
+
+  <dt>
+    If the stream's class does not supports packets
+  </dt>
+  <dd>
+    <dl>
+      <dt>
+        If the stream's class has a default clock class
+      </dt>
+      <dd>bt_message_event_create_with_default_clock_snapshot()</dd>
+
+      <dt>
+        If the stream's class does not have a
+        \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+      </dt>
+      <dd>bt_message_event_create()</dd>
+    </dl>
+  </dd>
+</dl>
+
+The four creation functions above accept an \bt_ev_cls parameter. When
+you create the message, the library instantiates this event class as an
+\bt_ev. Borrow the resulting event with bt_message_event_borrow_event().
+This event class must be part of the class of the event message's
+stream.
+
+An event message's event is initially <em>not set</em>: before you emit
+the event message from a \bt_msg_iter's
+\link api-msg-iter-cls-meth-next "next" method\endlink, you need to
+borrow each of its \bt_p_field (with bt_event_borrow_payload_field(),
+bt_event_borrow_specific_context_field(), and
+bt_event_borrow_common_context_field()) and, recursively, set the values
+of the all their inner fields.
+
+An event message has the following properties:
+
+<dl>
+  <dt>\anchor api-msg-ev-prop-ev Event</dt>
+  <dd>
+    \bt_c_ev which the message transports.
+
+    This is an instance of the \bt_ev_cls which was passed to the
+    message's creation function.
+
+    With this event, you can access its \bt_pkt (if any) with
+    bt_event_borrow_packet_const() and its
+    \bt_stream with bt_event_borrow_stream_const().
+
+    Borrow an event message's event with bt_message_event_borrow_event()
+    and bt_message_event_borrow_event_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-ev-prop-cs
+    \bt_dt_opt Default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock when the
+    event occurs.
+
+    An event message has a default clock snapshot
+    if its stream's \ref api-tir-stream-cls "class" has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class",
+    and has none otherwise.
+
+    Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
+    the default clock snapshot of an event message must be greater than
+    or equal to any default clock snapshot of any previous message.
+
+    Borrow an event message's default clock snapshot with
+    bt_message_event_borrow_default_clock_snapshot_const().
+  </dd>
+</dl>
+
+<h2>\anchor api-msg-pb Packet beginning message</h2>
+
+A <strong><em>packet beginning message</em></strong> indicates the
+beginning of a \bt_pkt.
+
+A packet beginning message can only exist if its \bt_stream's
+\ref api-tir-stream-cls "class"
+\ref api-tir-stream-cls-prop-supports-pkt "supports packets".
+
+For a given packet, there can be only one packet beginning message.
+
+Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
+beginning message can only occur after the \bt_sb_msg and before the
+\bt_se_msg.
+
+To create a packet beginning message for a given stream, use:
+
+<dl>
+  <dt>
+    If, for this stream's class,
+    \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot"
+  </dt>
+  <dd>bt_message_packet_beginning_create_with_default_clock_snapshot()</dd>
+
+  <dt>
+    If, for this stream's class, packets do not have a beginning default
+    clock snapshot
+  </dt>
+  <dd>bt_message_packet_beginning_create()</dd>
+</dl>
+
+A packet beginning message has the following properties:
+
+<dl>
+  <dt>\anchor api-msg-pb-prop-pkt Packet</dt>
+  <dd>
+    \bt_c_pkt of which the message indicates the beginning.
+
+    You cannot change the packet once the message is created.
+
+    Borrow a packet beginning message's packet with
+    bt_message_packet_beginning_borrow_packet() and
+    bt_message_packet_beginning_borrow_packet_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-pb-prop-cs
+    \bt_dt_opt Default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock when the
+    packet begins.
+
+    A packet beginning message has a default clock snapshot if:
+
+    - Its stream's \ref api-tir-stream-cls "class" has a
+      \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    - For its stream's class,
+      \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot".
+
+    Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
+    the default clock snapshot of a packet beginning message must be
+    greater than or equal to any clock snapshot of any previous message.
+
+    Borrow a packet beginning message's default clock snapshot with
+    bt_message_packet_beginning_borrow_default_clock_snapshot_const().
+  </dd>
+</dl>
+
+<h2>\anchor api-msg-pe Packet end message</h2>
+
+A <strong><em>packet end message</em></strong> indicates the
+end of a \bt_pkt.
+
+A packet end message can only exist if its \bt_stream's
+\ref api-tir-stream-cls "class"
+\ref api-tir-stream-cls-prop-supports-pkt "supports packets".
+
+For a given packet, there can be only one packet end message.
+
+Within its \bt_stream's \ref api-msg-seq "message sequence", a packet
+end message can only occur:
+
+- After the \bt_sb_msg and before the \bt_se_msg.
+- After a \bt_pb_msg for the same packet.
+
+To create a packet end message for a given stream, use:
+
+<dl>
+  <dt>
+    If, for this stream's class,
+    \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot"
+  </dt>
+  <dd>bt_message_packet_end_create_with_default_clock_snapshot()</dd>
+
+  <dt>
+    If, for this stream's class, packets do not have an end default
+    clock snapshot
+  </dt>
+  <dd>bt_message_packet_end_create()</dd>
+</dl>
+
+A packet end message has the following properties:
+
+<dl>
+  <dt>\anchor api-msg-pe-prop-pkt Packet</dt>
+  <dd>
+    \bt_c_pkt of which the message indicates the end.
+
+    You cannot change the packet once the message is created.
+
+    Borrow a packet end message's packet with
+    bt_message_packet_end_borrow_packet() and
+    bt_message_packet_end_borrow_packet_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-pe-prop-cs
+    \bt_dt_opt Default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock when the
+    packet ends.
+
+    A packet end message has a default clock snapshot if:
+
+    - Its stream's \ref api-tir-stream-cls "class" has a
+      \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    - For its stream's class,
+      \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot".
+
+    Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
+    the default clock snapshot of a packet end message must be greater
+    than or equal to any clock snapshot of any previous message.
+
+    Borrow a packet end message's default clock snapshot with
+    bt_message_packet_end_borrow_default_clock_snapshot_const().
+  </dd>
+</dl>
+
+<h2>\anchor api-msg-disc-ev Discarded events message</h2>
+
+A <strong><em>discarded events message</em></strong> indicates that
+events were discarded at <em>tracing time</em>. It does \em not indicate
+that \bt_p_ev_msg were dropped during a trace processing \bt_graph run.
+
+A discarded events message can only exist if its \bt_stream's
+\ref api-tir-stream-cls "class"
+\ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events".
+
+Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
+events message can only occur after the \bt_sb_msg and before the
+\bt_se_msg.
+
+To create a discarded events message for a given stream, use:
+
+<dl>
+  <dt>
+    If, for this stream's class,
+    \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots"
+  </dt>
+  <dd>bt_message_discarded_events_create_with_default_clock_snapshots()</dd>
+
+  <dt>
+    If, for this stream's class, discarded events do not have default
+    clock snapshots
+  </dt>
+  <dd>bt_message_discarded_events_create()</dd>
+</dl>
+
+A discarded events message has the following properties:
+
+<dl>
+  <dt>\anchor api-msg-disc-ev-prop-stream Stream</dt>
+  <dd>
+    \bt_c_stream into which events were discarded.
+
+    You cannot change the stream once the message is created.
+
+    Borrow a discarded events message's stream with
+    bt_message_discarded_events_borrow_stream() and
+    bt_message_discarded_events_borrow_stream_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-disc-ev-prop-cs-beg
+    \bt_dt_opt Beginning default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock which indicates
+    the beginning of the discarded events time range.
+
+    A discarded events message has a beginning default clock snapshot
+    if:
+
+    - Its stream's \ref api-tir-stream-cls "class" has a
+      \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    - For its stream's class,
+      \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
+
+    Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
+    the beginning default clock snapshot of a discarded events message
+    must be greater than or equal to any clock snapshot of any previous
+    message.
+
+    Borrow a discarded events message's beginning default clock snapshot
+    with
+    bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-disc-ev-prop-cs-end
+    \bt_dt_opt End default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock which indicates
+    the end of the discarded events time range.
+
+    A discarded events message has an end default clock snapshot if:
+
+    - Its stream's \ref api-tir-stream-cls "class" has a
+      \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    - For its stream's class,
+      \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots".
+
+    If a discarded events message has both a
+    \ref api-msg-disc-ev-prop-cs-beg "beginning" and an end default
+    clock snapshots, the end default clock snapshot must be greater than
+    or equal to the beginning default clock snapshot.
+
+    Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
+    the end default clock snapshot of a discarded events message must be
+    greater than or equal to any clock snapshot of any previous message.
+
+    Borrow a discarded events message's end default clock snapshot with
+    bt_message_discarded_events_borrow_end_default_clock_snapshot_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-disc-ev-prop-count
+    \bt_dt_opt Discarded event count
+  </dt>
+  <dd>
+    Exact number of discarded events.
+
+    If this property is missing, then the number of discarded events
+    is at least one.
+
+    Use bt_message_discarded_events_set_count() and
+    bt_message_discarded_events_get_count().
+  </dd>
+</dl>
+
+<h2>\anchor api-msg-disc-pkt Discarded packets message</h2>
+
+A <strong><em>discarded packets message</em></strong> indicates that
+packets were discarded at <em>tracing time</em>. It does \em not
+indicate that whole packets were dropped during a trace processing
+\bt_graph run.
+
+A discarded packets message can only exist if its \bt_stream's
+\ref api-tir-stream-cls "class"
+\ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets".
+
+Within its \bt_stream's \ref api-msg-seq "message sequence", a discarded
+packets message can only occur:
+
+- After the \bt_sb_msg.
+- Before the \bt_se_msg.
+- One of:
+  - Before any \bt_pb_msg.
+  - After any \bt_pe_msg.
+  - Between a packet end and a packet beginning message.
+
+To create a discarded packets message for a given stream, use:
+
+<dl>
+  <dt>
+    If, for this stream's class,
+    \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots"
+  </dt>
+  <dd>bt_message_discarded_packets_create_with_default_clock_snapshots()</dd>
+
+  <dt>
+    If, for this stream's class, discarded packets do not have default
+    clock snapshots
+  </dt>
+  <dd>bt_message_discarded_packets_create()</dd>
+</dl>
+
+A discarded packets message has the following properties:
+
+<dl>
+  <dt>\anchor api-msg-disc-pkt-prop-stream Stream</dt>
+  <dd>
+    \bt_c_stream into which packets were discarded.
+
+    You cannot change the stream once the message is created.
+
+    Borrow a discarded packets message's stream with
+    bt_message_discarded_packets_borrow_stream() and
+    bt_message_discarded_packets_borrow_stream_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-disc-pkt-prop-cs-beg
+    \bt_dt_opt Beginning default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock which indicates
+    the beginning of the discarded packets time range.
+
+    A discarded packets message has a beginning default clock snapshot
+    if:
+
+    - Its stream's \ref api-tir-stream-cls "class" has a
+      \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    - For its stream's class,
+      \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
+
+    Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
+    the beginning default clock snapshot of a discarded packets message
+    must be greater than or equal to any clock snapshot of any previous
+    message.
+
+    Borrow a discarded packets message's beginning default clock snapshot
+    with
+    bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-disc-pkt-prop-cs-end
+    \bt_dt_opt End default \bt_cs
+  </dt>
+  <dd>
+    Snapshot of the message's \bt_stream's default clock which indicates
+    the end of the discarded packets time range.
+
+    A discarded packets message has an end default clock snapshot if:
+
+    - Its stream's \ref api-tir-stream-cls "class" has a
+      \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    - For its stream's class,
+      \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots".
+
+    If a discarded packets message has both a
+    \ref api-msg-disc-pkt-prop-cs-beg "beginning" and an end default
+    clock snapshots, the end default clock snapshot must be greater than
+    or equal to the beginning default clock snapshot.
+
+    Within its \bt_msg_iter's \ref api-msg-seq "message sequence",
+    the end default clock snapshot of a discarded packets message must
+    be greater than or equal to any clock snapshot of any previous
+    message.
+
+    Borrow a discarded packets message's end default clock snapshot with
+    bt_message_discarded_packets_borrow_end_default_clock_snapshot_const().
+  </dd>
+
+  <dt>
+    \anchor api-msg-disc-pkt-prop-count
+    \bt_dt_opt Discarded packet count
+  </dt>
+  <dd>
+    Exact number of discarded packets.
+
+    If this property is missing, then the number of discarded packets
+    is at least one.
+
+    Use bt_message_discarded_packets_set_count() and
+    bt_message_discarded_packets_get_count().
+  </dd>
+</dl>
+
+<h2>\anchor api-msg-inac Message iterator inactivity</h2>
+
+A <strong><em>message iterator inactivity message</em></strong>
+indicates that, within the \ref api-msg-seq "message sequence" of a
+given \bt_msg_iter, there's no messages since the last message (if any)
+until a given point in time.
+
+A message iterator inactivity message is the only type of message that's
+not related to a \bt_stream: it targets the whole message sequence of a
+message iterator, and can occur at any position within the sequence.
+
+This message is mostly significant for real-time message iterators: if a
+message iterator A indicates that there's no messages until a given
+point in time T, then a downstream filter message iterator B which
+relies on multiple upstream message iterators does not have to wait for
+new messages from A until T.
+
+In other words, a message iterator inactivity message can help
+downstream message iterators or \bt_p_sink_comp <em>progress</em>.
+
+Create a message iterator inactivity message with
+bt_message_message_iterator_inactivity_create(). You must pass a
+\bt_clock_cls and the value of a fictitious (clock) instance to this
+function so that it creates a \bt_cs.
+
+A message iterator inactivity message has the following property:
+
+<dl>
+  <dt>
+    \anchor api-msg-inac-prop-cs
+    \bt_dt_opt \bt_c_cs
+  </dt>
+  <dd>
+    Snapshot of a fictitious instance of the message's \bt_clock_cls
+    which indicates the point in time until when there's no messages
+    in the message iterator's \ref api-msg-seq "message sequence".
+
+    Within its \bt_msg_iter's message sequence, the clock snapshot of a
+    message iterator inactivity message must be greater than or equal to
+    any clock snapshot of any previous message.
+
+    Borrow a message iterator inactivity message's clock snapshot
+    with
+    bt_message_message_iterator_inactivity_borrow_clock_snapshot_const().
+  </dd>
+</dl>
+
+<h1>\anchor api-msg-mip Message Interchange Protocol</h1>
+
+The <em>Message Interchange Protocol</em> (MIP) is the system of rules
+used by \bt_p_comp and \bt_p_msg_iter to exchance messages within a
+trace processing graph.
+
+The MIP covers everything related to messages and what they contain, as
+well as how they are ordered within the \ref api-msg-seq "sequence" that
+a message iterator produces.
+
+For example:
+
+- A valid message sequence for a given \bt_stream starts with a
+  \bt_sb_msg and ends with a \bt_se_msg.
+
+- The maximum
+  \ref api-tir-fc-int-prop-size "field value range" for an \bt_uint_fc
+  is [0,&nbsp;2<sup>64</sup>&nbsp;-&nbsp;1].
+
+- The available message types are stream beginning and end, event,
+  packet beginning and end, discarded events and packets, and message
+  iterator inactivity.
+
+The MIP has a version which is a single major number, independent from
+the \bt_name project's version. As of \bt_name_version_min_maj, the only
+available MIP version is 0.
+
+If what the MIP covers changes in a breaking or semantical way in the
+future, the MIP and \bt_name's minor versions will be bumped.
+
+When you create a trace processing \bt_graph with bt_graph_create(), you
+must pass the effective MIP version to use. Then, the components you
+\ref api-graph-lc-add "add" to this graph can access this configured MIP
+version with bt_self_component_get_graph_mip_version() and behave
+accordingly. In other words, if the configured MIP version is 0, then a
+component cannot use features introduced by MIP version&nbsp;1. For
+example, should the project introduce a new type of \bt_fc, the MIP
+version would be bumped.
+
+A component which cannot honor a given MIP can fail at
+initialization time, making the corresponding
+<code>bt_graph_add_*_component*()</code> call fail too. To avoid any
+surprise, you can create a \bt_comp_descr_set with descriptors of the
+components you intend to add to a trace processing graph and call
+bt_get_greatest_operative_mip_version() to get the greatest (most
+recent) MIP version you can use.
+
+To get the library's latest MIP version, use
+bt_get_maximal_mip_version().
+
+The ultimate goal of the MIP version feature is for the \bt_name project
+to be able to introduce new features or even major breaking changes
+without breaking existing \bt_p_comp_cls. This is especially important
+considering that \bt_name supports \bt_p_plugin written by different
+authors. Of course one of the project's objectives is to bump the MIP
+version as rarely as possible. When it is required, though, it's a
+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)
+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
+function documentation does not explicitly document a MIP version
+precondition, it means that the effective MIP version has no effect on
+said function's behaviour.
+
+<h2>\anchor api-msg-seq Message sequence rules</h2>
+
+The purpose of a \bt_msg_iter is to iterate a sequence of messages.
+
+Those messages can be related to different \bt_p_stream:
+
+@image html trace-structure-msg-seq.png "Messages of multiple streams as a single message sequence for a given message iterator."
+
+However, for such a message sequence, the current \bt_mip
+(version \bt_max_mip_version) dictates that:
+
+<ul>
+  <li>
+    For a given \bt_stream:
+
+    - The sequence must begin with a \bt_sb_msg.
+    - The sequence must end with a \bt_se_msg.
+    - <strong>If the stream's \ref api-tir-stream-cls "class"
+      \ref api-tir-stream-cls-prop-supports-pkt "supports packets"</strong>:
+      - Any \bt_pb_msg must be followed with a \bt_pe_msg.
+      - All \bt_p_ev_msg must be between a packet beginning and a
+        packet end message.
+      - A \bt_disc_pkt_msg must be (one of):
+        - Before the first packet beginning message.
+        - Between a packet end message and a packet beginning message.
+        - After the last packet end message.
+
+    The rules above can be summarized by the following regular
+    expressions:
+
+    <dl>
+      <dt>Without packets</dt>
+      <dd>
+        @code{.unparsed}
+        SB (E | DE)* SE
+        @endcode
+      </dd>
+
+      <dt>With packets</dt>
+      <dd>
+        @code{.unparsed}
+        SB ((PB (E | DE)* PE) | DE | DP)* SE
+        @endcode
+      </dd>
+    </dl>
+
+    With this alphabet:
+
+    <dl>
+      <dt>SB</dt>
+      <dd>\bt_c_sb_msg</dd>
+
+      <dt>SE</dt>
+      <dd>\bt_c_se_msg</dd>
+
+      <dt>E</dt>
+      <dd>\bt_c_ev_msg</dd>
+
+      <dt>PB</dt>
+      <dd>\bt_c_pb_msg</dd>
+
+      <dt>PE</dt>
+      <dd>\bt_c_pe_msg</dd>
+
+      <dt>DE</dt>
+      <dd>\bt_c_disc_ev_msg</dd>
+
+      <dt>DP</dt>
+      <dd>\bt_c_disc_pkt_msg</dd>
+    </dl>
+  <li>
+    For a given message iterator, for any message with a \bt_cs, its
+    clock snapshot must be greater than or equal to any clock snapshot
+    of any previous message.
+
+    For the scope of this rule, the clock snapshot of a \bt_disc_ev_msg
+    or of a \bt_disc_pkt_msg is its beginning default clock snapshot.
+  <li>
+    For a given message iterator, the \bt_p_cs of all the messages of
+    the sequence with a clock snapshot must be correlatable
+    (see \ref api-tir-clock-cls-origin "Clock value vs. clock class origin").
+</ul>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_message bt_message;
+
+@brief
+    Message.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+    Message type enumerators.
+*/
+typedef enum bt_message_type {
+       /*!
+       @brief
+           \bt_c_sb_msg.
+       */
+       BT_MESSAGE_TYPE_STREAM_BEGINNING                = 1 << 0,
+
+       /*!
+       @brief
+           \bt_c_se_msg.
+       */
+       BT_MESSAGE_TYPE_STREAM_END                      = 1 << 1,
+
+       /*!
+       @brief
+           \bt_c_ev_msg.
+       */
+       BT_MESSAGE_TYPE_EVENT                           = 1 << 2,
+
+       /*!
+       @brief
+           \bt_c_pb_msg.
+       */
+       BT_MESSAGE_TYPE_PACKET_BEGINNING                = 1 << 3,
+
+       /*!
+       @brief
+           \bt_c_pe_msg.
+       */
+       BT_MESSAGE_TYPE_PACKET_END                      = 1 << 4,
+
+       /*!
+       @brief
+           \bt_c_disc_ev_msg.
+       */
+       BT_MESSAGE_TYPE_DISCARDED_EVENTS                = 1 << 5,
+
+       /*!
+       @brief
+           \bt_c_disc_pkt_msg.
+       */
+       BT_MESSAGE_TYPE_DISCARDED_PACKETS               = 1 << 6,
+
+       /*!
+       @brief
+           \bt_c_inac_msg.
+       */
+       BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY     = 1 << 7,
+} bt_message_type;
+
+/*!
+@brief
+    Returns the type enumerator of the message \bt_p{message}.
+
+@param[in] message
+    Message of which to get the type enumerator
+
+@returns
+    Type enumerator of \bt_p{message}.
+
+@bt_pre_not_null{message}
+*/
+extern bt_message_type bt_message_get_type(const bt_message *message);
+
+/*! @} */
+
+/*!
+@name Common stream message
+@{
+*/
+
+/*!
+@brief
+    Return type of
+    bt_message_stream_beginning_borrow_default_clock_snapshot_const()
+    and
+    bt_message_stream_end_borrow_default_clock_snapshot_const().
+*/
+typedef enum bt_message_stream_clock_snapshot_state {
+       /*!
+       @brief
+           Known \bt_cs.
+       */
+       BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN    = 1,
+
+       /*!
+       @brief
+           Unknown (no) \bt_cs.
+       */
+       BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN  = 0,
+} bt_message_stream_clock_snapshot_state;
+
+/*! @} */
+
+/*!
+@name Stream beginning message
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_sb_msg for the \bt_stream \bt_p{stream} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+On success, the returned stream beginning message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-sb-prop-stream "Stream"
+    <td>\bt_p{stream}
+  <tr>
+    <td>\ref api-msg-sb-prop-cs "Default clock snapshot"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the stream beginning
+    message.
+@param[in] stream
+    Stream of which the message to create indicates the beginning.
+
+@returns
+    New stream beginning message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{stream}
+
+@bt_post_success_frozen{stream}
+*/
+extern
+bt_message *bt_message_stream_beginning_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_stream *stream);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}.
+
+See the \ref api-msg-sb-prop-stream "stream" property.
+
+@param[in] message
+    Stream beginning message from which to borrow the stream.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream of \bt_p{message}.
+
+    The returned pointer remains valid as long as \bt_p{message} exists.
+    @endparblock
+
+@bt_pre_not_null{message}
+@bt_pre_is_sb_msg{message}
+
+@sa bt_message_stream_beginning_borrow_stream_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_stream *bt_message_stream_beginning_borrow_stream(
+               bt_message *message);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_sb_msg \bt_p{message}
+    (\c const version).
+
+See bt_message_stream_beginning_borrow_stream().
+*/
+extern const bt_stream *bt_message_stream_beginning_borrow_stream_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Sets the value, in clock cycles, of the default \bt_cs of the
+    \bt_sb_msg \bt_p{message} to \bt_p{value}.
+
+See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
+
+@param[in] message
+    Stream beginning message of which to set the default clock snapshot
+    value to \bt_p{value}.
+@param[in] value
+    New value (clock cycles) of the default clock snapshot of
+    \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_hot{message}
+@bt_pre_is_sb_msg{message}
+@pre
+    The \bt_stream_cls of \bt_p{message} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+@sa bt_message_stream_beginning_borrow_default_clock_snapshot_const() &mdash;
+    Borrows the default clock snapshot of a stream beginning message.
+*/
+extern
+void bt_message_stream_beginning_set_default_clock_snapshot(
+               bt_message *message, uint64_t value);
+
+/*!
+@brief
+    Borrows the default \bt_cs of the \bt_sb_msg \bt_p{message}.
+
+See the \ref api-msg-sb-prop-cs "default clock snapshot" property.
+
+@param[in] message
+    Stream beginning message from which to borrow the default clock
+    snapshot.
+@param[out] clock_snapshot
+    <strong>If this function returns
+    #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
+    \bt_p{*clock_snapshot} is a \em borrowed reference of the default
+    clock snapshot of \bt_p{message}.
+
+@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
+    The default clock snapshot of \bt_p{message} is known and returned
+    as \bt_p{*clock_snapshot}.
+@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
+    \bt_p{message} has no default clock snapshot: its time is unknown.
+
+@bt_pre_not_null{message}
+@bt_pre_is_sb_msg{message}
+@pre
+    The \bt_stream_cls of \bt_p{message} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+@bt_pre_not_null{clock_snapshot}
+
+@sa bt_message_stream_beginning_set_default_clock_snapshot() &mdash;
+    Sets the default clock snapshot of a stream beginning message.
+*/
+extern bt_message_stream_clock_snapshot_state
+bt_message_stream_beginning_borrow_default_clock_snapshot_const(
+               const bt_message *message,
+               const bt_clock_snapshot **clock_snapshot);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls of the \bt_stream_cls
+    of the \bt_sb_msg \bt_p{message}.
+
+See the stream class's
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+This is a helper which is equivalent to
+
+@code
+bt_stream_class_borrow_default_clock_class_const(
+    bt_stream_borrow_class_const(
+        bt_message_stream_beginning_borrow_stream_const(message)))
+@endcode
+
+@param[in] message
+    Stream beginning message from which to borrow its stream's class's
+    default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    the stream class of \bt_p{message}, or \c NULL if none.
+
+@bt_pre_not_null{message}
+@bt_pre_is_sb_msg{message}
+*/
+extern const bt_clock_class *
+bt_message_stream_beginning_borrow_stream_class_default_clock_class_const(
+               const bt_message *message);
+
+/*! @} */
+
+/*!
+@name Stream end message
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_se_msg for the \bt_stream \bt_p{stream} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+On success, the returned stream end message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-se-prop-stream "Stream"
+    <td>\bt_p{stream}
+  <tr>
+    <td>\ref api-msg-se-prop-cs "Default clock snapshot"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the stream end
+    message.
+@param[in] stream
+    Stream of which the message to create indicates the end.
+
+@returns
+    New stream end message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{stream}
+
+@bt_post_success_frozen{stream}
+*/
+extern
+bt_message *bt_message_stream_end_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_stream *stream);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_se_msg \bt_p{message}.
+
+See the \ref api-msg-se-prop-stream "stream" property.
+
+@param[in] message
+    Stream end message from which to borrow the stream.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream of \bt_p{message}.
+
+    The returned pointer remains valid as long as \bt_p{message} exists.
+    @endparblock
+
+@bt_pre_not_null{message}
+@bt_pre_is_se_msg{message}
+
+@sa bt_message_stream_end_borrow_stream_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_stream *bt_message_stream_end_borrow_stream(
+               bt_message *message);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_se_msg \bt_p{message}
+    (\c const version).
+
+See bt_message_stream_end_borrow_stream().
+*/
+extern const bt_stream *bt_message_stream_end_borrow_stream_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Sets the value, in clock cycles, of the default \bt_cs of the
+    \bt_se_msg \bt_p{message} to \bt_p{value}.
+
+See the \ref api-msg-se-prop-cs "default clock snapshot" property.
+
+@param[in] message
+    Stream end message of which to set the default clock snapshot
+    value to \bt_p{value}.
+@param[in] value
+    New value (clock cycles) of the default clock snapshot of
+    \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_hot{message}
+@bt_pre_is_se_msg{message}
+@pre
+    The \bt_stream_cls of \bt_p{message} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+@sa bt_message_stream_end_borrow_default_clock_snapshot_const() &mdash;
+    Borrows the default clock snapshot of a stream end message.
+*/
+extern
+void bt_message_stream_end_set_default_clock_snapshot(
+               bt_message *message, uint64_t value);
+
+/*!
+@brief
+    Borrows the default \bt_cs of the \bt_se_msg \bt_p{message}.
+
+See the \ref api-msg-se-prop-cs "default clock snapshot" property.
+
+@param[in] message
+    Stream end message from which to borrow the default clock
+    snapshot.
+@param[out] clock_snapshot
+    <strong>If this function returns
+    #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN</strong>,
+    \bt_p{*clock_snapshot} is a \em borrowed reference of the default
+    clock snapshot of \bt_p{message}.
+
+@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN
+    The default clock snapshot of \bt_p{message} is known and returned
+    as \bt_p{*clock_snapshot}.
+@retval #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN
+    \bt_p{message} has no default clock snapshot: its time is unknown.
+
+@bt_pre_not_null{message}
+@bt_pre_is_se_msg{message}
+@pre
+    The \bt_stream_cls of \bt_p{message} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+@bt_pre_not_null{clock_snapshot}
+
+@sa bt_message_stream_end_set_default_clock_snapshot() &mdash;
+    Sets the default clock snapshot of a stream end message.
+*/
+extern bt_message_stream_clock_snapshot_state
+bt_message_stream_end_borrow_default_clock_snapshot_const(
+               const bt_message *message,
+               const bt_clock_snapshot **clock_snapshot);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls of the \bt_stream_cls
+    of the \bt_se_msg \bt_p{message}.
+
+See the stream class's
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+This is a helper which is equivalent to
+
+@code
+bt_stream_class_borrow_default_clock_class_const(
+    bt_stream_borrow_class_const(
+        bt_message_stream_end_borrow_stream_const(message)))
+@endcode
+
+@param[in] message
+    Stream end message from which to borrow its stream's class's
+    default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    the stream class of \bt_p{message}, or \c NULL if none.
+
+@bt_pre_not_null{message}
+@bt_pre_is_se_msg{message}
+*/
+extern const bt_clock_class *
+bt_message_stream_end_borrow_stream_class_default_clock_class_const(
+               const bt_message *message);
+
+/*! @} */
+
+/*!
+@name Event message
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
+    \bt_p{event_class}, for the \bt_stream \bt_p{stream} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns #BT_FALSE and
+
+    @code
+    bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns \c NULL.
+
+    Otherwise, use
+    bt_message_event_create_with_default_clock_snapshot(),
+    bt_message_event_create_with_packet(), or
+    bt_message_event_create_with_packet_and_default_clock_snapshot().
+    @endparblock
+
+On success, the returned event message has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-ev-prop-ev "Event"
+    <td>
+      An instance (with \bt_p_field that are not set) of
+      \bt_p{event_class}.
+  <tr>
+    <td>\ref api-msg-se-prop-cs "Default clock snapshot"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the event message.
+@param[in] event_class
+    Class of the \bt_ev of the message to create.
+@param[in] stream
+    Stream conceptually containing the event of the message to create.
+
+@returns
+    New event message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@pre
+    The \bt_stream_cls of \bt_p{event_class} is also the class of
+    \bt_p{stream}, that is,
+    <code>bt_event_class_borrow_stream_class_const(event_class)</code>
+    and
+    <code>bt_stream_borrow_class_const(stream)</code> have the
+    same value.
+@bt_pre_not_null{stream}
+@pre
+    <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
+    returns #BT_FALSE.
+@pre
+    <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
+    returns \c NULL.
+
+@bt_post_success_frozen{event_class}
+@bt_post_success_frozen{stream}
+*/
+extern
+bt_message *bt_message_event_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_event_class *event_class,
+               const bt_stream *stream);
+
+/*!
+@brief
+    Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
+    \bt_p{event_class} and a default \bt_cs with the value
+    \bt_p{clock_snapshot_value}, for the \bt_stream \bt_p{stream} from
+    the \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns #BT_FALSE and
+
+    @code
+    bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))
+    @endcode
+
+    does \em not return \c NULL.
+
+    Otherwise, use
+    bt_message_event_create(),
+    bt_message_event_create_with_packet(), or
+    bt_message_event_create_with_packet_and_default_clock_snapshot().
+    @endparblock
+
+On success, the returned event message has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-ev-prop-ev "Event"
+    <td>
+      An instance (with \bt_p_field that are not set) of
+      \bt_p{event_class}.
+  <tr>
+    <td>\ref api-msg-se-prop-cs "Default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the event message.
+@param[in] event_class
+    Class of the \bt_ev of the message to create.
+@param[in] stream
+    Stream conceptually containing the event of the message to create.
+@param[in] clock_snapshot_value
+    Value (clock cycles) of the default clock snapshot of
+    \bt_p{message}.
+
+@returns
+    New event message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@pre
+    The \bt_stream_cls of \bt_p{event_class} is also the class of
+    \bt_p{stream}, that is,
+    <code>bt_event_class_borrow_stream_class_const(event_class)</code>
+    and
+    <code>bt_stream_borrow_class_const(stream)</code> have the
+    same value.
+@bt_pre_not_null{stream}
+@pre
+    <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
+    returns #BT_FALSE.
+@pre
+    <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream))</code>
+    does \em not return \c NULL.
+
+@bt_post_success_frozen{event_class}
+@bt_post_success_frozen{stream}
+*/
+extern
+bt_message *bt_message_event_create_with_default_clock_snapshot(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_event_class *event_class,
+               const bt_stream *stream, uint64_t clock_snapshot_value);
+
+/*!
+@brief
+    Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
+    \bt_p{event_class}, for the \bt_pkt \bt_p{packet} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_supports_packets(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    returns #BT_TRUE and
+
+    @code
+    bt_stream_class_borrow_default_clock_class_const(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    returns \c NULL.
+
+    Otherwise, use
+    bt_message_event_create(),
+    bt_message_event_create_with_default_clock_snapshot(), or
+    bt_message_event_create_with_packet_and_default_clock_snapshot().
+    @endparblock
+
+On success, the returned event message has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-ev-prop-ev "Event"
+    <td>
+      An instance (with \bt_p_field that are not set) of
+      \bt_p{event_class}.
+  <tr>
+    <td>\ref api-msg-se-prop-cs "Default clock snapshot"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the event message.
+@param[in] event_class
+    Class of the \bt_ev of the message to create.
+@param[in] packet
+    Packet conceptually containing the event of the message to create.
+
+@returns
+    New event message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@pre
+    The \bt_stream_cls of \bt_p{event_class} is also the stream class of
+    \bt_p{packet}, that is,
+    <code>bt_event_class_borrow_stream_class_const(event_class)</code>
+    and
+    <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
+    have the same value.
+@bt_pre_not_null{packet}
+@pre
+    <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
+    returns #BT_TRUE.
+@pre
+    <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
+    returns \c NULL.
+@pre
+    The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
+    any, and all its contained \bt_p_field, recursively, are set.
+
+@bt_post_success_frozen{event_class}
+@bt_post_success_frozen{packet}
+*/
+extern
+bt_message *bt_message_event_create_with_packet(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_event_class *event_class,
+               const bt_packet *packet);
+
+/*!
+@brief
+    Creates an \bt_ev_msg, having an instance of the \bt_ev_cls
+    \bt_p{event_class} and a default \bt_cs with the value
+    \bt_p{clock_snapshot_value}, for the \bt_pkt \bt_p{packet} from
+    the \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_supports_packets(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    returns #BT_TRUE and
+
+    @code
+    bt_stream_class_borrow_default_clock_class_const(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    does \em not return \c NULL.
+
+    Otherwise, use
+    bt_message_event_create(),
+    bt_message_event_create_with_default_clock_snapshot(), or
+    bt_message_event_create_with_packet().
+    @endparblock
+
+On success, the returned event message has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-ev-prop-ev "Event"
+    <td>
+      An instance (with \bt_p_field that are not set) of
+      \bt_p{event_class}.
+  <tr>
+    <td>\ref api-msg-se-prop-cs "Default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the event message.
+@param[in] event_class
+    Class of the \bt_ev of the message to create.
+@param[in] packet
+    Packet conceptually containing the event of the message to create.
+@param[in] clock_snapshot_value
+    Value (clock cycles) of the default clock snapshot of
+    \bt_p{message}.
+
+@returns
+    New event message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@pre
+    The \bt_stream_cls of \bt_p{event_class} is also the stream class of
+    \bt_p{packet}, that is,
+    <code>bt_event_class_borrow_stream_class_const(event_class)</code>
+    and
+    <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>
+    have the same value.
+@bt_pre_not_null{packet}
+@pre
+    <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
+    returns #BT_TRUE.
+@pre
+    <code>bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))</code>
+    does \em not return \c NULL.
+@pre
+    The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
+    any, and all its contained \bt_p_field, recursively, are set.
+
+@bt_post_success_frozen{event_class}
+@bt_post_success_frozen{stream}
+*/
+extern
+bt_message *bt_message_event_create_with_packet_and_default_clock_snapshot(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_event_class *event_class,
+               const bt_packet *packet, uint64_t clock_snapshot_value);
+
+/*!
+@brief
+    Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}.
+
+See the \ref api-msg-ev-prop-ev "event" property.
+
+@param[in] message
+    Event message from which to borrow the event.
+
+@returns
+    @parblock
+    \em Borrowed reference of the event of \bt_p{message}.
+
+    The returned pointer remains valid as long as \bt_p{message} exists.
+    @endparblock
+
+@bt_pre_not_null{message}
+@bt_pre_is_ev_msg{message}
+
+@sa bt_message_event_borrow_event_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_event *bt_message_event_borrow_event(
+               bt_message *message);
+
+/*!
+@brief
+    Borrows the \bt_ev of the \bt_ev_msg \bt_p{message}
+    (\c const version).
+
+See bt_message_event_borrow_event().
+*/
+extern const bt_event *bt_message_event_borrow_event_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_cs of the \bt_ev_msg \bt_p{message}.
+
+See the \ref api-msg-ev-prop-cs "default clock snapshot" property.
+
+@param[in] message
+    Event message from which to borrow the default clock snapshot.
+
+@returns
+    Default clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_ev_msg{message}
+@pre
+    The \bt_stream_cls of \bt_p{message} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+*/
+extern const bt_clock_snapshot *
+bt_message_event_borrow_default_clock_snapshot_const(const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls of the \bt_stream_cls
+    of the \bt_ev_msg \bt_p{message}.
+
+See the stream class's
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+This is a helper which is equivalent to
+
+@code
+bt_stream_class_borrow_default_clock_class_const(
+    bt_stream_borrow_class_const(
+        bt_event_borrow_stream_const(
+            bt_message_event_borrow_event_const(message))))
+@endcode
+
+@param[in] message
+    Event message from which to borrow its stream's class's
+    default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    the stream class of \bt_p{message}, or \c NULL if none.
+
+@bt_pre_not_null{message}
+@bt_pre_is_ev_msg{message}
+*/
+extern const bt_clock_class *
+bt_message_event_borrow_stream_class_default_clock_class_const(
+               const bt_message *message);
+
+/*! @} */
+
+/*!
+@name Packet beginning message
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_pb_msg for the \bt_pkt \bt_p{packet} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_packets_have_beginning_default_clock_snapshot(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use
+    bt_message_packet_beginning_create_with_default_clock_snapshot().
+    @endparblock
+
+On success, the returned packet beginning message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-pb-prop-pkt "Packet"
+    <td>\bt_p{packet}
+  <tr>
+    <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the packet beginning
+    message.
+@param[in] packet
+    Packet of which the message to create indicates the beginning.
+
+@returns
+    New packet beginning message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{packet}
+@pre
+    bt_stream_class_packets_have_beginning_default_clock_snapshot()
+    returns #BT_FALSE for
+    <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
+@pre
+    The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
+    any, and all its contained \bt_p_field, recursively, are set.
+
+@bt_post_success_frozen{packet}
+*/
+extern
+bt_message *bt_message_packet_beginning_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_packet *packet);
+
+/*!
+@brief
+    Creates a \bt_pb_msg having a default \bt_cs with the value
+    \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_packets_have_beginning_default_clock_snapshot(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use
+    bt_message_packet_beginning_create().
+    @endparblock
+
+On success, the returned packet beginning message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-pb-prop-pkt "Packet"
+    <td>\bt_p{packet}
+  <tr>
+    <td>\ref api-msg-pb-prop-cs "Default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the packet beginning
+    message.
+@param[in] packet
+    Packet of which the message to create indicates the beginning.
+@param[in] clock_snapshot_value
+    Value (clock cycles) of the default clock snapshot of
+    \bt_p{message}.
+
+@returns
+    New packet beginning message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{packet}
+@pre
+    bt_stream_class_packets_have_beginning_default_clock_snapshot()
+    returns #BT_TRUE for
+    <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
+@pre
+    The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
+    any, and all its contained \bt_p_field, recursively, are set.
+
+@bt_post_success_frozen{packet}
+*/
+extern
+bt_message *bt_message_packet_beginning_create_with_default_clock_snapshot(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_packet *packet, uint64_t clock_snapshot_value);
+
+/*!
+@brief
+    Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}.
+
+See the \ref api-msg-pb-prop-pkt "packet" property.
+
+@param[in] message
+    Packet beginning message from which to borrow the packet.
+
+@returns
+    @parblock
+    \em Borrowed reference of the packet of \bt_p{message}.
+
+    The returned pointer remains valid as long as \bt_p{message} exists.
+    @endparblock
+
+@bt_pre_not_null{message}
+@bt_pre_is_pb_msg{message}
+
+@sa bt_message_packet_beginning_borrow_packet_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_packet *bt_message_packet_beginning_borrow_packet(
+               bt_message *message);
+
+/*!
+@brief
+    Borrows the \bt_pkt of the \bt_pb_msg \bt_p{message}
+    (\c const version).
+
+See bt_message_packet_beginning_borrow_packet().
+*/
+extern const bt_packet *bt_message_packet_beginning_borrow_packet_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_cs of the \bt_pb_msg \bt_p{message}.
+
+See the \ref api-msg-pb-prop-cs "default clock snapshot" property.
+
+@param[in] message
+    Packet beginning message from which to borrow the default clock
+    snapshot.
+
+@returns
+    Default clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_pb_msg{message}
+@pre
+    The packets of the \bt_stream_cls of \bt_p{message}
+    \ref api-tir-stream-cls-prop-pkt-beg-cs "have a beginning default clock snapshot".
+*/
+extern const bt_clock_snapshot *
+bt_message_packet_beginning_borrow_default_clock_snapshot_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls of the \bt_stream_cls
+    of the \bt_pb_msg \bt_p{message}.
+
+See the stream class's
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+This is a helper which is equivalent to
+
+@code
+bt_stream_class_borrow_default_clock_class_const(
+    bt_stream_borrow_class_const(
+        bt_packet_borrow_stream_const(
+            bt_message_packet_beginning_borrow_packet_const(message))))
+@endcode
+
+@param[in] message
+    Packet beginning message from which to borrow its stream's class's
+    default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    the stream class of \bt_p{message}, or \c NULL if none.
+
+@bt_pre_not_null{message}
+@bt_pre_is_pb_msg{message}
+*/
+extern const bt_clock_class *
+bt_message_packet_beginning_borrow_stream_class_default_clock_class_const(
+               const bt_message *message);
+
+/*! @} */
+
+/*!
+@name Packet end message
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_pe_msg for the \bt_pkt \bt_p{packet} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_packets_have_end_default_clock_snapshot(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use
+    bt_message_packet_end_create_with_default_clock_snapshot().
+    @endparblock
+
+On success, the returned packet end message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-pe-prop-pkt "Packet"
+    <td>\bt_p{packet}
+  <tr>
+    <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the packet end message.
+@param[in] packet
+    Packet of which the message to create indicates the end.
+
+@returns
+    New packet end message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{packet}
+@pre
+    bt_stream_class_packets_have_end_default_clock_snapshot()
+    returns #BT_FALSE for
+    <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
+@pre
+    The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
+    any, and all its contained \bt_p_field, recursively, are set.
+
+@bt_post_success_frozen{packet}
+*/
+extern
+bt_message *bt_message_packet_end_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_packet *packet);
+
+/*!
+@brief
+    Creates a \bt_pe_msg having a default \bt_cs with the value
+    \bt_p{clock_snapshot_value} for the \bt_pkt \bt_p{packet} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_packets_have_end_default_clock_snapshot(
+        bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)))
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use
+    bt_message_packet_end_create().
+    @endparblock
+
+On success, the returned packet end message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-pe-prop-pkt "Packet"
+    <td>\bt_p{packet}
+  <tr>
+    <td>\ref api-msg-pe-prop-cs "Default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{clock_snapshot_value}.
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the packet end
+    message.
+@param[in] packet
+    Packet of which the message to create indicates the end.
+@param[in] clock_snapshot_value
+    Value (clock cycles) of the default clock snapshot of
+    \bt_p{message}.
+
+@returns
+    New packet end message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{packet}
+@pre
+    bt_stream_class_packets_have_end_default_clock_snapshot()
+    returns #BT_TRUE for
+    <code>bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))</code>.
+@pre
+    The \ref api-tir-pkt-prop-ctx "context field" of \bt_p{packet}, if
+    any, and all its contained \bt_p_field, recursively, are set.
+
+@bt_post_success_frozen{packet}
+*/
+extern
+bt_message *bt_message_packet_end_create_with_default_clock_snapshot(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_packet *packet, uint64_t clock_snapshot_value);
+
+/*!
+@brief
+    Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}.
+
+See the \ref api-msg-pe-prop-pkt "packet" property.
+
+@param[in] message
+    Packet end message from which to borrow the packet.
+
+@returns
+    @parblock
+    \em Borrowed reference of the packet of \bt_p{message}.
+
+    The returned pointer remains valid as long as \bt_p{message} exists.
+    @endparblock
+
+@bt_pre_not_null{message}
+@bt_pre_is_pe_msg{message}
+
+@sa bt_message_packet_end_borrow_packet_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_packet *bt_message_packet_end_borrow_packet(
+               bt_message *message);
+
+/*!
+@brief
+    Borrows the \bt_pkt of the \bt_pe_msg \bt_p{message}
+    (\c const version).
+
+See bt_message_packet_end_borrow_packet().
+*/
+extern const bt_packet *bt_message_packet_end_borrow_packet_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_cs of the \bt_pe_msg \bt_p{message}.
+
+See the \ref api-msg-pe-prop-cs "default clock snapshot" property.
+
+@param[in] message
+    Packet end message from which to borrow the default clock
+    snapshot.
+
+@returns
+    Default clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_pe_msg{message}
+@pre
+    The packets of the \bt_stream_cls of \bt_p{message}
+    \ref api-tir-stream-cls-prop-pkt-end-cs "have an end default clock snapshot".
+*/
+extern const bt_clock_snapshot *
+bt_message_packet_end_borrow_default_clock_snapshot_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls of the \bt_stream_cls
+    of the \bt_pe_msg \bt_p{message}.
+
+See the stream class's
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+This is a helper which is equivalent to
+
+@code
+bt_stream_class_borrow_default_clock_class_const(
+    bt_stream_borrow_class_const(
+        bt_packet_borrow_stream_const(
+            bt_message_packet_end_borrow_packet_const(message))))
+@endcode
+
+@param[in] message
+    Packet end message from which to borrow its stream's class's
+    default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    the stream class of \bt_p{message}, or \c NULL if none.
+
+@bt_pre_not_null{message}
+@bt_pre_is_pe_msg{message}
+*/
+extern const bt_clock_class *
+bt_message_packet_end_borrow_stream_class_default_clock_class_const(
+               const bt_message *message);
+
+/*! @} */
+
+/*!
+@name Discarded events message
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_disc_ev_msg for the \bt_stream \bt_p{stream} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_discarded_events_have_default_clock_snapshots(
+        bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use
+    bt_message_discarded_events_create_with_default_clock_snapshots().
+    @endparblock
+
+On success, the returned discarded events message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-stream "Stream"
+    <td>\bt_p{stream}
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
+    <td>\em None
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
+    <td>\em None
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the discarded events
+    message.
+@param[in] stream
+    Stream from which the events were discarded.
+
+@returns
+    New discarded events message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{stream}
+@pre
+    <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
+    returns #BT_FALSE.
+
+@bt_post_success_frozen{stream}
+*/
+extern bt_message *bt_message_discarded_events_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_stream *stream);
+
+/*!
+@brief
+    Creates a \bt_disc_ev_msg having the beginning and end default
+    \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
+    \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
+    from the \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_discarded_events_have_default_clock_snapshots(
+        bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use
+    bt_message_discarded_events_create().
+    @endparblock
+
+On success, the returned discarded events message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-stream "Stream"
+    <td>\bt_p{stream}
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
+  <tr>
+    <td>\ref api-msg-disc-ev-prop-count "Discarded event count"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the discarded events
+    message.
+@param[in] stream
+    Stream from which the events were discarded.
+@param[in] beginning_clock_snapshot_value
+    Value (clock cycles) of the beginning default clock snapshot of
+    \bt_p{message}.
+@param[in] end_clock_snapshot_value
+    Value (clock cycles) of the end default clock snapshot of
+    \bt_p{message}.
+
+@returns
+    New discarded events message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{stream}
+@pre
+    <code>bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
+    returns #BT_TRUE.
+
+@bt_post_success_frozen{stream}
+*/
+extern bt_message *bt_message_discarded_events_create_with_default_clock_snapshots(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_stream *stream,
+               uint64_t beginning_clock_snapshot_value,
+               uint64_t end_clock_snapshot_value);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}.
+
+See the \ref api-msg-disc-ev-prop-stream "stream" property.
+
+@param[in] message
+    Discarded events message from which to borrow the stream.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream of \bt_p{message}.
+
+    The returned pointer remains valid as long as \bt_p{message} exists.
+    @endparblock
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_ev_msg{message}
+
+@sa bt_message_discarded_events_borrow_stream_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_stream *bt_message_discarded_events_borrow_stream(
+               bt_message *message);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_disc_ev_msg \bt_p{message}
+    (\c const version).
+
+See bt_message_discarded_events_borrow_stream().
+*/
+extern const bt_stream *
+bt_message_discarded_events_borrow_stream_const(const bt_message *message);
+
+/*!
+@brief
+    Borrows the beginning default \bt_cs of the \bt_disc_ev_msg
+    \bt_p{message}.
+
+See the
+\ref api-msg-disc-ev-prop-cs-beg "beginning default clock snapshot"
+property.
+
+@param[in] message
+    Discarded events message from which to borrow the beginning default
+    clock snapshot.
+
+@returns
+    Beginning default clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_ev_msg{message}
+@pre
+    The discarded packets messages of the \bt_stream_cls of
+    \bt_p{message}
+    \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
+*/
+extern const bt_clock_snapshot *
+bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the end default \bt_cs of the \bt_disc_ev_msg
+    \bt_p{message}.
+
+See the
+\ref api-msg-disc-ev-prop-cs-end "end default clock snapshot"
+property.
+
+@param[in] message
+    Discarded events message from which to borrow the end default clock
+    snapshot.
+
+@returns
+    End default clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_ev_msg{message}
+@pre
+    The discarded packets messages of the \bt_stream_cls of
+    \bt_p{message}
+    \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
+*/
+extern const bt_clock_snapshot *
+bt_message_discarded_events_borrow_end_default_clock_snapshot_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls of the \bt_stream_cls
+    of the \bt_disc_ev_msg \bt_p{message}.
+
+See the stream class's
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+This is a helper which is equivalent to
+
+@code
+bt_stream_class_borrow_default_clock_class_const(
+    bt_stream_borrow_class_const(
+        bt_message_discarded_events_borrow_stream_const(message)))
+@endcode
+
+@param[in] message
+    Discarded events message from which to borrow its stream's class's
+    default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    the stream class of \bt_p{message}, or \c NULL if none.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_ev_msg{message}
+*/
+extern const bt_clock_class *
+bt_message_discarded_events_borrow_stream_class_default_clock_class_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Sets the number of discarded events of the \bt_disc_ev_msg
+    \bt_p{message} to \bt_p{count}.
+
+See the \ref api-msg-disc-ev-prop-count "discarded event count"
+property.
+
+@param[in] message
+    Discarded events message of which to set the number of discarded
+    events to \bt_p{count}.
+@param[in] count
+    New number of discarded events of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_hot{message}
+@bt_pre_is_disc_ev_msg{message}
+
+@sa bt_message_discarded_events_get_count() &mdash;
+    Returns the number of discarded events of a discarded events
+    message.
+*/
+extern void bt_message_discarded_events_set_count(bt_message *message,
+               uint64_t count);
+
+/*!
+@brief
+    Returns the number of discarded events of the \bt_disc_ev_msg
+    \bt_p{message}.
+
+See the \ref api-msg-disc-ev-prop-count "discarded event count"
+property.
+
+@param[in] message
+    Discarded events message of which to get the number of discarded
+    events.
+@param[out] count
+    <strong>If this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
+    the number of discarded events of \bt_p{message}.
+
+@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
+    The number of discarded events of \bt_p{message} is available.
+@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
+    The number of discarded events of \bt_p{message} is not available.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_ev_msg{message}
+@bt_pre_not_null{count}
+
+@sa bt_message_discarded_events_set_count() &mdash;
+    Sets the number of discarded events of a discarded events message.
+*/
+extern bt_property_availability bt_message_discarded_events_get_count(
+               const bt_message *message, uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Discarded packets message
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_disc_pkt_msg for the \bt_stream \bt_p{stream} from the
+    \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_discarded_packets_have_default_clock_snapshots(
+        bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use
+    bt_message_discarded_packets_create_with_default_clock_snapshots().
+    @endparblock
+
+On success, the returned discarded packets message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-stream "Stream"
+    <td>\bt_p{stream}
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
+    <td>\em None
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
+    <td>\em None
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the discarded packets
+    message.
+@param[in] stream
+    Stream from which the packets were discarded.
+
+@returns
+    New discarded packets message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{stream}
+@pre
+    <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
+    returns #BT_FALSE.
+
+@bt_post_success_frozen{stream}
+*/
+extern bt_message *bt_message_discarded_packets_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_stream *stream);
+
+/*!
+@brief
+    Creates a \bt_disc_pkt_msg having the beginning and end default
+    \bt_p_cs with the values \bt_p{beginning_clock_snapshot_value} and
+    \bt_p{end_clock_snapshot_value} for the \bt_stream \bt_p{stream}
+    from the \bt_msg_iter \bt_p{self_message_iterator}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_discarded_packets_have_default_clock_snapshots(
+        bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use
+    bt_message_discarded_packets_create().
+    @endparblock
+
+On success, the returned discarded packets message has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-stream "Stream"
+    <td>\bt_p{stream}
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}.
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot"
+    <td>\bt_c_cs with the value \bt_p{end_clock_snapshot_value}.
+  <tr>
+    <td>\ref api-msg-disc-pkt-prop-count "Discarded packet count"
+    <td>\em None
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the discarded packets
+    message.
+@param[in] stream
+    Stream from which the packets were discarded.
+@param[in] beginning_clock_snapshot_value
+    Value (clock cycles) of the beginning default clock snapshot of
+    \bt_p{message}.
+@param[in] end_clock_snapshot_value
+    Value (clock cycles) of the end default clock snapshot of
+    \bt_p{message}.
+
+@returns
+    New discarded packets message reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{stream}
+@pre
+    <code>bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream))</code>
+    returns #BT_TRUE.
+
+@bt_post_success_frozen{stream}
+*/
+extern bt_message *bt_message_discarded_packets_create_with_default_clock_snapshots(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_stream *stream, uint64_t beginning_clock_snapshot_value,
+               uint64_t end_clock_snapshot_value);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}.
+
+See the \ref api-msg-disc-ev-prop-stream "stream" property.
+
+@param[in] message
+    Discarded packets message from which to borrow the stream.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream of \bt_p{message}.
+
+    The returned pointer remains valid as long as \bt_p{message} exists.
+    @endparblock
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_pkt_msg{message}
+
+@sa bt_message_discarded_packets_borrow_stream_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_stream *bt_message_discarded_packets_borrow_stream(
+               bt_message *message);
+
+/*!
+@brief
+    Borrows the \bt_stream of the \bt_disc_pkt_msg \bt_p{message}
+    (\c const version).
+
+See bt_message_discarded_packets_borrow_stream().
+*/
+extern const bt_stream *
+bt_message_discarded_packets_borrow_stream_const(const bt_message *message);
+
+/*!
+@brief
+    Borrows the beginning default \bt_cs of the \bt_disc_pkt_msg
+    \bt_p{message}.
+
+See the
+\ref api-msg-disc-pkt-prop-cs-beg "beginning default clock snapshot"
+property.
+
+@param[in] message
+    Discarded packets message from which to borrow the beginning default
+    clock snapshot.
+
+@returns
+    Beginning default clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_pkt_msg{message}
+@pre
+    The discarded packets messages of the \bt_stream_cls of
+    \bt_p{message}
+    \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
+*/
+extern const bt_clock_snapshot *
+bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the end default \bt_cs of the \bt_disc_pkt_msg
+    \bt_p{message}.
+
+See the
+\ref api-msg-disc-pkt-prop-cs-end "end default clock snapshot"
+property.
+
+@param[in] message
+    Discarded packets message from which to borrow the end default clock
+    snapshot.
+
+@returns
+    End default clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_pkt_msg{message}
+@pre
+    The discarded packets messages of the \bt_stream_cls of
+    \bt_p{message}
+    \ref api-tir-stream-cls-prop-disc-pkt-cs "have default clock snapshots".
+*/
+extern const bt_clock_snapshot *
+bt_message_discarded_packets_borrow_end_default_clock_snapshot_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls of the \bt_stream_cls
+    of the \bt_disc_pkt_msg \bt_p{message}.
+
+See the stream class's
+\ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+This is a helper which is equivalent to
+
+@code
+bt_stream_class_borrow_default_clock_class_const(
+    bt_stream_borrow_class_const(
+        bt_message_discarded_packets_borrow_stream_const(message)))
+@endcode
+
+@param[in] message
+    Discarded packets message from which to borrow its stream's class's
+    default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    the stream class of \bt_p{message}, or \c NULL if none.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_pkt_msg{message}
+*/
+extern const bt_clock_class *
+bt_message_discarded_packets_borrow_stream_class_default_clock_class_const(
+               const bt_message *message);
+
+/*!
+@brief
+    Sets the number of discarded packets of the \bt_disc_pkt_msg
+    \bt_p{message} to \bt_p{count}.
+
+See the \ref api-msg-disc-ev-prop-count "discarded packet count"
+property.
+
+@param[in] message
+    Discarded packets message of which to set the number of discarded
+    packets to \bt_p{count}.
+@param[in] count
+    New number of discarded packets of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_hot{message}
+@bt_pre_is_disc_pkt_msg{message}
+
+@sa bt_message_discarded_packets_get_count() &mdash;
+    Returns the number of discarded packets of a discarded packets
+    message.
+*/
+extern void bt_message_discarded_packets_set_count(bt_message *message,
+               uint64_t count);
+
+/*!
+@brief
+    Returns the number of discarded packets of the \bt_disc_pkt_msg
+    \bt_p{message}.
+
+See the \ref api-msg-disc-ev-prop-count "discarded packet count"
+property.
+
+@param[in] message
+    Discarded packets message of which to get the number of discarded
+    packets.
+@param[out] count
+    <strong>If this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*count} is
+    the number of discarded packets of \bt_p{message}.
+
+@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
+    The number of discarded packets of \bt_p{message} is available.
+@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
+    The number of discarded packets of \bt_p{message} is not available.
+
+@bt_pre_not_null{message}
+@bt_pre_is_disc_pkt_msg{message}
+@bt_pre_not_null{count}
+
+@sa bt_message_discarded_packets_set_count() &mdash;
+    Sets the number of discarded packets of a discarded packets message.
+*/
+extern bt_property_availability bt_message_discarded_packets_get_count(
+               const bt_message *message, uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Message iterator inactivity message
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_inac_msg having a \bt_cs of a fictitious instance of
+    the \bt_clock_cls \bt_p{clock_class} with the value
+    \bt_p{clock_snapshot_value} from the \bt_msg_iter
+    \bt_p{self_message_iterator}.
+
+On success, the returned message iterator inactivity message has the
+following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-msg-inac-prop-cs "Clock snapshot"
+    <td>
+      \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class})
+      with the value \bt_p{clock_snapshot_value}.
+</table>
+
+@param[in] self_message_iterator
+    Self message iterator from which to create the message iterator
+    inactivity message.
+@param[in] clock_class
+    Class of the fictitious instance of which
+    \bt_p{clock_snapshot_value} is the value of its snapshot.
+@param[in] clock_snapshot_value
+    Value (clock cycles) of the clock snapshot of \bt_p{message}.
+
+@returns
+    New message iterator inactivity message reference, or \c NULL on
+    memory error.
+
+@bt_pre_not_null{self_message_iterator}
+@bt_pre_not_null{clock_class}
+
+@bt_post_success_frozen{clock_class}
+*/
+extern
+bt_message *bt_message_message_iterator_inactivity_create(
+               bt_self_message_iterator *self_message_iterator,
+               const bt_clock_class *clock_class,
+               uint64_t clock_snapshot_value);
+
+/*!
+@brief
+    Borrows the \bt_cs of the \bt_inac_msg \bt_p{message}.
+
+See the \ref api-msg-inac-prop-cs "clock snapshot" property.
+
+@param[in] message
+    Message iterator inactivity message from which to borrow the clock
+    snapshot.
+
+@returns
+    Clock snapshot of \bt_p{message}.
+
+@bt_pre_not_null{message}
+@bt_pre_is_inac_msg{message}
+*/
+extern const bt_clock_snapshot *
+bt_message_message_iterator_inactivity_borrow_clock_snapshot_const(
+               const bt_message *message);
+
+/*! @} */
+
+/*!
+@name Message reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the message \bt_p{message}.
+
+@param[in] message
+    @parblock
+    Message of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_message_put_ref() &mdash;
+    Decrements the reference count of a message.
+*/
+extern void bt_message_get_ref(const bt_message *message);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the message \bt_p{message}.
+
+@param[in] message
+    @parblock
+    Message of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_message_get_ref() &mdash;
+    Increments the reference count of a message.
+*/
+extern void bt_message_put_ref(const bt_message *message);
+
+/*!
+@brief
+    Decrements the reference count of the message \bt_p{_message}, and
+    then sets \bt_p{_message} to \c NULL.
+
+@param _message
+    @parblock
+    Message of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_message}
+*/
+#define BT_MESSAGE_PUT_REF_AND_RESET(_message)         \
+       do {                                            \
+               bt_message_put_ref(_message);           \
+               (_message) = NULL;                      \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the message \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a message reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_MESSAGE_MOVE_REF(_dst, _src)                \
+       do {                                    \
+               bt_message_put_ref(_dst);       \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+
+/*!
+@name Message Interchange Protocol version
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_get_greatest_operative_mip_version().
+*/
+typedef enum bt_get_greatest_operative_mip_version_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK                 = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           No match found.
+       */
+       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH           = __BT_FUNC_STATUS_NO_MATCH,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR              = __BT_FUNC_STATUS_ERROR,
+} bt_get_greatest_operative_mip_version_status;
+
+/*!
+@brief
+    Computes the greatest \bt_mip version which
+    you can use to create a trace processing \bt_graph to which you
+    intend to \ref api-graph-lc-add "add components" described by the
+    component descriptors \bt_p{component_descriptors}, and sets
+    \bt_p{*mip_version} to the result.
+
+This function calls the
+\link api-comp-cls-dev-meth-mip "get supported MIP versions"\endlink
+method for each component descriptor in \bt_p{component_descriptors},
+and then returns the greatest common (operative) MIP version, if any.
+The "get supported MIP versions" method receives \bt_p{logging_level} as
+its \bt_p{logging_level} parameter.
+
+If this function does not find an operative MIP version for the
+component descriptors of \bt_p{component_descriptors}, it returns
+#BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH.
+
+@note
+    As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
+    returns 0, this function always sets \bt_p{*mip_version} to
+    0 on success.
+
+@param[in] component_descriptors
+    Component descriptors for which to get the supported MIP versions
+    to compute the greatest operative MIP version.
+@param[in] logging_level
+    Logging level to use when calling the "get supported MIP versions"
+    method for each component descriptor in
+    \bt_p{component_descriptors}.
+@param[out] mip_version
+    <strong>On success</strong>, \bt_p{*mip_version} is the greatest
+    operative MIP version of all the component descriptors in
+    \bt_p{component_descriptors}.
+
+@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK
+    Success.
+@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH
+    No operative MIP version exists for the component descriptors of
+    \bt_p{component_descriptors}.
+@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{component_descriptors}
+@pre
+    \bt_p{component_descriptors} contains one or more component
+    descriptors.
+@bt_pre_not_null{mip_version}
+*/
+extern bt_get_greatest_operative_mip_version_status
+bt_get_greatest_operative_mip_version(
+               const bt_component_descriptor_set *component_descriptors,
+               bt_logging_level logging_level, uint64_t *mip_version);
+
+/*!
+@brief
+    Returns the maximal available \bt_mip version as of
+    \bt_name_version_min_maj.
+
+As of \bt_name_version_min_maj, this function returns
+\bt_max_mip_version.
+
+@returns
+    Maximal available MIP version (\bt_max_mip_version).
+*/
+extern uint64_t bt_get_maximal_mip_version(void);
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_GRAPH_MESSAGE_H */

diff --git a/include/babeltrace2/graph/mip.h b/include/babeltrace2/graph/mip.h
deleted file mode 100644 (file)
index f5da87c..0000000
--- a/include/babeltrace2/graph/mip.h
+++ /dev/null
@@ -1,56 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_MIP_H
-#define BABELTRACE2_GRAPH_MIP_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_get_greatest_operative_mip_version_status {
-       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK                 = __BT_FUNC_STATUS_OK,
-       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR              = __BT_FUNC_STATUS_ERROR,
-       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH           = __BT_FUNC_STATUS_NO_MATCH,
-} bt_get_greatest_operative_mip_version_status;
-
-extern bt_get_greatest_operative_mip_version_status
-bt_get_greatest_operative_mip_version(
-               const bt_component_descriptor_set *comp_descriptor_set,
-               bt_logging_level log_level, uint64_t *operative_mip_version);
-
-extern uint64_t bt_get_maximal_mip_version(void);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_MIP_H */

diff --git a/include/babeltrace2/graph/port-const.h b/include/babeltrace2/graph/port-const.h
deleted file mode 100644 (file)
index eda9ccb..0000000
--- a/include/babeltrace2/graph/port-const.h
+++ /dev/null
@@ -1,88 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_PORT_CONST_H
-#define BABELTRACE2_GRAPH_PORT_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_port_type {
-       BT_PORT_TYPE_INPUT      = 1 << 0,
-       BT_PORT_TYPE_OUTPUT     = 1 << 1,
-} bt_port_type;
-
-extern const char *bt_port_get_name(const bt_port *port);
-
-extern bt_port_type bt_port_get_type(const bt_port *port);
-
-extern const bt_connection *bt_port_borrow_connection_const(
-               const bt_port *port);
-
-extern const bt_component *bt_port_borrow_component_const(
-               const bt_port *port);
-
-extern bt_bool bt_port_is_connected(const bt_port *port);
-
-static inline
-bt_bool bt_port_is_input(const bt_port *port)
-{
-       return bt_port_get_type(port) == BT_PORT_TYPE_INPUT;
-}
-
-static inline
-bt_bool bt_port_is_output(const bt_port *port)
-{
-       return bt_port_get_type(port) == BT_PORT_TYPE_OUTPUT;
-}
-
-extern void bt_port_get_ref(const bt_port *port);
-
-extern void bt_port_put_ref(const bt_port *port);
-
-#define BT_PORT_PUT_REF_AND_RESET(_var)                \
-       do {                                    \
-               bt_port_put_ref(_var);          \
-               (_var) = NULL;                  \
-       } while (0)
-
-#define BT_PORT_MOVE_REF(_var_dst, _var_src)   \
-       do {                                    \
-               bt_port_put_ref(_var_dst);      \
-               (_var_dst) = (_var_src);        \
-               (_var_src) = NULL;              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_PORT_CONST_H */

diff --git a/include/babeltrace2/graph/port-input-const.h b/include/babeltrace2/graph/port-input-const.h
deleted file mode 100644 (file)
index c3eff66..0000000
--- a/include/babeltrace2/graph/port-input-const.h
+++ /dev/null
@@ -1,65 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_PORT_INPUT_CONST_H
-#define BABELTRACE2_GRAPH_PORT_INPUT_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_port *bt_port_input_as_port_const(const bt_port_input *port_input)
-{
-       return __BT_UPCAST_CONST(bt_port, port_input);
-}
-
-extern void bt_port_input_get_ref(const bt_port_input *port_input);
-
-extern void bt_port_input_put_ref(const bt_port_input *port_input);
-
-#define BT_PORT_INPUT_PUT_REF_AND_RESET(_var)          \
-       do {                                            \
-               bt_port_input_put_ref(_var);            \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_PORT_INPUT_MOVE_REF(_var_dst, _var_src)     \
-       do {                                            \
-               bt_port_input_put_ref(_var_dst);        \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_PORT_INPUT_CONST_H */

diff --git a/include/babeltrace2/graph/port-output-const.h b/include/babeltrace2/graph/port-output-const.h
deleted file mode 100644 (file)
index 6d88926..0000000
--- a/include/babeltrace2/graph/port-output-const.h
+++ /dev/null
@@ -1,65 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_PORT_OUTPUT_CONST_H
-#define BABELTRACE2_GRAPH_PORT_OUTPUT_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_port *bt_port_output_as_port_const(const bt_port_output *port_output)
-{
-       return __BT_UPCAST_CONST(bt_port, port_output);
-}
-
-extern void bt_port_output_get_ref(const bt_port_output *port_output);
-
-extern void bt_port_output_put_ref(const bt_port_output *port_output);
-
-#define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_var)         \
-       do {                                            \
-               bt_port_output_put_ref(_var);           \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_PORT_OUTPUT_MOVE_REF(_var_dst, _var_src)    \
-       do {                                            \
-               bt_port_output_put_ref(_var_dst);       \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_PORT_OUTPUT_CONST_H */

diff --git a/include/babeltrace2/graph/port.h b/include/babeltrace2/graph/port.h
new file mode 100644 (file)
index 0000000..5567d04
--- /dev/null
+++ b/include/babeltrace2/graph/port.h
@@ -0,0 +1,673 @@
+#ifndef BABELTRACE2_GRAPH_PORT_H
+#define BABELTRACE2_GRAPH_PORT_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <stdint.h>
+
+#include <babeltrace2/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-port Ports
+@ingroup api-comp
+
+@brief
+    \bt_c_comp input and output ports.
+
+A <strong><em>port</em></strong> is a point of \bt_conn between
+\bt_p_comp:
+
+@image html component-zoom.png
+
+A port is a \ref api-fund-shared-object "shared object": get a new
+reference with bt_port_get_ref() and put an existing reference with
+bt_port_put_ref().
+
+The common C&nbsp;type of a port is #bt_port.
+
+There are two types of ports:
+
+<dl>
+  <dt>\anchor api-port-in Input port</dt>
+  <dd>
+    Input connection point from which \bt_p_msg are received.
+
+    Filter and sink components have input ports.
+
+    An input port's specific type is #bt_port_input and its type
+    enumerator is #BT_PORT_TYPE_INPUT.
+
+    \ref api-fund-c-typing "Upcast" the #bt_port_input type to the
+    #bt_port type with bt_port_input_as_port_const().
+
+    Get a new input port reference with bt_port_input_get_ref() and put
+    an existing one with bt_port_input_put_ref().
+  </dd>
+
+  <dt>\anchor api-port-out Output port</dt>
+  <dd>
+    Output connection point to which messages are sent.
+
+    Source and filter components have output ports.
+
+    An output port's specific type is #bt_port_output and its type
+    enumerator is #BT_PORT_TYPE_OUTPUT.
+
+    \ref api-fund-c-typing "Upcast" the #bt_port_output type to the
+    #bt_port type with bt_port_output_as_port_const().
+
+    Get a new output port reference with bt_port_output_get_ref() and
+    put an existing one with bt_port_output_put_ref().
+  </dd>
+</dl>
+
+Get a port's type enumerator with bt_port_get_type(). You can also use
+the bt_port_is_input() and bt_port_is_output() helper functions.
+
+A \bt_comp can add a port with:
+
+- bt_self_component_source_add_output_port()
+- bt_self_component_filter_add_input_port()
+- bt_self_component_filter_add_output_port()
+- bt_self_component_sink_add_input_port()
+
+Borrow a port's \bt_conn, if any, with
+bt_port_borrow_connection_const().
+
+Borrow the component to which a port belongs with
+bt_port_borrow_component_const().
+
+<h1>Properties</h1>
+
+A port has the following common properties:
+
+<dl>
+  <dt>
+    \anchor api-port-prop-name
+    Name
+  </dt>
+  <dd>
+    Name of the port.
+
+    For a given \bt_comp:
+
+    - Each input port has a unique name.
+    - Each output port has a unique name.
+
+    A port's name is set when the component adds it; you cannot change
+    it afterwards.
+
+    Get a port's name with bt_port_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-port-prop-is-connected
+    Is connected?
+  </dt>
+  <dd>
+    Whether or not the port is currently connected to another port.
+
+    Get whether or not a port is connected with bt_port_is_connected().
+
+    When a port is unconnected, bt_port_borrow_connection_const()
+    returns \c NULL.
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_port bt_port;
+
+@brief
+    Port.
+
+@typedef struct bt_port_input bt_port_input;
+
+@brief
+    \bt_c_iport.
+
+@typedef struct bt_port_output bt_port_output;
+
+@brief
+    \bt_c_oport.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+    Port type enumerators.
+*/
+typedef enum bt_port_type {
+       /*!
+       @brief
+           \bt_c_iport.
+       */
+       BT_PORT_TYPE_INPUT      = 1 << 0,
+
+       /*!
+       @brief
+           \bt_c_oport.
+       */
+       BT_PORT_TYPE_OUTPUT     = 1 << 1,
+} bt_port_type;
+
+/*!
+@brief
+    Returns the type enumerator of the port \bt_p{port}.
+
+@param[in] port
+    Port of which to get the type enumerator
+
+@returns
+    Type enumerator of \bt_p{port}.
+
+@bt_pre_not_null{port}
+
+@sa bt_port_is_input() &mdash;
+    Returns whether or not a port is an \bt_iport.
+@sa bt_port_is_output() &mdash;
+    Returns whether or not a port is an \bt_oport.
+*/
+extern bt_port_type bt_port_get_type(const bt_port *port);
+
+/*!
+@brief
+    Returns whether or not the port \bt_p{port} is an \bt_iport.
+
+@param[in] port
+    Port to check.
+
+@returns
+    #BT_TRUE if \bt_p{port} is an input port.
+
+@bt_pre_not_null{port}
+
+@sa bt_port_get_type() &mdash;
+    Returns the type enumerator of a port.
+*/
+static inline
+bt_bool bt_port_is_input(const bt_port *port)
+{
+       return bt_port_get_type(port) == BT_PORT_TYPE_INPUT;
+}
+
+/*!
+@brief
+    Returns whether or not the port \bt_p{port} is an \bt_oport.
+
+@param[in] port
+    Port to check.
+
+@returns
+    #BT_TRUE if \bt_p{port} is an output port.
+
+@bt_pre_not_null{port}
+
+@sa bt_port_get_type() &mdash;
+    Returns the type enumerator of a port.
+*/
+static inline
+bt_bool bt_port_is_output(const bt_port *port)
+{
+       return bt_port_get_type(port) == BT_PORT_TYPE_OUTPUT;
+}
+
+/*! @} */
+
+/*!
+@name Connection access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_conn of the port \bt_p{port}.
+
+This function returns \c NULL if \bt_p{port} is unconnected
+(bt_port_is_connected() returns #BT_FALSE).
+
+@param[in] port
+    Port of which to borrow the connection.
+
+@returns
+    \em Borrowed reference of the connection of \bt_p{port}.
+
+@bt_pre_not_null{port}
+*/
+extern const bt_connection *bt_port_borrow_connection_const(
+               const bt_port *port);
+
+/*! @} */
+
+/*!
+@name Component access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_comp to which the port \bt_p{port} belongs.
+
+@param[in] port
+    Port of which to borrow the component which owns it.
+
+@returns
+    \em Borrowed reference of the component which owns \bt_p{port}.
+
+@bt_pre_not_null{port}
+*/
+extern const bt_component *bt_port_borrow_component_const(
+               const bt_port *port);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Returns the name of the port \bt_p{port}.
+
+See the \ref api-port-prop-name "name" property.
+
+@param[in] port
+    Port of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{port}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{port} exists.
+    @endparblock
+
+@bt_pre_not_null{port}
+*/
+extern const char *bt_port_get_name(const bt_port *port);
+
+/*!
+@brief
+    Returns whether or not the port \bt_p{port} is connected.
+
+See the \ref api-port-prop-is-connected "is connected?" property.
+
+@param[in] port
+    Port of which to get whether or not it's connected.
+
+@returns
+    #BT_TRUE if \bt_p{port} is connected.
+
+@bt_pre_not_null{port}
+*/
+extern bt_bool bt_port_is_connected(const bt_port *port);
+
+/*! @} */
+
+/*!
+@name Reference count (common)
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the port \bt_p{port}.
+
+@param[in] port
+    @parblock
+    Port of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_port_put_ref() &mdash;
+    Decrements the reference count of a port.
+*/
+extern void bt_port_get_ref(const bt_port *port);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the port \bt_p{port}.
+
+@param[in] port
+    @parblock
+    Port of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_port_get_ref() &mdash;
+    Increments the reference count of a port.
+*/
+extern void bt_port_put_ref(const bt_port *port);
+
+/*!
+@brief
+    Decrements the reference count of the port
+    \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
+
+@param _port
+    @parblock
+    Port of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_port}
+*/
+#define BT_PORT_PUT_REF_AND_RESET(_port)       \
+       do {                                    \
+               bt_port_put_ref(_port);         \
+               (_port) = NULL;                 \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the port \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a port reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_PORT_MOVE_REF(_dst, _src)   \
+       do {                            \
+               bt_port_put_ref(_dst);  \
+               (_dst) = (_src);        \
+               (_src) = NULL;          \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Input port
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_iport \bt_p{port} to the
+    common #bt_port type.
+
+@param[in] port
+    @parblock
+    Input port to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{port} as a common port.
+*/
+static inline
+const bt_port *bt_port_input_as_port_const(const bt_port_input *port)
+{
+       return __BT_UPCAST_CONST(bt_port, port);
+}
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_iport \bt_p{port}.
+
+@param[in] port
+    @parblock
+    Input port of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_port_input_put_ref() &mdash;
+    Decrements the reference count of an input port.
+*/
+extern void bt_port_input_get_ref(const bt_port_input *port);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_iport \bt_p{port}.
+
+@param[in] port
+    @parblock
+    Input port of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_port_input_get_ref() &mdash;
+    Increments the reference count of an input port.
+*/
+extern void bt_port_input_put_ref(const bt_port_input *port);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_iport
+    \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
+
+@param _port
+    @parblock
+    Input port of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_port}
+*/
+#define BT_PORT_INPUT_PUT_REF_AND_RESET(_port)         \
+       do {                                            \
+               bt_port_input_put_ref(_port);           \
+               (_port) = NULL;                         \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_iport \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves an \bt_iport reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_PORT_INPUT_MOVE_REF(_dst, _src)     \
+       do {                                    \
+               bt_port_input_put_ref(_dst);    \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Output port
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_oport \bt_p{port} to the
+    common #bt_port type.
+
+@param[in] port
+    @parblock
+    Output port to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{port} as a common port.
+*/
+static inline
+const bt_port *bt_port_output_as_port_const(const bt_port_output *port)
+{
+       return __BT_UPCAST_CONST(bt_port, port);
+}
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the \bt_oport \bt_p{port}.
+
+@param[in] port
+    @parblock
+    Output port of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_port_output_put_ref() &mdash;
+    Decrements the reference count of a \bt_oport.
+*/
+extern void bt_port_output_get_ref(const bt_port_output *port);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the \bt_oport \bt_p{port}.
+
+@param[in] port
+    @parblock
+    Output port of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_port_output_get_ref() &mdash;
+    Increments the reference count of a \bt_oport.
+*/
+extern void bt_port_output_put_ref(const bt_port_output *port);
+
+/*!
+@brief
+    Decrements the reference count of the \bt_oport
+    \bt_p{_port}, and then sets \bt_p{_port} to \c NULL.
+
+@param _port
+    @parblock
+    Output port of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_port}
+*/
+#define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port)                \
+       do {                                            \
+               bt_port_output_put_ref(_port);          \
+               (_port) = NULL;                         \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the \bt_oport \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves an \bt_oport reference from the
+expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
+existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_PORT_OUTPUT_MOVE_REF(_dst, _src)    \
+       do {                                    \
+               bt_port_output_put_ref(_dst);   \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_GRAPH_PORT_H */

diff --git a/include/babeltrace2/graph/private-query-executor.h b/include/babeltrace2/graph/private-query-executor.h
index 348d30d4d221e59629b41fbe642a4c0eac856540..79b1f5f8fb8964fb8ef20adb77fd6b01632287ba 100644 (file)
--- a/include/babeltrace2/graph/private-query-executor.h
+++ b/include/babeltrace2/graph/private-query-executor.h
@@ -33,6 +33,63 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-priv-qexec Private query executor
+@ingroup api-comp-cls-dev
+
+@brief
+    Private view of a \bt_qexec for a \bt_comp_cls
+    \ref api-comp-cls-dev-meth-query "query method".
+
+A <strong><em>private query executor</em></strong> is a private view,
+from within a \bt_comp_cls
+\ref api-comp-cls-dev-meth-query "query method", of a
+\bt_qexec.
+
+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
+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
+\ref api-qexec-prop-log-lvl "logging level".
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_private_query_executor bt_private_query_executor;
+
+@brief
+    Private query executor.
+
+@}
+*/
+
+/*!
+@name Upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the private query executor
+    \bt_p{query_executor} to the public #bt_query_executor type.
+
+@param[in] query_executor
+    @parblock
+    Private query executor to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{query_executor} as a public query executor.
+*/
 static inline
 const bt_query_executor *
 bt_private_query_executor_as_query_executor_const(
@@ -41,6 +98,10 @@ bt_private_query_executor_as_query_executor_const(
        return __BT_UPCAST_CONST(bt_query_executor, query_executor);
 }
 
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/graph/query-executor-const.h b/include/babeltrace2/graph/query-executor-const.h
deleted file mode 100644 (file)
index a857ed7..0000000
--- a/include/babeltrace2/graph/query-executor-const.h
+++ /dev/null
@@ -1,63 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_CONST_H
-#define BABELTRACE2_GRAPH_QUERY_EXECUTOR_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern bt_bool bt_query_executor_is_interrupted(
-               const bt_query_executor *query_executor);
-
-extern bt_logging_level bt_query_executor_get_logging_level(
-               const bt_query_executor *query_executor);
-
-extern void bt_query_executor_get_ref(const bt_query_executor *query_executor);
-
-extern void bt_query_executor_put_ref(const bt_query_executor *query_executor);
-
-#define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_var)              \
-       do {                                                    \
-               bt_query_executor_put_ref(_var);                \
-               (_var) = NULL;                                  \
-       } while (0)
-
-#define BT_QUERY_EXECUTOR_MOVE_REF(_var_dst, _var_src)         \
-       do {                                                    \
-               bt_query_executor_put_ref(_var_dst);            \
-               (_var_dst) = (_var_src);                        \
-               (_var_src) = NULL;                              \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_CONST_H */

diff --git a/include/babeltrace2/graph/query-executor.h b/include/babeltrace2/graph/query-executor.h
index c393e6ec7668c9a08d408f8aaf6972c3e40401a9..a3d1c6376bbb88bf6ab57b27d868b3525a50e612 100644 (file)
--- a/include/babeltrace2/graph/query-executor.h
+++ b/include/babeltrace2/graph/query-executor.h
@@ -34,47 +34,547 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-qexec Query executor
+@ingroup api-graph
+
+@brief
+    Executor of \bt_comp_cls object queries.
+
+A <strong><em>query executor</em></strong> is an executor of
+\bt_comp_cls object queries.
+
+A component class can implement a query method to offer one or more
+\em objects depending on the query parameters.
+
+Both the query parameters and the returned objects are \bt_p_val.
+
+The query operation feature exists so that you can get benefit from a
+component class's implementation to get information about a trace, a
+stream, a distant server, and so on. For example, the
+<code>source.ctf.lttng-live</code> component class (see
+\bt_man{babeltrace2-source.ctf.lttng-live,7}) offers the \c sessions
+object to list the available
+<a href="https://lttng.org/docs/#doc-lttng-live">LTTng live</a>
+tracing session names and other properties.
+
+The semantics of the query parameters and the returned object are
+completely defined by the component class implementation: the library
+does not enforce or suggest any layout. The best way to know which
+objects you can query from a component class, what are the expected and
+optional parameters, and what the returned object contains is to read
+this component class's documentation.
+
+The purpose of the query executor itself is to keep some state for a
+specific query operation. For example, you can set a query executor's
+logging level with bt_query_executor_set_logging_level(); then a
+component class's query method can get the executor's current logging
+level with bt_query_executor_get_logging_level().
+
+Also, the query executor is an interruptible object: a long or blocking
+query operation can run, checking whether the executor is interrupted
+periodically, while another thread or a signal handler can interrupt the
+executor.
+
+A query executor is a
+\ref api-fund-shared-object "shared object": get a new reference with
+bt_query_executor_get_ref() and put an existing reference with
+bt_query_executor_put_ref().
+
+The type of a query executor is #bt_query_executor.
+
+Create a query executor with bt_query_executor_create() or
+bt_query_executor_create_with_method_data(). When you do so, you set the
+name of the object to query, from which component class to query the
+object, and what are the query parameters. You cannot change those
+properties once the query executor is created. With
+bt_query_executor_create_with_method_data(), you can also pass
+a custom, \bt_voidp pointer to the component class's
+query method.
+
+Perform a query operation with bt_query_executor_query(). This function
+can return #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN, in which case you can
+try to perform a query operation again later. It can also return
+#BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT, which means the
+component class does not offer the requested object.
+
+To interrupt a running query operation, either:
+
+- Borrow the query executor's default \bt_intr with
+  bt_query_executor_borrow_default_interrupter() and set it with
+  bt_interrupter_set().
+
+  When you call bt_query_executor_create() or
+  bt_query_executor_create_with_method_data(), the returned query
+  executor has a default interrupter.
+
+- Add your own interrupter with bt_query_executor_add_interrupter()
+  \em before you perform the query operation with
+  bt_query_executor_query().
+
+  Then, set the interrupter with bt_interrupter_set().
+
+<h1>Property</h1>
+
+A query executor has the following property:
+
+<dl>
+  <dt>
+    \anchor api-qexec-prop-log-lvl
+    Logging level
+  </dt>
+  <dd>
+    Logging level of the query executor's query operations.
+
+    Use bt_query_executor_set_logging_level() and
+    bt_query_executor_get_logging_level().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_query_executor bt_query_executor;
+
+@brief
+    Query executor.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Alias of bt_query_executor_create_with_method_data()
+    with the \bt_p{method_data} parameter set to \c NULL.
+*/
 extern
 bt_query_executor *bt_query_executor_create(
-               const bt_component_class *component_class, const char *object,
-               const bt_value *params);
+               const bt_component_class *component_class,
+               const char *object_name, const bt_value *params);
+
+/*!
+@brief
+    Creates a query executor to query the object named
+    \bt_p{object_name} from the \bt_comp_cls \bt_p{component_class} with
+    the parameters \bt_p{params} and the query user data
+    \bt_p{method_data}.
+
+When you call bt_query_executor_query() with the returned query
+executor, the query method of \bt_p{component_class} receives:
+
+- \bt_p{object_name} as its own \bt_p{object_name} parameter.
 
+- \bt_p{params} as its own \bt_p{params} parameter
+  (or #bt_value_null if \bt_p{params} is \c NULL).
+
+- \bt_p{method_data} as its own \bt_p{method_data} parameter.
+
+@param[in] component_class
+    Component class from which to query the object named
+    \bt_p{object_name}.
+@param[in] object_name
+    Name of the object to query from \bt_p{component_class}.
+@param[in] params
+    @parblock
+    Parameters for the query operation performed by the query executor
+    to create.
+
+    Unlike the \bt_p{params} parameter of
+    the <code>bt_graph_add_*_component_*_port_added_listener()</code>
+    functions (see \ref api-graph), this parameter does not need to
+    be a \bt_map_val.
+
+    Can be \c NULL (equivalent to passing #bt_value_null).
+    @endparblock
+@param[in] method_data
+    User data passed as is to the query method of \bt_p{component_class}
+    when you call bt_query_executor_query().
+
+@returns
+    New query executor reference, or \c NULL on memory error.
+
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{object}
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/
 extern
 bt_query_executor *bt_query_executor_create_with_method_data(
-               const bt_component_class *component_class, const char *object,
-               const bt_value *params, void *method_data);
+               const bt_component_class *component_class,
+               const char *object_name, const bt_value *params,
+               void *method_data);
+
+/*! @} */
 
+/*!
+@name Query operation
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_query_executor_query().
+*/
 typedef enum bt_query_executor_query_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_QUERY_EXECUTOR_QUERY_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Unknown object to query.
+       */
+       BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT   = __BT_FUNC_STATUS_UNKNOWN_OBJECT,
+
+       /*!
+       @brief
+           Try again.
+       */
        BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
-       BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT   = __BT_FUNC_STATUS_UNKNOWN_OBJECT,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
 } bt_query_executor_query_status;
 
+/*!
+@brief
+    Performs a query operation using the query executor
+    \bt_p{query_executor}, setting \bt_p{*result} to the operation's
+    result on success.
+
+This function calls the query executor's target \bt_comp_cls's
+query method, passing:
+
+- The object name of \bt_p{query_executor} as the
+  \bt_p{object_name} parameter.
+
+- The query parameters of \bt_p{query_executor} as the
+  \bt_p{params} parameter.
+
+- The query user data of \bt_p{query_executor} as the \bt_p{method_data}
+  parameter.
+
+The three items above were set when you created \bt_p{query_executor}
+with bt_query_executor_create() or
+bt_query_executor_create_with_method_data().
+
+@param[in] query_executor
+    Query executor to use to execute the query operation.
+@param[out] result
+    <strong>On success</strong>, \bt_p{*result} is a \em strong
+    reference of the query operation's result.
+
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
+    Success.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
+    Unknown object to query.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
+    Try again.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{query_executor}
+@bt_pre_not_null{result}
+*/
 extern
 bt_query_executor_query_status bt_query_executor_query(
                bt_query_executor *query_executor, const bt_value **result);
 
+/*! @} */
+
+/*!
+@name Property
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_query_executor_set_logging_level().
+*/
+typedef enum bt_query_executor_set_logging_level_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK   = __BT_FUNC_STATUS_OK,
+} bt_query_executor_set_logging_level_status;
+
+/*!
+@brief
+    Sets the logging level of the query executor \bt_p{query_executor}
+    to \bt_p{logging_level}.
+
+See the \ref api-qexec-prop-log-lvl "logging level" property.
+
+@param[in] query_executor
+    Query executor of which to set the logging level to
+    \bt_p{logging_level}.
+@param[in] logging_level
+    New logging level of \bt_p{query_executor}.
+
+@retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
+    Success.
+
+@bt_pre_not_null{query_executor}
+
+@sa bt_stream_class_get_logging_level() &mdash;
+    Returns the logging level of a query executor.
+*/
+extern bt_query_executor_set_logging_level_status
+bt_query_executor_set_logging_level(bt_query_executor *query_executor,
+               bt_logging_level logging_level);
+
+/*!
+@brief
+    Returns the logging level of the query executor
+    \bt_p{query_executor}.
+
+See the \ref api-qexec-prop-log-lvl "logging level" property.
+
+@param[in] query_executor
+    Query executor of which to get the logging level.
+
+@returns
+    Logging level of \bt_p{query_executor}.
+
+@bt_pre_not_null{query_executor}
+
+@sa bt_query_executor_set_logging_level() &mdash;
+    Sets the logging level of a query executor.
+*/
+extern bt_logging_level bt_query_executor_get_logging_level(
+               const bt_query_executor *query_executor);
+
+/*! @} */
+
+/*!
+@name Interruption
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_query_executor_add_interrupter().
+*/
 typedef enum bt_query_executor_add_interrupter_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK             = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_query_executor_add_interrupter_status;
 
+/*!
+@brief
+    Adds the \bt_intr \bt_p{interrupter} to the query executor
+    \bt_p{query_executor}.
+
+A \bt_comp_cls query method can check whether or not its executor is
+interrupted (any of its interrupters, including its default interrupter,
+is set) with bt_query_executor_is_interrupted().
+
+@note
+    @parblock
+    bt_query_executor_create() and
+    bt_query_executor_create_with_method_data() return a query executor
+    which comes with its own <em>default interrupter</em>.
+
+    Instead of adding your own interrupter to \bt_p{query_executor}, you
+    can set its default interrupter with
+
+    @code
+    bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
+    @endcode
+    @endparblock
+
+@param[in] query_executor
+    Query executor to which to add \bt_p{interrupter}.
+@param[in] interrupter
+    Interrupter to add to \bt_p{query_executor}.
+
+@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
+    Success.
+@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{query_executor}
+@bt_pre_not_null{interrupter}
+
+@sa bt_query_executor_borrow_default_interrupter() &mdash;
+    Borrows the default interrupter from a query executor.
+*/
 extern bt_query_executor_add_interrupter_status
 bt_query_executor_add_interrupter(bt_query_executor *query_executor,
                const bt_interrupter *interrupter);
 
+/*!
+@brief
+    Borrows the default \bt_intr from the query executor
+    \bt_p{query_executor}.
+
+@param[in] query_executor
+    Query executor from which to borrow the default interrupter.
+
+@returns
+    @parblock
+    \em Borrowed reference of the default interrupter of
+    \bt_p{query_executor}.
+
+    The returned pointer remains valid as long as \bt_p{query_executor}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{query_executor}
+
+@sa bt_query_executor_add_interrupter() &mdash;
+    Adds an interrupter to a query executor.
+*/
 extern bt_interrupter *bt_query_executor_borrow_default_interrupter(
                bt_query_executor *query_executor);
 
-typedef enum bt_query_executor_set_logging_level_status {
-       BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK   = __BT_FUNC_STATUS_OK,
-} bt_query_executor_set_logging_level_status;
+/*!
+@brief
+    Returns whether or not the query executor \bt_p{query_executor}
+    is interrupted, that is, whether or not any of its \bt_p_intr,
+    including its default interrupter, is set.
 
-extern bt_query_executor_set_logging_level_status
-bt_query_executor_set_logging_level(bt_query_executor *query_executor,
-               bt_logging_level logging_level);
+@param[in] query_executor
+    Query executor to check.
+
+@returns
+    #BT_TRUE if \bt_p{query_executor} is interrupted (any of its
+    interrupters is set).
+
+@bt_pre_not_null{query_executor}
+*/
+extern bt_bool bt_query_executor_is_interrupted(
+               const bt_query_executor *query_executor);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the query executor \bt_p{query_executor}.
+
+@param[in] query_executor
+    @parblock
+    Query executor of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_query_executor_put_ref() &mdash;
+    Decrements the reference count of a query executor.
+*/
+extern void bt_query_executor_get_ref(const bt_query_executor *query_executor);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the query executor \bt_p{query_executor}.
+
+@param[in] query_executor
+    @parblock
+    Query executor of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_query_executor_get_ref() &mdash;
+    Increments the reference count of a query executor.
+*/
+extern void bt_query_executor_put_ref(const bt_query_executor *query_executor);
+
+/*!
+@brief
+    Decrements the reference count of the query executor
+    \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.
+
+@param _query_executor
+    @parblock
+    Query executor of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_query_executor}
+*/
+#define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor)   \
+       do {                                                    \
+               bt_query_executor_put_ref(_query_executor);     \
+               (_query_executor) = NULL;                       \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the query executor \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a query executor reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src)         \
+       do {                                            \
+               bt_query_executor_put_ref(_dst);        \
+               (_dst) = (_src);                        \
+               (_src) = NULL;                          \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/graph/self-component-class-filter.h b/include/babeltrace2/graph/self-component-class-filter.h
deleted file mode 100644 (file)
index f2f96ce..0000000
--- a/include/babeltrace2/graph/self-component-class-filter.h
+++ /dev/null
@@ -1,57 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_FILTER_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_FILTER_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component_class_filter *
-bt_self_component_class_filter_as_component_class_filter(
-               bt_self_component_class_filter *self_comp_cls_filter)
-{
-       return __BT_UPCAST_CONST(bt_component_class_filter,
-               self_comp_cls_filter);
-}
-
-static inline
-bt_self_component_class*
-bt_self_component_class_filter_as_self_component_class(
-               bt_self_component_class_filter *self_comp_cls_filter)
-{
-       return __BT_UPCAST(bt_self_component_class, self_comp_cls_filter);
-}
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_FILTER_H */

diff --git a/include/babeltrace2/graph/self-component-class-sink.h b/include/babeltrace2/graph/self-component-class-sink.h
deleted file mode 100644 (file)
index 00f6841..0000000
--- a/include/babeltrace2/graph/self-component-class-sink.h
+++ /dev/null
@@ -1,56 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SINK_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SINK_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component_class_sink *
-bt_self_component_class_sink_as_component_class_sink(
-               bt_self_component_class_sink *self_comp_cls_sink)
-{
-       return __BT_UPCAST_CONST(bt_component_class_sink, self_comp_cls_sink);
-}
-
-static inline
-bt_self_component_class*
-bt_self_component_class_sink_as_self_component_class(
-               bt_self_component_class_sink *self_comp_cls_sink)
-{
-       return __BT_UPCAST(bt_self_component_class, self_comp_cls_sink);
-}
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SINK_H */

diff --git a/include/babeltrace2/graph/self-component-class-source.h b/include/babeltrace2/graph/self-component-class-source.h
deleted file mode 100644 (file)
index fb025f0..0000000
--- a/include/babeltrace2/graph/self-component-class-source.h
+++ /dev/null
@@ -1,57 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SOURCE_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SOURCE_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-const bt_component_class_source *
-bt_self_component_class_source_as_component_class_source(
-               bt_self_component_class_source *self_comp_cls_source)
-{
-       return __BT_UPCAST_CONST(bt_component_class_source,
-               self_comp_cls_source);
-}
-
-static inline
-bt_self_component_class*
-bt_self_component_class_source_as_self_component_class(
-               bt_self_component_class_source *self_comp_cls_source)
-{
-       return __BT_UPCAST(bt_self_component_class, self_comp_cls_source);
-}
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SOURCE_H */

diff --git a/include/babeltrace2/graph/self-component-class.h b/include/babeltrace2/graph/self-component-class.h
index 7cdd441e321d2ce5cf99a385c907108cb21b40bf..33fda7b0eb12490c91754e4ae342e1ff013c2078 100644 (file)
--- a/include/babeltrace2/graph/self-component-class.h
+++ b/include/babeltrace2/graph/self-component-class.h
@@ -33,6 +33,73 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-self-comp-cls Self component classes
+@ingroup api-comp-cls-dev
+
+@brief
+    Private views of \bt_p_comp_cls for class methods.
+
+The #bt_self_component_class, #bt_self_component_class_source,
+#bt_self_component_class_filter, #bt_self_component_class_sink types are
+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,
+#bt_component_class_filter, and #bt_component_class_sink counterparts.
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_self_component_class bt_self_component_class;
+
+@brief
+    Self \bt_comp_cls.
+
+@typedef struct bt_self_component_class_source bt_self_component_class_source;
+
+@brief
+    Self \bt_src_comp_cls.
+
+@typedef struct bt_self_component_class_filter bt_self_component_class_filter;
+
+@brief
+    Self \bt_flt_comp_cls.
+
+@typedef struct bt_self_component_class_sink bt_self_component_class_sink;
+
+@brief
+    Self \bt_sink_comp_cls.
+
+@}
+*/
+
+/*!
+@name Self to public upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_comp_cls
+    \bt_p{self_component_class} to the public #bt_component_class type.
+
+@param[in] self_component_class
+    @parblock
+    Component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_class} as a public component class.
+*/
 static inline
 const bt_component_class *bt_self_component_class_as_component_class(
                bt_self_component_class *self_component_class)
@@ -40,6 +107,163 @@ const bt_component_class *bt_self_component_class_as_component_class(
        return __BT_UPCAST(bt_component_class, self_component_class);
 }
 
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_src_comp_cls
+    \bt_p{self_component_class} to the public #bt_component_class_source
+    type.
+
+@param[in] self_component_class
+    @parblock
+    Source component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_class} as a public source component class.
+*/
+static inline
+const bt_component_class_source *
+bt_self_component_class_source_as_component_class_source(
+               bt_self_component_class_source *self_component_class)
+{
+       return __BT_UPCAST_CONST(bt_component_class_source,
+               self_component_class);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp_cls
+    \bt_p{self_component_class} to the public #bt_component_class_filter
+    type.
+
+@param[in] self_component_class
+    @parblock
+    Filter component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_class} as a public filter component class.
+*/
+static inline
+const bt_component_class_filter *
+bt_self_component_class_filter_as_component_class_filter(
+               bt_self_component_class_filter *self_component_class)
+{
+       return __BT_UPCAST_CONST(bt_component_class_filter,
+               self_component_class);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp_cls
+    \bt_p{self_component_class} to the public #bt_component_class_sink
+    type.
+
+@param[in] self_component_class
+    @parblock
+    Sink component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_class} as a public sink component class.
+*/
+static inline
+const bt_component_class_sink *
+bt_self_component_class_sink_as_component_class_sink(
+               bt_self_component_class_sink *self_component_class)
+{
+       return __BT_UPCAST_CONST(bt_component_class_sink, self_component_class);
+}
+
+/*! @} */
+
+/*!
+@name Self to common self upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_src_comp_cls
+    \bt_p{self_component_class} to the common #bt_self_component_class
+    type.
+
+@param[in] self_component_class
+    @parblock
+    Source component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_class} as a common self component class.
+*/
+static inline
+bt_self_component_class*
+bt_self_component_class_source_as_self_component_class(
+               bt_self_component_class_source *self_component_class)
+{
+       return __BT_UPCAST(bt_self_component_class, self_component_class);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp_cls
+    \bt_p{self_component_class} to the common #bt_self_component_class
+    type.
+
+@param[in] self_component_class
+    @parblock
+    Filter component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_class} as a common self component class.
+*/
+static inline
+bt_self_component_class*
+bt_self_component_class_filter_as_self_component_class(
+               bt_self_component_class_filter *self_component_class)
+{
+       return __BT_UPCAST(bt_self_component_class, self_component_class);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp_cls
+    \bt_p{self_component_class} to the common #bt_self_component_class
+    type.
+
+@param[in] self_component_class
+    @parblock
+    Sink component class to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_class} as a common self component class.
+*/
+static inline
+bt_self_component_class*
+bt_self_component_class_sink_as_self_component_class(
+               bt_self_component_class_sink *self_component_class)
+{
+       return __BT_UPCAST(bt_self_component_class, self_component_class);
+}
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/graph/self-component-filter.h b/include/babeltrace2/graph/self-component-filter.h
deleted file mode 100644 (file)
index ec49b6f..0000000
--- a/include/babeltrace2/graph/self-component-filter.h
+++ /dev/null
@@ -1,90 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_FILTER_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_FILTER_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/graph/self-component.h>
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-bt_self_component *bt_self_component_filter_as_self_component(
-               bt_self_component_filter *self_comp_filter)
-{
-       return __BT_UPCAST(bt_self_component, self_comp_filter);
-}
-
-static inline
-const bt_component_filter *
-bt_self_component_filter_as_component_filter(
-               bt_self_component_filter *self_comp_filter)
-{
-       return __BT_UPCAST_CONST(bt_component_filter, self_comp_filter);
-}
-
-extern bt_self_component_port_output *
-bt_self_component_filter_borrow_output_port_by_name(
-               bt_self_component_filter *self_component,
-               const char *name);
-
-extern bt_self_component_port_output *
-bt_self_component_filter_borrow_output_port_by_index(
-               bt_self_component_filter *self_component,
-               uint64_t index);
-
-extern bt_self_component_add_port_status
-bt_self_component_filter_add_output_port(
-               bt_self_component_filter *self_component,
-               const char *name, void *user_data,
-               bt_self_component_port_output **self_component_port);
-
-extern bt_self_component_port_input *
-bt_self_component_filter_borrow_input_port_by_name(
-               bt_self_component_filter *self_component,
-               const char *name);
-
-extern bt_self_component_port_input *
-bt_self_component_filter_borrow_input_port_by_index(
-               bt_self_component_filter *self_component,
-               uint64_t index);
-
-extern bt_self_component_add_port_status
-bt_self_component_filter_add_input_port(
-               bt_self_component_filter *self_component,
-               const char *name, void *user_data,
-               bt_self_component_port_input **self_component_port);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_FILTER_H */

diff --git a/include/babeltrace2/graph/self-component-port-input.h b/include/babeltrace2/graph/self-component-port-input.h
deleted file mode 100644 (file)
index 0c13c01..0000000
--- a/include/babeltrace2/graph/self-component-port-input.h
+++ /dev/null
@@ -1,55 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_INPUT_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_INPUT_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-bt_self_component_port *
-bt_self_component_port_input_as_self_component_port(
-               bt_self_component_port_input *self_component_port)
-{
-       return __BT_UPCAST(bt_self_component_port, self_component_port);
-}
-
-static inline
-const bt_port_input *bt_self_component_port_input_as_port_input(
-               const bt_self_component_port_input *self_component_port)
-{
-       return __BT_UPCAST_CONST(bt_port_input, self_component_port);
-}
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_INPUT_H */

diff --git a/include/babeltrace2/graph/self-component-port-output.h b/include/babeltrace2/graph/self-component-port-output.h
deleted file mode 100644 (file)
index b3daa62..0000000
--- a/include/babeltrace2/graph/self-component-port-output.h
+++ /dev/null
@@ -1,55 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_OUTPUT_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_OUTPUT_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-bt_self_component_port *
-bt_self_component_port_output_as_self_component_port(
-               bt_self_component_port_output *self_component_port)
-{
-       return __BT_UPCAST(bt_self_component_port, self_component_port);
-}
-
-static inline
-const bt_port_output *bt_self_component_port_output_as_port_output(
-               bt_self_component_port_output *self_component_port)
-{
-       return __BT_UPCAST_CONST(bt_port_output, self_component_port);
-}
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_OUTPUT_H */

diff --git a/include/babeltrace2/graph/self-component-port.h b/include/babeltrace2/graph/self-component-port.h
index db08e2c79b334dd206398f7ba57ec3deb6b3ca75..0ab59ac369778bf2c12602b048c59f725a4c7f1f 100644 (file)
--- a/include/babeltrace2/graph/self-component-port.h
+++ b/include/babeltrace2/graph/self-component-port.h
@@ -33,18 +33,235 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-self-comp-port Self component ports
+@ingroup api-self-comp
+
+@brief
+    Private views of \bt_p_port for \bt_comp_cls instance methods.
+
+The #bt_self_component_port, #bt_self_component_port_input, and
+#bt_self_component_port_output types are private views of a \bt_port
+from within a component class
+\ref api-comp-cls-dev-instance-meth "instance method".
+
+Borrow the \bt_self_comp of a port with
+bt_self_component_port_borrow_component().
+
+Get the user data attached to a port with
+bt_self_component_port_get_data().
+
+\ref api-fund-c-typing "Upcast" the "self" (private) types to the
+public and common self component port types with the
+<code>bt_self_component_port*_as_port*()</code> and
+<code>bt_self_component_port_*_as_self_component_port()</code>
+functions.
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_self_component_port bt_self_component_port;
+
+@brief
+    Self component \bt_comp.
+
+@typedef struct bt_self_component_port_input bt_self_component_port_input;
+
+@brief
+    Self component \bt_iport.
+
+@typedef struct bt_self_component_port_output bt_self_component_port_output;
+
+@brief
+    Self component \bt_oport.
+
+@}
+*/
+
+/*!
+@name Component access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_comp of the \bt_port \bt_p{self_component_port}.
+
+@param[in] self_component_port
+    Port from which to borrow the component which owns it.
+
+@returns
+    Component which owns \bt_p{self_component_port}.
+
+@bt_pre_not_null{self_component_port}
+*/
+extern bt_self_component *bt_self_component_port_borrow_component(
+               bt_self_component_port *self_component_port);
+
+/*! @} */
+
+/*!
+@name User data access
+@{
+*/
+
+/*!
+@brief
+    Returns the user data of the \bt_port \bt_p{self_component_port}.
+
+You can attach user data to a port when you add it to a component with
+bt_self_component_source_add_output_port(),
+bt_self_component_filter_add_input_port(),
+bt_self_component_filter_add_output_port(), and
+bt_self_component_sink_add_input_port().
+
+@param[in] self_component_port
+    Port of which to get the user data.
+
+@returns
+    User data of \bt_p{self_component_port}.
+
+@bt_pre_not_null{self_component_port}
+*/
+extern void *bt_self_component_port_get_data(
+               const bt_self_component_port *self_component_port);
+
+
+/*! @} */
+
+/*!
+@name Self to public upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self component port
+    \bt_p{self_component_port} to the public #bt_port type.
+
+@param[in] self_component_port
+    @parblock
+    Port to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_port} as a public port.
+*/
 static inline
 const bt_port *bt_self_component_port_as_port(
-               bt_self_component_port *self_port)
+               bt_self_component_port *self_component_port)
 {
-       return __BT_UPCAST_CONST(bt_port, self_port);
+       return __BT_UPCAST_CONST(bt_port, self_component_port);
 }
 
-extern bt_self_component *bt_self_component_port_borrow_component(
-               bt_self_component_port *self_port);
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self component \bt_iport
+    \bt_p{self_component_port} to the public #bt_port_input type.
 
-extern void *bt_self_component_port_get_data(
-               const bt_self_component_port *self_port);
+@param[in] self_component_port
+    @parblock
+    Input port to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_port} as a public input port.
+*/
+static inline
+const bt_port_input *bt_self_component_port_input_as_port_input(
+               const bt_self_component_port_input *self_component_port)
+{
+       return __BT_UPCAST_CONST(bt_port_input, self_component_port);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self component \bt_oport
+    \bt_p{self_component_port} to the public #bt_port_output type.
+
+@param[in] self_component_port
+    @parblock
+    Output port to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_port} as a public output port.
+*/
+static inline
+const bt_port_output *bt_self_component_port_output_as_port_output(
+               bt_self_component_port_output *self_component_port)
+{
+       return __BT_UPCAST_CONST(bt_port_output, self_component_port);
+}
+
+/*! @} */
+
+/*!
+@name Self to common self upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_iport
+    \bt_p{self_component_port} to the common #bt_self_component_port
+    type.
+
+@param[in] self_component_port
+    @parblock
+    Input port to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_port} as a common self component port.
+*/
+static inline
+bt_self_component_port *
+bt_self_component_port_input_as_self_component_port(
+               bt_self_component_port_input *self_component_port)
+{
+       return __BT_UPCAST(bt_self_component_port, self_component_port);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_oport
+    \bt_p{self_component_port} to the common #bt_self_component_port
+    type.
+
+@param[in] self_component_port
+    @parblock
+    Output port to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component_port} as a common self component port.
+*/
+static inline
+bt_self_component_port *
+bt_self_component_port_output_as_self_component_port(
+               bt_self_component_port_output *self_component_port)
+{
+       return __BT_UPCAST(bt_self_component_port, self_component_port);
+}
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/graph/self-component-sink.h b/include/babeltrace2/graph/self-component-sink.h
deleted file mode 100644 (file)
index 224c678..0000000
--- a/include/babeltrace2/graph/self-component-sink.h
+++ /dev/null
@@ -1,76 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_SINK_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_SINK_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/graph/self-component.h>
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-bt_self_component *bt_self_component_sink_as_self_component(
-               bt_self_component_sink *self_comp_sink)
-{
-       return __BT_UPCAST(bt_self_component, self_comp_sink);
-}
-
-static inline
-const bt_component_sink *
-bt_self_component_sink_as_component_sink(
-               bt_self_component_sink *self_comp_sink)
-{
-       return __BT_UPCAST_CONST(bt_component_sink, self_comp_sink);
-}
-
-extern bt_self_component_port_input *
-bt_self_component_sink_borrow_input_port_by_name(
-               bt_self_component_sink *self_component,
-               const char *name);
-
-extern bt_self_component_port_input *
-bt_self_component_sink_borrow_input_port_by_index(
-               bt_self_component_sink *self_component, uint64_t index);
-
-extern bt_self_component_add_port_status
-bt_self_component_sink_add_input_port(
-               bt_self_component_sink *self_component,
-               const char *name, void *user_data,
-               bt_self_component_port_input **self_component_port);
-
-extern bt_bool bt_self_component_sink_is_interrupted(
-               const bt_self_component_sink *self_component);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_SINK_H */

diff --git a/include/babeltrace2/graph/self-component-source.h b/include/babeltrace2/graph/self-component-source.h
deleted file mode 100644 (file)
index ec022fd..0000000
--- a/include/babeltrace2/graph/self-component-source.h
+++ /dev/null
@@ -1,74 +0,0 @@
-#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_SOURCE_H
-#define BABELTRACE2_GRAPH_SELF_COMPONENT_SOURCE_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/graph/self-component.h>
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-static inline
-bt_self_component *bt_self_component_source_as_self_component(
-               bt_self_component_source *self_comp_source)
-{
-       return __BT_UPCAST(bt_self_component, self_comp_source);
-}
-
-static inline
-const bt_component_source *
-bt_self_component_source_as_component_source(
-               bt_self_component_source *self_comp_source)
-{
-       return __BT_UPCAST_CONST(bt_component_source, self_comp_source);
-}
-
-extern bt_self_component_port_output *
-bt_self_component_source_borrow_output_port_by_name(
-               bt_self_component_source *self_component,
-               const char *name);
-
-extern bt_self_component_port_output *
-bt_self_component_source_borrow_output_port_by_index(
-               bt_self_component_source *self_component,
-               uint64_t index);
-
-extern bt_self_component_add_port_status
-bt_self_component_source_add_output_port(
-               bt_self_component_source *self_component,
-               const char *name, void *user_data,
-               bt_self_component_port_output **self_component_port);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_SOURCE_H */

diff --git a/include/babeltrace2/graph/self-component.h b/include/babeltrace2/graph/self-component.h
index ba722d9813cfd95e6e87c5899b5cfa507e9250e1..b995c0889bac554791bc3b6b873ad9bdc1c5afb0 100644 (file)
--- a/include/babeltrace2/graph/self-component.h
+++ b/include/babeltrace2/graph/self-component.h
@@ -33,12 +33,690 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-self-comp Self components
+@ingroup api-comp-cls-dev
+
+@brief
+    Private views of \bt_p_comp for instance methods.
+
+The #bt_self_component, #bt_self_component_source,
+#bt_self_component_filter, #bt_self_component_sink types are
+private views of a \bt_comp from within a component class
+\ref api-comp-cls-dev-instance-meth "instance method".
+
+Add a \bt_port to a component with
+bt_self_component_source_add_output_port(),
+bt_self_component_filter_add_input_port(),
+bt_self_component_filter_add_output_port(), and
+bt_self_component_sink_add_input_port().
+
+When you add a port to a component, you can attach custom user data
+to it (\bt_voidp). You can retrieve this user data
+afterwards with bt_self_component_port_get_data().
+
+Borrow a \bt_self_comp_port from a component by index with
+bt_self_component_source_borrow_output_port_by_index(),
+bt_self_component_filter_borrow_input_port_by_index(),
+bt_self_component_filter_borrow_output_port_by_index(), and
+bt_self_component_sink_borrow_input_port_by_index().
+
+Borrow a \bt_self_comp_port from a component by name with
+bt_self_component_source_borrow_output_port_by_name(),
+bt_self_component_filter_borrow_input_port_by_name(),
+bt_self_component_filter_borrow_output_port_by_name(), and
+bt_self_component_sink_borrow_input_port_by_name().
+
+Set and get user data attached to a component with
+bt_self_component_set_data() and bt_self_component_get_data().
+
+Get a component's owning trace processing \bt_graph's effective
+\bt_mip version with bt_self_component_get_graph_mip_version().
+
+Check whether or not a \bt_sink_comp is interrupted with
+bt_self_component_sink_is_interrupted().
+
+\ref api-fund-c-typing "Upcast" the "self" (private) types to the
+public and common self component types with the
+<code>bt_self_component*_as_component*()</code> and
+<code>bt_self_component_*_as_self_component()</code> functions.
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_self_component bt_self_component;
+
+@brief
+    Self \bt_comp.
+
+@typedef struct bt_self_component_source bt_self_component_source;
+
+@brief
+    Self \bt_src_comp.
+
+@typedef struct bt_self_component_filter bt_self_component_filter;
+
+@brief
+    Self \bt_flt_comp.
+
+@typedef struct bt_self_component_sink bt_self_component_sink;
+
+@brief
+    Self \bt_sink_comp.
+
+@typedef struct bt_self_component_source_configuration bt_self_component_source_configuration;
+
+@brief
+    Self \bt_src_comp configuration.
+
+@typedef struct bt_self_component_filter_configuration bt_self_component_filter_configuration;
+
+@brief
+    Self \bt_flt_comp configuration.
+
+@typedef struct bt_self_component_sink_configuration bt_self_component_sink_configuration;
+
+@brief
+    Self \bt_sink_comp configuration.
+
+@}
+*/
+
+/*!
+@name Port adding
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_self_component_source_add_output_port(),
+    bt_self_component_filter_add_input_port(),
+    bt_self_component_filter_add_output_port(), and
+    bt_self_component_sink_add_input_port().
+*/
 typedef enum bt_self_component_add_port_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_SELF_COMPONENT_ADD_PORT_STATUS_OK            = __BT_FUNC_STATUS_OK,
-       BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
 } bt_self_component_add_port_status;
 
+/*!
+@brief
+    Adds an \bt_oport named \bt_p{name} and having the user data
+    \bt_p{user_data} to the \bt_src_comp \bt_p{self_component},
+    and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+    You can only call this function from within the
+    \ref api-comp-cls-dev-meth-init "initialization",
+    \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+    and
+    \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+    methods.
+
+@param[in] self_component
+    Source component instance.
+@param[in] name
+    Name of the output port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+    User data of the output port to add to \bt_p{self_component}.
+@param[out] self_component_port
+    <strong>On success, if not \c NULL</strong>,
+    \bt_p{*self_component_port} is a \em borrowed reference of the
+    created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+    Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+    No other output port within \bt_p{self_component} has the name
+    \bt_p{name}.
+*/
+extern bt_self_component_add_port_status
+bt_self_component_source_add_output_port(
+               bt_self_component_source *self_component,
+               const char *name, void *user_data,
+               bt_self_component_port_output **self_component_port);
+
+/*!
+@brief
+    Adds an \bt_iport named \bt_p{name} and having the user data
+    \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
+    and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+    You can only call this function from within the
+    \ref api-comp-cls-dev-meth-init "initialization",
+    \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+    and
+    \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+    methods.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] name
+    Name of the input port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+    User data of the input port to add to \bt_p{self_component}.
+@param[out] self_component_port
+    <strong>On success, if not \c NULL</strong>,
+    \bt_p{*self_component_port} is a \em borrowed reference of the
+    created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+    Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+    No other input port within \bt_p{self_component} has the name
+    \bt_p{name}.
+*/
+extern bt_self_component_add_port_status
+bt_self_component_filter_add_input_port(
+               bt_self_component_filter *self_component,
+               const char *name, void *user_data,
+               bt_self_component_port_input **self_component_port);
+
+/*!
+@brief
+    Adds an \bt_oport named \bt_p{name} and having the user data
+    \bt_p{user_data} to the \bt_flt_comp \bt_p{self_component},
+    and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+    You can only call this function from within the
+    \ref api-comp-cls-dev-meth-init "initialization",
+    \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+    and
+    \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+    methods.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] name
+    Name of the output port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+    User data of the output port to add to \bt_p{self_component}.
+@param[out] self_component_port
+    <strong>On success, if not \c NULL</strong>,
+    \bt_p{*self_component_port} is a \em borrowed reference of the
+    created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+    Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+    No other output port within \bt_p{self_component} has the name
+    \bt_p{name}.
+*/
+extern bt_self_component_add_port_status
+bt_self_component_filter_add_output_port(
+               bt_self_component_filter *self_component,
+               const char *name, void *user_data,
+               bt_self_component_port_output **self_component_port);
+
+/*!
+@brief
+    Adds an \bt_iport named \bt_p{name} and having the user data
+    \bt_p{user_data} to the \bt_sink_comp \bt_p{self_component},
+    and sets \bt_p{*self_component_port} to the resulting port.
+
+@attention
+    You can only call this function from within the
+    \ref api-comp-cls-dev-meth-init "initialization",
+    \link api-comp-cls-dev-meth-iport-connected "input port connected"\endlink,
+    and
+    \link api-comp-cls-dev-meth-oport-connected "output port connected"\endlink
+    methods.
+
+@param[in] self_component
+    Sink component instance.
+@param[in] name
+    Name of the input port to add to \bt_p{self_component} (copied).
+@param[in] user_data
+    User data of the input port to add to \bt_p{self_component}.
+@param[out] self_component_port
+    <strong>On success, if not \c NULL</strong>,
+    \bt_p{*self_component_port} is a \em borrowed reference of the
+    created port.
+
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_OK
+    Success.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_SELF_COMPONENT_ADD_PORT_STATUS_ERROR
+    Other error.
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+@pre
+    No other input port within \bt_p{self_component} has the name
+    \bt_p{name}.
+*/
+
+extern bt_self_component_add_port_status
+bt_self_component_sink_add_input_port(
+               bt_self_component_sink *self_component,
+               const char *name, void *user_data,
+               bt_self_component_port_input **self_component_port);
+
+/*! @} */
+
+/*!
+@name Port access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_self_comp_oport at index \bt_p{index} from the
+    \bt_src_comp \bt_p{self_component}.
+
+@param[in] self_component
+    Source component instance.
+@param[in] index
+    Index of the output port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{self_component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+    \bt_p{index} is less than the number of output ports
+    \bt_p{self_component} has (as returned by
+    bt_component_source_get_output_port_count()).
+
+@sa bt_component_source_get_output_port_count() &mdash;
+    Returns the number of output ports that a source component has.
+*/
+extern bt_self_component_port_output *
+bt_self_component_source_borrow_output_port_by_index(
+               bt_self_component_source *self_component,
+               uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_self_comp_iport at index \bt_p{index} from the
+    \bt_flt_comp \bt_p{self_component}.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] index
+    Index of the input port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the input port of
+    \bt_p{self_component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+    \bt_p{index} is less than the number of input ports
+    \bt_p{self_component} has (as returned by
+    bt_component_filter_get_input_port_count()).
+
+@sa bt_component_filter_get_input_port_count() &mdash;
+    Returns the number of input ports that a filter component has.
+*/
+extern bt_self_component_port_input *
+bt_self_component_filter_borrow_input_port_by_index(
+               bt_self_component_filter *self_component,
+               uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_self_comp_oport at index \bt_p{index} from the
+    \bt_flt_comp \bt_p{self_component}.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] index
+    Index of the output port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{self_component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+    \bt_p{index} is less than the number of output ports
+    \bt_p{self_component} has (as returned by
+    bt_component_filter_get_output_port_count()).
+
+@sa bt_component_filter_get_output_port_count() &mdash;
+    Returns the number of output ports that a filter component has.
+*/
+extern bt_self_component_port_output *
+bt_self_component_filter_borrow_output_port_by_index(
+               bt_self_component_filter *self_component,
+               uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_self_comp_iport at index \bt_p{index} from the
+    \bt_sink_comp \bt_p{self_component}.
+
+@param[in] self_component
+    Sink component instance.
+@param[in] index
+    Index of the input port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the input port of
+    \bt_p{self_component} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@pre
+    \bt_p{index} is less than the number of input ports
+    \bt_p{self_component} has (as returned by
+    bt_component_sink_get_input_port_count()).
+
+@sa bt_component_sink_get_input_port_count() &mdash;
+    Returns the number of input ports that a sink component has.
+*/
+extern bt_self_component_port_input *
+bt_self_component_sink_borrow_input_port_by_index(
+               bt_self_component_sink *self_component, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_self_comp_oport named \bt_p{name} from the
+    \bt_src_comp \bt_p{self_component}.
+
+If \bt_p{self_component} has no output port named \bt_p{name}, this
+function returns \c NULL.
+
+@param[in] self_component
+    Source component instance.
+@param[in] name
+    Name of the output port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+*/
+extern bt_self_component_port_output *
+bt_self_component_source_borrow_output_port_by_name(
+               bt_self_component_source *self_component,
+               const char *name);
+
+/*!
+@brief
+    Borrows the \bt_self_comp_iport named \bt_p{name} from the
+    \bt_flt_comp \bt_p{self_component}.
+
+If \bt_p{self_component} has no input port named \bt_p{name}, this
+function returns \c NULL.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] name
+    Name of the input port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the input port of
+    \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+*/
+extern bt_self_component_port_input *
+bt_self_component_filter_borrow_input_port_by_name(
+               bt_self_component_filter *self_component,
+               const char *name);
+
+/*!
+@brief
+    Borrows the \bt_self_comp_oport named \bt_p{name} from the
+    \bt_flt_comp \bt_p{self_component}.
+
+If \bt_p{self_component} has no output port named \bt_p{name}, this
+function returns \c NULL.
+
+@param[in] self_component
+    Filter component instance.
+@param[in] name
+    Name of the output port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the output port of
+    \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+*/
+extern bt_self_component_port_output *
+bt_self_component_filter_borrow_output_port_by_name(
+               bt_self_component_filter *self_component,
+               const char *name);
+
+/*!
+@brief
+    Borrows the \bt_self_comp_iport named \bt_p{name} from the
+    \bt_sink_comp \bt_p{self_component}.
+
+If \bt_p{self_component} has no input port named \bt_p{name}, this
+function returns \c NULL.
+
+@param[in] self_component
+    Sink component instance.
+@param[in] name
+    Name of the input port to borrow from \bt_p{self_component}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the input port of
+    \bt_p{self_component} named \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{self_component}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{self_component}
+@bt_pre_not_null{name}
+*/
+extern bt_self_component_port_input *
+bt_self_component_sink_borrow_input_port_by_name(
+               bt_self_component_sink *self_component,
+               const char *name);
+
+/*! @} */
+
+/*!
+@name User data
+@{
+*/
+
+/*!
+@brief
+    Sets the user data of the \bt_comp \bt_p{self_component} to
+    \bt_p{data}.
+
+@param[in] self_component
+    Component instance.
+@param[in] user_data
+    New user data of \bt_p{self_component}.
+
+@bt_pre_not_null{self_component}
+
+@sa bt_self_component_get_data() &mdash;
+    Returns the user data of a component.
+*/
+extern void bt_self_component_set_data(
+               bt_self_component *self_component, void *user_data);
+
+/*!
+@brief
+    Returns the user data of the \bt_comp \bt_p{self_component}.
+
+@param[in] self_component
+    Component instance.
+
+@returns
+    User data of \bt_p{self_component}.
+
+@bt_pre_not_null{self_component}
+
+@sa bt_self_component_set_data() &mdash;
+    Sets the user data of a component.
+*/
+extern void *bt_self_component_get_data(
+               const bt_self_component *self_component);
+
+/*! @} */
+
+/*!
+@name Trace processing graph's effective MIP version access
+@{
+*/
+
+/*!
+@brief
+    Returns the effective \bt_mip (MIP) version of the trace processing
+    \bt_graph which contains the \bt_comp \bt_p{self_component}.
+
+@note
+    As of \bt_name_version_min_maj, because bt_get_maximal_mip_version()
+    returns 0, this function always returns 0.
+
+@param[in] self_component
+    Component instance.
+
+@returns
+    Effective MIP version of the trace processing graph which
+    contains \bt_p{self_component}.
+
+@bt_pre_not_null{self_component}
+*/
+extern
+uint64_t bt_self_component_get_graph_mip_version(
+               bt_self_component *self_component);
+
+/*! @} */
+
+/*!
+@name Sink component's interruption query
+@{
+*/
+
+/*!
+@brief
+    Returns whether or not the \bt_sink_comp \bt_p{self_component}
+    is interrupted, that is, whether or not any of its \bt_p_intr
+    is set.
+
+@param[in] self_component
+    Component instance.
+
+@returns
+    #BT_TRUE if \bt_p{self_component} is interrupted (any of its
+    interrupters is set).
+
+@bt_pre_not_null{self_component}
+
+@sa bt_graph_borrow_default_interrupter() &mdash;
+    Borrows a trace processing graph's default interrupter.
+@sa bt_graph_add_interrupter() &mdash;
+    Adds an interrupter to a graph.
+*/
+extern bt_bool bt_self_component_sink_is_interrupted(
+               const bt_self_component_sink *self_component);
+
+/*! @} */
+
+/*!
+@name Self to public upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_comp
+    \bt_p{self_component} to the public #bt_component type.
+
+@param[in] self_component
+    @parblock
+    Component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component} as a public component.
+*/
 static inline
 const bt_component *bt_self_component_as_component(
                bt_self_component *self_component)
@@ -46,14 +724,157 @@ const bt_component *bt_self_component_as_component(
        return __BT_UPCAST(bt_component, self_component);
 }
 
-extern
-uint64_t bt_self_component_get_graph_mip_version(bt_self_component *self_component);
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
+    \bt_p{self_component} to the public #bt_component_source
+    type.
 
-extern void *bt_self_component_get_data(
-               const bt_self_component *self_component);
+@param[in] self_component
+    @parblock
+    Source component to upcast.
 
-extern void bt_self_component_set_data(
-               bt_self_component *self_component, void *data);
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component} as a public source component.
+*/
+static inline
+const bt_component_source *
+bt_self_component_source_as_component_source(
+               bt_self_component_source *self_component)
+{
+       return __BT_UPCAST_CONST(bt_component_source, self_component);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
+    \bt_p{self_component} to the public #bt_component_filter
+    type.
+
+@param[in] self_component
+    @parblock
+    Filter component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component} as a public filter component.
+*/
+static inline
+const bt_component_filter *
+bt_self_component_filter_as_component_filter(
+               bt_self_component_filter *self_component)
+{
+       return __BT_UPCAST_CONST(bt_component_filter, self_component);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
+    \bt_p{self_component} to the public #bt_component_sink
+    type.
+
+@param[in] self_component
+    @parblock
+    Sink component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component} as a public sink component.
+*/
+static inline
+const bt_component_sink *
+bt_self_component_sink_as_component_sink(
+               bt_self_component_sink *self_component)
+{
+       return __BT_UPCAST_CONST(bt_component_sink, self_component);
+}
+
+/*! @} */
+
+/*!
+@name Self to common self upcast
+@{
+*/
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_src_comp
+    \bt_p{self_component} to the common #bt_self_component
+    type.
+
+@param[in] self_component
+    @parblock
+    Source component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component} as a common self component.
+*/
+static inline
+bt_self_component *bt_self_component_source_as_self_component(
+               bt_self_component_source *self_component)
+{
+       return __BT_UPCAST(bt_self_component, self_component);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp
+    \bt_p{self_component} to the common #bt_self_component
+    type.
+
+@param[in] self_component
+    @parblock
+    Filter component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component} as a common self component.
+*/
+static inline
+bt_self_component *bt_self_component_filter_as_self_component(
+               bt_self_component_filter *self_component)
+{
+       return __BT_UPCAST(bt_self_component, self_component);
+}
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp
+    \bt_p{self_component} to the common #bt_self_component
+    type.
+
+@param[in] self_component
+    @parblock
+    Sink component to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{self_component} as a common self component.
+*/
+static inline
+bt_self_component *bt_self_component_sink_as_self_component(
+               bt_self_component_sink *self_component)
+{
+       return __BT_UPCAST(bt_self_component, self_component);
+}
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/graph/self-message-iterator.h b/include/babeltrace2/graph/self-message-iterator.h
index 9aaa2767159918a63a4995e11c684dbd54e880a4..0a6697d14b1d0d159111d986d840ce7838a30f0c 100644 (file)
--- a/include/babeltrace2/graph/self-message-iterator.h
+++ b/include/babeltrace2/graph/self-message-iterator.h
@@ -33,28 +33,214 @@
 extern "C" {
 #endif
 
-extern bt_bool bt_self_message_iterator_is_interrupted(
-               const bt_self_message_iterator *message_iterator);
+/*!
+@defgroup api-self-msg-iter Self message iterator
+@ingroup api-msg-iter-cls
+
+@brief
+    Private view of a \bt_msg_iter for methods.
+
+The #bt_self_message_iterator type is a private view of a \bt_msg_iter
+from within a \bt_msg_iter_cls method.
+
+Borrow the \bt_comp which provides a message iterator with
+bt_self_message_iterator_borrow_component().
+
+Borrow the \bt_oport on which a message iterator operates with
+bt_self_message_iterator_borrow_port().
+
+Set and get user data attached to a message iterator with
+bt_self_message_iterator_set_data() and
+bt_self_message_iterator_get_data().
+
+Check whether or not a message iterator is interrupted with
+bt_self_message_iterator_is_interrupted().
+
+Set whether or not a message iterator can seek forward with
+bt_self_message_iterator_configuration_set_can_seek_forward().
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_self_message_iterator bt_self_message_iterator;
+
+@brief
+    Self \bt_msg_iter.
+
+@typedef struct bt_self_message_iterator_configuration bt_self_message_iterator_configuration;
 
+@brief
+    Self \bt_msg_iter configuration.
+
+@}
+*/
+
+/*!
+@name Component access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_comp which provides the \bt_msg_iter
+    \bt_p{self_message_iterator}.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    Component which provides \bt_p{self_message_iterator}.
+
+@bt_pre_not_null{self_message_iterator}
+*/
 extern bt_self_component *
 bt_self_message_iterator_borrow_component(
-               bt_self_message_iterator *message_iterator);
+               bt_self_message_iterator *self_message_iterator);
 
+/*! @} */
+
+/*!
+@name Output port access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_oport on which the \bt_msg_iter
+    \bt_p{self_message_iterator} operates.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    Output port on which \bt_p{self_message_iterator} operates.
+
+@bt_pre_not_null{self_message_iterator}
+*/
 extern bt_self_component_port_output *
 bt_self_message_iterator_borrow_port(
-               bt_self_message_iterator *message_iterator);
+               bt_self_message_iterator *self_message_iterator);
+
+/*! @} */
 
+/*!
+@name User data
+@{
+*/
+
+/*!
+@brief
+    Sets the user data of the \bt_msg_iter \bt_p{self_message_iterator}
+    to \bt_p{data}.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+@param[in] user_data
+    New user data of \bt_p{self_message_iterator}.
+
+@bt_pre_not_null{self_message_iterator}
+
+@sa bt_self_message_iterator_get_data() —
+    Returns the user data of a message iterator.
+*/
 extern void bt_self_message_iterator_set_data(
-               bt_self_message_iterator *message_iterator,
+               bt_self_message_iterator *self_message_iterator,
                void *user_data);
 
-extern void *bt_self_message_iterator_get_data(
-               const bt_self_message_iterator *message_iterator);
+/*!
+@brief
+    Returns the user data of the \bt_msg_iter
+    \bt_p{self_message_iterator}.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    User data of \bt_p{self_message_iterator}.
+
+@bt_pre_not_null{self_message_iterator}
+
+@sa bt_self_message_iterator_set_data() —
+    Sets the user data of a message iterator.
+*/
+extern
+void *bt_self_message_iterator_get_data(
+               const bt_self_message_iterator *self_message_iterator);
+
+/*! @} */
+
+/*!
+@name Interruption query
+@{
+*/
+
+/*!
+@brief
+    Returns whether or not the \bt_msg_iter \bt_p{self_message_iterator}
+    is interrupted, that is, whether or not any of its \bt_p_intr
+    is set.
+
+@param[in] self_message_iterator
+    Message iterator instance.
+
+@returns
+    #BT_TRUE if \bt_p{self_message_iterator} is interrupted (any of its
+    interrupters is set).
 
+@bt_pre_not_null{self_message_iterator}
+
+@sa bt_graph_borrow_default_interrupter() —
+    Borrows a trace processing graph's default interrupter.
+@sa bt_graph_add_interrupter() —
+    Adds an interrupter to a graph.
+*/
+extern bt_bool bt_self_message_iterator_is_interrupted(
+               const bt_self_message_iterator *self_message_iterator);
+
+/*! @} */
+
+/*!
+@name Configuration
+@{
+*/
+
+/*!
+@brief
+    Sets whether or not the \bt_msg_iter of which the configuration
+    is \bt_p{configuration} can seek forward.
+
+A message iterator can seek forward if all the \bt_p_msg of its
+message sequence have some \bt_cs.
+
+@attention
+    You can only call this function during the execution of a
+    message iterator's
+    \ref api-msg-iter-cls-meth-init "initialization method".
+
+@param[in] configuration
+    Configuration of the message iterator of which to set whether or
+    not it can seek forward.
+@param[in] can_seek_forward
+    #BT_TRUE to make the message iterator of which the configuration is
+    \bt_p{configuration} forward-seekable.
+
+@bt_pre_not_null{configuration}
+
+@sa bt_message_iterator_can_seek_forward() —
+    Returns whether or not a message iterator can seek forward.
+*/
 extern void bt_self_message_iterator_configuration_set_can_seek_forward(
-               bt_self_message_iterator_configuration *config,
+               bt_self_message_iterator_configuration *configuration,
                bt_bool can_seek_forward);
 
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/integer-range-set-const.h b/include/babeltrace2/integer-range-set-const.h
deleted file mode 100644 (file)
index cbf9f33..0000000
--- a/include/babeltrace2/integer-range-set-const.h
+++ /dev/null
@@ -1,133 +0,0 @@
-#ifndef BABELTRACE2_INTEGER_RANGE_SET_CONST_H
-#define BABELTRACE2_INTEGER_RANGE_SET_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-#include <stddef.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern uint64_t bt_integer_range_unsigned_get_lower(
-               const bt_integer_range_unsigned *range);
-
-extern uint64_t bt_integer_range_unsigned_get_upper(
-               const bt_integer_range_unsigned *range);
-
-extern int64_t bt_integer_range_signed_get_lower(
-               const bt_integer_range_signed *range);
-
-extern int64_t bt_integer_range_signed_get_upper(
-               const bt_integer_range_signed *range);
-
-extern bt_bool bt_integer_range_unsigned_is_equal(
-               const bt_integer_range_unsigned *range_a,
-               const bt_integer_range_unsigned *range_b);
-
-extern bt_bool bt_integer_range_signed_is_equal(
-               const bt_integer_range_signed *range_a,
-               const bt_integer_range_signed *range_b);
-
-static inline
-const bt_integer_range_set *bt_integer_range_set_unsigned_as_range_set_const(
-               const bt_integer_range_set_unsigned *range_set)
-{
-       return __BT_UPCAST_CONST(bt_integer_range_set, range_set);
-}
-
-static inline
-const bt_integer_range_set *bt_integer_range_set_signed_as_range_set_const(
-               const bt_integer_range_set_signed *range_set)
-{
-       return __BT_UPCAST_CONST(bt_integer_range_set, range_set);
-}
-
-extern uint64_t bt_integer_range_set_get_range_count(const bt_integer_range_set *range_set);
-
-extern const bt_integer_range_unsigned *
-bt_integer_range_set_unsigned_borrow_range_by_index_const(
-               const bt_integer_range_set_unsigned *range_set, uint64_t index);
-
-extern const bt_integer_range_signed *
-bt_integer_range_set_signed_borrow_range_by_index_const(
-               const bt_integer_range_set_signed *range_set, uint64_t index);
-
-extern bt_bool bt_integer_range_set_unsigned_is_equal(
-               const bt_integer_range_set_unsigned *range_set_a,
-               const bt_integer_range_set_unsigned *range_set_b);
-
-extern bt_bool bt_integer_range_set_signed_is_equal(
-               const bt_integer_range_set_signed *range_set_a,
-               const bt_integer_range_set_signed *range_set_b);
-
-extern void bt_integer_range_set_unsigned_get_ref(
-               const bt_integer_range_set_unsigned *range_set);
-
-extern void bt_integer_range_set_unsigned_put_ref(
-               const bt_integer_range_set_unsigned *range_set);
-
-#define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_var)          \
-       do {                                                            \
-               bt_integer_range_set_unsigned_put_ref(_var);            \
-               (_var) = NULL;                                          \
-       } while (0)
-
-#define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_var_dst, _var_src)     \
-       do {                                                            \
-               bt_integer_range_set_unsigned_put_ref(_var_dst);        \
-               (_var_dst) = (_var_src);                                \
-               (_var_src) = NULL;                                      \
-       } while (0)
-
-extern void bt_integer_range_set_signed_get_ref(
-               const bt_integer_range_set_signed *range_set);
-
-extern void bt_integer_range_set_signed_put_ref(
-               const bt_integer_range_set_signed *range_set);
-
-#define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_var)            \
-       do {                                                            \
-               bt_integer_range_set_signed_put_ref(_var);              \
-               (_var) = NULL;                                          \
-       } while (0)
-
-#define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_var_dst, _var_src)       \
-       do {                                                            \
-               bt_integer_range_set_signed_put_ref(_var_dst);          \
-               (_var_dst) = (_var_src);                                \
-               (_var_src) = NULL;                                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_INTEGER_RANGE_SET_CONST_H */

diff --git a/include/babeltrace2/integer-range-set.h b/include/babeltrace2/integer-range-set.h
index f1d9a56c780eec2b93f75592d6af0f9c1228f5a4..8eb13434de06d032d2162b1acb0729a1ea7effcd 100644 (file)
--- a/include/babeltrace2/integer-range-set.h
+++ b/include/babeltrace2/integer-range-set.h
@@ -31,29 +31,757 @@
 #include <stddef.h>
 
 #include <babeltrace2/types.h>
-#include <babeltrace2/integer-range-set-const.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-extern bt_integer_range_set_unsigned *bt_integer_range_set_unsigned_create(void);
+/*!
+@defgroup api-int-rs Integer range sets
+
+@brief
+    Sets of unsigned and signed 64-bit integer ranges.
+
+An <strong><em>integer range set</em></strong>
+is an \em unordered set of integer ranges.
+
+An <strong><em>integer range</em></strong> represents all the
+integers \b 𝑥 which satisfy
+(<em>lower&nbsp;value</em>&nbsp;≤&nbsp;<strong>𝑥</strong>&nbsp;≤&nbsp;<em>upper&nbsp;value</em>).
+
+For example, an unsigned integer range set could contain the ranges
+[5,&nbsp;14], [199,&nbsp;2001], and [1976,&nbsp;3000].
+
+This integer range set API offers unsigned and signed 64-bit integer
+ranges and integer range sets with dedicated C&nbsp;types:
+
+- #bt_integer_range_unsigned
+- #bt_integer_range_signed
+- #bt_integer_range_set_unsigned
+- #bt_integer_range_set_signed
+
+This API uses the \em abstract #bt_integer_range_set type for common
+properties and operations (for example,
+bt_integer_range_set_get_range_count()).
+\ref api-fund-c-typing "Upcast" a specific
+integer range set to the #bt_integer_range_set type with
+bt_integer_range_set_unsigned_as_range_set_const() or
+bt_integer_range_set_signed_as_range_set_const().
+
+An integer range set is a \ref api-fund-shared-object "shared object":
+get a new reference with bt_integer_range_set_unsigned_get_ref() or
+bt_integer_range_set_signed_get_ref() and put an existing reference with
+bt_integer_range_set_unsigned_put_ref() or
+bt_integer_range_set_signed_put_ref().
+
+An integer range is a \ref api-fund-unique-object "unique object": it
+belongs to the integer range set which contains it.
+
+Some library functions \ref api-fund-freezing "freeze" integer range
+sets on success. The documentation of those functions indicate this
+postcondition.
+
+Create an empty integer range set with
+bt_integer_range_set_unsigned_create() or
+bt_integer_range_set_signed_create().
+
+Add an integer range to an integer range set with
+bt_integer_range_set_unsigned_add_range() or
+bt_integer_range_set_signed_add_range(). Although integer ranges can
+overlap, specific functions of the \bt_api expect an integer range set
+with non-overlapping integer ranges.
+
+As of \bt_name_version_min_maj, you cannot remove an existing
+integer range from an integer range set.
+
+Check that two integer ranges are equal with
+bt_integer_range_unsigned_is_equal() or
+bt_integer_range_signed_is_equal().
+
+Check that two integer range sets are equal with
+bt_integer_range_set_unsigned_is_equal() or
+bt_integer_range_set_signed_is_equal().
+*/
+
+/*! @{ */
+
+/*!
+@name Types
+@{
+
+@typedef struct bt_integer_range_unsigned bt_integer_range_unsigned
+
+@brief
+    Unsigned 64-bit integer range.
+
+
+@typedef struct bt_integer_range_signed bt_integer_range_signed
+
+@brief
+    Signed 64-bit integer range.
+
+
+@typedef struct bt_integer_range_set bt_integer_range_set
+
+@brief
+    Set of 64-bit integer ranges.
+
+This is an abstract type for common properties and operations. See \ref
+api-fund-c-typing to learn more about conceptual object type
+inheritance.
+
+
+@typedef struct bt_integer_range_set_unsigned bt_integer_range_set_unsigned;
+
+@brief
+    Set of unsigned 64-bit integer ranges.
+
+
+@typedef struct bt_integer_range_set_signed bt_integer_range_set_signed;
+
+@brief
+    Set of signed 64-bit integer ranges.
+
+@}
+*/
+
+/*!
+@name Unsigned integer range
+@{
+*/
+
+/*!
+@brief
+    Returns the lower value of the unsigned integer range
+    \bt_p{int_range}.
+
+The returned lower value is included in \bt_p{int_range}.
+
+@param[in] int_range
+    Unsigned integer range of which to get the lower value.
+
+@returns
+    Lower value of \bt_p{int_range}.
+
+@bt_pre_not_null{int_range}
+@bt_pre_is_bool_val{int_range}
+*/
+extern uint64_t bt_integer_range_unsigned_get_lower(
+               const bt_integer_range_unsigned *int_range);
 
+/*!
+@brief
+    Returns the upper value of the unsigned integer range
+    \bt_p{int_range}.
+
+The returned upper value is included in \bt_p{int_range}.
+
+@param[in] int_range
+    Unsigned integer range of which to get the upper value.
+
+@returns
+    Upper value of \bt_p{int_range}.
+
+@bt_pre_not_null{int_range}
+@bt_pre_is_bool_val{int_range}
+*/
+extern uint64_t bt_integer_range_unsigned_get_upper(
+               const bt_integer_range_unsigned *int_range);
+
+/*!
+@brief
+    Returns whether or not the unsigned integer range
+    \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
+
+Two unsigned integer ranges are considered equal if they have the same
+lower and upper values.
+
+@param[in] a_int_range
+    Unsigned integer range A.
+@param[in] b_int_range
+    Unsigned integer range B.
+
+@returns
+    #BT_TRUE if \bt_p{a_int_range} is equal to
+    \bt_p{b_int_range}.
+
+@bt_pre_not_null{a_int_range}
+@bt_pre_not_null{b_int_range}
+*/
+extern bt_bool bt_integer_range_unsigned_is_equal(
+               const bt_integer_range_unsigned *a_int_range,
+               const bt_integer_range_unsigned *b_int_range);
+
+/*! @} */
+
+/*!
+@name Signed integer range
+@{
+*/
+
+/*!
+@brief
+    Returns the lower value of the signed integer range
+    \bt_p{int_range}.
+
+The returned lower value is included in \bt_p{int_range}.
+
+@param[in] int_range
+    Signed integer range of which to get the lower value.
+
+@returns
+    Lower value of \bt_p{int_range}.
+
+@bt_pre_not_null{int_range}
+@bt_pre_is_bool_val{int_range}
+*/
+extern int64_t bt_integer_range_signed_get_lower(
+               const bt_integer_range_signed *int_range);
+
+/*!
+@brief
+    Returns the upper value of the signed integer range
+    \bt_p{int_range}.
+
+The returned upper value is included in \bt_p{int_range}.
+
+@param[in] int_range
+    Signed integer range of which to get the upper value.
+
+@returns
+    Upper value of \bt_p{int_range}.
+
+@bt_pre_not_null{int_range}
+@bt_pre_is_bool_val{int_range}
+*/
+extern int64_t bt_integer_range_signed_get_upper(
+               const bt_integer_range_signed *int_range);
+
+/*!
+@brief
+    Returns whether or not the signed integer range
+    \bt_p{a_int_range} is equal to \bt_p{b_int_range}.
+
+Two signed integer ranges are considered equal if they have the same
+lower and upper values.
+
+@param[in] a_int_range
+    Signed integer range A.
+@param[in] b_int_range
+    Signed integer range B.
+
+@returns
+    #BT_TRUE if \bt_p{a_int_range} is equal to
+    \bt_p{b_int_range}.
+
+@bt_pre_not_null{a_int_range}
+@bt_pre_not_null{b_int_range}
+*/
+extern bt_bool bt_integer_range_signed_is_equal(
+               const bt_integer_range_signed *a_int_range,
+               const bt_integer_range_signed *b_int_range);
+
+/*! @} */
+
+/*!
+@name Integer range set: common
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_integer_range_set_unsigned_add_range() and
+    bt_integer_range_set_signed_add_range().
+*/
 typedef enum bt_integer_range_set_add_range_status {
-       BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK            = __BT_FUNC_STATUS_OK,
+       /*!
+       @brief
+           Success.
+       */
+       BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_integer_range_set_add_range_status;
 
-extern bt_integer_range_set_add_range_status bt_integer_range_set_unsigned_add_range(
-               bt_integer_range_set_unsigned *range_set,
+/*!
+@brief
+    Returns the number of integer ranges contained in the integer
+    range set \bt_p{int_range_set}.
+
+@note
+    The parameter \bt_p{int_range_set} has the abstract type
+    #bt_integer_range_set: use
+    bt_integer_range_set_unsigned_as_range_set_const() or
+    bt_integer_range_set_signed_as_range_set_const() to upcast a
+    specific integer range set to this type.
+
+@param[in] int_range_set
+    Integer range set of which to get the number of contained integer
+    ranges.
+
+@returns
+    Number of contained integer ranges in \bt_p{int_range_set}.
+
+@bt_pre_not_null{int_range_set}
+*/
+extern uint64_t bt_integer_range_set_get_range_count(
+               const bt_integer_range_set *int_range_set);
+
+/*! @} */
+
+/*!
+@name Unsigned integer range set
+@{
+*/
+
+/*!
+@brief
+    Creates and returns an empty set of unsigned 64-bit integer ranges.
+
+@returns
+    New unsigned integer range set, or \c NULL on memory error.
+*/
+extern bt_integer_range_set_unsigned *bt_integer_range_set_unsigned_create(void);
+
+/*!
+@brief
+    Adds an unsigned 64-bit integer range having the lower value
+    \bt_p{lower} and the upper value \bt_p{upper} to the unsigned
+    integer range set
+    \bt_p{int_range_set}.
+
+The values \bt_p{lower} and \bt_p{upper} are included in the unsigned
+integer range to add to \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    Unsigned integer range set to which to add an unsigned integer
+    range.
+@param[in] lower
+    Lower value (included) of the unsigned integer range to add to
+    \bt_p{int_range_set}.
+@param[in] upper
+    Upper value (included) of the unsigned integer range to add to
+    \bt_p{int_range_set}.
+
+@retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
+    Success.
+@retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{int_range_set}
+@bt_pre_hot{int_range_set}
+@pre
+    \bt_p{lower} ≤ \bt_p{upper}.
+*/
+extern bt_integer_range_set_add_range_status
+bt_integer_range_set_unsigned_add_range(
+               bt_integer_range_set_unsigned *int_range_set,
                uint64_t lower, uint64_t upper);
 
+/*!
+@brief
+    Borrows the unsigned integer range at index \bt_p{index} from the
+    unsigned integer range set \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    Unsigned integer range set from which to borrow the unsigned integer
+    range at index \bt_p{index}.
+@param[in] index
+    Index of the unsigned integer range to borrow from
+    \bt_p{int_range_set}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the unsigned integer range of
+    \bt_p{int_range_set} at index \bt_p{index}.
+
+    The returned pointer remains valid until \bt_p{int_range_set} is
+    modified.
+    @endparblock
+
+@bt_pre_not_null{int_range_set}
+@pre
+    \bt_p{index} is less than the number of unsigned integer ranges in
+    \bt_p{int_range_set} (as returned by
+    bt_integer_range_set_get_range_count()).
+*/
+extern const bt_integer_range_unsigned *
+bt_integer_range_set_unsigned_borrow_range_by_index_const(
+               const bt_integer_range_set_unsigned *int_range_set,
+               uint64_t index);
+
+/*!
+@brief
+    Returns whether or not the unsigned integer range set
+    \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
+
+Two unsigned integer range sets are considered equal if they contain the
+exact same unsigned integer ranges, whatever the order. In other words,
+an unsigned integer range set containing [2,&nbsp;9] and [10,&nbsp;15]
+is \em not equal to an unsigned integer range containing [2,&nbsp;15].
+
+@param[in] int_range_set_a
+    Unsigned integer range set A.
+@param[in] int_range_set_b
+    Unsigned integer range set B.
+
+@returns
+    #BT_TRUE if \bt_p{int_range_set_a} is equal to
+    \bt_p{int_range_set_b}.
+
+@bt_pre_not_null{int_range_set_a}
+@bt_pre_not_null{int_range_set_b}
+*/
+extern bt_bool bt_integer_range_set_unsigned_is_equal(
+               const bt_integer_range_set_unsigned *int_range_set_a,
+               const bt_integer_range_set_unsigned *int_range_set_b);
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the unsigned integer range set
+    \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
+
+@param[in] int_range_set
+    @parblock
+    Unsigned integer range set to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{int_range_set} as an abstract integer range set.
+*/
+static inline
+const bt_integer_range_set *bt_integer_range_set_unsigned_as_range_set_const(
+               const bt_integer_range_set_unsigned *int_range_set)
+{
+       return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set);
+}
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the unsigned integer range set \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    @parblock
+    Unsigned integer range set of which to increment the reference
+    count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_integer_range_set_unsigned_put_ref() &mdash;
+    Decrements the reference count of an unsigned integer range set.
+*/
+extern void bt_integer_range_set_unsigned_get_ref(
+               const bt_integer_range_set_unsigned *int_range_set);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the unsigned integer range set \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    @parblock
+    Unsigned integer range set of which to decrement the reference
+    count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_integer_range_set_unsigned_get_ref() &mdash;
+    Increments the reference count of an unsigned integer range set.
+*/
+extern void bt_integer_range_set_unsigned_put_ref(
+               const bt_integer_range_set_unsigned *int_range_set);
+
+/*!
+@brief
+    Decrements the reference count of the unsigned integer range set
+    \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
+    NULL.
+
+@param _int_range_set
+    @parblock
+    Unsigned integer range set of which to decrement the reference
+    count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_int_range_set}
+*/
+#define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_int_range_set)        \
+       do {                                                            \
+               bt_integer_range_set_unsigned_put_ref(_int_range_set);  \
+               (_int_range_set) = NULL;                                \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the unsigned integer range set
+    \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
+    \bt_p{_src} to \c NULL.
+
+This macro effectively moves an unsigned integer range set reference
+from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
+the existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_dst, _src)     \
+       do {                                                    \
+               bt_integer_range_set_unsigned_put_ref(_dst);    \
+               (_dst) = (_src);                                \
+               (_src) = NULL;                                  \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Signed integer range set
+@{
+*/
+
+/*!
+@brief
+    Creates and returns an empty set of signed 64-bit integer ranges.
+
+@returns
+    New signed integer range set, or \c NULL on memory error.
+*/
 extern bt_integer_range_set_signed *bt_integer_range_set_signed_create(void);
 
-extern bt_integer_range_set_add_range_status bt_integer_range_set_signed_add_range(
-               bt_integer_range_set_signed *range_set,
+/*!
+@brief
+    Adds a signed 64-bit integer range having the lower value
+    \bt_p{lower} and the upper value \bt_p{upper} to the signed
+    integer range set
+    \bt_p{int_range_set}.
+
+The values \bt_p{lower} and \bt_p{upper} are included in the signed
+integer range to add to \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    Signed integer range set to which to add a signed integer
+    range.
+@param[in] lower
+    Lower value (included) of the signed integer range to add to
+    \bt_p{int_range_set}.
+@param[in] upper
+    Upper value (included) of the signed integer range to add to
+    \bt_p{int_range_set}.
+
+@retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_OK
+    Success.
+@retval #BT_INTEGER_RANGE_SET_ADD_RANGE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{int_range_set}
+@bt_pre_hot{int_range_set}
+@pre
+    \bt_p{lower} ≤ \bt_p{upper}.
+*/
+extern bt_integer_range_set_add_range_status
+bt_integer_range_set_signed_add_range(
+               bt_integer_range_set_signed *int_range_set,
                int64_t lower, int64_t upper);
 
+/*!
+@brief
+    Borrows the signed integer range at index \bt_p{index} from the
+    signed integer range set \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    Signed integer range set from which to borrow the signed integer
+    range at index \bt_p{index}.
+@param[in] index
+    Index of the signed integer range to borrow from
+    \bt_p{int_range_set}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the signed integer range of
+    \bt_p{int_range_set} at index \bt_p{index}.
+
+    The returned pointer remains valid until \bt_p{int_range_set} is
+    modified.
+    @endparblock
+
+@bt_pre_not_null{int_range_set}
+@pre
+    \bt_p{index} is less than the number of signed integer ranges in
+    \bt_p{int_range_set} (as returned by
+    bt_integer_range_set_get_range_count()).
+*/
+extern const bt_integer_range_signed *
+bt_integer_range_set_signed_borrow_range_by_index_const(
+               const bt_integer_range_set_signed *int_range_set, uint64_t index);
+
+/*!
+@brief
+    Returns whether or not the signed integer range set
+    \bt_p{int_range_set_a} is equal to \bt_p{int_range_set_b}.
+
+Two signed integer range sets are considered equal if they contain the
+exact same signed integer ranges, whatever the order. In other words,
+a signed integer range set containing [-57,&nbsp;23] and [24,&nbsp;42]
+is \em not equal to a signed integer range containing [-57,&nbsp;42].
+
+@param[in] int_range_set_a
+    Signed integer range set A.
+@param[in] int_range_set_b
+    Signed integer range set B.
+
+@returns
+    #BT_TRUE if \bt_p{int_range_set_a} is equal to
+    \bt_p{int_range_set_b}.
+
+@bt_pre_not_null{int_range_set_a}
+@bt_pre_not_null{int_range_set_b}
+*/
+extern bt_bool bt_integer_range_set_signed_is_equal(
+               const bt_integer_range_set_signed *int_range_set_a,
+               const bt_integer_range_set_signed *int_range_set_b);
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the signed integer range set
+    \bt_p{int_range_set} to the abstract #bt_integer_range_set type.
+
+@param[in] int_range_set
+    @parblock
+    Signed integer range set to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{int_range_set} as an abstract integer range set.
+*/
+static inline
+const bt_integer_range_set *bt_integer_range_set_signed_as_range_set_const(
+               const bt_integer_range_set_signed *int_range_set)
+{
+       return __BT_UPCAST_CONST(bt_integer_range_set, int_range_set);
+}
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the signed integer range set \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    @parblock
+    Signed integer range set of which to increment the reference
+    count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_integer_range_set_signed_put_ref() &mdash;
+    Decrements the reference count of a signed integer range set.
+*/
+extern void bt_integer_range_set_signed_get_ref(
+               const bt_integer_range_set_signed *int_range_set);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the signed integer range set \bt_p{int_range_set}.
+
+@param[in] int_range_set
+    @parblock
+    Signed integer range set of which to decrement the reference
+    count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_integer_range_set_signed_get_ref() &mdash;
+    Increments the reference count of a signed integer range set.
+*/
+extern void bt_integer_range_set_signed_put_ref(
+               const bt_integer_range_set_signed *int_range_set);
+
+/*!
+@brief
+    Decrements the reference count of the signed integer range set
+    \bt_p{_int_range_set}, and then sets \bt_p{_int_range_set} to \c
+    NULL.
+
+@param _int_range_set
+    @parblock
+    Signed integer range set of which to decrement the reference
+    count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_int_range_set}
+*/
+#define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_int_range_set)  \
+       do {                                                            \
+               bt_integer_range_set_signed_put_ref(_int_range_set);    \
+               (_int_range_set) = NULL;                                \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the signed integer range set
+    \bt_p{_dst}, sets \bt_p{_dst} to \bt_p{_src}, and then sets
+    \bt_p{_src} to \c NULL.
+
+This macro effectively moves a signed integer range set reference
+from the expression \bt_p{_src} to the expression \bt_p{_dst}, putting
+the existing \bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_dst, _src)       \
+       do {                                                    \
+               bt_integer_range_set_signed_put_ref(_dst);      \
+               (_dst) = (_src);                                \
+               (_src) = NULL;                                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/logging.h b/include/babeltrace2/logging.h
index 8091ec436a2bc512f5eada01cb26c77a7ef7e905..1c931743252fb10d9171f9089d6bcaec75375415 100644 (file)
--- a/include/babeltrace2/logging.h
+++ b/include/babeltrace2/logging.h
@@ -33,116 +33,210 @@
 extern "C" {
 #endif
 
-/**
-@defgroup logging Logging
-@ingroup apiref
-@brief Logging.
+/*!
+@defgroup api-logging Logging
 
-@code
-#include <babeltrace2/logging.h>
-@endcode
+@brief
+    Logging level enumerators and library logging control.
+
+The logging API offers logging level enumerators (#bt_logging_level)
+as well as functions to control libbabeltrace2's internal logging.
+
+@note
+    This API does \em not offer macros and functions to write logging
+    statements: as of \bt_name_version_min_maj, the actual mechanism to
+    log is implementation-defined for each user \bt_plugin.
+
+libbabeltrace2 contains many hundreds of logging statements to help you
+follow and debug your plugin or program.
+
+The library's initial logging level is controlled by the
+\c LIBBABELTRACE2_INIT_LOG_LEVEL environment variable. If this
+environment variable is not set at library load time, the library's
+initial logging level is #BT_LOGGING_LEVEL_NONE. See
+\ref api-fund-logging to learn more.
+
+Set libbabeltrace2's current logging level with
+bt_logging_set_global_level().
+
+\anchor api-logging-extra-lib bt_logging_set_global_level() only
+controls <strong>libbabeltrace2</strong>'s logging level; it does \em
+not control the logging level of:
+
+- Individual \bt_p_comp: bt_graph_add_source_component(),
+  bt_graph_add_source_component_with_initialize_method_data(),
+  bt_graph_add_filter_component(),
+  bt_graph_add_filter_component_with_initialize_method_data(),
+  bt_graph_add_sink_component(), and
+  bt_graph_add_sink_component_with_initialize_method_data() control
+  this.
 
-The functions in this module control the Babeltrace library's logging
-behaviour.
+- A \ref api-qexec "query operation":
+  bt_query_executor_set_logging_level() controls this.
 
-You can set the current global log level of the library with
-bt_logging_set_global_level(). Note that, if the level you set is below
-the minimal logging level (configured at build time, which you can get
-with bt_logging_get_minimal_level()), the logging statement between the
-current global log level and the minimal log level are not executed.
+- The bt_get_greatest_operative_mip_version() operation: its
+  \bt_p{logging_level} parameter controls this.
 
-@file
-@brief Logging functions.
-@sa logging
+As of \bt_name_version_min_maj, there's no module-specific logging level
+control: bt_logging_set_global_level() sets the logging level of all the
+library's modules.
 
-@addtogroup logging
-@{
+libbabeltrace2 writes its logging statements to the standard error
+stream. A logging line looks like this:
+
+@code{.unparsed}
+05-11 00:58:03.691 23402 23402 D VALUES bt_value_destroy@values.c:498 Destroying value: addr=0xb9c3eb0
+@endcode
+
+See \ref api-fund-logging to learn more about the logging statement
+line's format.
+
+You can set a \em minimal logging level at the \bt_name project's build
+time (see \ref api-fund-logging to learn how). The logging statements
+with a level that's less severe than the minimal logging level are \em
+not built. For example, if the minimal logging level is
+#BT_LOGGING_LEVEL_INFO, the #BT_LOGGING_LEVEL_TRACE and
+#BT_LOGGING_LEVEL_DEBUG logging statements are not built. Use
+bt_logging_get_minimal_level() to get the library's minimal logging
+level.
 */
 
-/**
-@brief Log levels.
+/*! @{ */
+
+/*!
+@brief
+    Logging level enumerators.
 */
 typedef enum bt_logging_level {
-       /// Additional, low-level debugging context information.
+       /*!
+       @brief
+           \em TRACE level.
+
+       Low-level debugging context information.
+
+       The \em TRACE logging statements can significantly
+       impact performance.
+       */
        BT_LOGGING_LEVEL_TRACE          = __BT_LOGGING_LEVEL_TRACE,
 
-       /**
-       Debugging information, only useful when searching for the
-       cause of a bug.
+       /*!
+       @brief
+           \em DEBUG level.
+
+       Debugging information, with a higher level of details than the
+       \em TRACE level.
+
+       The \em DEBUG logging statements do not significantly
+       impact performance.
        */
        BT_LOGGING_LEVEL_DEBUG          = __BT_LOGGING_LEVEL_DEBUG,
 
-       /**
-       Non-debugging information and failure to load optional
-       subsystems.
+       /*!
+       @brief
+           \em INFO level.
+
+       Informational messages that highlight progress or important
+       states of the application, plugins, or library.
+
+       The \em INFO logging statements do not significantly
+       impact performance.
        */
        BT_LOGGING_LEVEL_INFO           = __BT_LOGGING_LEVEL_INFO,
 
-       /**
-       Errors caused by a bad usage of the library, that is, a
-       non-observance of the documented function preconditions.
+       /*!
+       @brief
+           \em WARNING level.
 
-       The library's and object's states remain consistent when a
-       warning is issued.
+       Unexpected situations which still allow the execution to
+       continue.
+
+       The \em WARNING logging statements do not significantly
+       impact performance.
        */
        BT_LOGGING_LEVEL_WARNING        = __BT_LOGGING_LEVEL_WARNING,
 
-       /**
-       An important error from which the library cannot recover, but
-       the executed stack of functions can still return cleanly.
+       /*!
+       @brief
+           \em ERROR level.
+
+       Errors that might still allow the execution to continue.
+
+       Usually, once one or more errors are reported at this level, the
+       application, plugin, or library won't perform any more useful
+       task, but it should still exit cleanly.
+
+       The \em ERROR logging statements do not significantly
+       impact performance.
        */
        BT_LOGGING_LEVEL_ERROR          = __BT_LOGGING_LEVEL_ERROR,
 
-       /**
-       The library cannot continue to work in this condition: it must
-       terminate immediately, without even returning to the user's
-       execution.
+       /*!
+       @brief
+           \em FATAL level.
+
+       Severe errors that lead the execution to abort immediately.
+
+       The \em FATAL logging statements do not significantly
+       impact performance.
        */
        BT_LOGGING_LEVEL_FATAL          = __BT_LOGGING_LEVEL_FATAL,
 
-       /// Logging is disabled.
+       /*!
+       @brief
+           Logging is disabled.
+       */
        BT_LOGGING_LEVEL_NONE           = __BT_LOGGING_LEVEL_NONE,
 } bt_logging_level;
 
-/**
-@brief Returns the minimal log level of the Babeltrace library.
+/*!
+@brief
+    Sets the logging level of all the libbabeltrace2 modules to
+    \bt_p{logging_level}.
 
-The minimal log level is defined at the library's build time. Any
-logging statement with a level below the minimal log level is not
-compiled. This means that it is useless, although possible, to set the
-global log level with bt_logging_set_global_level() below this level.
+The library's global logging level
+\ref api-logging-extra-lib "does not affect" the logging level of
+individual components and query operations.
 
-@returns       Minimal, build time log level.
+@param[in] logging_level
+    New library's global logging level.
 
-@sa bt_logging_get_global_level(): Returns the current global log level.
+@sa bt_logging_get_global_level() &mdash;
+    Returns the current library's global logging level.
 */
-extern bt_logging_level bt_logging_get_minimal_level(void);
+extern void bt_logging_set_global_level(bt_logging_level logging_level);
 
-/**
-@brief Returns the current global log level of the Babeltrace library.
+/*!
+@brief
+    Returns the current logging level of all the libbabeltrace2 modules.
 
-@returns       Current global log level.
+@returns
+    Library's current global logging level.
 
-@sa bt_logging_set_global_level(): Sets the current global log level.
-@sa bt_logging_get_minimal_level(): Returns the minimal log level.
+@sa bt_logging_set_global_level() &mdash;
+    Sets the current library's global logging level.
 */
 extern bt_logging_level bt_logging_get_global_level(void);
 
-/**
-@brief Sets the current global log level of the Babeltrace library
-       to \p log_level.
+/*!
+@brief
+    Returns the library's minimal (build-time) logging level.
+
+The library logging statements with a level that's less severe than the
+minimal logging level are \em not built.
 
-If \p log_level is below what bt_logging_get_minimal_level() returns,
-the logging statements with a level between \p log_level and the minimal
-log level cannot be executed.
+For example, if the minimal logging level is #BT_LOGGING_LEVEL_INFO, the
+#BT_LOGGING_LEVEL_TRACE and #BT_LOGGING_LEVEL_DEBUG logging statements
+are not built.
 
-@param[in] log_level   Library's new global log level.
+@returns
+    Library's minimal logging level.
 
-@sa bt_logging_get_global_level(): Returns the global log level.
+@sa bt_logging_get_global_level() &mdash;
+    Returns the current library's global logging level.
 */
-extern void bt_logging_set_global_level(bt_logging_level log_level);
+extern bt_logging_level bt_logging_get_minimal_level(void);
 
-/** @} */
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/plugin/plugin-const.h b/include/babeltrace2/plugin/plugin-const.h
deleted file mode 100644 (file)
index 65b66de..0000000
--- a/include/babeltrace2/plugin/plugin-const.h
+++ /dev/null
@@ -1,164 +0,0 @@
-#ifndef BABELTRACE2_PLUGIN_PLUGIN_CONST_H
-#define BABELTRACE2_PLUGIN_PLUGIN_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-#include <stddef.h>
-
-#include <babeltrace2/types.h>
-#include <babeltrace2/property.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_plugin_find_status {
-       BT_PLUGIN_FIND_STATUS_OK                = __BT_FUNC_STATUS_OK,
-       BT_PLUGIN_FIND_STATUS_NOT_FOUND         = __BT_FUNC_STATUS_NOT_FOUND,
-       BT_PLUGIN_FIND_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
-       BT_PLUGIN_FIND_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_plugin_find_status;
-
-extern bt_plugin_find_status bt_plugin_find(const char *plugin_name,
-               bt_bool find_in_std_env_var, bt_bool find_in_user_dir,
-               bt_bool find_in_sys_dir, bt_bool find_in_static,
-               bt_bool fail_on_load_error, const bt_plugin **plugin);
-
-typedef enum bt_plugin_find_all_status {
-       BT_PLUGIN_FIND_ALL_STATUS_OK            = __BT_FUNC_STATUS_OK,
-       BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND     = __BT_FUNC_STATUS_NOT_FOUND,
-       BT_PLUGIN_FIND_ALL_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
-       BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_plugin_find_all_status;
-
-bt_plugin_find_all_status bt_plugin_find_all(bt_bool find_in_std_env_var,
-               bt_bool find_in_user_dir, bt_bool find_in_sys_dir,
-               bt_bool find_in_static, bt_bool fail_on_load_error,
-               const bt_plugin_set **plugin_set);
-
-typedef enum bt_plugin_find_all_from_file_status {
-       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK                  = __BT_FUNC_STATUS_OK,
-       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND           = __BT_FUNC_STATUS_NOT_FOUND,
-       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
-       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_plugin_find_all_from_file_status;
-
-extern bt_plugin_find_all_from_file_status bt_plugin_find_all_from_file(
-               const char *path, bt_bool fail_on_load_error,
-               const bt_plugin_set **plugin_set);
-
-typedef enum bt_plugin_find_all_from_dir_status {
-       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK                   = __BT_FUNC_STATUS_OK,
-       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND            = __BT_FUNC_STATUS_NOT_FOUND,
-       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR                = __BT_FUNC_STATUS_ERROR,
-       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR         = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_plugin_find_all_from_dir_status;
-
-extern bt_plugin_find_all_from_dir_status bt_plugin_find_all_from_dir(
-               const char *path, bt_bool recurse, bt_bool fail_on_load_error,
-               const bt_plugin_set **plugin_set);
-
-typedef enum bt_plugin_find_all_from_static_status {
-       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK                        = __BT_FUNC_STATUS_OK,
-       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND                 = __BT_FUNC_STATUS_NOT_FOUND,
-       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR                     = __BT_FUNC_STATUS_ERROR,
-       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR              = __BT_FUNC_STATUS_MEMORY_ERROR,
-} bt_plugin_find_all_from_static_status;
-
-extern bt_plugin_find_all_from_static_status bt_plugin_find_all_from_static(
-               bt_bool fail_on_load_error, const bt_plugin_set **plugin_set);
-
-extern const char *bt_plugin_get_name(const bt_plugin *plugin);
-
-extern const char *bt_plugin_get_author(const bt_plugin *plugin);
-
-extern const char *bt_plugin_get_license(const bt_plugin *plugin);
-
-extern const char *bt_plugin_get_description(const bt_plugin *plugin);
-
-extern const char *bt_plugin_get_path(const bt_plugin *plugin);
-
-extern bt_property_availability bt_plugin_get_version(
-               const bt_plugin *plugin, unsigned int *major,
-               unsigned int *minor, unsigned int *patch, const char **extra);
-
-extern uint64_t bt_plugin_get_source_component_class_count(
-               const bt_plugin *plugin);
-
-extern uint64_t bt_plugin_get_filter_component_class_count(
-               const bt_plugin *plugin);
-
-extern uint64_t bt_plugin_get_sink_component_class_count(
-               const bt_plugin *plugin);
-
-extern const bt_component_class_source *
-bt_plugin_borrow_source_component_class_by_index_const(
-               const bt_plugin *plugin, uint64_t index);
-
-extern const bt_component_class_filter *
-bt_plugin_borrow_filter_component_class_by_index_const(
-               const bt_plugin *plugin, uint64_t index);
-
-extern const bt_component_class_sink *
-bt_plugin_borrow_sink_component_class_by_index_const(
-               const bt_plugin *plugin, uint64_t index);
-
-extern const bt_component_class_source *
-bt_plugin_borrow_source_component_class_by_name_const(
-               const bt_plugin *plugin, const char *name);
-
-extern const bt_component_class_filter *
-bt_plugin_borrow_filter_component_class_by_name_const(
-               const bt_plugin *plugin, const char *name);
-
-extern const bt_component_class_sink *
-bt_plugin_borrow_sink_component_class_by_name_const(
-               const bt_plugin *plugin, const char *name);
-
-extern void bt_plugin_get_ref(const bt_plugin *plugin);
-
-extern void bt_plugin_put_ref(const bt_plugin *plugin);
-
-#define BT_PLUGIN_PUT_REF_AND_RESET(_var)              \
-       do {                                            \
-               bt_plugin_put_ref(_var);                \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_PLUGIN_MOVE_REF(_var_dst, _var_src)         \
-       do {                                            \
-               bt_plugin_put_ref(_var_dst);            \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_PLUGIN_PLUGIN_CONST_H */

diff --git a/include/babeltrace2/plugin/plugin-dev.h b/include/babeltrace2/plugin/plugin-dev.h
index c78288b8d87ef276914eed64fb066cb911b32a20..713725366f9ca9034a0dbb31f4118c84d463357f 100644 (file)
--- a/include/babeltrace2/plugin/plugin-dev.h
+++ b/include/babeltrace2/plugin/plugin-dev.h
@@ -29,10 +29,7 @@
 
 #include <stdint.h>
 
-#include <babeltrace2/graph/component-class-const.h>
-#include <babeltrace2/graph/component-class-source.h>
-#include <babeltrace2/graph/component-class-filter.h>
-#include <babeltrace2/graph/component-class-sink.h>
+#include <babeltrace2/graph/component-class-dev.h>
 #include <babeltrace2/graph/message-iterator-class.h>
 #include <babeltrace2/types.h>
 
@@ -51,19 +48,2386 @@
 extern "C" {
 #endif
 
-/* Plugin initialization function type */
+/*!
+@defgroup api-plugin-dev Plugin development
+
+@brief
+    Shared object plugin development.
+
+This module 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.
+
+See \ref guide-comp-link-plugin-so.
+
+<h1>Plugin definition C file structure</h1>
+
+The structure of a \bt_name plugin definition C file is as such:
+
+<ol>
+  <li>
+    Start with
+
+    @code
+    BT_PLUGIN_MODULE();
+    @endcode
+  </li>
+
+  <li>
+    Define a \bt_name plugin with BT_PLUGIN() if the plugin's name is a
+    valid C identifier, or with BT_PLUGIN_WITH_ID() otherwise.
+
+    See \ref api-plugin-dev-custom-plugin-id "Custom plugin ID" to
+    learn more about plugin IDs.
+
+    @note
+        When you use BT_PLUGIN(), the plugin's ID is <code>auto</code>.
+  </li>
+
+  <li>
+    \bt_dt_opt Use any of the following macros (or their
+    <code>*_WITH_ID()</code> counterpart) \em once to set the properties
+    of the plugin:
+
+    - BT_PLUGIN_AUTHOR()
+    - BT_PLUGIN_DESCRIPTION()
+    - BT_PLUGIN_LICENSE()
+    - BT_PLUGIN_VERSION()
+  </li>
+
+  <li>
+    \bt_dt_opt Use any of the following macros (or their
+    <code>*_WITH_ID()</code> counterpart) \em once to set the
+    initialization and finalization functions of the plugin:
+
+    - BT_PLUGIN_INITIALIZE_FUNC()
+    - BT_PLUGIN_FINALIZE_FUNC()
+
+    A plugin's initialization function is executed when the shared
+    object is loaded (see \ref api-plugin).
+
+    A plugin's finalization function is executed when the \bt_plugin
+    object is destroyed, if the initialization function (if any)
+    succeeded.
+  </li>
+
+  <li>
+    Use any of the following macros (or their <code>*_WITH_ID()</code>
+    counterpart) to add a component class to the plugin:
+
+    - BT_PLUGIN_SOURCE_COMPONENT_CLASS()
+    - BT_PLUGIN_FILTER_COMPONENT_CLASS()
+    - BT_PLUGIN_SINK_COMPONENT_CLASS()
+  </li>
+
+  <li>
+    \bt_dt_opt Depending on the type of the component class of step 5,
+    use any of the following macros (or their <code>*_WITH_ID()</code>
+    counterpart)
+    \em once to set its properties:
+
+    <dl>
+      <dt>\bt_c_src_comp_cls</dt>
+      <dd>
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION()
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP()
+      </dd>
+
+      <dt>\bt_c_flt_comp_cls</dt>
+      <dd>
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP()
+      </dd>
+
+      <dt>\bt_c_sink_comp_cls</dt>
+      <dd>
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION()
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_HELP()
+      </dd>
+    </dl>
+  </li>
+
+  <li>
+    \bt_dt_opt Depending on the type of the component class of step 5,
+    use any of the following macros (or their <code>*_WITH_ID()</code>
+    counterpart) to set its optional methods:
+
+    <dl>
+      <dt>Source component class</dt>
+      <dd>
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD()
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD()
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD()
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD()
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD()
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD()
+        - BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD()
+      </dd>
+
+      <dt>Filter component class</dt>
+      <dd>
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD()
+        - BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD()
+      </dd>
+
+      <dt>Sink component class</dt>
+      <dd>
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD()
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD()
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD()
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD()
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD()
+        - BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD()
+      </dd>
+    </dl>
+  </li>
+</ol>
+
+You can repeat steps 5 to 7 to add more than one component class to a
+given plugin.
+
+See \ref example-simple-plugin-def-file for a concrete example of how
+to use the macros of this module.
+
+<h1>\anchor api-plugin-dev-custom-plugin-id Custom plugin ID</h1>
+
+The BT_PLUGIN() macro defines a plugin with a specific name and the
+ID <code>auto</code>.
+
+All the <code>BT_PLUGIN_*()</code> macros which do not end with
+<code>_WITH_ID</code> refer to the <code>auto</code> plugin.
+
+There are two situations which demand that you use a custom plugin ID:
+
+- You want more than one plugin contained in your shared object file.
+
+  Although the \bt_name project does not recommend this, it is possible.
+  This is why bt_plugin_find_all_from_file() returns a \bt_plugin_set
+  instead of a single \bt_plugin.
+
+  In this case, each plugin of the shared object needs its own, unique
+  ID.
+
+- You want to give the plugin a name which is not a valid C identifier.
+
+  The BT_PLUGIN() macro accepts a C identifier as the plugin name, while
+  the BT_PLUGIN_WITH_ID() accepts a C identifier for the ID and a C
+  string for the name.
+
+To define a plugin with a specific ID, use BT_PLUGIN_WITH_ID(), for
+example:
+
+@code
+BT_PLUGIN_WITH_ID(my_plugin_id, "my-plugin-name");
+@endcode
+
+Then, use the <code>BT_PLUGIN_*_WITH_ID()</code> macros to refer to
+this specific plugin, for example:
+
+@code
+BT_PLUGIN_AUTHOR_WITH_ID(my_plugin_id, "Patrick Bouchard");
+@endcode
+
+@note
+    @parblock
+    You can still use the <code>auto</code> ID with BT_PLUGIN_WITH_ID()
+    to use the simpler macros afterwards while still giving the plugin a
+    name which is not a valid C identifier, for example:
+
+    @code
+    BT_PLUGIN_WITH_ID(auto, "my-plugin-name");
+    BT_PLUGIN_AUTHOR("Patrick Bouchard");
+    @endcode
+    @endparblock
+
+<h1>Custom component class ID</h1>
+
+The BT_PLUGIN_SOURCE_COMPONENT_CLASS(),
+BT_PLUGIN_FILTER_COMPONENT_CLASS(), and
+BT_PLUGIN_SINK_COMPONENT_CLASS() add a component class with a specific
+name to the plugin having the ID <code>auto</code>.
+
+The name you pass to those macros must be a valid C identifier and it
+also serves as the component class's ID within the <code>auto</code>
+plugin.
+
+There are two situations which demand that you use a custom component
+class ID:
+
+- You want to add the component class to a specific plugin (other than
+  <code>auto</code>, if you have more than one).
+
+- You want to give the component class a name which is not a valid C
+  identifier.
+
+  The <code>BT_PLUGIN_*_COMPONENT_CLASS_WITH_ID()</code> macros accept a
+  C identifier for the component class ID and a string for its name.
+
+For a given plugin and for a given component class type, all component
+class IDs must be unique.
+
+To add a component class having a specific ID to a plugin,
+use the BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(),
+BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID(), and
+BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID() macros, for example:
+
+@code
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(my_plugin_id, my_comp_class_id,
+    "my-source", my_source_iter_next);
+@endcode
+
+@note
+    @parblock
+    The <code>BT_PLUGIN_*_COMPONENT_CLASS_WITH_ID()</code> macros
+    specify the ID of the plugin to which to add the component class.
+
+    If you use the BT_PLUGIN() macro to define your plugin, then its
+    ID is <code>auto</code>:
+
+    @code
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(auto, my_comp_class_id,
+        "my-source", my_source_iter_next);
+    @endcode
+    @endparblock
+
+Then, use the <code>BT_PLUGIN_*_COMPONENT_CLASS_*_WITH_ID()</code>
+macros to refer to this specific component class, for example:
+
+@code
+BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(my_plugin_id,
+    my_comp_class_id, my_source_finalize);
+@endcode
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_self_plugin bt_self_plugin;
+
+@brief
+    Self plugin.
+
+@}
+*/
+
+/*!
+@name Plugin module
+@{
+*/
+
+/*!
+@brief
+    Defines a plugin module.
+
+In a plugin define C file, you must use this macro before you use any
+other <code>BT_PLUGIN*()</code> macro.
+*/
+#define BT_PLUGIN_MODULE() \
+       static struct __bt_plugin_descriptor const * const __bt_plugin_descriptor_dummy __BT_PLUGIN_DESCRIPTOR_ATTRS = NULL; \
+       _BT_HIDDEN extern struct __bt_plugin_descriptor const *__BT_PLUGIN_DESCRIPTOR_BEGIN_SYMBOL __BT_PLUGIN_DESCRIPTOR_BEGIN_EXTRA; \
+       _BT_HIDDEN extern struct __bt_plugin_descriptor const *__BT_PLUGIN_DESCRIPTOR_END_SYMBOL __BT_PLUGIN_DESCRIPTOR_END_EXTRA; \
+       \
+       static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_dummy __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = NULL; \
+       _BT_HIDDEN extern struct __bt_plugin_descriptor_attribute const *__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_EXTRA; \
+       _BT_HIDDEN extern struct __bt_plugin_descriptor_attribute const *__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_SYMBOL __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_EXTRA; \
+       \
+       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_component_class_descriptor_dummy __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = NULL; \
+       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_EXTRA; \
+       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_EXTRA; \
+       \
+       static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_component_class_descriptor_attribute_dummy __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = NULL; \
+       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor_attribute const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_EXTRA; \
+       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor_attribute const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_EXTRA; \
+       \
+       struct __bt_plugin_descriptor const * const *__bt_get_begin_section_plugin_descriptors(void) \
+       { \
+               return &__BT_PLUGIN_DESCRIPTOR_BEGIN_SYMBOL; \
+       } \
+       struct __bt_plugin_descriptor const * const *__bt_get_end_section_plugin_descriptors(void) \
+       { \
+               return &__BT_PLUGIN_DESCRIPTOR_END_SYMBOL; \
+       } \
+       struct __bt_plugin_descriptor_attribute const * const *__bt_get_begin_section_plugin_descriptor_attributes(void) \
+       { \
+               return &__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL; \
+       } \
+       struct __bt_plugin_descriptor_attribute const * const *__bt_get_end_section_plugin_descriptor_attributes(void) \
+       { \
+               return &__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_SYMBOL; \
+       } \
+       struct __bt_plugin_component_class_descriptor const * const *__bt_get_begin_section_component_class_descriptors(void) \
+       { \
+               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_SYMBOL; \
+       } \
+       struct __bt_plugin_component_class_descriptor const * const *__bt_get_end_section_component_class_descriptors(void) \
+       { \
+               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_SYMBOL; \
+       } \
+       struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_begin_section_component_class_descriptor_attributes(void) \
+       { \
+               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL; \
+       } \
+       struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_end_section_component_class_descriptor_attributes(void) \
+       { \
+               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_SYMBOL; \
+       }
+
+/*! @} */
+
+/*!
+@name Plugin definition
+@{
+*/
+
+/*!
+@brief
+    Defines a plugin named \bt_p{_name} and having the ID \bt_p{_id}.
+
+@param[in] _id
+    @parblock
+    C identifier.
+
+    Plugin's ID, unique amongst all the plugin IDs of the same shared
+    object.
+    @endparblock
+@param[in] _name
+    @parblock
+    <code>const char *</code>
+
+    Plugin's name.
+    @endparblock
+
+@bt_pre_not_null{_name}
+*/
+#define BT_PLUGIN_WITH_ID(_id, _name)                                  \
+       struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id = {  \
+               .name = _name,                                          \
+       };                                                              \
+       static struct __bt_plugin_descriptor const * const __bt_plugin_descriptor_##_id##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRS = &__bt_plugin_descriptor_##_id
+
+/*!
+@brief
+    Alias of BT_PLUGIN_WITH_ID() with the \bt_p{_id} parameter set to
+    <code>auto</code>.
+*/
+#define BT_PLUGIN(_name)               static BT_PLUGIN_WITH_ID(auto, #_name)
+
+/*! @} */
+
+/*!
+@name Plugin properties
+@{
+*/
+
+/*!
+@brief
+    Sets the description of the plugin having the ID \bt_p{_id} to
+    \bt_p{_description}.
+
+See the \ref api-comp-cls-prop-descr "description" property.
+
+@param[in] _id
+    @parblock
+    C identifier.
+
+    ID of the plugin of which to set the description.
+    @endparblock
+@param[in] _description
+    @parblock
+    <code>const char *</code>
+
+    Plugin's description.
+    @endparblock
+
+@bt_pre_not_null{_description}
+*/
+#define BT_PLUGIN_DESCRIPTION_WITH_ID(_id, _description) \
+       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _description)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_DESCRIPTION_WITH_ID() with the \bt_p{_id}
+    parameter set to <code>auto</code>.
+*/
+#define BT_PLUGIN_DESCRIPTION(_description)    BT_PLUGIN_DESCRIPTION_WITH_ID(auto, _description)
+
+
+/*!
+@brief
+    Sets the name(s) of the author(s) of the plugin having the ID
+    \bt_p{_id} to \bt_p{_author}.
+
+See the \ref api-plugin-prop-author "author name(s)" property.
+
+@param[in] _id
+    @parblock
+    C identifier.
+
+    ID of the plugin of which to set the author(s).
+    @endparblock
+@param[in] _author
+    @parblock
+    <code>const char *</code>
+
+    Plugin's author(s).
+    @endparblock
+
+@bt_pre_not_null{_author}
+*/
+#define BT_PLUGIN_AUTHOR_WITH_ID(_id, _author) \
+       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(author, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR, _id, _author)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_AUTHOR_WITH_ID() with the \bt_p{_id}
+    parameter set to <code>auto</code>.
+*/
+#define BT_PLUGIN_AUTHOR(_author)              BT_PLUGIN_AUTHOR_WITH_ID(auto, _author)
+
+/*!
+@brief
+    Sets the license (name or full) of the plugin having the ID
+    \bt_p{_id} to \bt_p{_license}.
+
+See the \ref api-plugin-prop-license "license" property.
+
+@param[in] _id
+    @parblock
+    C identifier.
+
+    ID of the plugin of which to set the license.
+    @endparblock
+@param[in] _license
+    @parblock
+    <code>const char *</code>
+
+    Plugin's license.
+    @endparblock
+
+@bt_pre_not_null{_license}
+*/
+#define BT_PLUGIN_LICENSE_WITH_ID(_id, _license) \
+       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(license, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE, _id, _license)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_LICENSE_WITH_ID() with the \bt_p{_id}
+    parameter set to <code>auto</code>.
+*/
+#define BT_PLUGIN_LICENSE(_license)            BT_PLUGIN_LICENSE_WITH_ID(auto, _license)
+
+/*!
+@brief
+    Sets the version of the plugin having the ID \bt_p{_id} to
+    \bt_p{_version}.
+
+See the \ref api-plugin-prop-version "version" property.
+
+@param[in] _id
+    @parblock
+    C identifier.
+
+    ID of the plugin of which to set the version.
+    @endparblock
+@param[in] _major
+    @parblock
+    <code>unsigned int</code>
+
+    Plugin's major version.
+    @endparblock
+@param[in] _minor
+    @parblock
+    <code>unsigned int</code>
+
+    Plugin's minor version.
+    @endparblock
+@param[in] _patch
+    @parblock
+    <code>unsigned int</code>
+
+    Plugin's patch version.
+    @endparblock
+@param[in] _extra
+    @parblock
+    <code>const char *</code>
+
+    Plugin's version's extra information.
+
+    Can be \c NULL if the plugin's version has no extra information.
+    @endparblock
+*/
+#define BT_PLUGIN_VERSION_WITH_ID(_id, _major, _minor, _patch, _extra) \
+       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(version, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_VERSION, _id, __BT_PLUGIN_VERSION_STRUCT_VALUE(_major, _minor, _patch, _extra))
+
+/*!
+@brief
+    Alias of BT_PLUGIN_VERSION_WITH_ID() with the \bt_p{_id}
+    parameter set to <code>auto</code>.
+*/
+#define BT_PLUGIN_VERSION(_major, _minor, _patch, _extra) BT_PLUGIN_VERSION_WITH_ID(auto, _major, _minor, _patch, _extra)
+
+/*! @} */
+
+/*!
+@name Plugin functions
+@{
+*/
+
+/*!
+@brief
+    Status codes for #bt_plugin_initialize_func.
+*/
 typedef enum bt_plugin_initialize_func_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_PLUGIN_INITIALIZE_FUNC_STATUS_OK             = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
        BT_PLUGIN_INITIALIZE_FUNC_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Error.
+       */
        BT_PLUGIN_INITIALIZE_FUNC_STATUS_ERROR          = __BT_FUNC_STATUS_ERROR,
 } bt_plugin_initialize_func_status;
 
-typedef bt_plugin_initialize_func_status (*bt_plugin_initialize_func)(
-               bt_self_plugin *plugin);
+/*!
+@brief
+    User plugin initialization function.
+
+@param[in] self_plugin
+    @parblock
+    Plugin instance.
+
+    This parameter is a private view of the \bt_plugin object for
+    this function.
+
+    As of \bt_name_version_min_maj, there's no self plugin API.
+    @endparblock
+
+@retval #BT_PLUGIN_INITIALIZE_FUNC_STATUS_OK
+    Success.
+@retval #BT_PLUGIN_INITIALIZE_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_PLUGIN_INITIALIZE_FUNC_STATUS_ERROR
+    Error.
 
-/* Plugin exit function type */
+@bt_pre_not_null{self_plugin}
+*/
+typedef bt_plugin_initialize_func_status (*bt_plugin_initialize_func)(
+               bt_self_plugin *self_plugin);
+
+/*!
+@brief
+    Sets the initialization function of the plugin having the ID
+    \bt_p{_id} to \bt_p{_func}.
+
+@param[in] _id
+    @parblock
+    C identifier.
+
+    ID of the plugin of which to set the initialization function.
+    @endparblock
+@param[in] _func
+    @parblock
+    #bt_plugin_initialize_func
+
+    Plugin's initialization function.
+    @endparblock
+
+@bt_pre_not_null{_func}
+*/
+#define BT_PLUGIN_INITIALIZE_FUNC_WITH_ID(_id, _func) \
+       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(init, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT, _id, _func)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_INITIALIZE_FUNC_WITH_ID() with the \bt_p{_id}
+    parameter set to <code>auto</code>.
+*/
+#define BT_PLUGIN_INITIALIZE_FUNC(_func)       BT_PLUGIN_INITIALIZE_FUNC_WITH_ID(auto, _func)
+
+/*!
+@brief
+    User plugin finalization function.
+*/
 typedef void (*bt_plugin_finalize_func)(void);
 
+/*!
+@brief
+    Sets the finalization function of the plugin having the ID
+    \bt_p{_id} to \bt_p{_func}.
+
+@param[in] _id
+    @parblock
+    C identifier.
+
+    ID of the plugin of which to set the finalization function.
+    @endparblock
+@param[in] _func
+    @parblock
+    #bt_plugin_finalize_func
+
+    Plugin's finalization function.
+    @endparblock
+
+@bt_pre_not_null{_func}
+*/
+#define BT_PLUGIN_FINALIZE_FUNC_WITH_ID(_id, _func) \
+       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(exit, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT, _id, _func)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_FINALIZE_FUNC_WITH_ID() with the \bt_p{_id}
+    parameter set to <code>auto</code>.
+*/
+#define BT_PLUGIN_FINALIZE_FUNC(_func) BT_PLUGIN_FINALIZE_FUNC_WITH_ID(auto, _func)
+
+/*! @} */
+
+/*!
+@name Component class adding
+@{
+*/
+
+/*!
+@brief
+    Adds a \bt_src_comp_cls named \bt_p{_name}, having the ID
+    \bt_p{_component_class_id} and the message iterator class's "next"
+    method \bt_p{_message_iterator_class_next_method}, to the plugin
+    having the ID \bt_p{_plugin_id}.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin to which to add the source component class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    Source component class's ID, unique amongst all the source component
+    class IDs of the same plugin.
+    @endparblock
+@param[in] _name
+    @parblock
+    <code>const char *</code>
+
+    Source component class's name, unique amongst all the source
+    component class names of the same plugin.
+    @endparblock
+@param[in] _message_iterator_class_next_method
+    @parblock
+    #bt_message_iterator_class_next_method
+
+    Source component class's message iterator class's "next" method.
+    @endparblock
+
+@bt_pre_not_null{_name}
+@bt_pre_not_null{_message_iterator_class_next_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(_plugin_id, _component_class_id, _name, _message_iterator_class_next_method) \
+       static struct __bt_plugin_component_class_descriptor __bt_plugin_source_component_class_descriptor_##_plugin_id##_##_component_class_id = { \
+               .plugin_descriptor = &__bt_plugin_descriptor_##_plugin_id,              \
+               .name = _name,                                                          \
+               .type = BT_COMPONENT_CLASS_TYPE_SOURCE,                                 \
+               .methods = { .source = { .msg_iter_next = _message_iterator_class_next_method } },      \
+       };                                                                              \
+       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_source_component_class_descriptor_##_plugin_id##_##_component_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_source_component_class_descriptor_##_plugin_id##_##_component_class_id
+
+/*!
+@brief
+    Alias of BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID() with the
+    \bt_p{_plugin_id} parameter set to <code>auto</code>, the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}, and
+    the \bt_p{_name} parameter set to a string version of \bt_p{_name}.
+
+@param[in] _name
+    @parblock
+    C identifier
+
+    Passed as both the \bt_p{_component_class_id} and the
+    \bt_p{_name} (once converted to a string) parameters of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID().
+    @endparblock
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS(_name, _message_iterator_class_next_method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _message_iterator_class_next_method)
+
+/*!
+@brief
+    Adds a \bt_flt_comp_cls named \bt_p{_name}, having the ID
+    \bt_p{_component_class_id} and the message iterator class's "next"
+    method \bt_p{_message_iterator_class_next_method}, to the plugin
+    having the ID \bt_p{_plugin_id}.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin to which to add the filter component class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    Filter component class's ID, unique amongst all the filter component
+    class IDs of the same plugin.
+    @endparblock
+@param[in] _name
+    @parblock
+    <code>const char *</code>
+
+    Filter component class's name, unique amongst all the filter
+    component class names of the same plugin.
+    @endparblock
+@param[in] _message_iterator_class_next_method
+    @parblock
+    #bt_message_iterator_class_next_method
+
+    Filter component class's message iterator class's "next" method.
+    @endparblock
+
+@bt_pre_not_null{_name}
+@bt_pre_not_null{_message_iterator_class_next_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID(_plugin_id, _component_class_id, _name, _message_iterator_class_next_method) \
+       static struct __bt_plugin_component_class_descriptor __bt_plugin_filter_component_class_descriptor_##_plugin_id##_##_component_class_id = { \
+               .plugin_descriptor = &__bt_plugin_descriptor_##_plugin_id,              \
+               .name = _name,                                                          \
+               .type = BT_COMPONENT_CLASS_TYPE_FILTER,                                 \
+               .methods = { .filter = { .msg_iter_next = _message_iterator_class_next_method } },      \
+       };                                                                              \
+       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_filter_component_class_descriptor_##_plugin_id##_##_component_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_filter_component_class_descriptor_##_plugin_id##_##_component_class_id
+
+/*!
+@brief
+    Alias of BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID() with the
+    \bt_p{_plugin_id} parameter set to <code>auto</code>, the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}, and
+    the \bt_p{_name} parameter set to a string version of \bt_p{_name}.
+
+@param[in] _name
+    @parblock
+    C identifier
+
+    Passed as both the \bt_p{_component_class_id} and the
+    \bt_p{_name} (once converted to a string) parameters of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID().
+    @endparblock
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS(_name, _message_iterator_class_next_method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _message_iterator_class_next_method)
+
+/*!
+@brief
+    Adds a \bt_sink_comp_cls named \bt_p{_name}, having the ID
+    \bt_p{_component_class_id} and the consuming method
+    \bt_p{_consume_method}, to the plugin
+    having the ID \bt_p{_plugin_id}.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin to which to add the sink component class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    Sink component class's ID, unique amongst all the sink component
+    class IDs of the same plugin.
+    @endparblock
+@param[in] _name
+    @parblock
+    <code>const char *</code>
+
+    Sink component class's name, unique amongst all the sink
+    component class names of the same plugin.
+    @endparblock
+@param[in] _consume_method
+    @parblock
+    #bt_component_class_sink_consume_method
+
+    Sink component class's message iterator class's "next" method.
+    @endparblock
+
+@bt_pre_not_null{_name}
+@bt_pre_not_null{_consume_method}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID(_plugin_id, _component_class_id, _name, _consume_method) \
+       static struct __bt_plugin_component_class_descriptor __bt_plugin_sink_component_class_descriptor_##_plugin_id##_##_component_class_id = { \
+               .plugin_descriptor = &__bt_plugin_descriptor_##_plugin_id, \
+               .name = _name,                                          \
+               .type = BT_COMPONENT_CLASS_TYPE_SINK,                   \
+               .methods = { .sink = { .consume = _consume_method } },  \
+       };                                                              \
+       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_sink_component_class_descriptor_##_plugin_id##_##_component_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_sink_component_class_descriptor_##_plugin_id##_##_component_class_id
+
+/*!
+@brief
+    Alias of BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID() with the
+    \bt_p{_plugin_id} parameter set to <code>auto</code>, the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}, and
+    the \bt_p{_name} parameter set to a string version of \bt_p{_name}.
+
+@param[in] _name
+    @parblock
+    C identifier
+
+    Passed as both the \bt_p{_component_class_id} and the
+    \bt_p{_name} (once converted to a string) parameters of
+    BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID().
+    @endparblock
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS(_name, _consume_method) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _consume_method)
+
+/*! @} */
+
+/*!
+@name Source component class properties
+@{
+*/
+
+/*!
+@brief
+    Sets the description of the \bt_src_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_description}.
+
+See the \ref api-comp-cls-prop-descr "description" property.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the description.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the description to
+    \bt_p{_description}.
+    @endparblock
+@param[in] _description
+    @parblock
+    <code>const char *</code>
+
+    Source component class's description.
+    @endparblock
+
+@bt_pre_not_null{_description}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_plugin_id, _component_class_id, _description) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _plugin_id, _component_class_id, source, _description)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION_WITH_ID() with
+    the \bt_p{_plugin_id} parameter set to <code>auto</code> and the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION(_name, _description) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _description)
+
+/*!
+@brief
+    Sets the help text of the \bt_src_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_help_text}.
+
+See the \ref api-comp-cls-prop-help "help text" property.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the help text.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the help text to
+    \bt_p{_help_text}.
+    @endparblock
+@param[in] _help_text
+    @parblock
+    <code>const char *</code>
+
+    Source component class's help text.
+    @endparblock
+
+@bt_pre_not_null{_help_text}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP_WITH_ID(_plugin_id, _component_class_id, _help_text) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _plugin_id, _component_class_id, source, _help_text)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP_WITH_ID() with the
+    \bt_p{_plugin_id} parameter set to <code>auto</code> and the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP(_name, _help_text) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _help_text)
+
+/*! @} */
+
+/*!
+@name Filter component class properties
+@{
+*/
+
+/*!
+@brief
+    Sets the description of the \bt_flt_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_description}.
+
+See the \ref api-comp-cls-prop-descr "description" property.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the description.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the description to
+    \bt_p{_description}.
+    @endparblock
+@param[in] _description
+    @parblock
+    <code>const char *</code>
+
+    Filter component class's description.
+    @endparblock
+
+@bt_pre_not_null{_description}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_plugin_id, _component_class_id, _description) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _plugin_id, _component_class_id, filter, _description)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION_WITH_ID() with
+    the \bt_p{_plugin_id} parameter set to <code>auto</code> and the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION(_name, _description) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _description)
+
+/*!
+@brief
+    Sets the help text of the \bt_flt_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_help_text}.
+
+See the \ref api-comp-cls-prop-help "help text" property.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the help text.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the help text to
+    \bt_p{_help_text}.
+    @endparblock
+@param[in] _help_text
+    @parblock
+    <code>const char *</code>
+
+    Filter component class's help text.
+    @endparblock
+
+@bt_pre_not_null{_help_text}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP_WITH_ID(_plugin_id, _component_class_id, _help_text) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _plugin_id, _component_class_id, filter, _help_text)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP_WITH_ID() with the
+    \bt_p{_plugin_id} parameter set to <code>auto</code> and the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP(_name, _help_text) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _help_text)
+
+/*! @} */
+
+/*!
+@name Sink component class properties
+@{
+*/
+
+/*!
+@brief
+    Sets the description of the \bt_sink_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_description}.
+
+See the \ref api-comp-cls-prop-descr "description" property.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the description.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the description to
+    \bt_p{_description}.
+    @endparblock
+@param[in] _description
+    @parblock
+    <code>const char *</code>
+
+    Sink component class's description.
+    @endparblock
+
+@bt_pre_not_null{_description}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_plugin_id, _component_class_id, _description) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _plugin_id, _component_class_id, sink, _description)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION_WITH_ID() with
+    the \bt_p{_plugin_id} parameter set to <code>auto</code> and the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION(_name, _description) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _description)
+
+/*!
+@brief
+    Sets the help text of the \bt_sink_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_help_text}.
+
+See the \ref api-comp-cls-prop-help "help text" property.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the help text.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the help text to
+    \bt_p{_help_text}.
+    @endparblock
+@param[in] _help_text
+    @parblock
+    <code>const char *</code>
+
+    Sink component class's help text.
+    @endparblock
+
+@bt_pre_not_null{_help_text}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_HELP_WITH_ID(_plugin_id, _component_class_id, _help_text) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _plugin_id, _component_class_id, sink, _help_text)
+
+/*!
+@brief
+    Alias of BT_PLUGIN_SINK_COMPONENT_CLASS_HELP_WITH_ID() with
+    the \bt_p{_plugin_id} parameter set to <code>auto</code> and the
+    \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_HELP(_name, _help_text) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _help_text)
+
+/*! @} */
+
+/*!
+@name Source component class methods
+@{
+*/
+
+/*!
+@brief
+    Sets the finalization method of the \bt_src_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the finalization method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the finalization method to
+    \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_source_finalize_method
+
+    Source component class's finalization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _plugin_id, _component_class_id, source, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the \"get supported \bt_mip versions\" method of the
+    \bt_src_comp_cls having the ID \bt_p{_component_class_id} in the
+    plugin having the ID \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the "get supported MIP versions" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "get supported MIP versions"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_source_get_supported_mip_versions_method
+
+    Source component class's "get supported MIP versions" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _plugin_id, _component_class_id, source, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the initialization method of the \bt_src_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the initialization method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the initialization method to
+    \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_source_initialize_method
+
+    Source component class's initialization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _plugin_id, _component_class_id, source, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the finalization method of the \bt_msg_iter_cls of the
+    \bt_src_comp_cls having the ID \bt_p{_component_class_id} in the
+    plugin having the ID \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-msg-iter-cls-meth-fini "finalize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the finalization method of the message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the finalization method of the
+    message iterator class to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_message_iterator_class_finalize_method
+
+    Source component class's message iterator class's finalization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_FINALIZE_METHOD, _plugin_id, _component_class_id, source, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the initialization method of the \bt_msg_iter_cls of the
+    \bt_src_comp_cls having the ID \bt_p{_component_class_id} in the
+    plugin having the ID \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-msg-iter-cls-meth-init "initialize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the initialization method of the message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the initialization method of the
+    message iterator class to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_message_iterator_class_initialize_method
+
+    Source component class's message iterator class's initialization
+    method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_INITIALIZE_METHOD, _plugin_id, _component_class_id, source, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the "seek beginning" and "can seek beginning?" methods of the
+    \bt_msg_iter_cls of the \bt_src_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_seek_method} and
+    \bt_p{_can_seek_method}.
+
+See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning" and
+\ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?" methods.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the "seek beginning" and "can seek beginning?" methods of the
+    message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "seek beginning" and "can
+    seek beginning" methods of the message iterator class to
+    \bt_p{_seek_method} and \bt_p{_can_seek_method}.
+    @endparblock
+@param[in] _seek_method
+    @parblock
+    #bt_message_iterator_class_seek_beginning_method
+
+    Source component class's message iterator class's "seek beginning"
+    method.
+    @endparblock
+@param[in] _can_seek_method
+    @parblock
+    #bt_message_iterator_class_can_seek_beginning_method
+
+    Source component class's message iterator class's
+    "can seek beginning?" method.
+
+    Can be \c NULL, in which case it is equivalent to setting a method
+    which always returns #BT_TRUE.
+    @endparblock
+
+@bt_pre_not_null{_seek_method}
+@bt_pre_not_null{_can_seek_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(_plugin_id, _component_class_id, _seek_method, _can_seek_method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_BEGINNING_METHOD, _plugin_id, _component_class_id, source, _seek_method); \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_BEGINNING_METHOD, _plugin_id, _component_class_id, source, _can_seek_method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS(_name, _seek_method, _can_seek_method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
+
+/*!
+@brief
+    Sets the "seek ns from origin" and "can seek ns from origin?"
+    methods of the \bt_msg_iter_cls of the \bt_src_comp_cls having the
+    ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_seek_method} and
+    \bt_p{_can_seek_method}.
+
+See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" and
+\ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+methods.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the "seek ns from origin" and "can seek ns from origin?"
+    methods of the message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "seek ns from origin" and
+    "can seek ns from origin" methods of the message iterator class to
+    \bt_p{_seek_method} and \bt_p{_can_seek_method}.
+    @endparblock
+@param[in] _seek_method
+    @parblock
+    #bt_message_iterator_class_seek_ns_from_origin_method
+
+    Source component class's message iterator class's "seek ns from
+    origin" method.
+    @endparblock
+@param[in] _can_seek_method
+    @parblock
+    #bt_message_iterator_class_can_seek_ns_from_origin_method
+
+    Source component class's message iterator class's "can seek ns from
+    origin?" method.
+
+    Can be \c NULL, in which case it is equivalent to setting a method
+    which always returns #BT_TRUE.
+    @endparblock
+
+@bt_pre_not_null{_seek_method}
+@bt_pre_not_null{_can_seek_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(_plugin_id, _component_class_id, _seek_method, _can_seek_method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_NS_FROM_ORIGIN_METHOD, _plugin_id, _component_class_id, source, _seek_method); \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_NS_FROM_ORIGIN_METHOD, _plugin_id, _component_class_id, source, _can_seek_method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS(_name, _seek_method, _can_seek_method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
+
+/*!
+@brief
+    Sets the "output port connected" method of the \bt_src_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the
+\ref api-comp-cls-dev-meth-oport-connected "output port connected"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the "output port connected" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "output port connected"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_source_output_port_connected_method
+
+    Source component class's "output port connected" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_output_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_OUTPUT_PORT_CONNECTED_METHOD, _plugin_id, _component_class_id, source, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD(_name, _method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the query method of the \bt_src_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the source component class of which
+    to set the query method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the source component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the query
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_source_query_method
+
+    Source component class's query method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _plugin_id, _component_class_id, source, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD(_name, _method) \
+       BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _method)
+
+/*! @} */
+
+/*!
+@name Filter component class methods
+@{
+*/
+
+/*!
+@brief
+    Sets the finalization method of the \bt_flt_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the finalization method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the finalization method to
+    \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_filter_finalize_method
+
+    Filter component class's finalization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the \"get supported \bt_mip versions\" method of the
+    \bt_flt_comp_cls having the ID \bt_p{_component_class_id} in the
+    plugin having the ID \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the "get supported MIP versions" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "get supported MIP versions"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_filter_get_supported_mip_versions_method
+
+    Filter component class's "get supported MIP versions" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the initialization method of the \bt_flt_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the initialization method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the initialization method to
+    \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_filter_initialize_method
+
+    Filter component class's initialization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the "input port connected" method of the \bt_flt_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the
+\ref api-comp-cls-dev-meth-iport-connected "input port connected"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the "input port connected" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "input port connected"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_filter_input_port_connected_method
+
+    Filter component class's "input port connected" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_input_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INPUT_PORT_CONNECTED_METHOD, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the finalization method of the \bt_msg_iter_cls of the
+    \bt_flt_comp_cls having the ID \bt_p{_component_class_id} in the
+    plugin having the ID \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-msg-iter-cls-meth-fini "finalize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the finalization method of the message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the finalization method of the
+    message iterator class to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_message_iterator_class_finalize_method
+
+    Filter component class's message iterator class's finalization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_FINALIZE_METHOD, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the initialization method of the \bt_msg_iter_cls of the
+    \bt_flt_comp_cls having the ID \bt_p{_component_class_id} in the
+    plugin having the ID \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-msg-iter-cls-meth-init "initialize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the initialization method of the message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the initialization method of the
+    message iterator class to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_message_iterator_class_initialize_method
+
+    Filter component class's message iterator class's initialization
+    method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_INITIALIZE_METHOD, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the "seek beginning" and "can seek beginning?" methods of the
+    \bt_msg_iter_cls of the \bt_flt_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_seek_method} and
+    \bt_p{_can_seek_method}.
+
+See the \ref api-msg-iter-cls-meth-seek-beg "seek beginning" and
+\ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?" methods.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the "seek beginning" and "can seek beginning?" methods of the
+    message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "seek beginning" and "can
+    seek beginning" methods of the message iterator class to
+    \bt_p{_seek_method} and \bt_p{_can_seek_method}.
+    @endparblock
+@param[in] _seek_method
+    @parblock
+    #bt_message_iterator_class_seek_beginning_method
+
+    Filter component class's message iterator class's "seek beginning"
+    method.
+    @endparblock
+@param[in] _can_seek_method
+    @parblock
+    #bt_message_iterator_class_can_seek_beginning_method
+
+    Filter component class's message iterator class's
+    "can seek beginning?" method.
+
+    Can be \c NULL, in which case it is equivalent to setting a method
+    which always returns #BT_TRUE.
+    @endparblock
+
+@bt_pre_not_null{_seek_method}
+@bt_pre_not_null{_can_seek_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(_plugin_id, _component_class_id, _seek_method, _can_seek_method) \
+               __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_BEGINNING_METHOD, _plugin_id, _component_class_id, filter, _seek_method); \
+               __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_BEGINNING_METHOD, _plugin_id, _component_class_id, filter, _can_seek_method);
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS(_name, _seek_method, _can_seek_method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
+
+/*!
+@brief
+    Sets the "seek ns from origin" and "can seek ns from origin?"
+    methods of the \bt_msg_iter_cls of the \bt_flt_comp_cls having the
+    ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_seek_method} and
+    \bt_p{_can_seek_method}.
+
+See the \ref api-msg-iter-cls-meth-seek-ns "seek ns from origin" and
+\ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?"
+methods.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the "seek ns from origin" and "can seek ns from origin?"
+    methods of the message iterator class.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "seek ns from origin" and
+    "can seek ns from origin" methods of the message iterator class to
+    \bt_p{_seek_method} and \bt_p{_can_seek_method}.
+    @endparblock
+@param[in] _seek_method
+    @parblock
+    #bt_message_iterator_class_seek_ns_from_origin_method
+
+    Filter component class's message iterator class's "seek ns from
+    origin" method.
+    @endparblock
+@param[in] _can_seek_method
+    @parblock
+    #bt_message_iterator_class_can_seek_ns_from_origin_method
+
+    Filter component class's message iterator class's "can seek ns from
+    origin?" method.
+
+    Can be \c NULL, in which case it is equivalent to setting a method
+    which always returns #BT_TRUE.
+    @endparblock
+
+@bt_pre_not_null{_seek_method}
+@bt_pre_not_null{_can_seek_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(_plugin_id, _component_class_id, _seek_method, _can_seek_method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_NS_FROM_ORIGIN_METHOD, _plugin_id, _component_class_id, filter, _seek_method); \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_NS_FROM_ORIGIN_METHOD, _plugin_id, _component_class_id, filter, _can_seek_method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS(_name, _seek_method, _can_seek_method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
+
+/*!
+@brief
+    Sets the "output port connected" method of the \bt_flt_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the
+\ref api-comp-cls-dev-meth-oport-connected "output port connected"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the "output port connected" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "output port connected"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_filter_output_port_connected_method
+
+    Filter component class's "output port connected" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_output_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_OUTPUT_PORT_CONNECTED_METHOD, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the query method of the \bt_flt_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the filter component class of which
+    to set the query method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the filter component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the query
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_filter_query_method
+
+    Filter component class's query method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _plugin_id, _component_class_id, filter, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD(_name, _method) \
+       BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _method)
+
+/*! @} */
+
+/*!
+@name Sink component class methods
+@{
+*/
+
+/*!
+@brief
+    Sets the finalization method of the \bt_sink_comp_cls having the ID
+    \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-fini "finalize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the finalization method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the finalization method to
+    \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_sink_finalize_method
+
+    Sink component class's finalization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _plugin_id, _component_class_id, sink, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the \"get supported \bt_mip versions\" method of the
+    \bt_sink_comp_cls having the ID \bt_p{_component_class_id} in the
+    plugin having the ID \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the "get supported MIP versions" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "get supported MIP versions"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_sink_get_supported_mip_versions_method
+
+    Sink component class's "get supported MIP versions" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _plugin_id, _component_class_id, sink, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _method) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the "graph is configured" method of the \bt_sink_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the
+\ref api-comp-cls-dev-meth-graph-configured "graph is configured"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the "graph is configured" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "graph is configured"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_sink_graph_is_configured_method
+
+    Sink component class's "graph is configured" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_graph_is_configured_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GRAPH_IS_CONFIGURED_METHOD, _plugin_id, _component_class_id, sink, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD(_name, _method) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the initialization method of the \bt_sink_comp_cls having the
+    ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-init "initialize" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the initialization method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the initialization method to
+    \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_sink_initialize_method
+
+    Sink component class's initialization method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _plugin_id, _component_class_id, sink, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _method) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the "input port connected" method of the \bt_sink_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the
+\ref api-comp-cls-dev-meth-iport-connected "input port connected"
+method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the "input port connected" method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the "input port connected"
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_sink_input_port_connected_method
+
+    Sink component class's "input port connected" method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_input_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INPUT_PORT_CONNECTED_METHOD, _plugin_id, _component_class_id, sink, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD(_name, _method) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _method)
+
+/*!
+@brief
+    Sets the query method of the \bt_sink_comp_cls
+    having the ID \bt_p{_component_class_id} in the plugin having the ID
+    \bt_p{_plugin_id} to \bt_p{_method}.
+
+See the \ref api-comp-cls-dev-meth-query "query" method.
+
+@param[in] _plugin_id
+    @parblock
+    C identifier.
+
+    ID of the plugin which contains the sink component class of which
+    to set the query method.
+    @endparblock
+@param[in] _component_class_id
+    @parblock
+    C identifier.
+
+    ID of the sink component class, within the plugin having the ID
+    \bt_p{_plugin_id}, of which to set the query
+    method to \bt_p{_method}.
+    @endparblock
+@param[in] _method
+    @parblock
+    #bt_component_class_sink_query_method
+
+    Sink component class's query method.
+    @endparblock
+
+@bt_pre_not_null{_method}
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_plugin_id, _component_class_id, _method) \
+       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _plugin_id, _component_class_id, sink, _method)
+
+/*!
+@brief
+    Alias of
+    BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID()
+    with the \bt_p{_plugin_id} parameter set to <code>auto</code> and
+    the \bt_p{_component_class_id} parameter set to \bt_p{_name}.
+*/
+#define BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD(_name, _method) \
+       BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _method)
+
+/*! @} */
+
+/*! @} */
+
 /* Plugin descriptor: describes a single plugin (internal use) */
 struct __bt_plugin_descriptor {
        /* Plugin's name */
@@ -255,6 +2619,47 @@ struct __bt_plugin_component_class_descriptor const * const *__bt_get_end_sectio
 struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_begin_section_component_class_descriptor_attributes(void);
 struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_end_section_component_class_descriptor_attributes(void);
 
+/*
+ * Defines a plugin attribute (generic, internal use).
+ *
+ * _attr_name: Name of the attribute (C identifier).
+ * _attr_type: Type of the attribute (enum __bt_plugin_descriptor_attribute_type).
+ * _id:        Plugin descriptor ID (C identifier).
+ * _x:         Value.
+ */
+#define __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _x) \
+       static struct __bt_plugin_descriptor_attribute __bt_plugin_descriptor_attribute_##_id##_##_attr_name = { \
+               .plugin_descriptor = &__bt_plugin_descriptor_##_id,     \
+               .type_name = #_attr_name,                               \
+               .type = _attr_type,                                     \
+               .value = { ._attr_name = _x },                          \
+       };                                                              \
+       static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_##_id##_##_attr_name##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_descriptor_attribute_##_id##_##_attr_name
+
+#define __BT_PLUGIN_VERSION_STRUCT_VALUE(_major, _minor, _patch, _extra) \
+       {.major = _major, .minor = _minor, .patch = _patch, .extra = _extra,}
+
+/*
+ * Defines a component class descriptor attribute (generic, internal
+ * use).
+ *
+ * _id:            Plugin descriptor ID (C identifier).
+ * _component_class_id: Component class ID (C identifier).
+ * _type:          Component class type (`source`, `filter`, or `sink`).
+ * _attr_name:     Name of the attribute (C identifier).
+ * _attr_type:     Type of the attribute
+ *                 (enum __bt_plugin_descriptor_attribute_type).
+ * _x:             Value.
+ */
+#define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _component_class_id, _type, _x) \
+       static struct __bt_plugin_component_class_descriptor_attribute __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_component_class_id##_##_attr_name = { \
+               .comp_class_descriptor = &__bt_plugin_##_type##_component_class_descriptor_##_id##_##_component_class_id, \
+               .type_name = #_attr_name,                               \
+               .type = _attr_type,                                     \
+               .value = { ._attr_name = _x },                          \
+       };                                                              \
+       static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_component_class_id##_##_attr_name##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_component_class_id##_##_attr_name
+
 /*
  * Variable attributes for a plugin descriptor pointer to be added to
  * the plugin descriptor section (internal use).
@@ -400,1042 +2805,6 @@ struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_
 #define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_EXTRA
 #endif
 
-/*
- * Declares a plugin descriptor pointer variable with a custom ID.
- *
- * _id: ID (any valid C identifier except `auto`).
- */
-#define BT_PLUGIN_DECLARE(_id) extern struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id
-
-/*
- * Defines a plugin descriptor with a custom ID.
- *
- * _id:   ID (any valid C identifier except `auto`).
- * _name: Plugin's name (C string).
- */
-#define BT_PLUGIN_WITH_ID(_id, _name)                                  \
-       struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id = {  \
-               .name = _name,                                          \
-       };                                                              \
-       static struct __bt_plugin_descriptor const * const __bt_plugin_descriptor_##_id##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRS = &__bt_plugin_descriptor_##_id
-
-/*
- * Defines a plugin attribute (generic, internal use).
- *
- * _attr_name: Name of the attribute (C identifier).
- * _attr_type: Type of the attribute (enum __bt_plugin_descriptor_attribute_type).
- * _id:        Plugin descriptor ID (C identifier).
- * _x:         Value.
- */
-#define __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _x) \
-       static struct __bt_plugin_descriptor_attribute __bt_plugin_descriptor_attribute_##_id##_##_attr_name = { \
-               .plugin_descriptor = &__bt_plugin_descriptor_##_id,     \
-               .type_name = #_attr_name,                               \
-               .type = _attr_type,                                     \
-               .value = { ._attr_name = _x },                          \
-       };                                                              \
-       static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_##_id##_##_attr_name##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_descriptor_attribute_##_id##_##_attr_name
-
-/*
- * Defines a plugin initialization function attribute attached to a
- * specific plugin descriptor.
- *
- * _id: Plugin descriptor ID (C identifier).
- * _x:  Initialization function (bt_plugin_initialize_func).
- */
-#define BT_PLUGIN_INITIALIZE_FUNC_WITH_ID(_id, _x) \
-       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(init, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT, _id, _x)
-
-/*
- * Defines a plugin exit function attribute attached to a specific
- * plugin descriptor.
- *
- * _id: Plugin descriptor ID (C identifier).
- * _x:  Exit function (bt_plugin_finalize_func).
- */
-#define BT_PLUGIN_FINALIZE_FUNC_WITH_ID(_id, _x) \
-       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(exit, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT, _id, _x)
-
-/*
- * Defines an author attribute attached to a specific plugin descriptor.
- *
- * _id: Plugin descriptor ID (C identifier).
- * _x:  Author (C string).
- */
-#define BT_PLUGIN_AUTHOR_WITH_ID(_id, _x) \
-       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(author, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR, _id, _x)
-
-/*
- * Defines a license attribute attached to a specific plugin descriptor.
- *
- * _id: Plugin descriptor ID (C identifier).
- * _x:  License (C string).
- */
-#define BT_PLUGIN_LICENSE_WITH_ID(_id, _x) \
-       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(license, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE, _id, _x)
-
-/*
- * Defines a description attribute attached to a specific plugin
- * descriptor.
- *
- * _id: Plugin descriptor ID (C identifier).
- * _x:  Description (C string).
- */
-#define BT_PLUGIN_DESCRIPTION_WITH_ID(_id, _x) \
-       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _x)
-
-#define __BT_PLUGIN_VERSION_STRUCT_VALUE(_major, _minor, _patch, _extra) \
-       {.major = _major, .minor = _minor, .patch = _patch, .extra = _extra,}
-
-/*
- * Defines a version attribute attached to a specific plugin descriptor.
- *
- * _id:    Plugin descriptor ID (C identifier).
- * _major: Plugin's major version (uint32_t).
- * _minor: Plugin's minor version (uint32_t).
- * _patch: Plugin's patch version (uint32_t).
- * _extra: Plugin's version extra information (C string).
- */
-#define BT_PLUGIN_VERSION_WITH_ID(_id, _major, _minor, _patch, _extra) \
-       __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(version, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_VERSION, _id, __BT_PLUGIN_VERSION_STRUCT_VALUE(_major, _minor, _patch, _extra))
-
-/*
- * Defines a source component class descriptor with a custom ID.
- *
- * _id:                     ID (any valid C identifier except `auto`).
- * _comp_class_id:          Component class ID (C identifier).
- * _name:                   Component class name (C string).
- * _msg_iter_next_method: Component class's iterator next method
- *                          (bt_component_class_source_message_iterator_next_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(_id, _comp_class_id, _name, _msg_iter_next_method) \
-       static struct __bt_plugin_component_class_descriptor __bt_plugin_source_component_class_descriptor_##_id##_##_comp_class_id = { \
-               .plugin_descriptor = &__bt_plugin_descriptor_##_id,                     \
-               .name = _name,                                                          \
-               .type = BT_COMPONENT_CLASS_TYPE_SOURCE,                                 \
-               .methods = { .source = { .msg_iter_next = _msg_iter_next_method } },    \
-       };                                                                              \
-       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_source_component_class_descriptor_##_id##_##_comp_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_source_component_class_descriptor_##_id##_##_comp_class_id
-
-/*
- * Defines a filter component class descriptor with a custom ID.
- *
- * _id:                     ID (any valid C identifier except `auto`).
- * _comp_class_id:          Component class ID (C identifier).
- * _name:                   Component class name (C string).
- * _msg_iter_next_method: Component class's iterator next method
- *                          (bt_component_class_filter_message_iterator_next_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID(_id, _comp_class_id, _name, _msg_iter_next_method) \
-       static struct __bt_plugin_component_class_descriptor __bt_plugin_filter_component_class_descriptor_##_id##_##_comp_class_id = { \
-               .plugin_descriptor = &__bt_plugin_descriptor_##_id,                     \
-               .name = _name,                                                          \
-               .type = BT_COMPONENT_CLASS_TYPE_FILTER,                                 \
-               .methods = { .filter = { .msg_iter_next = _msg_iter_next_method } },    \
-       };                                                                              \
-       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_filter_component_class_descriptor_##_id##_##_comp_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_filter_component_class_descriptor_##_id##_##_comp_class_id
-
-/*
- * Defines a sink component class descriptor with a custom ID.
- *
- * _id:                 ID (any valid C identifier except `auto`).
- * _comp_class_id:      Component class ID (C identifier).
- * _name:               Component class name (C string).
- * _consume_method:     Component class's iterator consume method
- *                      (bt_component_class_sink_consume_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID(_id, _comp_class_id, _name, _consume_method) \
-       static struct __bt_plugin_component_class_descriptor __bt_plugin_sink_component_class_descriptor_##_id##_##_comp_class_id = { \
-               .plugin_descriptor = &__bt_plugin_descriptor_##_id,     \
-               .name = _name,                                          \
-               .type = BT_COMPONENT_CLASS_TYPE_SINK,                   \
-               .methods = { .sink = { .consume = _consume_method } },  \
-       };                                                              \
-       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_sink_component_class_descriptor_##_id##_##_comp_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_sink_component_class_descriptor_##_id##_##_comp_class_id
-
-/*
- * Defines a component class descriptor attribute (generic, internal
- * use).
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class ID (C identifier).
- * _type:          Component class type (`source`, `filter`, or `sink`).
- * _attr_name:     Name of the attribute (C identifier).
- * _attr_type:     Type of the attribute
- *                 (enum __bt_plugin_descriptor_attribute_type).
- * _x:             Value.
- */
-#define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _comp_class_id, _type, _x) \
-       static struct __bt_plugin_component_class_descriptor_attribute __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_attr_name = { \
-               .comp_class_descriptor = &__bt_plugin_##_type##_component_class_descriptor_##_id##_##_comp_class_id, \
-               .type_name = #_attr_name,                               \
-               .type = _attr_type,                                     \
-               .value = { ._attr_name = _x },                          \
-       };                                                              \
-       static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_attr_name##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_attr_name
-
-/*
- * Defines a description attribute attached to a specific source
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Description (C string).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _comp_class_id, source, _x)
-
-/*
- * Defines a description attribute attached to a specific filter
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Description (C string).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines a description attribute attached to a specific sink
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Description (C string).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines a help attribute attached to a specific source component
- * class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Help (C string).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _id, _comp_class_id, source, _x)
-
-/*
- * Defines a help attribute attached to a specific filter component
- * class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Help (C string).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines a help attribute attached to a specific sink component class
- * descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Help (C string).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_HELP_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines an initialization method attribute attached to a specific
- * source component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Initialization method (bt_component_class_source_initialize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _id, _comp_class_id, source, _x)
-
-/*
- * Defines an initialization method attribute attached to a specific
- * filter component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Initialization method (bt_component_class_filter_initialize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines an initialization method attribute attached to a specific
- * sink component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Initialization method (bt_component_class_sink_initialize_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines a "get supported MIP versions" attribute attached to a
- * specific source component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             "Get supported MIP versions" method (bt_component_class_source_get_supported_mip_versions_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _id, _comp_class_id, source, _x)
-
-/*
- * Defines a "get supported MIP versions" attribute attached to a
- * specific filter component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             "Get supported MIP versions" method (bt_component_class_filter_get_supported_mip_versions_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines a "get supported MIP versions" attribute attached to a
- * specific sink component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             "Get supported MIP versions" method (bt_component_class_sink_get_supported_mip_versions_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines a finalization method attribute attached to a specific source
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Finalize method (bt_component_class_source_finalize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _id, _comp_class_id, source, _x)
-
-/*
- * Defines a finalization method attribute attached to a specific filter
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Finalize method (bt_component_class_filter_finalize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines a finalization method attribute attached to a specific sink
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Finalize method (bt_component_class_sink_finalize_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines a query method attribute attached to a specific source
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Finalize method (bt_component_class_source_query_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _id, _comp_class_id, source, _x)
-
-/*
- * Defines a query method attribute attached to a specific filter
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Finalize method (bt_component_class_filter_query_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines a query method attribute attached to a specific sink
- * component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Finalize method (bt_component_class_sink_query_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines an input port connected method attribute attached to a
- * specific filter component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Port connected method
- *                 (bt_component_class_filter_input_port_connected_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_input_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines an input port connected method attribute attached to a
- * specific sink component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Port connected method
- *                 (bt_component_class_sink_input_port_connected_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_input_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines an output port connected method attribute attached to a
- * specific source component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Port connected method
- *                 (bt_component_class_source_output_port_connected_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_output_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_OUTPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, source, _x)
-
-/*
- * Defines an output port connected method attribute attached to a
- * specific filter component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Port connected method
- *                 (bt_component_class_filter_output_port_connected_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_output_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_OUTPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines a "graph is configured" method attribute attached to a
- * specific sink component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             "Graph is configured" method
- *                 (bt_component_class_sink_graph_is_configured_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_graph_is_configured_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GRAPH_IS_CONFIGURED_METHOD, _id, _comp_class_id, sink, _x)
-
-/*
- * Defines an iterator initialization method attribute attached to a
- * specific source component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Iterator initialization method
- *                 (bt_component_class_source_message_iterator_initialize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_INITIALIZE_METHOD, _id, _comp_class_id, source, _x)
-
-/*
- * Defines an iterator finalize method attribute attached to a specific
- * source component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Iterator finalize method
- *                 (bt_component_class_source_message_iterator_finalize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_FINALIZE_METHOD, _id, _comp_class_id, source, _x)
-
-/*
- * Defines an iterator "seek nanoseconds from origin" and "can seek nanoseconds
- * from origin" method attributes attached to a specific source component class
- * descriptor.
- *
- * _id:              Plugin descriptor ID (C identifier).
- * _comp_class_id:   Component class descriptor ID (C identifier).
- * _seek_method:     Iterator "seek nanoseconds from origin" method
- *                   (bt_component_class_source_message_iterator_seek_ns_from_origin_method).
- * _can_seek_method: Iterator "can seek nanoseconds from origin" method
- *                   (bt_component_class_source_message_iterator_can_seek_ns_from_origin_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, source, _seek_method); \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, source, _can_seek_method)
-
-/*
- * Defines an iterator "seek beginning" and "can seek beginning" method
- * attributes attached to a specific source component class descriptor.
- *
- * _id:              Plugin descriptor ID (C identifier).
- * _comp_class_id:   Component class descriptor ID (C identifier).
- * _seek_method:     Iterator "seek beginning" method
- *                   (bt_component_class_source_message_iterator_seek_beginning_method).
- * _can_seek_method: Iterator "can seek beginning" method
- *                   (bt_component_class_source_message_iterator_can_seek_beginning_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_BEGINNING_METHOD, _id, _comp_class_id, source, _seek_method); \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_BEGINNING_METHOD, _id, _comp_class_id, source, _can_seek_method)
-
-/*
- * Defines an iterator initialization method attribute attached to a
- * specific filter component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Iterator initialization method
- *                 (bt_component_class_filter_message_iterator_initialize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_INITIALIZE_METHOD, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines an iterator finalize method attribute attached to a specific
- * filter component class descriptor.
- *
- * _id:            Plugin descriptor ID (C identifier).
- * _comp_class_id: Component class descriptor ID (C identifier).
- * _x:             Iterator finalize method
- *                 (bt_component_class_filter_message_iterator_finalize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_FINALIZE_METHOD, _id, _comp_class_id, filter, _x)
-
-/*
- * Defines an iterator "seek nanoseconds" and "can seek nanoseconds from origin"
- * method attributes attached to a specific filter component class descriptor.
- *
- * _id:              Plugin descriptor ID (C identifier).
- * _comp_class_id:   Component class descriptor ID (C identifier).
- * _seek_method:     Iterator "seek nanoseconds from origin" method
- *                   (bt_component_class_filter_message_iterator_seek_ns_from_origin_method).
- * _can_seek_method: Iterator "can seek nanoseconds from origin" method
- *                   (bt_component_class_filter_message_iterator_can_seek_ns_from_origin_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, filter, _seek_method); \
-       __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, filter, _can_seek_method)
-
-/*
- * Defines an iterator "seek beginning" and "can seek beginning" method
- * attributes attached to a specific filter component class descriptor.
- *
- * _id:              Plugin descriptor ID (C identifier).
- * _comp_class_id:   Component class descriptor ID (C identifier).
- * _seek_method:     Iterator "seek beginning" method
- *                   (bt_component_class_filter_message_iterator_seek_beginning_method).
- * _can_seek_method: Iterator "can seek beginning" method
- *                   (bt_component_class_filter_message_iterator_can_seek_beginning_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \
-               __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_BEGINNING_METHOD, _id, _comp_class_id, filter, _seek_method); \
-               __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_BEGINNING_METHOD, _id, _comp_class_id, filter, _can_seek_method);
-
-/*
- * Defines a plugin descriptor with an automatic ID.
- *
- * _name: Plugin's name (C string).
- */
-#define BT_PLUGIN(_name)               static BT_PLUGIN_WITH_ID(auto, #_name)
-
-/*
- * Defines a plugin initialization function attribute attached to the
- * automatic plugin descriptor.
- *
- * _x: Initialization function (bt_plugin_initialize_func).
- */
-#define BT_PLUGIN_INITIALIZE_FUNC(_x)  BT_PLUGIN_INITIALIZE_FUNC_WITH_ID(auto, _x)
-
- /*
- * Defines a plugin exit function attribute attached to the automatic
- * plugin descriptor.
- *
- * _x: Exit function (bt_plugin_finalize_func).
- */
-#define BT_PLUGIN_FINALIZE_FUNC(_x)    BT_PLUGIN_FINALIZE_FUNC_WITH_ID(auto, _x)
-
-/*
- * Defines an author attribute attached to the automatic plugin
- * descriptor.
- *
- * _x: Author (C string).
- */
-#define BT_PLUGIN_AUTHOR(_x)           BT_PLUGIN_AUTHOR_WITH_ID(auto, _x)
-
-/*
- * Defines a license attribute attached to the automatic plugin
- * descriptor.
- *
- * _x: License (C string).
- */
-#define BT_PLUGIN_LICENSE(_x)          BT_PLUGIN_LICENSE_WITH_ID(auto, _x)
-
-/*
- * Defines a description attribute attached to the automatic plugin
- * descriptor.
- *
- * _x: Description (C string).
- */
-#define BT_PLUGIN_DESCRIPTION(_x)      BT_PLUGIN_DESCRIPTION_WITH_ID(auto, _x)
-
-/*
- * Defines a version attribute attached to the automatic plugin
- * descriptor.
- *
- * _major: Plugin's major version (uint32_t).
- * _minor: Plugin's minor version (uint32_t).
- * _patch: Plugin's patch version (uint32_t).
- * _extra: Plugin's version extra information (C string).
- */
-#define BT_PLUGIN_VERSION(_major, _minor, _patch, _extra) BT_PLUGIN_VERSION_WITH_ID(auto, _major, _minor, _patch, _extra)
-
-/*
- * Defines a source component class attached to the automatic plugin
- * descriptor. Its ID is the same as its name, hence its name must be a
- * C identifier in this version.
- *
- * _name:                   Component class name (C identifier).
- * _msg_iter_next_method: Component class's iterator next method
- *                          (bt_component_class_source_message_iterator_next_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS(_name, _msg_iter_next_method) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _msg_iter_next_method)
-
-/*
- * Defines a filter component class attached to the automatic plugin
- * descriptor. Its ID is the same as its name, hence its name must be a
- * C identifier in this version.
- *
- * _name:                   Component class name (C identifier).
- * _msg_iter_next_method: Component class's iterator next method
- *                          (bt_component_class_filter_message_iterator_next_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS(_name, _msg_iter_next_method) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _msg_iter_next_method)
-
-/*
- * Defines a sink component class attached to the automatic plugin
- * descriptor. Its ID is the same as its name, hence its name must be a
- * C identifier in this version.
- *
- * _name:           Component class name (C identifier).
- * _consume_method: Component class's consume method
- *                  (bt_component_class_sink_consume_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS(_name, _consume_method) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _consume_method)
-
-/*
- * Defines a description attribute attached to a source component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Description (C string).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a description attribute attached to a filter component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Description (C string).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a description attribute attached to a sink component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Description (C string).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a help attribute attached to a source component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Help (C string).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a help attribute attached to a filter component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Help (C string).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a help attribute attached to a sink component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Help (C string).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_HELP(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an initialization method attribute attached to a source
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_source_initialize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an initialization method attribute attached to a filter
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_filter_initialize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an initialization method attribute attached to a sink
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_sink_initialize_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a "get supported MIP versions" method attribute attached to a
- * source component class descriptor which is attached to the automatic
- * plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_source_get_supported_mip_versions_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a "get supported MIP versions" method attribute attached to a
- * filter component class descriptor which is attached to the automatic
- * plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_filter_get_supported_mip_versions_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a "get supported MIP versions" method attribute attached to a
- * sink component class descriptor which is attached to the automatic
- * plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_sink_get_supported_mip_versions_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a finalization method attribute attached to a source component
- * class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_source_finalize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a finalization method attribute attached to a filter component
- * class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_filter_finalize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a finalization method attribute attached to a sink component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_sink_finalize_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a query method attribute attached to a source component
- * class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_source_query_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a query method attribute attached to a filter component
- * class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_filter_query_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a query method attribute attached to a sink component
- * class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Initialization method (bt_component_class_sink_query_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an input port connected method attribute attached to a filter
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Port connected (bt_component_class_filter_input_port_connected_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an input port connected method attribute attached to a sink
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Port connected (bt_component_class_sink_input_port_connected_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an output port connected method attribute attached to a source
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Port connected (bt_component_class_source_output_port_connected_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an output port connected method attribute attached to a filter
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Port connected (bt_component_class_filter_output_port_connected_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines a "graph is configured" method attribute attached to
- * a sink component class descriptor which is attached to the automatic
- * plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    "Graph is configured" method
- *        (bt_component_class_sink_graph_is_configured_method).
- */
-#define BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD(_name, _x) \
-       BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an iterator initialization method attribute attached to a
- * source component class descriptor which is attached to the automatic
- * plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Iterator initialization method
- *        (bt_component_class_source_message_iterator_initialize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an iterator finalize method attribute attached to a source
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Iterator finalize method
- *        (bt_component_class_source_message_iterator_finalize_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an iterator "seek nanoseconds from origin" and "can seek nanoseconds
- * from origin" method attributes attached to a source component class
- * descriptor which is attached to the automatic plugin descriptor.
- *
- * _name:            Component class name (C identifier).
- * _seek_method:     Iterator "seek nanoseconds from origin" method
- *                   (bt_component_class_source_message_iterator_seek_ns_from_origin_method).
- * _can_seek_method: Iterator "can seek nanoseconds from origin" method
- *                   (bt_component_class_source_message_iterator_can_seek_ns_from_origin_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS(_name, _seek_method, _can_seek_method) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
-
-/*
- * Defines an iterator "seek beginning" and "can seek beginning" method
- * attributes attached to a source component class descriptor which is attached
- * to the automatic plugin descriptor.
- *
- * _name:            Component class name (C identifier).
- * _seek_method:     Iterator "can seek beginning" method
- *                   (bt_component_class_source_message_iterator_can_seek_beginning_method).
- * _can_seek_method: Iterator "can seek beginning" method
- *                   (bt_component_class_source_message_iterator_seek_beginning_method).
- */
-#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS(_name, _seek_method, _can_seek_method) \
-       BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
-
-/*
- * Defines an iterator initialization method attribute attached to a
- * filter component class descriptor which is attached to the automatic
- * plugin descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Iterator initialization method
- *        (bt_component_class_filter_message_iterator_initialize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an iterator finalize method attribute attached to a filter
- * component class descriptor which is attached to the automatic plugin
- * descriptor.
- *
- * _name: Component class name (C identifier).
- * _x:    Iterator finalize method
- *        (bt_component_class_filter_message_iterator_finalize_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(_name, _x) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x)
-
-/*
- * Defines an iterator "seek nanosecconds from origin" and "can seek
- * nanoseconds from origin" method attributes attached to a filter component
- * class descriptor which is attached to the automatic plugin descriptor.
- *
- * _name:            Component class name (C identifier).
- * _seek_method:     Iterator "seek nanoseconds from origin" method
- *                   (bt_component_class_filter_message_iterator_seek_ns_from_origin_method).
- * _can_seek_method: Iterator "can seek nanoseconds from origin" method
- *                   (bt_component_class_filter_message_iterator_can_seek_ns_from_origin_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS(_name, _seek_method, _can_seek_method) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
-
-/*
- * Defines an iterator "seek beginning" and "can seek beginning" method
- * attributes attached to a filter component class descriptor which is attached
- * to the automatic plugin descriptor.
- *
- * _name:            Component class name (C identifier).
- * _seek_method:     Iterator "seek beginning" method
- *                   (bt_component_class_filter_message_iterator_seek_beginning_method).
- * _can_seek_method: Iterator "can seek beginning" method
- *                   (bt_component_class_filter_message_iterator_can_seek_beginning_method).
- */
-#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS(_name, _seek_method, _can_seek_method) \
-       BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method)
-
-#define BT_PLUGIN_MODULE() \
-       static struct __bt_plugin_descriptor const * const __bt_plugin_descriptor_dummy __BT_PLUGIN_DESCRIPTOR_ATTRS = NULL; \
-       _BT_HIDDEN extern struct __bt_plugin_descriptor const *__BT_PLUGIN_DESCRIPTOR_BEGIN_SYMBOL __BT_PLUGIN_DESCRIPTOR_BEGIN_EXTRA; \
-       _BT_HIDDEN extern struct __bt_plugin_descriptor const *__BT_PLUGIN_DESCRIPTOR_END_SYMBOL __BT_PLUGIN_DESCRIPTOR_END_EXTRA; \
-       \
-       static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_dummy __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = NULL; \
-       _BT_HIDDEN extern struct __bt_plugin_descriptor_attribute const *__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_EXTRA; \
-       _BT_HIDDEN extern struct __bt_plugin_descriptor_attribute const *__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_SYMBOL __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_EXTRA; \
-       \
-       static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_component_class_descriptor_dummy __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = NULL; \
-       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_EXTRA; \
-       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_EXTRA; \
-       \
-       static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_component_class_descriptor_attribute_dummy __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = NULL; \
-       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor_attribute const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_EXTRA; \
-       _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor_attribute const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_EXTRA; \
-       \
-       struct __bt_plugin_descriptor const * const *__bt_get_begin_section_plugin_descriptors(void) \
-       { \
-               return &__BT_PLUGIN_DESCRIPTOR_BEGIN_SYMBOL; \
-       } \
-       struct __bt_plugin_descriptor const * const *__bt_get_end_section_plugin_descriptors(void) \
-       { \
-               return &__BT_PLUGIN_DESCRIPTOR_END_SYMBOL; \
-       } \
-       struct __bt_plugin_descriptor_attribute const * const *__bt_get_begin_section_plugin_descriptor_attributes(void) \
-       { \
-               return &__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL; \
-       } \
-       struct __bt_plugin_descriptor_attribute const * const *__bt_get_end_section_plugin_descriptor_attributes(void) \
-       { \
-               return &__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_SYMBOL; \
-       } \
-       struct __bt_plugin_component_class_descriptor const * const *__bt_get_begin_section_component_class_descriptors(void) \
-       { \
-               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_SYMBOL; \
-       } \
-       struct __bt_plugin_component_class_descriptor const * const *__bt_get_end_section_component_class_descriptors(void) \
-       { \
-               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_SYMBOL; \
-       } \
-       struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_begin_section_component_class_descriptor_attributes(void) \
-       { \
-               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL; \
-       } \
-       struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_end_section_component_class_descriptor_attributes(void) \
-       { \
-               return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_SYMBOL; \
-       }
-
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/plugin/plugin-loading.h b/include/babeltrace2/plugin/plugin-loading.h
new file mode 100644 (file)
index 0000000..c95b53c
--- /dev/null
+++ b/include/babeltrace2/plugin/plugin-loading.h
@@ -0,0 +1,1432 @@
+#ifndef BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
+#define BABELTRACE2_PLUGIN_PLUGIN_LOADING_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include <babeltrace2/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-plugin Plugin loading
+
+@brief
+    Plugin loading functions.
+
+A <strong><em>plugin</em></strong> is a package of \bt_p_comp_cls:
+
+@image html plugin.png "A plugin is a package of component classes."
+
+@attention
+    The plugin loading API offers functions to <em>find and load</em>
+    existing plugins and use the packaged \bt_p_comp_cls. To \em write a
+    plugin, see \ref api-plugin-dev.
+
+There are three types of plugins:
+
+<dl>
+  <dt>Shared object plugin</dt>
+  <dd>
+    <code>.so</code> file on Unix systems;
+    <code>.dll</code> file on Windows systems.
+  </dd>
+
+  <dt>Python&nbsp;3 plugin</dt>
+  <dd>
+      <code>.py</code> file which starts with the
+      <code>bt_plugin_</code> prefix.
+  </dd>
+
+  <dt>Static plugin</dt>
+  <dd>
+      A plugin built directly into libbabeltrace2 or into the
+      user application.
+  </dd>
+</dl>
+
+libbabeltrace2 loads shared object and Python plugins. Those plugins
+need libbabeltrace2 in turn to create and use \bt_name objects:
+
+@image html linking.png "libbabeltrace2 loads plugins which need libbabeltrace2."
+
+A plugin is a \ref api-fund-shared-object "shared object": get a new
+reference with bt_plugin_get_ref() and put an existing reference with
+bt_plugin_put_ref().
+
+Get the number of \bt_comp_cls in a plugin with
+bt_plugin_get_source_component_class_count(),
+bt_plugin_get_filter_component_class_count(), and
+bt_plugin_get_sink_component_class_count().
+
+Borrow a \bt_comp_cls by index from a plugin with
+bt_plugin_borrow_source_component_class_by_index_const(),
+bt_plugin_borrow_filter_component_class_by_index_const(), and
+bt_plugin_borrow_sink_component_class_by_index_const().
+
+Borrow a \bt_comp_cls by name from a plugin with
+bt_plugin_borrow_source_component_class_by_name_const(),
+bt_plugin_borrow_filter_component_class_by_name_const(), and
+bt_plugin_borrow_sink_component_class_by_name_const().
+
+The bt_plugin_find_all(), bt_plugin_find_all_from_file(),
+bt_plugin_find_all_from_dir(), and bt_plugin_find_all_from_static()
+functions return a <strong>plugin set</strong>, that is, a shared object
+containing one or more plugins.
+
+<h1>Find and load plugins</h1>
+
+\anchor api-plugin-def-dirs The bt_plugin_find() and
+bt_plugin_find_all() functions find and load plugins from the default
+plugin search directories and from the static plugins.
+
+The plugin search order is:
+
+-# The colon-separated (or semicolon-separated on Windows) list of
+   directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
+   if it's set.
+
+   The function searches each directory in this list, without recursing.
+
+-# <code>$HOME/.local/lib/babeltrace2/plugins</code>,
+   without recursing.
+
+-# The system \bt_name plugin directory, typically
+   <code>/usr/lib/babeltrace2/plugins</code> or
+   <code>/usr/local/lib/babeltrace2/plugins</code> on Linux,
+   without recursing.
+
+-# The static plugins.
+
+Both bt_plugin_find() and bt_plugin_find_all() functions have dedicated
+boolean parameters to include or exclude each of the four locations
+above.
+
+<h2>Find and load a plugin by name</h2>
+
+Find and load a plugin by name with bt_plugin_find().
+
+bt_plugin_find() tries to find a plugin with a specific name within
+the \ref api-plugin-def-dirs "default plugin search directories"
+and static plugins.
+
+<h2>Find and load all the plugins from the default directories</h2>
+
+Load all the plugins found in the
+\ref api-plugin-def-dirs "default plugin search directories"
+and static plugins with bt_plugin_find_all().
+
+<h2>Find and load plugins from a specific file or directory</h2>
+
+Find and load plugins from a specific file (<code>.so</code>,
+<code>.dll</code>, or <code>.py</code>) with
+bt_plugin_find_all_from_file().
+
+A single shared object file can contain multiple plugins, although it's
+not common practice to do so.
+
+Find and load plugins from a specific directory with
+bt_plugin_find_all_from_dir(). This function can search for plugins
+within the given directory recursively or not.
+
+<h2>Find and load static plugins</h2>
+
+Find and load static plugins with bt_plugin_find_all_from_static().
+
+A static plugin is built directly into the application or library
+instead of being a separate shared object file.
+
+<h1>Plugin properties</h1>
+
+A plugin has the following properties:
+
+<dl>
+  <dt>
+    \anchor api-plugin-prop-name
+    Name
+  </dt>
+  <dd>
+    Name of the plugin.
+
+    The plugin's name is not related to its file name. For example,
+    a plugin found in the file \c patente.so can be named
+    <code>Dan</code>.
+
+    Use bt_plugin_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-plugin-prop-descr
+    \bt_dt_opt Description
+  </dt>
+  <dd>
+    Description of the plugin.
+
+    Use bt_plugin_get_description().
+  </dd>
+
+  <dt>
+    \anchor api-plugin-prop-author
+    \bt_dt_opt Author name(s)
+  </dt>
+  <dd>
+    Name(s) of the plugin's author(s).
+
+    Use bt_plugin_get_author().
+  </dd>
+
+  <dt>
+    \anchor api-plugin-prop-license
+    \bt_dt_opt License
+  </dt>
+  <dd>
+    License or license name of the plugin.
+
+    Use bt_plugin_get_license().
+  </dd>
+
+  <dt>
+    \anchor api-plugin-prop-path
+    \bt_dt_opt Path
+  </dt>
+  <dd>
+    Path of the file which contains the plugin.
+
+    A static plugin has no path property.
+
+    Get bt_plugin_get_path().
+  </dd>
+
+  <dt>
+    \anchor api-plugin-prop-version
+    \bt_dt_opt Version
+  </dt>
+  <dd>
+    Version of the plugin (major, minor, patch, and extra information).
+
+    The plugin's version is completely user-defined: the library does
+    not use this property in any way to verify the plugin's
+    compatibility.
+
+    Use bt_plugin_get_version().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_plugin bt_plugin;
+
+@brief
+    Plugin.
+
+
+@typedef struct bt_plugin_set bt_plugin_set;
+
+@brief
+    Set of plugins.
+
+@}
+*/
+
+/*!
+@name Find and load plugins
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_plugin_find().
+*/
+typedef enum bt_plugin_find_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_PLUGIN_FIND_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Plugin not found.
+       */
+       BT_PLUGIN_FIND_STATUS_NOT_FOUND         = __BT_FUNC_STATUS_NOT_FOUND,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_PLUGIN_FIND_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Error.
+       */
+       BT_PLUGIN_FIND_STATUS_ERROR             = __BT_FUNC_STATUS_ERROR,
+} bt_plugin_find_status;
+
+/*!
+@brief
+    Finds and loads a single plugin which has the name
+    \bt_p{plugin_name} from the default plugin search directories and
+    static plugins, setting \bt_p{*plugin} to the result.
+
+This function returns the first plugin which has the name
+\bt_p{plugin_name} within, in order:
+
+-# <strong>If the \bt_p{find_in_std_env_var} parameter is
+   #BT_TRUE</strong>,
+   the colon-separated (or semicolon-separated on Windows) list of
+   directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
+   if it's set.
+
+   The function searches each directory in this list, without recursing.
+
+-# <strong>If the \bt_p{find_in_user_dir} parameter is
+   #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
+   without recursing.
+
+-# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
+   system \bt_name plugin directory, typically
+   <code>/usr/lib/babeltrace2/plugins</code> or
+   <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
+   recursing.
+
+-# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
+   the static plugins.
+
+@note
+    A plugin's name is not related to the name of its file (shared
+    object or Python file). For example, a plugin found in the file
+    \c patente.so can be named <code>Dan</code>.
+
+If this function finds a file which looks like a plugin (shared object
+file or Python file with the \c bt_plugin_ prefix), but it fails to load
+it for any reason, the function:
+
+<dl>
+  <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
+  <dd>Returns #BT_PLUGIN_FIND_STATUS_ERROR.</dd>
+
+  <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
+  <dd>Ignores the loading error and continues searching.</dd>
+</dl>
+
+If this function doesn't find any plugin, it returns
+#BT_PLUGIN_FIND_STATUS_NOT_FOUND and does \em not set \bt_p{*plugin}.
+
+@param[in] plugin_name
+    Name of the plugin to find and load.
+@param[in] find_in_std_env_var
+    #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
+    colon-separated (or semicolon-separated on Windows) list of
+    directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
+@param[in] find_in_user_dir
+    #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
+    the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
+    without recursing.
+@param[in] find_in_sys_dir
+    #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in
+    the system \bt_name plugin directory.
+@param[in] find_in_static
+    #BT_TRUE to try to find the plugin named \bt_p{plugin_name} in the
+    static plugins.
+@param[in] fail_on_load_error
+    #BT_TRUE to make this function return #BT_PLUGIN_FIND_STATUS_ERROR
+    on any plugin loading error instead of ignoring it.
+@param[out] plugin
+    <strong>On success</strong>, \bt_p{*plugin} is a new plugin
+    reference of named \bt_p{plugin_name}.
+
+@retval #BT_PLUGIN_FIND_STATUS_OK
+    Success.
+@retval #BT_PLUGIN_FIND_STATUS_NOT_FOUND
+    Plugin not found.
+@retval #BT_PLUGIN_FIND_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_PLUGIN_FIND_STATUS_ERROR
+    Error.
+
+@bt_pre_not_null{plugin_name}
+@pre
+    At least one of the \bt_p{find_in_std_env_var},
+    \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
+    \bt_p{find_in_static} parameters is #BT_TRUE.
+@bt_pre_not_null{plugin}
+
+@sa bt_plugin_find_all() &mdash;
+    Finds and loads all plugins from the default plugin search
+    directories and static plugins.
+*/
+extern bt_plugin_find_status bt_plugin_find(const char *plugin_name,
+               bt_bool find_in_std_env_var, bt_bool find_in_user_dir,
+               bt_bool find_in_sys_dir, bt_bool find_in_static,
+               bt_bool fail_on_load_error, const bt_plugin **plugin);
+
+/*!
+@brief
+    Status codes for bt_plugin_find_all().
+*/
+typedef enum bt_plugin_find_all_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_PLUGIN_FIND_ALL_STATUS_OK            = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           No plugins found.
+       */
+       BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND     = __BT_FUNC_STATUS_NOT_FOUND,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Error.
+       */
+       BT_PLUGIN_FIND_ALL_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
+} bt_plugin_find_all_status;
+
+/*!
+@brief
+    Finds and loads all the plugins from the default
+    plugin search directories and static plugins, setting
+    \bt_p{*plugins} to the result.
+
+This function returns all the plugins within, in order:
+
+-# <strong>If the \bt_p{find_in_std_env_var} parameter is
+   #BT_TRUE</strong>,
+   the colon-separated (or semicolon-separated on Windows) list of
+   directories in the \c BABELTRACE_PLUGIN_PATH environment variable,
+   if it's set.
+
+   The function searches each directory in this list, without recursing.
+
+-# <strong>If the \bt_p{find_in_user_dir} parameter is
+   #BT_TRUE</strong>, <code>$HOME/.local/lib/babeltrace2/plugins</code>,
+   without recursing.
+
+-# <strong>If the \bt_p{find_in_sys_dir} is #BT_TRUE</strong>, the
+   system \bt_name plugin directory, typically
+   <code>/usr/lib/babeltrace2/plugins</code> or
+   <code>/usr/local/lib/babeltrace2/plugins</code> on Linux, without
+   recursing.
+
+-# <strong>If the \bt_p{find_in_static} is #BT_TRUE</strong>,
+   the static plugins.
+
+During the search process, if a found plugin shares the name of an
+already loaded plugin, this function ignores it and continues.
+
+If this function finds a file which looks like a plugin (shared object
+file or Python file with the \c bt_plugin_ prefix), but it fails to load
+it for any reason, the function:
+
+<dl>
+  <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
+  <dd>Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.</dd>
+
+  <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
+  <dd>Ignores the loading error and continues searching.</dd>
+</dl>
+
+If this function doesn't find any plugin, it returns
+#BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND and does \em not set
+\bt_p{*plugins}.
+
+@param[in] find_in_std_env_var
+    #BT_TRUE to try to find all the plugins in the
+    colon-separated (or semicolon-separated on Windows) list of
+    directories in the \c BABELTRACE_PLUGIN_PATH environment variable.
+@param[in] find_in_user_dir
+    #BT_TRUE to try to find all the plugins in
+    the <code>$HOME/.local/lib/babeltrace2/plugins</code> directory,
+    without recursing.
+@param[in] find_in_sys_dir
+    #BT_TRUE to try to find all the plugins in the system \bt_name
+    plugin directory.
+@param[in] find_in_static
+    #BT_TRUE to try to find all the plugins in the static plugins.
+@param[in] fail_on_load_error
+    #BT_TRUE to make this function return
+    #BT_PLUGIN_FIND_ALL_STATUS_ERROR on any plugin loading error instead
+    of ignoring it.
+@param[out] plugins
+    <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
+    reference which contains all the plugins found from the default
+    plugin search directories and static plugins.
+
+@retval #BT_PLUGIN_FIND_ALL_STATUS_OK
+    Success.
+@retval #BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND
+    No plugins found.
+@retval #BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_PLUGIN_FIND_ALL_STATUS_ERROR
+    Error.
+
+@pre
+    At least one of the \bt_p{find_in_std_env_var},
+    \bt_p{find_in_user_dir}, \bt_p{find_in_sys_dir}, and
+    \bt_p{find_in_static} parameters is #BT_TRUE.
+@bt_pre_not_null{plugins}
+
+@sa bt_plugin_find() &mdash;
+    Finds and loads a single plugin by name from the default plugin search
+    directories and static plugins.
+*/
+bt_plugin_find_all_status bt_plugin_find_all(bt_bool find_in_std_env_var,
+               bt_bool find_in_user_dir, bt_bool find_in_sys_dir,
+               bt_bool find_in_static, bt_bool fail_on_load_error,
+               const bt_plugin_set **plugins);
+
+/*!
+@brief
+    Status codes for bt_plugin_find_all_from_file().
+*/
+typedef enum bt_plugin_find_all_from_file_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK                  = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           No plugins found.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND           = __BT_FUNC_STATUS_NOT_FOUND,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR        = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Error.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR               = __BT_FUNC_STATUS_ERROR,
+} bt_plugin_find_all_from_file_status;
+
+/*!
+@brief
+    Finds and loads all the plugins from the file with path \bt_p{path},
+    setting \bt_p{*plugins} to the result.
+
+@note
+    A plugin's name is not related to the name of its file (shared
+    object or Python file). For example, a plugin found in the file
+    \c patente.so can be named <code>Dan</code>.
+
+If any plugin loading error occurs during this function's execution, the
+function:
+
+<dl>
+  <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
+  <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.</dd>
+
+  <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
+  <dd>Ignores the loading error and continues.</dd>
+</dl>
+
+If this function doesn't find any plugin, it returns
+#BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND and does \em not set
+\bt_p{*plugins}.
+
+@param[in] path
+    Path of the file in which to find and load all the plugins.
+@param[in] fail_on_load_error
+    #BT_TRUE to make this function return
+    #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR on any plugin loading
+    error instead of ignoring it.
+@param[out] plugins
+    <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
+    reference which contains all the plugins found in the file with path
+    \bt_p{path}.
+
+@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK
+    Success.
+@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND
+    No plugins found.
+@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR
+    Error.
+
+@bt_pre_not_null{path}
+@pre
+    \bt_p{path} is the path of a regular file.
+@bt_pre_not_null{plugins}
+
+@sa bt_plugin_find_all_from_dir() &mdash;
+    Finds and loads all plugins from a given directory.
+*/
+extern bt_plugin_find_all_from_file_status bt_plugin_find_all_from_file(
+               const char *path, bt_bool fail_on_load_error,
+               const bt_plugin_set **plugins);
+
+/*!
+@brief
+    Status codes for bt_plugin_find_all_from_dir().
+*/
+typedef enum bt_plugin_find_all_from_dir_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK                   = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           No plugins found.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND            = __BT_FUNC_STATUS_NOT_FOUND,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR         = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Error.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR                = __BT_FUNC_STATUS_ERROR,
+} bt_plugin_find_all_from_dir_status;
+
+/*!
+@brief
+    Finds and loads all the plugins from the directory with path
+    \bt_p{path}, setting \bt_p{*plugins} to the result.
+
+If \bt_p{recurse} is #BT_TRUE, this function recurses into the
+subdirectories of \bt_p{path} to find plugins.
+
+During the search process, if a found plugin shares the name of an
+already loaded plugin, this function ignores it and continues.
+
+@attention
+    As of \bt_name_version_min_maj, the file and directory traversal
+    order is undefined.
+
+If any plugin loading error occurs during this function's execution, the
+function:
+
+<dl>
+  <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
+  <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.</dd>
+
+  <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
+  <dd>Ignores the loading error and continues.</dd>
+</dl>
+
+If this function doesn't find any plugin, it returns
+#BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND and does \em not set
+\bt_p{*plugins}.
+
+@param[in] path
+    Path of the directory in which to find and load all the plugins.
+@param[in] recurse
+    #BT_TRUE to make this function recurse into the subdirectories
+    of \bt_p{path}.
+@param[in] fail_on_load_error
+    #BT_TRUE to make this function return
+    #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR on any plugin loading
+    error instead of ignoring it.
+@param[out] plugins
+    <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
+    reference which contains all the plugins found in the directory with
+    path \bt_p{path}.
+
+@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK
+    Success.
+@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND
+    No plugins found.
+@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR
+    Error.
+
+@bt_pre_not_null{path}
+@pre
+    \bt_p{path} is the path of a directory.
+@bt_pre_not_null{plugins}
+
+@sa bt_plugin_find_all_from_file() &mdash;
+    Finds and loads all plugins from a given file.
+*/
+extern bt_plugin_find_all_from_dir_status bt_plugin_find_all_from_dir(
+               const char *path, bt_bool recurse, bt_bool fail_on_load_error,
+               const bt_plugin_set **plugins);
+
+/*!
+@brief
+    Status codes for bt_plugin_find_all_from_static().
+*/
+typedef enum bt_plugin_find_all_from_static_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK                        = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           No static plugins found.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND                 = __BT_FUNC_STATUS_NOT_FOUND,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR              = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Error.
+       */
+       BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR                     = __BT_FUNC_STATUS_ERROR,
+} bt_plugin_find_all_from_static_status;
+
+/*!
+@brief
+    Finds and loads all the static plugins,
+    setting \bt_p{*plugins} to the result.
+
+A static plugin is built directly into the application or library
+instead of being a separate shared object file.
+
+If any plugin loading error occurs during this function's execution, the
+function:
+
+<dl>
+  <dt>If \bt_p{fail_on_load_error} is #BT_TRUE</dt>
+  <dd>Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.</dd>
+
+  <dt>If \bt_p{fail_on_load_error} is #BT_FALSE</dt>
+  <dd>Ignores the loading error and continues.</dd>
+</dl>
+
+If this function doesn't find any plugin, it returns
+#BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND and does \em not set
+\bt_p{*plugins}.
+
+@param[in] fail_on_load_error
+    #BT_TRUE to make this function return
+    #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR on any plugin loading
+    error instead of ignoring it.
+@param[out] plugins
+    <strong>On success</strong>, \bt_p{*plugins} is a new plugin set
+    reference which contains all the static plugins.
+
+@retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK
+    Success.
+@retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND
+    No static plugins found.
+@retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR
+    Error.
+
+@bt_pre_not_null{path}
+@bt_pre_not_null{plugins}
+*/
+extern bt_plugin_find_all_from_static_status bt_plugin_find_all_from_static(
+               bt_bool fail_on_load_error, const bt_plugin_set **plugins);
+
+/*! @} */
+
+/*!
+@name Plugin properties
+@{
+*/
+
+/*!
+@brief
+    Returns the name of the plugin \bt_p{plugin}.
+
+See the \ref api-plugin-prop-name "name" property.
+
+@param[in] plugin
+    Plugin of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{plugin}.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+*/
+extern const char *bt_plugin_get_name(const bt_plugin *plugin);
+
+/*!
+@brief
+    Returns the description of the plugin \bt_p{plugin}.
+
+See the \ref api-plugin-prop-descr "description" property.
+
+@param[in] plugin
+    Plugin of which to get description.
+
+@returns
+    @parblock
+    Description of \bt_p{plugin}, or \c NULL if not available.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+*/
+extern const char *bt_plugin_get_description(const bt_plugin *plugin);
+
+/*!
+@brief
+    Returns the name(s) of the author(s) of the plugin \bt_p{plugin}.
+
+See the \ref api-plugin-prop-author "author name(s)" property.
+
+@param[in] plugin
+    Plugin of which to get the author name(s).
+
+@returns
+    @parblock
+    Author name(s) of \bt_p{plugin}, or \c NULL if not available.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+*/
+extern const char *bt_plugin_get_author(const bt_plugin *plugin);
+
+/*!
+@brief
+    Returns the license text or the license name of the plugin
+    \bt_p{plugin}.
+
+See the \ref api-plugin-prop-license "license" property.
+
+@param[in] plugin
+    Plugin of which to get the license.
+
+@returns
+    @parblock
+    License of \bt_p{plugin}, or \c NULL if not available.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+*/
+extern const char *bt_plugin_get_license(const bt_plugin *plugin);
+
+/*!
+@brief
+    Returns the path of the file which contains the plugin
+    \bt_p{plugin}.
+
+See the \ref api-plugin-prop-path "path" property.
+
+This function returns \c NULL if \bt_p{plugin} is a static plugin
+because a static plugin has no path property.
+
+@param[in] plugin
+    Plugin of which to get the containing file's path.
+
+@returns
+    @parblock
+    Path of the file which contains \bt_p{plugin}, or \c NULL if
+    not available.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+*/
+extern const char *bt_plugin_get_path(const bt_plugin *plugin);
+
+/*!
+@brief
+    Returns the version of the plugin \bt_p{plugin}.
+
+See the \ref api-plugin-prop-version "version" property.
+
+@param[in] plugin
+    Plugin of which to get the version.
+@param[out] major
+    <strong>If not \c NULL and this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*major} is the
+    major version of \bt_p{plugin}.
+@param[out] minor
+    <strong>If not \c NULL and this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*minor} is the
+    minor version of \bt_p{plugin}.
+@param[out] patch
+    <strong>If not \c NULL and this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*patch} is the
+    patch version of \bt_p{plugin}.
+@param[out] extra
+    @parblock
+    <strong>If not \c NULL and this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*extra} is the
+    version's extra information of \bt_p{plugin}.
+
+    \bt_p{*extra} can be \c NULL if the plugin's version has no extra
+    information.
+
+    \bt_p{*extra} remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
+    The version of \bt_p{plugin} is available.
+@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
+    The version of \bt_p{plugin} is not available.
+
+@bt_pre_not_null{plugin}
+*/
+extern bt_property_availability bt_plugin_get_version(
+               const bt_plugin *plugin, unsigned int *major,
+               unsigned int *minor, unsigned int *patch, const char **extra);
+
+/*! @} */
+
+/*!
+@name Plugin component class access
+@{
+*/
+
+/*!
+@brief
+    Returns the number of source component classes contained in the
+    plugin \bt_p{plugin}.
+
+@param[in] plugin
+    Plugin of which to get the number of contained source
+    component classes.
+
+@returns
+    Number of contained source component classes in \bt_p{plugin}.
+
+@bt_pre_not_null{plugin}
+*/
+extern uint64_t bt_plugin_get_source_component_class_count(
+               const bt_plugin *plugin);
+
+/*!
+@brief
+    Returns the number of filter component classes contained in the
+    plugin \bt_p{plugin}.
+
+@param[in] plugin
+    Plugin of which to get the number of contained filter
+    component classes.
+
+@returns
+    Number of contained filter component classes in \bt_p{plugin}.
+
+@bt_pre_not_null{plugin}
+*/
+extern uint64_t bt_plugin_get_filter_component_class_count(
+               const bt_plugin *plugin);
+
+/*!
+@brief
+    Returns the number of sink component classes contained in the
+    plugin \bt_p{plugin}.
+
+@param[in] plugin
+    Plugin of which to get the number of contained sink
+    component classes.
+
+@returns
+    Number of contained sink component classes in \bt_p{plugin}.
+
+@bt_pre_not_null{plugin}
+*/
+extern uint64_t bt_plugin_get_sink_component_class_count(
+               const bt_plugin *plugin);
+
+/*!
+@brief
+    Borrows the source component class at index \bt_p{index} from the
+    plugin \bt_p{plugin}.
+
+@param[in] plugin
+    Plugin from which to borrow the source component class at index
+    \bt_p{index}.
+@param[in] index
+    Index of the source component class to borrow from \bt_p{plugin}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the source component class of
+    \bt_p{plugin} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+@pre
+    \bt_p{index} is less than the number of source component classes in
+    \bt_p{plugin} (as returned by
+    bt_plugin_get_source_component_class_count()).
+
+@sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
+    Borrows a source component class by name from a plugin.
+*/
+extern const bt_component_class_source *
+bt_plugin_borrow_source_component_class_by_index_const(
+               const bt_plugin *plugin, uint64_t index);
+
+/*!
+@brief
+    Borrows the filter component class at index \bt_p{index} from the
+    plugin \bt_p{plugin}.
+
+@param[in] plugin
+    Plugin from which to borrow the filter component class at index
+    \bt_p{index}.
+@param[in] index
+    Index of the filter component class to borrow from \bt_p{plugin}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the filter component class of
+    \bt_p{plugin} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+@pre
+    \bt_p{index} is less than the number of filter component classes in
+    \bt_p{plugin} (as returned by
+    bt_plugin_get_source_component_class_count()).
+
+@sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
+    Borrows a filter component class by name from a plugin.
+*/
+extern const bt_component_class_filter *
+bt_plugin_borrow_filter_component_class_by_index_const(
+               const bt_plugin *plugin, uint64_t index);
+
+/*!
+@brief
+    Borrows the sink component class at index \bt_p{index} from the
+    plugin \bt_p{plugin}.
+
+@param[in] plugin
+    Plugin from which to borrow the sink component class at index
+    \bt_p{index}.
+@param[in] index
+    Index of the sink component class to borrow from \bt_p{plugin}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the sink component class of
+    \bt_p{plugin} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+@pre
+    \bt_p{index} is less than the number of sink component classes in
+    \bt_p{plugin} (as returned by
+    bt_plugin_get_source_component_class_count()).
+
+@sa bt_plugin_borrow_source_component_class_by_name_const() &mdash;
+    Borrows a sink component class by name from a plugin.
+*/
+extern const bt_component_class_sink *
+bt_plugin_borrow_sink_component_class_by_index_const(
+               const bt_plugin *plugin, uint64_t index);
+
+/*!
+@brief
+    Borrows the source component class named \bt_p{name} from the
+    plugin \bt_p{plugin}.
+
+If no source component class has the name \bt_p{name} within
+\bt_p{plugin}, this function returns \c NULL.
+
+@param[in] plugin
+    Plugin from which to borrow the source component class named
+    \bt_p{name}.
+@param[in] name
+    Name of the source component class to borrow from \bt_p{plugin}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the source component class of
+    \bt_p{plugin} named \bt_p{name}, or \c NULL if no source component
+    class is named \bt_p{name} within \bt_p{plugin}.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+@bt_pre_not_null{name}
+
+@sa bt_plugin_borrow_source_component_class_by_index_const() &mdash;
+    Borrows a source component class by index from a plugin.
+*/
+extern const bt_component_class_source *
+bt_plugin_borrow_source_component_class_by_name_const(
+               const bt_plugin *plugin, const char *name);
+
+/*!
+@brief
+    Borrows the filter component class named \bt_p{name} from the
+    plugin \bt_p{plugin}.
+
+If no filter component class has the name \bt_p{name} within
+\bt_p{plugin}, this function returns \c NULL.
+
+@param[in] plugin
+    Plugin from which to borrow the filter component class named
+    \bt_p{name}.
+@param[in] name
+    Name of the filter component class to borrow from \bt_p{plugin}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the filter component class of
+    \bt_p{plugin} named \bt_p{name}, or \c NULL if no filter component
+    class is named \bt_p{name} within \bt_p{plugin}.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+@bt_pre_not_null{name}
+
+@sa bt_plugin_borrow_filter_component_class_by_index_const() &mdash;
+    Borrows a filter component class by index from a plugin.
+*/
+extern const bt_component_class_filter *
+bt_plugin_borrow_filter_component_class_by_name_const(
+               const bt_plugin *plugin, const char *name);
+
+/*!
+@brief
+    Borrows the sink component class named \bt_p{name} from the
+    plugin \bt_p{plugin}.
+
+If no sink component class has the name \bt_p{name} within
+\bt_p{plugin}, this function returns \c NULL.
+
+@param[in] plugin
+    Plugin from which to borrow the sink component class named
+    \bt_p{name}.
+@param[in] name
+    Name of the sink component class to borrow from \bt_p{plugin}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the sink component class of
+    \bt_p{plugin} named \bt_p{name}, or \c NULL if no sink component
+    class is named \bt_p{name} within \bt_p{plugin}.
+
+    The returned pointer remains valid as long as \bt_p{plugin} exists.
+    @endparblock
+
+@bt_pre_not_null{plugin}
+@bt_pre_not_null{name}
+
+@sa bt_plugin_borrow_sink_component_class_by_index_const() &mdash;
+    Borrows a sink component class by index from a plugin.
+*/
+extern const bt_component_class_sink *
+bt_plugin_borrow_sink_component_class_by_name_const(
+               const bt_plugin *plugin, const char *name);
+
+/*! @} */
+
+/*!
+@name Plugin reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the plugin \bt_p{plugin}.
+
+@param[in] plugin
+    @parblock
+    Plugin of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_plugin_put_ref() &mdash;
+    Decrements the reference count of a plugin.
+*/
+extern void bt_plugin_get_ref(const bt_plugin *plugin);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the plugin \bt_p{plugin}.
+
+@param[in] plugin
+    @parblock
+    Plugin of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_plugin_get_ref() &mdash;
+    Increments the reference count of a plugin.
+*/
+extern void bt_plugin_put_ref(const bt_plugin *plugin);
+
+/*!
+@brief
+    Decrements the reference count of the plugin \bt_p{_plugin}, and
+    then sets \bt_p{_plugin} to \c NULL.
+
+@param _plugin
+    @parblock
+    Plugin of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_plugin}
+*/
+#define BT_PLUGIN_PUT_REF_AND_RESET(_plugin)           \
+       do {                                            \
+               bt_plugin_put_ref(_plugin);             \
+               (_plugin) = NULL;                       \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the plugin \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a plugin reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_PLUGIN_MOVE_REF(_dst, _src)         \
+       do {                                    \
+               bt_plugin_put_ref(_dst);        \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Plugin set plugin access
+@{
+*/
+
+/*!
+@brief
+    Returns the number of plugins contained in the
+    plugin set \bt_p{plugin_set}.
+
+@param[in] plugin_set
+    Plugin set of which to get the number of contained plugins.
+
+@returns
+    Number of contained plugins in \bt_p{plugin_set}.
+
+@bt_pre_not_null{plugin}
+*/
+extern uint64_t bt_plugin_set_get_plugin_count(
+               const bt_plugin_set *plugin_set);
+
+/*!
+@brief
+    Borrows the plugin at index \bt_p{index} from the plugin set
+    \bt_p{plugin_set}.
+
+@param[in] plugin_set
+    Plugin set from which to borrow the plugin at index \bt_p{index}.
+@param[in] index
+    Index of the plugin to borrow from \bt_p{plugin_set}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the plugin of \bt_p{plugin_set} at index
+    \bt_p{index}.
+
+    The returned pointer remains valid until \bt_p{plugin_set} is
+    modified.
+    @endparblock
+
+@bt_pre_not_null{plugin_set}
+@pre
+    \bt_p{index} is less than the number of plugins in
+    \bt_p{plugin_set} (as returned by bt_plugin_set_get_plugin_count()).
+*/
+extern const bt_plugin *bt_plugin_set_borrow_plugin_by_index_const(
+               const bt_plugin_set *plugin_set, uint64_t index);
+
+/*! @} */
+
+/*!
+@name Plugin set reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the plugin set \bt_p{plugin_set}.
+
+@param[in] plugin_set
+    @parblock
+    Plugin set of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_plugin_set_put_ref() &mdash;
+    Decrements the reference count of a plugin set.
+*/
+extern void bt_plugin_set_get_ref(const bt_plugin_set *plugin_set);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the plugin set \bt_p{plugin_set}.
+
+@param[in] plugin_set
+    @parblock
+    Plugin set of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_plugin_set_get_ref() &mdash;
+    Increments the reference count of a plugin set.
+*/
+extern void bt_plugin_set_put_ref(const bt_plugin_set *plugin_set);
+
+/*!
+@brief
+    Decrements the reference count of the plugin set \bt_p{_plugin_set},
+    and then sets \bt_p{_plugin_set} to \c NULL.
+
+@param _plugin_set
+    @parblock
+    Plugin set of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_plugin_set}
+*/
+#define BT_PLUGIN_SET_PUT_REF_AND_RESET(_plugin_set)   \
+       do {                                            \
+               bt_plugin_set_put_ref(_plugin_set);     \
+               (_plugin_set) = NULL;                   \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the plugin set \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a plugin set reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_PLUGIN_SET_MOVE_REF(_dst, _src)     \
+       do {                                    \
+               bt_plugin_set_put_ref(_dst);    \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_PLUGIN_PLUGIN_LOADING_H */

diff --git a/include/babeltrace2/plugin/plugin-set-const.h b/include/babeltrace2/plugin/plugin-set-const.h
deleted file mode 100644 (file)
index 209e1d3..0000000
--- a/include/babeltrace2/plugin/plugin-set-const.h
+++ /dev/null
@@ -1,65 +0,0 @@
-#ifndef BABELTRACE2_PLUGIN_PLUGIN_SET_CONST_H
-#define BABELTRACE2_PLUGIN_PLUGIN_SET_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern uint64_t bt_plugin_set_get_plugin_count(
-               const bt_plugin_set *plugin_set);
-
-extern const bt_plugin *bt_plugin_set_borrow_plugin_by_index_const(
-               const bt_plugin_set *plugin_set, uint64_t index);
-
-extern void bt_plugin_set_get_ref(const bt_plugin_set *plugin_set);
-
-extern void bt_plugin_set_put_ref(const bt_plugin_set *plugin_set);
-
-#define BT_PLUGIN_SET_PUT_REF_AND_RESET(_var)          \
-       do {                                            \
-               bt_plugin_set_put_ref(_var);            \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_PLUGIN_SET_MOVE_REF(_var_dst, _var_src)     \
-       do {                                            \
-               bt_plugin_set_put_ref(_var_dst);        \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_PLUGIN_PLUGIN_SET_CONST_H */

diff --git a/include/babeltrace2/property.h b/include/babeltrace2/property.h
deleted file mode 100644 (file)
index 1ede142..0000000
--- a/include/babeltrace2/property.h
+++ /dev/null
@@ -1,43 +0,0 @@
-#ifndef BABELTRACE2_PROPERTY_H
-#define BABELTRACE2_PROPERTY_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_property_availability {
-       BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE  = 0,
-       BT_PROPERTY_AVAILABILITY_AVAILABLE      = 1,
-} bt_property_availability;
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_PROPERTY_H */

diff --git a/include/babeltrace2/trace-ir/clock-class-const.h b/include/babeltrace2/trace-ir/clock-class-const.h
deleted file mode 100644 (file)
index 6316f83..0000000
--- a/include/babeltrace2/trace-ir/clock-class-const.h
+++ /dev/null
@@ -1,93 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_CLOCK_CLASS_CONST_H
-#define BABELTRACE2_TRACE_IR_CLOCK_CLASS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_value *bt_clock_class_borrow_user_attributes_const(
-               const bt_clock_class *clock_class);
-
-extern const char *bt_clock_class_get_name(
-               const bt_clock_class *clock_class);
-
-extern const char *bt_clock_class_get_description(
-               const bt_clock_class *clock_class);
-
-extern uint64_t bt_clock_class_get_frequency(
-               const bt_clock_class *clock_class);
-
-extern uint64_t bt_clock_class_get_precision(
-               const bt_clock_class *clock_class);
-
-extern void bt_clock_class_get_offset(const bt_clock_class *clock_class,
-               int64_t *seconds, uint64_t *cycles);
-
-extern bt_bool bt_clock_class_origin_is_unix_epoch(
-               const bt_clock_class *clock_class);
-
-extern bt_uuid bt_clock_class_get_uuid(
-               const bt_clock_class *clock_class);
-
-typedef enum bt_clock_class_cycles_to_ns_from_origin_status {
-       BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR   = __BT_FUNC_STATUS_OVERFLOW_ERROR,
-       BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK               = __BT_FUNC_STATUS_OK,
-} bt_clock_class_cycles_to_ns_from_origin_status;
-
-extern bt_clock_class_cycles_to_ns_from_origin_status
-bt_clock_class_cycles_to_ns_from_origin(
-               const bt_clock_class *clock_class,
-               uint64_t cycles, int64_t *ns_from_origin);
-
-extern void bt_clock_class_get_ref(const bt_clock_class *clock_class);
-
-extern void bt_clock_class_put_ref(const bt_clock_class *clock_class);
-
-#define BT_CLOCK_CLASS_PUT_REF_AND_RESET(_var)         \
-       do {                                            \
-               bt_clock_class_put_ref(_var);           \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_CLOCK_CLASS_MOVE_REF(_var_dst, _var_src)    \
-       do {                                            \
-               bt_clock_class_put_ref(_var_dst);       \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_CLOCK_CLASS_CONST_H */

diff --git a/include/babeltrace2/trace-ir/clock-class.h b/include/babeltrace2/trace-ir/clock-class.h
index 5d0c5987c5fbe64ebfefe9d0727bb9532a0bbf02..4fbbf53310a50693fc65d2b8053b04cb29240896 100644 (file)
--- a/include/babeltrace2/trace-ir/clock-class.h
+++ b/include/babeltrace2/trace-ir/clock-class.h
@@ -35,45 +35,954 @@
 extern "C" {
 #endif
 
-extern bt_clock_class *bt_clock_class_create(bt_self_component *self_comp);
+/*!
+@defgroup api-tir-clock-cls Clock class
+@ingroup api-tir
 
-extern bt_value *bt_clock_class_borrow_user_attributes(
-               bt_clock_class *clock_class);
+@brief
+    Class of \bt_stream clocks.
 
-extern void bt_clock_class_set_user_attributes(
-               bt_clock_class *clock_class, const bt_value *user_attributes);
+A <strong><em>clock class</em></strong> is the class of \bt_stream
+clocks.
+
+A clock class is a \ref api-tir "trace IR" metadata object.
+
+<em>Stream clocks</em> only exist conceptually in \bt_name because they
+are stateful objects. \bt_cp_msg cannot refer to stateful objects
+because they must not change while being transported from one
+\bt_comp to the other.
+
+Instead of having a stream clock object, messages have a
+default \bt_cs: this is a snapshot of the value of a stream's default
+clock (a clock class instance):
+
+@image html clocks.png
+
+In the illustration above, notice that:
+
+- \bt_cp_stream (horizontal blue rectangles) are instances of a
+  \bt_stream_cls (orange).
+- A stream class has a default clock class (orange bell alarm clock).
+- Each stream has a default clock (yellow bell alarm clock): this is an
+  instance of the stream's class's default clock class.
+- Each \bt_msg (objects in blue stream rectangles) created for a given
+  stream has a default \bt_cs (yellow star): this is a snapshot of the
+  stream's default clock.
+
+  In other words, a default clock snapshot contains the value of the
+  stream's default clock when this message occured.
+
+The default clock class property of a \bt_stream_cls is optional:
+if a stream class has no default clock class, then its instances
+(\bt_p_stream) have no default clock, therefore all the \bt_p_msg
+created from this stream have no default clock snapshot.
+
+A clock class is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_clock_class_get_ref() and put an existing
+reference with bt_clock_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" clock classes on
+success. The documentation of those functions indicate this
+postcondition.
+
+The type of a clock class is #bt_clock_class.
+
+Create a default clock class from a \bt_self_comp with
+bt_clock_class_create().
+
+<h1>\anchor api-tir-clock-cls-origin Clock value vs. clock class origin</h1>
+
+The value of a \bt_stream clock (a conceptual instance of a clock class)
+is in <em>cycles</em>. This value is always positive and is relative to
+the clock's class's offset, which is relative to its origin.
+
+A clock class's origin is one of:
+
+<dl>
+  <dt>If bt_clock_class_origin_is_unix_epoch() returns #BT_TRUE</dt>
+  <dd>
+    The
+    <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
+
+    The stream clocks of all the clock classes which have a Unix
+    epoch origin, whatever the clock class
+    <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUIDs</a>,
+    are correlatable.
+  </dd>
+
+  <dt>If bt_clock_class_origin_is_unix_epoch() returns #BT_FALSE</dt>
+  <dd>
+    Undefined.
+
+    In that case, two clock classes which share the same UUID, as
+    returned by bt_clock_class_get_uuid(), including having no UUID,
+    also share the same origin: their instances (stream clocks) are
+    correlatable.
+  </dd>
+</dl>
+
+To compute an effective stream clock value, in cycles from its class's
+origin:
+
+-# Convert the clock class's
+   \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
+   property to cycles using its
+   \ref api-tir-clock-cls-prop-freq "frequency".
+-# Add the value of 1., the stream clock's value, and the clock class's
+   \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
+   property.
+
+Because typical tracer clocks have a high frequency (often 1&nbsp;GHz
+and more), an effective stream clock value (cycles since Unix epoch, for
+example) can be larger than \c UINT64_MAX. This is why a clock class has
+two offset properties (one in seconds and one in cycles): to make it
+possible for a stream clock to have smaller values, relative to this
+offset.
+
+The bt_clock_class_cycles_to_ns_from_origin(),
+bt_util_clock_cycles_to_ns_from_origin(), and
+bt_clock_snapshot_get_ns_from_origin() functions convert a stream clock
+value (cycles) to an equivalent <em>nanoseconds from origin</em> value
+using the relevant clock class properties (frequency and offset).
+
+Those functions perform this computation:
+
+-# Convert the clock class's "offset in cycles" property to seconds
+   using its frequency.
+-# Convert the stream clock's value to seconds using the clock class's
+   frequency.
+-# Add the values of 1., 2., and the clock class's "offset in seconds"
+   property.
+-# Convert the value of 3. to nanoseconds.
+
+The following illustration shows the possible scenarios:
+
+@image html clock-terminology.png
+
+The clock class's "offset in seconds" property can be negative.
+For example, considering:
+
+- Frequency: 1000&nbsp;Hz.
+- Offset in seconds: -10&nbsp;seconds.
+- Offset in cycles: 500&nbsp;cycles (that is, 0.5&nbsp;seconds).
+- Stream clock's value: 2000&nbsp;cycles (that is, 2&nbsp;seconds).
+
+Then the computed value is -7.5&nbsp;seconds from origin, or
+-7,500,000,000&nbsp;nanoseconds from origin.
+
+<h1>Properties</h1>
+
+A clock class has the following properties:
+
+<dl>
+  <dt>\anchor api-tir-clock-cls-prop-freq Frequency</dt>
+  <dd>
+    Frequency of the clock class's instances (stream clocks)
+    (cycles/second).
+
+    Use bt_clock_class_set_frequency() and
+    bt_clock_class_get_frequency().
+  </dd>
+
+  <dt>
+    \anchor api-tir-clock-cls-prop-offset
+    Offset (in seconds and in cycles)
+  </dt>
+  <dd>
+    Offset in seconds relative to the clock class's
+    \ref api-tir-clock-cls-origin "origin", and offset in cycles
+    relative to the offset in seconds, of the clock class's
+    instances (stream clocks).
+
+    The values of the clock class's instances are relative to the
+    computed offset.
+
+    Use bt_clock_class_set_offset() and bt_clock_class_get_offset().
+  </dd>
+
+  <dt>\anchor api-tir-clock-cls-prop-precision Precision</dt>
+  <dd>
+    Precision of the clock class's instance (stream clocks) values
+    (cycles).
+
+    For example, considering a precision of 7&nbsp;cycles and the stream
+    clock value 42&nbsp;cycles, the real stream clock value can be
+    anything between 35&nbsp;cycles and 49&nbsp;cycles.
+
+    Use bt_clock_class_set_precision() and
+    bt_clock_class_get_precision().
+  </dd>
+
+  <dt>
+    \anchor api-tir-clock-cls-prop-origin-unix-epoch
+    Origin is Unix epoch?
+  </dt>
+  <dd>
+    Whether or not the clock class's
+    \ref api-tir-clock-cls-origin "origin"
+    is the
+    <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
+
+    Use bt_clock_class_set_origin_is_unix_epoch() and
+    bt_clock_class_origin_is_unix_epoch().
+  </dd>
+
+  <dt>\anchor api-tir-clock-cls-prop-name \bt_dt_opt Name</dt>
+  <dd>
+    Name of the clock class.
+
+    Use bt_clock_class_set_name() and bt_clock_class_get_name().
+  </dd>
+
+  <dt>\anchor api-tir-clock-cls-prop-descr \bt_dt_opt Description</dt>
+  <dd>
+    Description of the clock class.
+
+    Use bt_clock_class_set_description() and
+    bt_clock_class_get_description().
+  </dd>
+
+  <dt>\anchor api-tir-clock-cls-prop-uuid \bt_dt_opt UUID</dt>
+  <dd>
+    <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
+    of the clock class.
+
+    The clock class's UUID uniquely identifies the clock class.
+
+    When the clock class's origin is \em not the
+    <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>,
+    then the clock class's UUID determines whether or not two different
+    clock classes have correlatable instances.
+
+    Use bt_clock_class_set_uuid() and bt_clock_class_get_uuid().
+  </dd>
+
+  <dt>
+    \anchor api-tir-clock-cls-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the clock class.
+
+    User attributes are custom attributes attached to a clock class.
+
+    Use bt_clock_class_set_user_attributes(),
+    bt_clock_class_borrow_user_attributes(), and
+    bt_clock_class_borrow_user_attributes_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_clock_class bt_clock_class;
+
+@brief
+    Clock class.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a default clock class from the \bt_self_comp
+    \bt_p{self_component}.
+
+On success, the returned clock class has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-freq "Frequency"
+    <td>1&nbsp;GHz
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-offset "Offset" in seconds
+    <td>0&nbsp;seconds
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-offset "Offset" in cycles
+    <td>0&nbsp;cycles
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-precision "Precision"
+    <td>0&nbsp;cycles
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-origin-unix-epoch "Origin is Unix epoch?"
+    <td>Yes
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-descr "Description"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-uuid "UUID"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-clock-cls-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] self_component
+    Self component from which to create the default clock class.
+
+@returns
+    New clock class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{self_component}
+*/
+extern bt_clock_class *bt_clock_class_create(bt_self_component *self_component);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Sets the frequency (Hz) of the clock class \bt_p{clock_class} to
+    \bt_p{frequency}.
+
+See the \ref api-tir-clock-cls-prop-freq "frequency" property.
+
+@param[in] clock_class
+    Clock class of which to set the frequency to \bt_p{frequency}.
+@param[in] frequency
+    New frequency of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+@pre
+    \bt_p{frequency} is not 0.
+@pre
+    \bt_p{frequency} is not <code>UINT64_C(-1)</code>.
+@pre
+    \bt_p{frequency} is greater than the clock class's offset in cycles
+    (as returned by bt_clock_class_get_offset()).
+
+@sa bt_clock_class_get_frequency() &mdash;
+    Returns the frequency of a clock class.
+*/
+extern void bt_clock_class_set_frequency(bt_clock_class *clock_class,
+               uint64_t frequency);
+
+/*!
+@brief
+    Returns the frequency (Hz) of the clock class \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-freq "frequency" property.
+
+@param[in] clock_class
+    Clock class of which to get the frequency.
+
+@returns
+    Frequency (Hz) of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+
+@sa bt_clock_class_set_frequency() &mdash;
+    Sets the frequency of a clock class.
+*/
+extern uint64_t bt_clock_class_get_frequency(
+               const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Sets the offset of the clock class \bt_p{clock_class} to
+    \bt_p{offset_seconds} plus \bt_p{offset_cycles} from its
+    \ref api-tir-clock-cls-origin "origin".
+
+See the \ref api-tir-clock-cls-prop-offset "offset" property.
+
+@param[in] clock_class
+    Clock class of which to set the offset to \bt_p{offset_seconds}
+    and \bt_p{offset_cycles}.
+@param[in] offset_seconds
+    New offset in seconds of \bt_p{clock_class}.
+@param[in] offset_cycles
+    New offset in cycles of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+@pre
+    \bt_p{offset_cycles} is less than the clock class's frequency
+    (as returned by bt_clock_class_get_frequency()).
+
+@sa bt_clock_class_get_offset() &mdash;
+    Returns the offset of a clock class.
+*/
+extern void bt_clock_class_set_offset(bt_clock_class *clock_class,
+               int64_t offset_seconds, uint64_t offset_cycles);
+
+/*!
+@brief
+    Returns the offsets in seconds and cycles of the clock class
+    \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-offset "offset" property.
+
+@param[in] clock_class
+    Clock class of which to get the offset.
+@param[out] offset_seconds
+    When this function returns, \bt_p{*offset_seconds} is the offset in
+    seconds of
+    \bt_p{clock_class}.
+@param[out] offset_cycles
+    When this function returns, \bt_p{*offset_cycles} is the offset in
+    cycles of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_not_null{offset_seconds}
+@bt_pre_not_null{offset_cycles}
+
+@sa bt_clock_class_set_offset() &mdash;
+    Sets the offset of a clock class.
+*/
+extern void bt_clock_class_get_offset(const bt_clock_class *clock_class,
+               int64_t *offset_seconds, uint64_t *offset_cycles);
+
+/*!
+@brief
+    Sets the precision (cycles) of the clock class \bt_p{clock_class} to
+    \bt_p{precision}.
+
+See the \ref api-tir-clock-cls-prop-precision "precision" property.
+
+@param[in] clock_class
+    Clock class of which to set the precision to \bt_p{precision}.
+@param[in] precision
+    New precision of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+
+@sa bt_clock_class_get_precision() &mdash;
+    Returns the precision of a clock class.
+*/
+extern void bt_clock_class_set_precision(bt_clock_class *clock_class,
+               uint64_t precision);
+
+/*!
+@brief
+    Returns the precision (cycles) of the clock class
+    \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-precision "precision" property.
+
+@param[in] clock_class
+    Clock class of which to get the precision.
+
+@returns
+    Precision (cycles) of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+
+@sa bt_clock_class_set_precision() &mdash;
+    Sets the precision of a clock class.
+*/
+extern uint64_t bt_clock_class_get_precision(
+               const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Sets whether or not the \ref api-tir-clock-cls-origin "origin"
+    of the clock class \bt_p{clock_class} is the
+    <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
+
+See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
+property.
+
+@param[in] clock_class
+    Clock class of which to set whether or not its origin is the
+    Unix epoch.
+@param[in] origin_is_unix_epoch
+    #BT_TRUE to make \bt_p{clock_class} have a Unix epoch origin.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
 
+@sa bt_clock_class_origin_is_unix_epoch() &mdash;
+    Returns whether or not the origin of a clock class is the
+    Unix epoch.
+*/
+extern void bt_clock_class_set_origin_is_unix_epoch(bt_clock_class *clock_class,
+               bt_bool origin_is_unix_epoch);
+
+/*!
+@brief
+    Returns whether or not the \ref api-tir-clock-cls-origin "origin"
+    of the clock class \bt_p{clock_class} is the
+    <a href="https://en.wikipedia.org/wiki/Unix_time">Unix epoch</a>.
+
+See the \ref api-tir-clock-cls-prop-origin-unix-epoch "origin is Unix epoch?"
+property.
+
+@param[in] clock_class
+    Clock class of which to get whether or not its origin is the
+    Unix epoch.
+
+@returns
+    #BT_TRUE if the origin of \bt_p{clock_class} is the Unix epoch.
+
+@bt_pre_not_null{clock_class}
+
+@sa bt_clock_class_set_origin_is_unix_epoch() &mdash;
+    Sets whether or not the origin of a clock class is the Unix epoch.
+*/
+extern bt_bool bt_clock_class_origin_is_unix_epoch(
+               const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Status codes for bt_clock_class_set_name().
+*/
 typedef enum bt_clock_class_set_name_status {
-       BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_CLOCK_CLASS_SET_NAME_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_clock_class_set_name_status;
 
+/*!
+@brief
+    Sets the name of the clock class \bt_p{clock_class} to
+    a copy of \bt_p{name}.
+
+See the \ref api-tir-clock-cls-prop-name "name" property.
+
+@param[in] clock_class
+    Clock class of which to set the name to \bt_p{name}.
+@param[in] name
+    New name of \bt_p{clock_class} (copied).
+
+@retval #BT_CLOCK_CLASS_SET_NAME_STATUS_OK
+    Success.
+@retval #BT_CLOCK_CLASS_SET_NAME_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+@bt_pre_not_null{name}
+
+@sa bt_clock_class_get_name() &mdash;
+    Returns the name of a clock class.
+*/
 extern bt_clock_class_set_name_status bt_clock_class_set_name(
                bt_clock_class *clock_class, const char *name);
 
+/*!
+@brief
+    Returns the name of the clock class \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-name "name" property.
+
+If \bt_p{clock_class} has no name, this function returns \c NULL.
+
+@param[in] clock_class
+    Clock class of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{clock_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{clock_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{clock_class}
+
+@sa bt_clock_class_set_name() &mdash;
+    Sets the name of a clock class.
+*/
+extern const char *bt_clock_class_get_name(
+               const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Status codes for bt_clock_class_set_description().
+*/
 typedef enum bt_clock_class_set_description_status {
-       BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_clock_class_set_description_status;
 
+/*!
+@brief
+    Sets the description of the clock class \bt_p{clock_class} to a copy
+    of \bt_p{description}.
+
+See the \ref api-tir-clock-cls-prop-descr "description" property.
+
+@param[in] clock_class
+    Clock class of which to set the description to \bt_p{description}.
+@param[in] description
+    New description of \bt_p{clock_class} (copied).
+
+@retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_OK
+    Success.
+@retval #BT_CLOCK_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+@bt_pre_not_null{description}
+
+@sa bt_clock_class_get_description() &mdash;
+    Returns the description of a clock class.
+*/
 extern bt_clock_class_set_description_status bt_clock_class_set_description(
                bt_clock_class *clock_class, const char *description);
 
-extern void bt_clock_class_set_frequency(bt_clock_class *clock_class,
-               uint64_t freq);
+/*!
+@brief
+    Returns the description of the clock class \bt_p{clock_class}.
 
-extern void bt_clock_class_set_precision(bt_clock_class *clock_class,
-               uint64_t precision);
+See the \ref api-tir-clock-cls-prop-descr "description" property.
 
-extern void bt_clock_class_set_offset(bt_clock_class *clock_class,
-               int64_t seconds, uint64_t cycles);
+If \bt_p{clock_class} has no description, this function returns \c NULL.
 
-extern void bt_clock_class_set_origin_is_unix_epoch(bt_clock_class *clock_class,
-               bt_bool origin_is_unix_epoch);
+@param[in] clock_class
+    Clock class of which to get the description.
+
+@returns
+    @parblock
+    Description of \bt_p{clock_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{clock_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{clock_class}
 
+@sa bt_clock_class_set_description() &mdash;
+    Sets the description of a clock class.
+*/
+extern const char *bt_clock_class_get_description(
+               const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Sets the
+    <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
+    of the clock class \bt_p{clock_class} to a copy of \bt_p{uuid}.
+
+See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
+
+@param[in] clock_class
+    Clock class of which to set the UUID to \bt_p{uuid}.
+@param[in] uuid
+    New UUID of \bt_p{clock_class} (copied).
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+@bt_pre_not_null{uuid}
+
+@sa bt_clock_class_get_uuid() &mdash;
+    Returns the UUID of a clock class.
+*/
 extern void bt_clock_class_set_uuid(bt_clock_class *clock_class,
                bt_uuid uuid);
 
+/*!
+@brief
+    Returns the UUID of the clock class \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-uuid "UUID" property.
+
+If \bt_p{clock_class} has no UUID, this function returns \c NULL.
+
+@param[in] clock_class
+    Clock class of which to get the UUID.
+
+@returns
+    @parblock
+    UUID of \bt_p{clock_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{clock_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{clock_class}
+
+@sa bt_clock_class_set_uuid() &mdash;
+    Sets the UUID of a clock class.
+*/
+extern bt_uuid bt_clock_class_get_uuid(
+               const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Sets the user attributes of the clock class \bt_p{clock_class} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default clock class with bt_clock_class_create(),
+    the clock class's initial user attributes is an empty \bt_map_val.
+    Therefore you can borrow it with
+    bt_clock_class_borrow_user_attributes() and fill it directly instead
+    of setting a new one with this function.
+
+@param[in] clock_class
+    Clock class of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{clock_class}.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_hot{clock_class}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_clock_class_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a clock class.
+*/
+extern void bt_clock_class_set_user_attributes(
+               bt_clock_class *clock_class, const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the clock class \bt_p{clock_class}.
+
+See the \ref api-tir-clock-cls-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default clock class with bt_clock_class_create(),
+    the clock class's initial user attributes is an empty \bt_map_val.
+
+@param[in] clock_class
+    Clock class from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{clock_class} (a \bt_map_val).
+
+@bt_pre_not_null{clock_class}
+
+@sa bt_clock_class_set_user_attributes() &mdash;
+    Sets the user attributes of a clock class.
+@sa bt_clock_class_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_clock_class_borrow_user_attributes(
+               bt_clock_class *clock_class);
+
+/*!
+@brief
+    Borrows the user attributes of the clock class \bt_p{clock_class}
+    (\c const version).
+
+See bt_clock_class_borrow_user_attributes().
+*/
+extern const bt_value *bt_clock_class_borrow_user_attributes_const(
+               const bt_clock_class *clock_class);
+
+/*! @} */
+
+/*!
+@name Utilities
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_clock_class_cycles_to_ns_from_origin().
+*/
+typedef enum bt_clock_class_cycles_to_ns_from_origin_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Integer overflow while computing the result.
+       */
+       BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR   = __BT_FUNC_STATUS_OVERFLOW_ERROR,
+} bt_clock_class_cycles_to_ns_from_origin_status;
+
+/*!
+@brief
+    Converts the stream clock value \bt_p{value} from cycles to
+    nanoseconds from the \ref api-tir-clock-cls-origin "origin" of the
+    clock class \bt_p{clock_class} and sets \bt_p{*ns_from_origin}
+    to the result.
+
+This function:
+
+-# Converts the
+   \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
+   property of \bt_p{clock_class} to seconds using its
+   \ref api-tir-clock-cls-prop-freq "frequency".
+-# Converts the \bt_p{value} value to seconds using the frequency of
+   \bt_p{clock_class}.
+-# Adds the values of 1., 2., and the
+   \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
+   property of \bt_p{clock_class}.
+-# Converts the value of 3. to nanoseconds and sets
+   \bt_p{*ns_from_origin} to this result.
+
+The following illustration shows the possible scenarios:
+
+@image html clock-terminology.png
+
+This function can fail and return the
+#BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
+code if any step of the computation process causes an integer overflow.
+
+@param[in] clock_class
+    Stream clock's class.
+@param[in] value
+    Stream clock's value (cycles) to convert to nanoseconds from
+    the origin of \bt_p{clock_class}.
+@param[out] ns_from_origin
+    <strong>On success</strong>, \bt_p{*ns_from_origin} is \bt_p{value}
+    converted to nanoseconds from the origin of \bt_p{clock_class}.
+
+@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
+    Success.
+@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
+    Integer overflow while computing the result.
+
+@bt_pre_not_null{clock_class}
+@bt_pre_not_null{ns_from_origin}
+
+@sa bt_util_clock_cycles_to_ns_from_origin() &mdash;
+    Converts a clock value from cycles to nanoseconds from the clock's
+    origin.
+*/
+extern bt_clock_class_cycles_to_ns_from_origin_status
+bt_clock_class_cycles_to_ns_from_origin(
+               const bt_clock_class *clock_class,
+               uint64_t value, int64_t *ns_from_origin);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the clock class \bt_p{clock_class}.
+
+@param[in] clock_class
+    @parblock
+    Clock class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_clock_class_put_ref() &mdash;
+    Decrements the reference count of a clock class.
+*/
+extern void bt_clock_class_get_ref(const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the clock class \bt_p{clock_class}.
+
+@param[in] clock_class
+    @parblock
+    Clock class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_clock_class_get_ref() &mdash;
+    Increments the reference count of a clock class.
+*/
+extern void bt_clock_class_put_ref(const bt_clock_class *clock_class);
+
+/*!
+@brief
+    Decrements the reference count of the clock class
+    \bt_p{_clock_class}, and then sets \bt_p{_clock_class} to \c NULL.
+
+@param _clock_class
+    @parblock
+    Clock class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_clock_class}
+*/
+#define BT_CLOCK_CLASS_PUT_REF_AND_RESET(_clock_class) \
+       do {                                            \
+               bt_clock_class_put_ref(_clock_class);   \
+               (_clock_class) = NULL;                  \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the clock class \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a clock class reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_CLOCK_CLASS_MOVE_REF(_dst, _src)    \
+       do {                                    \
+               bt_clock_class_put_ref(_dst);   \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/trace-ir/clock-snapshot-const.h b/include/babeltrace2/trace-ir/clock-snapshot-const.h
deleted file mode 100644 (file)
index 3363b9d..0000000
--- a/include/babeltrace2/trace-ir/clock-snapshot-const.h
+++ /dev/null
@@ -1,58 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_CONST_H
-#define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_clock_class *bt_clock_snapshot_borrow_clock_class_const(
-               const bt_clock_snapshot *clock_snapshot);
-
-extern uint64_t bt_clock_snapshot_get_value(
-               const bt_clock_snapshot *clock_snapshot);
-
-typedef enum bt_clock_snapshot_get_ns_from_origin_status {
-       BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK                  = __BT_FUNC_STATUS_OK,
-       BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR      = __BT_FUNC_STATUS_OVERFLOW_ERROR,
-} bt_clock_snapshot_get_ns_from_origin_status;
-
-extern bt_clock_snapshot_get_ns_from_origin_status
-bt_clock_snapshot_get_ns_from_origin(
-               const bt_clock_snapshot *clock_snapshot,
-               int64_t *ns_from_origin);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_CONST_H */

diff --git a/include/babeltrace2/trace-ir/clock-snapshot.h b/include/babeltrace2/trace-ir/clock-snapshot.h
new file mode 100644 (file)
index 0000000..23d8678
--- /dev/null
+++ b/include/babeltrace2/trace-ir/clock-snapshot.h
@@ -0,0 +1,228 @@
+#ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
+#define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <stdint.h>
+
+#include <babeltrace2/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-tir-cs Clock snapshot
+@ingroup api-tir
+
+@brief
+    Snapshot of a \bt_stream clock.
+
+A <strong><em>clock snapshot</em></strong> is a snapshot of the value
+of a \bt_stream clock (a \bt_clock_cls instance).
+
+A clock snapshot is a \ref api-tir "trace IR" data object.
+
+<em>Stream clocks</em> only exist conceptually in \bt_name because they
+are stateful objects. \bt_cp_msg cannot refer to stateful objects
+because they must not change while being transported from one
+\bt_comp to the other.
+
+Instead of having a stream clock object, messages have a default
+clock snapshot: this is a snapshot of the value of a stream's
+default clock (a clock class instance):
+
+@image html clocks.png
+
+In the illustration above, notice that:
+
+- Each stream has a default clock (yellow bell alarm clock): this is an
+  instance of the stream's class's default clock class.
+- Each \bt_msg (objects in blue stream rectangles) created for a given
+  stream has a default clock snapshot (yellow star): this is a snapshot
+  of the stream's default clock.
+
+  In other words, a default clock snapshot contains the value of the
+  stream's default clock when this message occured.
+
+A clock snapshot is a \ref api-fund-unique-object "unique object": it
+belongs to a \bt_msg.
+
+The type of a clock snapshot is #bt_clock_snapshot.
+
+You cannot create a clock snapshot: you specify a clock snapshot value
+(in clock cycles, a \c uint64_t value) when you create a \bt_msg or set
+a message's clock snapshot with one of:
+
+- bt_message_stream_beginning_set_default_clock_snapshot()
+- bt_message_stream_end_set_default_clock_snapshot()
+- bt_message_event_create_with_default_clock_snapshot()
+- bt_message_event_create_with_packet_and_default_clock_snapshot()
+- bt_message_packet_beginning_create_with_default_clock_snapshot()
+- bt_message_packet_end_create_with_default_clock_snapshot()
+- bt_message_discarded_events_create_with_default_clock_snapshots()
+- bt_message_discarded_packets_create_with_default_clock_snapshots()
+- bt_message_message_iterator_inactivity_create()
+
+See \ref api-tir-clock-cls-origin "Clock value vs. clock class origin"
+to understand the meaning of a clock's value in relation to the
+properties of its class.
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_clock_snapshot bt_clock_snapshot;
+
+@brief
+    Clock snapshot.
+
+@}
+*/
+
+/*!
+@brief
+    Borrows the \ref api-tir-clock-cls "class" of the clock of which
+    \bt_p{clock_snapshot} is a snapshot.
+
+@param[in] clock_snapshot
+    Clock snapshot of which to borrow the clock class.
+
+@returns
+    \em Borrowed reference of the clock class of \bt_p{clock_snapshot}.
+
+@bt_pre_not_null{clock_snapshot}
+*/
+extern const bt_clock_class *bt_clock_snapshot_borrow_clock_class_const(
+               const bt_clock_snapshot *clock_snapshot);
+
+/*!
+@brief
+    Returns the value, in clock cycles, of the clock snapshot
+    \bt_p{clock_snapshot}.
+
+@param[in] clock_snapshot
+    Clock snapshot of which to get the value.
+
+@returns
+    Value of \bt_p{clock_snapshot} (clock cycles).
+
+@bt_pre_not_null{clock_snapshot}
+
+@sa bt_clock_snapshot_get_ns_from_origin() &mdash;
+    Returns the equivalent nanoseconds from clock class origin of a
+    clock snapshot's value.
+*/
+extern uint64_t bt_clock_snapshot_get_value(
+               const bt_clock_snapshot *clock_snapshot);
+
+/*!
+@brief
+    Status codes for bt_clock_snapshot_get_ns_from_origin().
+*/
+typedef enum bt_clock_snapshot_get_ns_from_origin_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK                  = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Integer overflow while computing the result.
+       */
+       BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR      = __BT_FUNC_STATUS_OVERFLOW_ERROR,
+} bt_clock_snapshot_get_ns_from_origin_status;
+
+/*!
+@brief
+    Converts the value of the clock snapshot
+    \bt_p{clock_snapshot} from cycles to nanoseconds from the
+    \ref api-tir-clock-cls-origin "origin" of its
+    \bt_clock_cls and sets \bt_p{*ns_from_origin} to the result.
+
+This function:
+
+-# Converts the
+   \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
+   property of the clock class of \bt_p{clock_snapshot} to
+   seconds using its
+   \ref api-tir-clock-cls-prop-freq "frequency".
+-# Converts the value of \bt_p{clock_snapshot} to seconds using the
+   frequency of its clock class.
+-# Adds the values of 1., 2., and the
+   \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
+   property of the clock class of \bt_p{clock_snapshot}.
+-# Converts the value of 3. to nanoseconds and sets
+   \bt_p{*ns_from_origin} to this result.
+
+The following illustration shows the possible scenarios:
+
+@image html clock-terminology.png
+
+This function can fail and return the
+#BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
+code if any step of the computation process causes an integer overflow.
+
+@param[in] clock_snapshot
+    Clock snapshot containing the value to convert to nanoseconds
+    from the origin of its clock class.
+@param[out] ns_from_origin
+    <strong>On success</strong>, \bt_p{*ns_from_origin} is the value
+    of \bt_p{clock_snapshot} converted to nanoseconds from the origin
+    of its clock class.
+
+@retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK
+    Success.
+@retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
+    Integer overflow while computing the result.
+
+@bt_pre_not_null{clock_snapshot}
+@bt_pre_not_null{ns_from_origin}
+
+@sa bt_util_clock_cycles_to_ns_from_origin() &mdash;
+    Converts a clock value from cycles to nanoseconds from the clock's
+    origin.
+@sa bt_clock_class_cycles_to_ns_from_origin() &mdash;
+    Converts a clock value from cycles to nanoseconds from a clock
+    class's origin.
+*/
+extern bt_clock_snapshot_get_ns_from_origin_status
+bt_clock_snapshot_get_ns_from_origin(
+               const bt_clock_snapshot *clock_snapshot,
+               int64_t *ns_from_origin);
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H */

diff --git a/include/babeltrace2/trace-ir/event-class-const.h b/include/babeltrace2/trace-ir/event-class-const.h
deleted file mode 100644 (file)
index fa1ff78..0000000
--- a/include/babeltrace2/trace-ir/event-class-const.h
+++ /dev/null
@@ -1,103 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_EVENT_CLASS_CONST_H
-#define BABELTRACE2_TRACE_IR_EVENT_CLASS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-#include <stddef.h>
-
-#include <babeltrace2/property.h>
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_event_class_log_level {
-       BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY              = 0,
-       BT_EVENT_CLASS_LOG_LEVEL_ALERT                  = 1,
-       BT_EVENT_CLASS_LOG_LEVEL_CRITICAL               = 2,
-       BT_EVENT_CLASS_LOG_LEVEL_ERROR                  = 3,
-       BT_EVENT_CLASS_LOG_LEVEL_WARNING                = 4,
-       BT_EVENT_CLASS_LOG_LEVEL_NOTICE                 = 5,
-       BT_EVENT_CLASS_LOG_LEVEL_INFO                   = 6,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM           = 7,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM          = 8,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS          = 9,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE           = 10,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT             = 11,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION         = 12,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE             = 13,
-       BT_EVENT_CLASS_LOG_LEVEL_DEBUG                  = 14,
-} bt_event_class_log_level;
-
-extern const bt_value *bt_event_class_borrow_user_attributes_const(
-               const bt_event_class *event_class);
-
-extern const bt_stream_class *bt_event_class_borrow_stream_class_const(
-               const bt_event_class *event_class);
-
-extern const char *bt_event_class_get_name(const bt_event_class *event_class);
-
-extern uint64_t bt_event_class_get_id(const bt_event_class *event_class);
-
-extern bt_property_availability bt_event_class_get_log_level(
-               const bt_event_class *event_class,
-               bt_event_class_log_level *log_level);
-
-extern const char *bt_event_class_get_emf_uri(
-               const bt_event_class *event_class);
-
-extern const bt_field_class *
-bt_event_class_borrow_specific_context_field_class_const(
-               const bt_event_class *event_class);
-
-extern const bt_field_class *bt_event_class_borrow_payload_field_class_const(
-               const bt_event_class *event_class);
-
-extern void bt_event_class_get_ref(const bt_event_class *event_class);
-
-extern void bt_event_class_put_ref(const bt_event_class *event_class);
-
-#define BT_EVENT_CLASS_PUT_REF_AND_RESET(_var)         \
-       do {                                            \
-               bt_event_class_put_ref(_var);           \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_EVENT_CLASS_MOVE_REF(_var_dst, _var_src)    \
-       do {                                            \
-               bt_event_class_put_ref(_var_dst);       \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_EVENT_CLASS_CONST_H */

diff --git a/include/babeltrace2/trace-ir/event-class.h b/include/babeltrace2/trace-ir/event-class.h
index e435d3876608665443f6f1fecba14c12bca11bd3..c82e6263ac59bdecb02f345e73494749626aabe5 100644 (file)
--- a/include/babeltrace2/trace-ir/event-class.h
+++ b/include/babeltrace2/trace-ir/event-class.h
@@ -29,67 +29,1028 @@
 
 #include <stdint.h>
 
-#include <babeltrace2/trace-ir/event-class-const.h>
 #include <babeltrace2/types.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-ev-cls Event class
+@ingroup api-tir
+
+@brief
+    Class of \bt_p_ev.
+
+An <strong><em>event class</em></strong> is the class of \bt_p_ev,
+which \bt_p_ev_msg contain:
+
+@image html trace-structure.png
+
+In the illustration above, notice that:
+
+- A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
+  some of which are \bt_p_ev_msg.
+- An event message contains an \bt_ev.
+- An event is an instance of an event class.
+- The \ref api-tir-ev-prop-payload "payload field" of an event is an
+  instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
+  which an event class contains.
+
+An event class is a \ref api-tir "trace IR" metadata object.
+
+An event class is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_event_class_get_ref() and put an existing
+reference with bt_event_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" event classes on
+success. The documentation of those functions indicate this
+postcondition.
+
+The type of an event class is #bt_event_class.
+
+A \bt_stream_cls contains event classes. All the event classes of a
+given stream class have unique
+\ref api-tir-ev-cls-prop-id "numeric IDs". Borrow the stream class
+which contains an event class with bt_event_class_borrow_stream_class()
+or bt_event_class_borrow_stream_class_const().
+
+To create a default event class:
+
+<dl>
+  <dt>
+    If bt_stream_class_assigns_automatic_event_class_id() returns
+    #BT_TRUE (the default) for the stream class to use
+  </dt>
+  <dd>Use bt_event_class_create().</dd>
+
+  <dt>
+    If bt_stream_class_assigns_automatic_event_class_id() returns
+    #BT_FALSE for the stream class to use
+  </dt>
+  <dd>Use bt_event_class_create_with_id().</dd>
+</dl>
+
+<h1>Properties</h1>
+
+An event class has the following properties:
+
+<dl>
+  <dt>\anchor api-tir-ev-cls-prop-id Numeric ID</dt>
+  <dd>
+    Numeric ID, unique amongst the numeric IDs of the event class's
+    \bt_stream_cls's event classes.
+
+    Depending on whether or not the event class's stream class
+    automatically assigns event class IDs
+    (see bt_stream_class_assigns_automatic_event_class_id()),
+    set the event class's numeric ID on creation with
+    bt_event_class_create() or
+    bt_event_class_create_with_id().
+
+    You cannot change the numeric ID once the event class is created.
+
+    Get an event class's numeric ID with bt_event_class_get_id().
+  </dd>
+
+  <dt>\anchor api-tir-ev-cls-prop-name \bt_dt_opt Name</dt>
+  <dd>
+    Name of the event class.
+
+    Use bt_event_class_set_name() and bt_event_class_get_name().
+  </dd>
+
+  <dt>\anchor api-tir-ev-cls-prop-log-lvl \bt_dt_opt Log level</dt>
+  <dd>
+    Log level of the event class.
+
+    The event class's log level corresponds to the log level of the
+    tracer's original instrumentation point.
+
+    Use bt_event_class_set_log_level() and
+    bt_event_class_get_log_level().
+  </dd>
+
+  <dt>
+    \anchor api-tir-ev-cls-prop-emf-uri
+    \bt_dt_opt Eclipse Modeling Framework (EMF) URI
+  </dt>
+  <dd>
+    EMF URI of the event class.
+
+    Use bt_event_class_set_emf_uri() and
+    bt_event_class_get_emf_uri().
+  </dd>
+
+  <dt>
+    \anchor api-tir-ev-cls-prop-p-fc
+    \bt_dt_opt Payload field class
+  </dt>
+  <dd>
+    Payload \bt_fc of the event class.
+
+    The payload of an event class instance (\bt_ev) contains the
+    event's main data.
+
+    Use bt_event_class_set_payload_field_class()
+    bt_event_class_borrow_payload_field_class(),
+    and bt_event_class_borrow_payload_field_class_const().
+  </dd>
+
+  <dt>
+    \anchor api-tir-ev-cls-prop-sc-fc
+    \bt_dt_opt Specific context field class
+  </dt>
+  <dd>
+    Specific context \bt_fc of the event class.
+
+    The specific context of an event class instance (\bt_ev) contains
+    any contextual data of which the layout is specific to the
+    event's class and which does not belong to the payload.
+
+    Use bt_event_class_set_specific_context_field_class()
+    bt_event_class_borrow_specific_context_field_class(),
+    and bt_event_class_borrow_specific_context_field_class_const().
+  </dd>
+
+  <dt>
+    \anchor api-tir-ev-cls-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the event class.
+
+    User attributes are custom attributes attached to an event class.
+
+    Use bt_event_class_set_user_attributes(),
+    bt_event_class_borrow_user_attributes(), and
+    bt_event_class_borrow_user_attributes_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_event_class bt_event_class;
+
+@brief
+    Event class.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a default event class and adds it to the \bt_stream_cls
+    \bt_p{stream_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_assigns_automatic_event_class_id(stream_class)
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use bt_event_class_create_with_id().
+    @endparblock
+
+On success, the returned event class has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
+    <td>Automatically assigned by \bt_p{stream_class}
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] stream_class
+    Stream class to add the created event class to.
+
+@returns
+    New event class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{stream_class}
+@pre
+    <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
+    returns #BT_TRUE.
+
+@bt_post_success_frozen{stream_class}
+
+@sa bt_event_class_create_with_id() &mdash;
+    Creates an event class with a specific numeric ID and adds it to a
+    stream class.
+*/
 extern bt_event_class *bt_event_class_create(
                bt_stream_class *stream_class);
 
+/*!
+@brief
+    Creates a default event class with the numeric ID \bt_p{id} and adds
+    it to the \bt_stream_cls \bt_p{stream_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_assigns_automatic_event_class_id(stream_class)
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use bt_event_class_create().
+    @endparblock
+
+On success, the returned event class has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-id "Numeric ID"
+    <td>\bt_p{id}
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-log-lvl "Log level"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-emf-uri "EMF URI"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-p-fc "Payload field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-sc-fc "Specific context field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-ev-cls-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] stream_class
+    Stream class to add the created event class to.
+@param[in] id
+    Numeric ID of the event class to create and add to
+    \bt_p{stream_class}.
+
+@returns
+    New event class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{stream_class}
+@pre
+    <code>bt_stream_class_assigns_automatic_event_class_id(stream_class)</code>
+    returns #BT_FALSE.
+@pre
+    \bt_p{stream_class} does not contain an event class with the numeric
+    ID \bt_p{id}.
+
+@bt_post_success_frozen{stream_class}
+
+@sa bt_event_class_create() &mdash;
+    Creates an event class with an automatic numeric ID and adds it to a
+    stream class.
+*/
 extern bt_event_class *bt_event_class_create_with_id(
                bt_stream_class *stream_class, uint64_t id);
 
-extern bt_value *bt_event_class_borrow_user_attributes(
-               bt_event_class *event_class);
+/*! @} */
 
-extern void bt_event_class_set_user_attributes(
-               bt_event_class *event_class, const bt_value *user_attributes);
+/*!
+@name Stream class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_stream_cls which contains the event class
+    \bt_p{event_class}.
 
+@param[in] event_class
+    Event class from which to borrow the stream class which contains it.
+
+@returns
+    Stream class which contains \bt_p{event_class}.
+
+@bt_pre_not_null{event_class}
+
+@sa bt_event_class_borrow_stream_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_stream_class *bt_event_class_borrow_stream_class(
                bt_event_class *event_class);
 
+/*!
+@brief
+    Borrows the \bt_stream_cls which contains the event class
+    \bt_p{event_class} (\c const version).
+
+See bt_event_class_borrow_stream_class().
+*/
+extern const bt_stream_class *bt_event_class_borrow_stream_class_const(
+               const bt_event_class *event_class);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Returns the numeric ID of the event class \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-id "numeric ID" property.
+
+@param[in] event_class
+    Event class of which to get the numeric ID.
+
+@returns
+    Numeric ID of \bt_p{event_class}.
+
+@bt_pre_not_null{event_class}
+
+@sa bt_event_class_create_with_id() &mdash;
+    Creates an event class with a specific numeric ID and adds it to a
+    stream class.
+*/
+extern uint64_t bt_event_class_get_id(const bt_event_class *event_class);
+
+/*!
+@brief
+    Status codes for bt_event_class_set_name().
+*/
 typedef enum bt_event_class_set_name_status {
-       BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_EVENT_CLASS_SET_NAME_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_event_class_set_name_status;
 
+/*!
+@brief
+    Sets the name of the event class \bt_p{event_class} to
+    a copy of \bt_p{name}.
+
+See the \ref api-tir-ev-cls-prop-name "name" property.
+
+@param[in] event_class
+    Event class of which to set the name to \bt_p{name}.
+@param[in] name
+    New name of \bt_p{event_class} (copied).
+
+@retval #BT_EVENT_CLASS_SET_NAME_STATUS_OK
+    Success.
+@retval #BT_EVENT_CLASS_SET_NAME_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{event_class}
+@bt_pre_hot{event_class}
+@bt_pre_not_null{name}
+
+@sa bt_event_class_get_name() &mdash;
+    Returns the name of an event class.
+*/
 extern bt_event_class_set_name_status bt_event_class_set_name(
                bt_event_class *event_class, const char *name);
 
+/*!
+@brief
+    Returns the name of the event class \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-name "name" property.
+
+If \bt_p{event_class} has no name, this function returns \c NULL.
+
+@param[in] event_class
+    Event class of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{event_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{event_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{event_class}
+
+@sa bt_event_class_set_name() &mdash;
+    Sets the name of an event class.
+*/
+extern const char *bt_event_class_get_name(const bt_event_class *event_class);
+
+/*!
+@brief
+    Event class log level enumerators.
+*/
+typedef enum bt_event_class_log_level {
+       /*!
+       @brief
+           System is unusable.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY              = 0,
+
+       /*!
+       @brief
+           Action must be taken immediately.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_ALERT                  = 1,
+
+       /*!
+       @brief
+           Critical conditions.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_CRITICAL               = 2,
+
+       /*!
+       @brief
+           Error conditions.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_ERROR                  = 3,
+
+       /*!
+       @brief
+           Warning conditions.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_WARNING                = 4,
+
+       /*!
+       @brief
+           Normal, but significant, condition.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_NOTICE                 = 5,
+
+       /*!
+       @brief
+           Informational message.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_INFO                   = 6,
+
+       /*!
+       @brief
+           Debugging information with system-level scope
+           (set of programs).
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM           = 7,
+
+       /*!
+       @brief
+           Debugging information with program-level scope
+           (set of processes).
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM          = 8,
+
+       /*!
+       @brief
+           Debugging information with process-level scope
+           (set of modules).
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS          = 9,
+
+       /*!
+       @brief
+           Debugging information with module (executable/library) scope
+           (set of units).
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE           = 10,
+
+       /*!
+       @brief
+           Debugging information with compilation unit scope
+           (set of functions).
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT             = 11,
+
+       /*!
+       @brief
+           Debugging information with function-level scope.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION         = 12,
+
+       /*!
+       @brief
+           Debugging information with function-level scope.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE             = 13,
+
+       /*!
+       @brief
+           Debugging-level message.
+       */
+       BT_EVENT_CLASS_LOG_LEVEL_DEBUG                  = 14,
+} bt_event_class_log_level;
+
+/*!
+@brief
+    Sets the log level of the event class \bt_p{event_class} to
+    \bt_p{log_level}.
+
+See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
+
+@param[in] event_class
+    Event class of which to set the log level to \bt_p{log_level}.
+@param[in] log_level
+    New log level of \bt_p{event_class}.
+
+@bt_pre_not_null{event_class}
+@bt_pre_hot{event_class}
+
+@sa bt_event_class_get_log_level() &mdash;
+    Returns the log level of an event class.
+*/
 extern void bt_event_class_set_log_level(bt_event_class *event_class,
                bt_event_class_log_level log_level);
 
+/*!
+@brief
+    Returns the log level of the event class \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-log-lvl "log level" property.
+
+@param[in] event_class
+    Event class of which to get the log level.
+@param[out] log_level
+    <strong>If this function returns
+    #BT_PROPERTY_AVAILABILITY_AVAILABLE</strong>, \bt_p{*log_level} is
+    the log level of \bt_p{event_class}.
+
+@retval #BT_PROPERTY_AVAILABILITY_AVAILABLE
+    The log level of \bt_p{event_class} is available.
+@retval #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE
+    The log level of \bt_p{event_class} is not available.
+
+@bt_pre_not_null{event_class}
+@bt_pre_not_null{log_level}
+
+@sa bt_event_class_set_log_level() &mdash;
+    Sets the log level of an event class.
+*/
+extern bt_property_availability bt_event_class_get_log_level(
+               const bt_event_class *event_class,
+               bt_event_class_log_level *log_level);
+
+/*!
+@brief
+    Status codes for bt_event_class_set_emf_uri().
+*/
 typedef enum bt_event_class_set_emf_uri_status {
-       BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK            = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_event_class_set_emf_uri_status;
 
+/*!
+@brief
+    Sets the Eclipse Modeling Framework (EMF) URI of the event class
+    \bt_p{event_class} to a copy of \bt_p{emf_uri}.
+
+See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
+
+@param[in] event_class
+    Event class of which to set the EMF URI to \bt_p{emf_uri}.
+@param[in] emf_uri
+    New EMF URI of \bt_p{event_class} (copied).
+
+@retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_OK
+    Success.
+@retval #BT_EVENT_CLASS_SET_EMF_URI_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{event_class}
+@bt_pre_hot{event_class}
+@bt_pre_not_null{emf_uri}
+
+@sa bt_event_class_get_emf_uri() &mdash;
+    Returns the EMF URI of an event class.
+*/
 extern bt_event_class_set_emf_uri_status bt_event_class_set_emf_uri(
                bt_event_class *event_class, const char *emf_uri);
 
+/*!
+@brief
+    Returns the Eclipse Modeling Framework (EMF) URI of the event
+    class \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-emf-uri "EMF URI" property.
+
+If \bt_p{event_class} has no EMF URI, this function returns \c NULL.
+
+@param[in] event_class
+    Event class of which to get the EMF URI.
+
+@returns
+    @parblock
+    EMF URI of \bt_p{event_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{event_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{event_class}
+
+@sa bt_event_class_set_emf_uri() &mdash;
+    Sets the EMF URI of an event class.
+*/
+extern const char *bt_event_class_get_emf_uri(
+               const bt_event_class *event_class);
+
+/*!
+@brief
+    Status codes for bt_event_class_set_payload_field_class() and
+    bt_event_class_set_specific_context_field_class().
+*/
 typedef enum bt_event_class_set_field_class_status {
-       BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_event_class_set_field_class_status;
 
+/*!
+@brief
+    Sets the payload \bt_fc of the event class
+    \bt_p{event_class} to \bt_p{field_class}.
+
+See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
+
+@param[in] event_class
+    Event class of which to set the payload field class to
+    \bt_p{field_class}.
+@param[in] field_class
+    New payload field class of \bt_p{event_class}.
+
+@retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
+    Success.
+@retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{event_class}
+@bt_pre_hot{event_class}
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+    \bt_p{field_class}, or any of its contained field classes,
+    is not already part of a \bt_stream_cls or of an event class.
+@pre
+    If any of the field classes recursively contained in
+    \bt_p{field_class} has a
+    \ref api-tir-fc-link "link to another field class", it must honor
+    the field class link rules.
+
+@bt_post_success_frozen{field_class}
+
+@sa bt_event_class_borrow_payload_field_class() &mdash;
+    Borrows the payload field class of an event class.
+@sa bt_event_class_borrow_payload_field_class_const() &mdash;
+    Borrows the payload field class of an event class
+    (\c const version).
+*/
+extern bt_event_class_set_field_class_status
+bt_event_class_set_payload_field_class(bt_event_class *event_class,
+               bt_field_class *field_class);
+
+/*!
+@brief
+    Borrows the payload \bt_fc from the event class \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-p-fc "payload field class" property.
+
+If \bt_p{event_class} has no payload field class, this function
+returns \c NULL.
+
+@param[in] event_class
+    Event class from which to borrow the payload field class.
+
+@returns
+    \em Borrowed reference of the payload field class of
+    \bt_p{event_class}, or \c NULL if none.
+
+@bt_pre_not_null{event_class}
+
+@sa bt_event_class_set_payload_field_class() &mdash;
+    Sets the payload field class of an event class.
+@sa bt_event_class_borrow_payload_field_class_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class *bt_event_class_borrow_payload_field_class(
+               bt_event_class *event_class);
+
+/*!
+@brief
+    Borrows the payload \bt_fc from the event class \bt_p{event_class}
+    (\c const version).
+
+See bt_event_class_borrow_payload_field_class().
+*/
+extern const bt_field_class *bt_event_class_borrow_payload_field_class_const(
+               const bt_event_class *event_class);
+
+/*!
+@brief
+    Sets the specific context \bt_fc of the event class
+    \bt_p{event_class} to \bt_p{field_class}.
+
+See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
+property.
+
+@param[in] event_class
+    Event class of which to set the specific context field class to
+    \bt_p{field_class}.
+@param[in] field_class
+    New specific context field class of \bt_p{event_class}.
+
+@retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_OK
+    Success.
+@retval #BT_EVENT_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{event_class}
+@bt_pre_hot{event_class}
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+    \bt_p{field_class}, or any of its contained field classes,
+    is not already part of a \bt_stream_cls or of an event class.
+@pre
+    If any of the field classes recursively contained in
+    \bt_p{field_class} has a
+    \ref api-tir-fc-link "link to another field class", it must honor
+    the field class link rules.
+
+@bt_post_success_frozen{field_class}
+
+@sa bt_event_class_borrow_specific_context_field_class() &mdash;
+    Borrows the specific context field class of an event class.
+@sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
+    Borrows the specific context field class of an event class
+    (\c const version).
+*/
 extern bt_event_class_set_field_class_status
 bt_event_class_set_specific_context_field_class(bt_event_class *event_class,
                bt_field_class *field_class);
 
+/*!
+@brief
+    Borrows the specific context \bt_fc from the event class
+    \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-sc-fc "specific context field class"
+property.
+
+If \bt_p{event_class} has no specific context field class, this function
+returns \c NULL.
+
+@param[in] event_class
+    Event class from which to borrow the specific context field class.
+
+@returns
+    \em Borrowed reference of the specific context field class of
+    \bt_p{event_class}, or \c NULL if none.
+
+@bt_pre_not_null{event_class}
+
+@sa bt_event_class_set_specific_context_field_class() &mdash;
+    Sets the specific context field class of an event class.
+@sa bt_event_class_borrow_specific_context_field_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field_class *
 bt_event_class_borrow_specific_context_field_class(bt_event_class *event_class);
 
-extern bt_event_class_set_field_class_status
-bt_event_class_set_payload_field_class(
-               bt_event_class *event_class,
-               bt_field_class *field_class);
+/*!
+@brief
+    Borrows the specific context \bt_fc from the event class
+    \bt_p{event_class} (\c const version).
 
-extern bt_field_class *bt_event_class_borrow_payload_field_class(
+See bt_event_class_borrow_specific_context_field_class().
+*/
+extern const bt_field_class *
+bt_event_class_borrow_specific_context_field_class_const(
+               const bt_event_class *event_class);
+
+/*!
+@brief
+    Sets the user attributes of the event class \bt_p{event_class} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
+
+@note
+    When you create a default event class with bt_event_class_create()
+    or bt_event_class_create_with_id(), the event class's initial user
+    attributes is an empty \bt_map_val. Therefore you can borrow it with
+    bt_event_class_borrow_user_attributes() and fill it directly instead
+    of setting a new one with this function.
+
+@param[in] event_class
+    Event class of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{event_class}.
+
+@bt_pre_not_null{event_class}
+@bt_pre_hot{event_class}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_event_class_borrow_user_attributes() &mdash;
+    Borrows the user attributes of an event class.
+*/
+extern void bt_event_class_set_user_attributes(
+               bt_event_class *event_class, const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the event class \bt_p{event_class}.
+
+See the \ref api-tir-ev-cls-prop-user-attrs "user attributes" property.
+
+@note
+    When you create a default event class with bt_event_class_create()
+    or bt_event_class_create_with_id(), the event class's initial user
+    attributes is an empty \bt_map_val.
+
+@param[in] event_class
+    Event class from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{event_class} (a \bt_map_val).
+
+@bt_pre_not_null{event_class}
+
+@sa bt_event_class_set_user_attributes() &mdash;
+    Sets the user attributes of an event class.
+@sa bt_event_class_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_event_class_borrow_user_attributes(
                bt_event_class *event_class);
 
+/*!
+@brief
+    Borrows the user attributes of the event class \bt_p{event_class}
+    (\c const version).
+
+See bt_event_class_borrow_user_attributes().
+*/
+extern const bt_value *bt_event_class_borrow_user_attributes_const(
+               const bt_event_class *event_class);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the event class \bt_p{event_class}.
+
+@param[in] event_class
+    @parblock
+    Event class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_event_class_put_ref() &mdash;
+    Decrements the reference count of an event class.
+*/
+extern void bt_event_class_get_ref(const bt_event_class *event_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the event class \bt_p{event_class}.
+
+@param[in] event_class
+    @parblock
+    Event class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_event_class_get_ref() &mdash;
+    Increments the reference count of an event class.
+*/
+extern void bt_event_class_put_ref(const bt_event_class *event_class);
+
+/*!
+@brief
+    Decrements the reference count of the event class
+    \bt_p{_event_class}, and then sets \bt_p{_event_class} to \c NULL.
+
+@param _event_class
+    @parblock
+    Event class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_event_class}
+*/
+#define BT_EVENT_CLASS_PUT_REF_AND_RESET(_event_class) \
+       do {                                            \
+               bt_event_class_put_ref(_event_class);   \
+               (_event_class) = NULL;                  \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the event class \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves an event class reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_EVENT_CLASS_MOVE_REF(_dst, _src)    \
+       do {                                    \
+               bt_event_class_put_ref(_dst);   \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/trace-ir/event-const.h b/include/babeltrace2/trace-ir/event-const.h
deleted file mode 100644 (file)
index fec42ea..0000000
--- a/include/babeltrace2/trace-ir/event-const.h
+++ /dev/null
@@ -1,58 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_EVENT_CONST_H
-#define BABELTRACE2_TRACE_IR_EVENT_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_event_class *bt_event_borrow_class_const(
-               const bt_event *event);
-
-extern const bt_packet *bt_event_borrow_packet_const(
-               const bt_event *event);
-
-extern const bt_stream *bt_event_borrow_stream_const(
-               const bt_event *event);
-
-extern const bt_field *bt_event_borrow_common_context_field_const(
-               const bt_event *event);
-
-extern const bt_field *bt_event_borrow_specific_context_field_const(
-               const bt_event *event);
-
-extern const bt_field *bt_event_borrow_payload_field_const(
-               const bt_event *event);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_EVENT_CONST_H */

diff --git a/include/babeltrace2/trace-ir/event.h b/include/babeltrace2/trace-ir/event.h
index 12a27563e1311b3c927ff95d16e6b370300dba4c..f1431844bc581d6fa80a8332eae167ec5df2f69a 100644 (file)
--- a/include/babeltrace2/trace-ir/event.h
+++ b/include/babeltrace2/trace-ir/event.h
@@ -33,19 +33,346 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-ev Event
+@ingroup api-tir
+
+@brief
+    Trace event.
+
+An <strong><em>event</em></strong> represents a trace event record.
+
+An event is an instance of an \bt_ev_cls:
+
+@image html trace-structure.png
+
+In the illustration above, notice that:
+
+- A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages",
+  some of which are \bt_p_ev_msg.
+- An event message contains an \bt_ev.
+- An event is an instance of an event class.
+- The \ref api-tir-ev-prop-payload "payload field" of an event is an
+  instance of the \ref api-tir-ev-cls-prop-p-fc "payload field class"
+  which an event class contains.
+
+Borrow the class of an event with bt_event_borrow_class() and
+bt_event_borrow_class_const().
+
+An event is a \ref api-tir "trace IR" data object.
+
+You cannot directly create an event: there's no
+<code>bt_event_create()</code> function. The \bt_name library
+creates an event within an \bt_ev_msg from an \bt_ev_cls.
+Therefore, to fill the fields of an event, you must first
+borrow the event from an event message with
+bt_message_event_borrow_event().
+
+An event is a \ref api-fund-unique-object "unique object": it belongs to
+an \bt_ev_msg.
+
+Some library functions \ref api-fund-freezing "freeze" events on
+success. The documentation of those functions indicate this
+postcondition.
+
+The type of an event is #bt_event.
+
+An event conceptually belongs to a \bt_stream. Borrow the stream of an
+event with bt_event_borrow_stream() and bt_event_borrow_stream_const().
+
+If the event's stream's class
+\ref api-tir-stream-cls-prop-supports-pkt "supports packets",
+the event also belongs to a \bt_pkt. In that case, borrow the packet of
+an event with bt_event_borrow_packet() and
+bt_event_borrow_packet_const().
+
+Because a stream or a packet could contain millions of events, there are
+no actual links from a stream or from a packet to its events.
+
+<h1>Properties</h1>
+
+An event has the following properties:
+
+<dl>
+  <dt>\anchor api-tir-ev-prop-payload Payload field</dt>
+  <dd>
+    Event's payload \bt_field.
+
+    The payload of an event contains its main trace data.
+
+    The \ref api-tir-fc "class" of an event's payload field is set
+    at the event's \ref api-tir-ev-cls "class" level. See
+    bt_event_class_set_payload_field_class(),
+    bt_event_class_borrow_payload_field_class(), and
+    bt_event_class_borrow_payload_field_class_const().
+
+    Use bt_event_borrow_payload_field() and
+    bt_event_borrow_payload_field_const().
+  </dd>
+
+  <dt>\anchor api-tir-ev-prop-spec-ctx Specific context field</dt>
+  <dd>
+    Event's specific context \bt_field.
+
+    The specific context of an event contains
+    any contextual data of which the layout is specific to the
+    event's \ref api-tir-ev-cls "class" and which does not belong to the
+    payload.
+
+    The \ref api-tir-fc "class" of an event's specific context field is
+    set at the event's \ref api-tir-ev-cls "class" level. See
+    bt_event_class_set_specific_context_field_class()
+    bt_event_class_borrow_specific_context_field_class(),
+    and bt_event_class_borrow_specific_context_field_class_const()
+
+    Use bt_event_borrow_specific_context_field() and
+    bt_event_borrow_specific_context_field_const().
+  </dd>
+
+  <dt>\anchor api-tir-ev-prop-common-ctx Common context field</dt>
+  <dd>
+    Event's common context \bt_field.
+
+    The common context of an event contains contextual data of which the
+    layout is common to all the \bt_p_ev_cls of the
+    event's stream's \ref api-tir-stream-cls "class".
+
+    The \ref api-tir-fc "class" of an event's common context field is set
+    at the event's \bt_stream_cls level. See
+    bt_stream_class_set_event_common_context_field_class()
+    bt_stream_class_borrow_event_common_context_field_class(),
+    and bt_stream_class_borrow_event_common_context_field_class_const().
+
+    Use bt_event_borrow_common_context_field() and
+    bt_event_borrow_common_context_field_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_event bt_event;
+
+@brief
+    Event.
+
+@}
+*/
+
+/*!
+@name Class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}.
+
+@param[in] event
+    Event of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{event}.
+
+@bt_pre_not_null{event}
+
+@sa bt_event_borrow_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_event_class *bt_event_borrow_class(bt_event *event);
 
-extern bt_packet *bt_event_borrow_packet(bt_event *event);
+/*!
+@brief
+    Borrows the \ref api-tir-ev-cls "class" of the event \bt_p{event}
+    (\c const version).
+
+See bt_event_borrow_class().
+*/
+extern const bt_event_class *bt_event_borrow_class_const(
+               const bt_event *event);
+
+/*! @} */
+
+/*!
+@name Stream access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_stream conceptually containing the event
+    \bt_p{event}.
+
+@param[in] event
+    Event of which to borrow the stream conceptually containing it.
 
+@returns
+    \em Borrowed reference of the stream conceptually containing
+    \bt_p{event}.
+
+@bt_pre_not_null{event}
+
+@sa bt_event_borrow_stream_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_stream *bt_event_borrow_stream(bt_event *event);
 
-extern bt_field *
-bt_event_borrow_common_context_field(bt_event *event);
+/*!
+@brief
+    Borrows the \bt_stream conceptually containing the event
+    \bt_p{event} (\c const version).
+
+See bt_event_borrow_stream().
+*/
+extern const bt_stream *bt_event_borrow_stream_const(
+               const bt_event *event);
+
+/*! @} */
+
+/*!
+@name Packet access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_pkt conceptually containing the event
+    \bt_p{event}.
+
+@attention
+    Only call this function if bt_stream_class_supports_packets()
+    returns #BT_TRUE for the \bt_stream_cls of \bt_p{event}.
+
+@param[in] event
+    Event of which to borrow the packet conceptually containing it.
+
+@returns
+    \em Borrowed reference of the packet conceptually containing
+    \bt_p{event}.
+
+@bt_pre_not_null{event}
+
+@sa bt_event_borrow_packet_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_packet *bt_event_borrow_packet(bt_event *event);
+
+/*!
+@brief
+    Borrows the \bt_pkt conceptually containing the event
+    \bt_p{event} (\c const version).
+
+See bt_event_borrow_packet().
+*/
+extern const bt_packet *bt_event_borrow_packet_const(
+               const bt_event *event);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Borrows the payload \bt_field of the event \bt_p{event}.
+
+See the \ref api-tir-ev-prop-payload "payload field" property.
+
+@param[in] event
+    Event of which to borrow the payload field.
+
+@returns
+    \em Borrowed reference of the payload field of \bt_p{event},
+    or \c NULL if none.
+
+@bt_pre_not_null{event}
 
+@sa bt_event_borrow_payload_field_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field *bt_event_borrow_payload_field(bt_event *event);
+
+/*!
+@brief
+    Borrows the payload \bt_field of the event \bt_p{event}
+    (\c const version).
+
+See bt_event_borrow_payload_field().
+*/
+extern const bt_field *bt_event_borrow_payload_field_const(
+               const bt_event *event);
+
+/*!
+@brief
+    Borrows the specific context \bt_field of the event \bt_p{event}.
+
+See the \ref api-tir-ev-prop-spec-ctx "specific context field" property.
+
+@param[in] event
+    Event of which to borrow the specific context field.
+
+@returns
+    \em Borrowed reference of the specific context field of
+    \bt_p{event}, or \c NULL if none.
+
+@bt_pre_not_null{event}
+
+@sa bt_event_borrow_specific_context_field_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field *
 bt_event_borrow_specific_context_field(bt_event *event);
 
-extern bt_field *bt_event_borrow_payload_field(bt_event *event);
+/*!
+@brief
+    Borrows the specific context \bt_field of the event \bt_p{event}
+    (\c const version).
+
+See bt_event_borrow_specific_context_field().
+*/
+extern const bt_field *bt_event_borrow_specific_context_field_const(
+               const bt_event *event);
+
+/*!
+@brief
+    Borrows the common context \bt_field of the event \bt_p{event}.
+
+See the \ref api-tir-ev-prop-common-ctx "common context field" property.
+
+@param[in] event
+    Event of which to borrow the common context field.
+
+@returns
+    \em Borrowed reference of the common context field of
+    \bt_p{event}, or \c NULL if none.
+
+@bt_pre_not_null{event}
+
+@sa bt_event_borrow_specific_context_field_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field *
+bt_event_borrow_common_context_field(bt_event *event);
+
+/*!
+@brief
+    Borrows the common context \bt_field of the event \bt_p{event}
+    (\c const version).
+
+See bt_event_borrow_common_context_field().
+*/
+extern const bt_field *bt_event_borrow_common_context_field_const(
+               const bt_event *event);
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/trace-ir/field-class-const.h b/include/babeltrace2/trace-ir/field-class-const.h
deleted file mode 100644 (file)
index 2a5c88d..0000000
--- a/include/babeltrace2/trace-ir/field-class-const.h
+++ /dev/null
@@ -1,313 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_FIELD_CLASS_CONST_H
-#define BABELTRACE2_TRACE_IR_FIELD_CLASS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-#include <stddef.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_field_class_type {
-       BT_FIELD_CLASS_TYPE_BOOL                                                = 1ULL << 0,
-       BT_FIELD_CLASS_TYPE_BIT_ARRAY                                           = 1ULL << 1,
-       BT_FIELD_CLASS_TYPE_INTEGER                                             = 1ULL << 2,
-       BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER                                    = (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER,
-       BT_FIELD_CLASS_TYPE_SIGNED_INTEGER                                      = (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER,
-       BT_FIELD_CLASS_TYPE_ENUMERATION                                         = 1ULL << 5,
-       BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION                                = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER,
-       BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION                                  = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_SIGNED_INTEGER,
-       BT_FIELD_CLASS_TYPE_REAL                                                = 1ULL << 6,
-       BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL                               = (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL,
-       BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL                               = (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL,
-       BT_FIELD_CLASS_TYPE_STRING                                              = 1ULL << 9,
-       BT_FIELD_CLASS_TYPE_STRUCTURE                                           = 1ULL << 10,
-       BT_FIELD_CLASS_TYPE_ARRAY                                               = 1ULL << 11,
-       BT_FIELD_CLASS_TYPE_STATIC_ARRAY                                        = (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY,
-       BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY                                       = (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY,
-       BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD                  = (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY,
-       BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD                     = (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY,
-       BT_FIELD_CLASS_TYPE_OPTION                                              = 1ULL << 16,
-       BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD                       = (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION,
-       BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD                          = (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION,
-       BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD                     = (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD,
-       BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD                  = (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD,
-       BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD         = (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD,
-       BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD           = (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD,
-       BT_FIELD_CLASS_TYPE_VARIANT                                             = 1ULL << 23,
-       BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD                      = (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT,
-       BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD                         = (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT,
-       BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD                 = (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD,
-       BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD        = (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD,
-       BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD          = (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD,
-
-       /*
-        * Make sure the enumeration type is a 64-bit integer in case
-        * the project needs field class types in the future.
-        *
-        * This is not part of the API.
-        */
-       __BT_FIELD_CLASS_TYPE_BIG_VALUE                                         = 1ULL << 62,
-} bt_field_class_type;
-
-typedef enum bt_field_class_integer_preferred_display_base {
-       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY            = 2,
-       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL             = 8,
-       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL           = 10,
-       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL       = 16,
-} bt_field_class_integer_preferred_display_base;
-
-extern bt_field_class_type bt_field_class_get_type(
-               const bt_field_class *field_class);
-
-static inline
-bt_bool bt_field_class_type_is(const bt_field_class_type type,
-               const bt_field_class_type type_to_check)
-{
-       return (type & type_to_check) == type_to_check;
-}
-
-extern const bt_value *bt_field_class_borrow_user_attributes_const(
-               const bt_field_class *field_class);
-
-extern uint64_t bt_field_class_bit_array_get_length(
-               const bt_field_class *field_class);
-
-extern uint64_t bt_field_class_integer_get_field_value_range(
-               const bt_field_class *field_class);
-
-extern bt_field_class_integer_preferred_display_base
-bt_field_class_integer_get_preferred_display_base(
-               const bt_field_class *field_class);
-
-extern uint64_t bt_field_class_enumeration_get_mapping_count(
-               const bt_field_class *field_class);
-
-extern const bt_field_class_enumeration_unsigned_mapping *
-bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
-               const bt_field_class *field_class, uint64_t index);
-
-extern const bt_field_class_enumeration_unsigned_mapping *
-bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
-               const bt_field_class *field_class, const char *label);
-
-extern const bt_field_class_enumeration_signed_mapping *
-bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
-               const bt_field_class *field_class, uint64_t index);
-
-extern const bt_field_class_enumeration_signed_mapping *
-bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
-               const bt_field_class *field_class, const char *label);
-
-static inline
-const bt_field_class_enumeration_mapping *
-bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
-               const bt_field_class_enumeration_unsigned_mapping *mapping)
-{
-       return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping);
-}
-
-static inline
-const bt_field_class_enumeration_mapping *
-bt_field_class_enumeration_signed_mapping_as_mapping_const(
-               const bt_field_class_enumeration_signed_mapping *mapping)
-{
-       return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping);
-}
-
-extern const char *bt_field_class_enumeration_mapping_get_label(
-               const bt_field_class_enumeration_mapping *mapping);
-
-extern const bt_integer_range_set_unsigned *
-bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
-               const bt_field_class_enumeration_unsigned_mapping *mapping);
-
-extern const bt_integer_range_set_signed *
-bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
-               const bt_field_class_enumeration_signed_mapping *mapping);
-
-typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status {
-       BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK                = __BT_FUNC_STATUS_OK,
-} bt_field_class_enumeration_get_mapping_labels_for_value_status;
-
-extern bt_field_class_enumeration_get_mapping_labels_for_value_status
-bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
-               const bt_field_class *field_class, uint64_t value,
-               bt_field_class_enumeration_mapping_label_array *label_array,
-               uint64_t *count);
-
-extern bt_field_class_enumeration_get_mapping_labels_for_value_status
-bt_field_class_enumeration_signed_get_mapping_labels_for_value(
-               const bt_field_class *field_class, int64_t value,
-               bt_field_class_enumeration_mapping_label_array *label_array,
-               uint64_t *count);
-
-extern uint64_t bt_field_class_structure_get_member_count(
-               const bt_field_class *field_class);
-
-extern const bt_field_class_structure_member *
-bt_field_class_structure_borrow_member_by_index_const(
-               const bt_field_class *field_class, uint64_t index);
-
-extern const bt_field_class_structure_member *
-bt_field_class_structure_borrow_member_by_name_const(
-               const bt_field_class *field_class, const char *name);
-
-extern const char *bt_field_class_structure_member_get_name(
-               const bt_field_class_structure_member *member);
-
-extern const bt_field_class *
-bt_field_class_structure_member_borrow_field_class_const(
-               const bt_field_class_structure_member *member);
-
-extern const bt_value *bt_field_class_structure_member_borrow_user_attributes_const(
-               const bt_field_class_structure_member *member);
-
-extern const bt_field_class *
-bt_field_class_array_borrow_element_field_class_const(
-               const bt_field_class *field_class);
-
-extern uint64_t bt_field_class_array_static_get_length(
-               const bt_field_class *field_class);
-
-extern const bt_field_path *
-bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
-               const bt_field_class *field_class);
-
-extern const bt_field_class *
-bt_field_class_option_borrow_field_class_const(
-               const bt_field_class *field_class);
-
-extern const bt_field_path *
-bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
-               const bt_field_class *field_class);
-
-extern bt_bool
-bt_field_class_option_with_selector_field_bool_selector_is_reversed(
-               const bt_field_class *field_class);
-
-extern const bt_integer_range_set_unsigned *
-bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
-               const bt_field_class *field_class);
-
-extern const bt_integer_range_set_signed *
-bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(
-               const bt_field_class *field_class);
-
-extern uint64_t bt_field_class_variant_get_option_count(
-               const bt_field_class *field_class);
-
-extern const bt_field_class_variant_option *
-bt_field_class_variant_borrow_option_by_index_const(
-               const bt_field_class *field_class, uint64_t index);
-
-extern const bt_field_class_variant_option *
-bt_field_class_variant_borrow_option_by_name_const(
-               const bt_field_class *field_class, const char *name);
-
-extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
-bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
-               const bt_field_class *field_class, uint64_t index);
-
-extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
-bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(
-               const bt_field_class *field_class, const char *name);
-
-extern const bt_field_class_variant_with_selector_field_integer_signed_option *
-bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
-               const bt_field_class *field_class, uint64_t index);
-
-extern const bt_field_class_variant_with_selector_field_integer_signed_option *
-bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(
-               const bt_field_class *field_class, const char *name);
-
-extern const char *bt_field_class_variant_option_get_name(
-               const bt_field_class_variant_option *option);
-
-extern const bt_field_class *
-bt_field_class_variant_option_borrow_field_class_const(
-               const bt_field_class_variant_option *option);
-
-extern const bt_value *bt_field_class_variant_option_borrow_user_attributes_const(
-               const bt_field_class_variant_option *option);
-
-extern const bt_field_path *
-bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
-               const bt_field_class *field_class);
-
-extern const bt_integer_range_set_unsigned *
-bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const(
-               const bt_field_class_variant_with_selector_field_integer_unsigned_option *option);
-
-static inline
-const bt_field_class_variant_option *
-bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const(
-               const bt_field_class_variant_with_selector_field_integer_unsigned_option *option)
-{
-       return __BT_UPCAST_CONST(bt_field_class_variant_option, option);
-}
-
-extern const bt_integer_range_set_signed *
-bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(
-               const bt_field_class_variant_with_selector_field_integer_signed_option *option);
-
-static inline
-const bt_field_class_variant_option *
-bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(
-               const bt_field_class_variant_with_selector_field_integer_signed_option *option)
-{
-       return __BT_UPCAST_CONST(bt_field_class_variant_option, option);
-}
-
-extern void bt_field_class_get_ref(const bt_field_class *field_class);
-
-extern void bt_field_class_put_ref(const bt_field_class *field_class);
-
-#define BT_FIELD_CLASS_PUT_REF_AND_RESET(_var)         \
-       do {                                            \
-               bt_field_class_put_ref(_var);           \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_FIELD_CLASS_MOVE_REF(_var_dst, _var_src)    \
-       do {                                            \
-               bt_field_class_put_ref(_var_dst);       \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_FIELD_CLASS_CONST_H */

diff --git a/include/babeltrace2/trace-ir/field-class.h b/include/babeltrace2/trace-ir/field-class.h
index e8be1c51e75d1394ff670e682599da2e3874365b..0aab9682e0383d637775763fd3e65153153010b1 100644 (file)
--- a/include/babeltrace2/trace-ir/field-class.h
+++ b/include/babeltrace2/trace-ir/field-class.h
@@ -31,188 +31,4590 @@
 #include <stddef.h>
 
 #include <babeltrace2/types.h>
-#include <babeltrace2/trace-ir/field-class-const.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-fc Field classes
+@ingroup api-tir
+
+@brief
+    Classes of \bt_p_field.
+
+<strong><em>Field classes</em></strong> are the classes of \bt_p_field:
+
+@image html field-class-zoom.png
+
+Field classes are \ref api-tir "trace IR" metadata objects.
+
+There are many types of field classes. They can be divided into two main
+categories:
+
+<dl>
+  <dt>Scalar</dt>
+  <dd>
+    Classes of fields which contain a simple value.
+
+    The scalar field classes are:
+
+    - \ref api-tir-fc-bool "Boolean"
+    - \ref api-tir-fc-ba "Bit array"
+    - \ref api-tir-fc-int "Integer" (unsigned and signed)
+    - \ref api-tir-fc-enum "Enumeration" (unsigned and signed)
+    - \ref api-tir-fc-real "Real" (single-precision and double-precision)
+    - \ref api-tir-fc-string "String"
+  </dd>
+
+  <dt>Container</dt>
+  <dd>
+    Classes of fields which contain other fields.
+
+    The container field classes are:
+
+    - \ref api-tir-fc-array "Array" (static and dynamic)
+    - \ref api-tir-fc-struct "Structure"
+    - \ref api-tir-fc-opt "Option"
+    - \ref api-tir-fc-var "Variant"
+  </dd>
+</dl>
+
+@image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
+
+Some field classes conceptually inherit other field classes, eventually
+making an inheritance hierarchy. For example, a \bt_sarray_fc
+\em is an array field class. Therefore, a static array field class has
+any property that an array field class has.
+
+The complete field class inheritance hierarchy is:
+
+@image html all-field-classes.png
+
+In the illustration above:
+
+- You can create any field class with a dark background with
+  a dedicated <code>bt_field_class_*_create()</code> function.
+
+- A field class with a pale background is an \em abstract field class:
+  you cannot create it, but it has properties, therefore there are
+  functions which apply to it.
+
+  For example, bt_field_class_integer_set_preferred_display_base()
+  applies to any \bt_int_fc.
+
+Field classes are \ref api-fund-shared-object "shared objects": get a
+new reference with bt_field_class_get_ref() and put an existing
+reference with bt_field_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" field classes on
+success. The documentation of those functions indicate this
+postcondition.
+
+All the field class types share the same C type, #bt_field_class.
+
+Get the type enumerator of a field class with bt_field_class_get_type().
+Get whether or not a field class type conceptually \em is a given type
+with the inline bt_field_class_type_is() function.
+
+The following table shows the available type enumerators and creation
+functions for each type of \em concrete (non-abstract) field class:
+
+<table>
+  <tr>
+    <th>Name
+    <th>Type enumerator
+    <th>Creation function
+  <tr>
+    <td><em>\ref api-tir-fc-bool "Boolean"</em>
+    <td>#BT_FIELD_CLASS_TYPE_BOOL
+    <td>bt_field_class_bool_create()
+  <tr>
+    <td><em>\ref api-tir-fc-ba "Bit array"</em>
+    <td>#BT_FIELD_CLASS_TYPE_BIT_ARRAY
+    <td>bt_field_class_bit_array_create()
+  <tr>
+    <td><em>Unsigned \ref api-tir-fc-int "integer"</em>
+    <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER
+    <td>bt_field_class_integer_unsigned_create()
+  <tr>
+    <td><em>Signed \ref api-tir-fc-int "integer"</em>
+    <td>#BT_FIELD_CLASS_TYPE_SIGNED_INTEGER
+    <td>bt_field_class_integer_signed_create()
+  <tr>
+    <td><em>Unsigned \ref api-tir-fc-enum "enumeration"</em>
+    <td>#BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION
+    <td>bt_field_class_enumeration_unsigned_create()
+  <tr>
+    <td><em>Signed \ref api-tir-fc-enum "enumeration"</em>
+    <td>#BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION
+    <td>bt_field_class_enumeration_signed_create()
+  <tr>
+    <td><em>Single-precision \ref api-tir-fc-real "real"</em>
+    <td>#BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL
+    <td>bt_field_class_real_single_precision_create()
+  <tr>
+    <td><em>Double-precision \ref api-tir-fc-real "real"</em>
+    <td>#BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL
+    <td>bt_field_class_real_double_precision_create()
+  <tr>
+    <td><em>\ref api-tir-fc-string "String"</em>
+    <td>#BT_FIELD_CLASS_TYPE_STRING
+    <td>bt_field_class_string_create()
+  <tr>
+    <td><em>Static \ref api-tir-fc-array "array"</em>
+    <td>#BT_FIELD_CLASS_TYPE_STATIC_ARRAY
+    <td>bt_field_class_array_static_create()
+  <tr>
+    <td><em>Dynamic \ref api-tir-fc-array "array" (no length field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
+    <td>bt_field_class_array_dynamic_create()
+  <tr>
+    <td><em>Dynamic \ref api-tir-fc-array "array" (with length field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
+    <td>bt_field_class_array_dynamic_create()
+  <tr>
+    <td><em>\ref api-tir-fc-struct "Structure"</em>
+    <td>#BT_FIELD_CLASS_TYPE_STRUCTURE
+    <td>bt_field_class_structure_create()
+  <tr>
+    <td><em>\ref api-tir-fc-opt "Option" (no selector field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
+    <td>bt_field_class_option_without_selector_create()
+  <tr>
+    <td><em>\ref api-tir-fc-opt "Option" (boolean selector field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
+    <td>bt_field_class_option_with_selector_field_bool_create()
+  <tr>
+    <td><em>\ref api-tir-fc-opt "Option" (unsigned integer selector field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
+    <td>bt_field_class_option_with_selector_field_integer_unsigned_create()
+  <tr>
+    <td><em>\ref api-tir-fc-opt "Option" (signed integer selector field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
+    <td>bt_field_class_option_with_selector_field_integer_signed_create()
+  <tr>
+    <td><em>\ref api-tir-fc-var "Variant" (no selector field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
+    <td>bt_field_class_variant_create()
+  <tr>
+    <td><em>\ref api-tir-fc-var "Variant" (unsigned integer selector field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
+    <td>bt_field_class_variant_create()
+  <tr>
+    <td><em>\ref api-tir-fc-var "Variant" (signed integer selector field)</em>
+    <td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
+    <td>bt_field_class_variant_create()
+</table>
+
+You need a \bt_trace_cls to create a field class: create one from a
+\bt_self_comp with bt_trace_class_create().
+
+Outside the field class API, you can use field classes at four
+locations, called <em>scopes</em>, within the trace IR API:
+
+- To set the packet context field class of a \bt_stream_cls with
+  bt_stream_class_set_packet_context_field_class().
+
+- To set the event common context field class of a stream class with
+  bt_stream_class_set_event_common_context_field_class().
+
+- To set the specific context field class of an \bt_ev_cls with
+  bt_event_class_set_specific_context_field_class().
+
+- To set the payload field class of an event class with
+  bt_event_class_set_payload_field_class().
+
+When you call one of the four functions above:
+
+- The passed field class must be a \bt_struct_fc.
+
+- You must \em not have already called any of the four functions above
+  with the passed field class or with any of its contained field
+  classes.
+
+- If any of the field classes recursively contained in the passed
+  field class has a \ref api-tir-fc-link "link to another field class",
+  it must honor the field class link rules.
+
+Once you have called one of the four functions above, the passed field
+class becomes \ref api-fund-freezing "frozen".
+
+<h1>Common field class property</h1>
+
+A field class has the following common property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the field class.
+
+    User attributes are custom attributes attached to a field class.
+
+    Use bt_field_class_set_user_attributes(),
+    bt_field_class_borrow_user_attributes(), and
+    bt_field_class_borrow_user_attributes_const().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-fc-bool Boolean field class</h1>
+
+@image html fc-bool.png
+
+A <strong><em>boolean field class</em></strong> is the class
+of \bt_p_bool_field.
+
+A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
+
+Create a boolean field class with bt_field_class_bool_create().
+
+A boolean field class has no specific properties.
+
+<h1>\anchor api-tir-fc-ba Bit array field class</h1>
+
+@image html fc-ba.png
+
+A <strong><em>bit array field class</em></strong> is the class
+of \bt_p_ba_field.
+
+A bit array field contains a fixed-length array of bits.
+
+Create a bit array field class with bt_field_class_bit_array_create().
+
+A bit array field class has the following property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-ba-prop-len
+    Length
+  </dt>
+  <dd>
+    Number of bits contained in the instances (bit array fields) of
+    the bit array field class.
+
+    As of \bt_name_version_min_maj, the maximum length of a bit array
+    field is 64.
+
+    You cannot change the length once the bit array field class is
+    created.
+
+    Get a bit array field class's length with
+    bt_field_class_bit_array_get_length().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-fc-int Integer field classes</h1>
+
+@image html fc-int.png
+
+<strong><em>Integer field classes</em></strong> are classes
+of \bt_p_int_field.
+
+Integer fields contain integral values.
+
+An integer field class is an \em abstract field class: you cannot create
+one. The concrete integer field classes are:
+
+<dl>
+  <dt>Unsigned integer field class</dt>
+  <dd>
+    Its instances (unsigned integer fields) contain an unsigned integral
+    value (\c uint64_t).
+
+    Create with bt_field_class_integer_unsigned_create().
+  </dd>
+
+  <dt>Signed integer field class</dt>
+  <dd>
+    Its instances (signed integer fields) contain a signed integral
+    value (\c int64_t).
+
+    Create with bt_field_class_integer_signed_create().
+  </dd>
+</dl>
+
+Integer field classes have the following common properties:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-int-prop-size
+    Field value range
+  </dt>
+  <dd>
+    Expected range of values that the instances (integer fields)
+    of the integer field class can contain.
+
+    For example, if the field value range of an unsigned integer
+    field class is [0,&nbsp;16383], then its unsigned integer fields
+    can only contain the values from 0 to 16383.
+
+    \bt_cp_sink_comp can benefit from this property to make some space
+    optimizations when writing trace data.
+
+    Use bt_field_class_integer_set_field_value_range() and
+    bt_field_class_integer_get_field_value_range().
+  </dd>
+
+  <dt>
+    \anchor api-tir-fc-int-prop-base
+    Preferred display base
+  </dt>
+  <dd>
+    Preferred base (2, 8, 10, or 16) to use when displaying the
+    instances (integer fields) of the integer field class.
+
+    Use bt_field_class_integer_set_preferred_display_base() and
+    bt_field_class_integer_get_preferred_display_base().
+  </dd>
+</dl>
+
+<h2>\anchor api-tir-fc-enum Enumeration field classes</h2>
+
+@image html fc-enum.png
+
+<strong><em>Enumeration field classes</em></strong> are classes
+of \bt_p_enum_field.
+
+Enumeration field classes \em are \bt_p_int_fc: they have the integer
+field classes properties.
+
+Enumeration fields \em are integer fields: they contain integral values.
+
+Enumeration field classes associate labels (strings) to specific
+ranges of integral values. This association is called an enumeration
+field class <em>mapping</em>.
+
+For example, if an enumeration field class maps the label \c SUGAR to
+the integer ranges [1,&nbsp;19] and [25,&nbsp;31], then an instance
+(enumeration field) of this field class with the value 15 or 28 has the
+label <code>SUGAR</code>.
+
+An enumeration field class is an \em abstract field class: you cannot
+create one. The concrete enumeration field classes are:
+
+<dl>
+  <dt>Unsigned enumeration field class</dt>
+  <dd>
+    Its instances (unsigned enumeration fields) contain an unsigned
+    value (\c uint64_t).
+
+    Create with bt_field_class_enumeration_unsigned_create().
+  </dd>
+
+  <dt>Signed enumeration field class</dt>
+  <dd>
+    Its instances (signed enumeration fields) contain a signed value
+    (\c int64_t).
+
+    Create with bt_field_class_enumeration_signed_create().
+  </dd>
+</dl>
+
+Enumeration field classes have the following common property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-enum-prop-mappings
+    Mappings
+  </dt>
+  <dd>
+    Set of mappings of the enumeration field class.
+
+    An enumeration field class mapping is a label (string) and an
+    \bt_int_rs.
+
+    The integer ranges of a given mapping or of multiple mappings of
+    the same enumeration field class can overlap. For example,
+    an enumeration field class can have those two mappings:
+
+    - <code>CALORIES</code>: [1,&nbsp;11], [15,&nbsp;37]
+    - <code>SODIUM</code>: [7,&nbsp;13]
+
+    In that case, the values 2 and 30 correpond to the label
+    <code>CALORIES</code>, the value 12 to the label
+    <code>SODIUM</code>, and the value 10 to the labels
+    \c CALORIES \em and <code>SODIUM</code>.
+
+    Two mappings of the same enumeration field class cannot have the
+    same label.
+
+    Add a mapping to an enumeration field class with
+    bt_field_class_enumeration_unsigned_add_mapping() or
+    bt_field_class_enumeration_signed_add_mapping().
+
+    Get the number of mappings in an enumeration field class with
+    bt_field_class_enumeration_get_mapping_count().
+
+    Borrow a mapping from an enumeration field class with
+    bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(),
+    bt_field_class_enumeration_signed_borrow_mapping_by_index_const(),
+    bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(),
+    and
+    bt_field_class_enumeration_signed_borrow_mapping_by_label_const().
+
+    An enumeration field class mapping is a
+    \ref api-fund-unique-object "unique object": it
+    belongs to the enumeration field class which contains it.
+
+    There are two enumeration field class mapping types, depending on
+    the field class's type:
+    #bt_field_class_enumeration_unsigned_mapping and
+    #bt_field_class_enumeration_signed_mapping.
+
+    There is also the #bt_field_class_enumeration_mapping type for
+    common properties and operations (for example,
+    bt_field_class_enumeration_mapping_get_label()).
+    \ref api-fund-c-typing "Upcast" a specific enumeration field class
+    mapping to the #bt_field_class_enumeration_mapping type with
+    bt_field_class_enumeration_unsigned_mapping_as_mapping_const() or
+    bt_field_class_enumeration_signed_mapping_as_mapping_const().
+
+    Get all the enumeration field class labels mapped to a given integer
+    value with
+    bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
+    and
+    bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-fc-real Real field classes</h1>
+
+@image html fc-real.png
+
+<strong><em>Real field classes</em></strong> are classes
+of \bt_p_real_field.
+
+Real fields contain
+<a href="https://en.wikipedia.org/wiki/Real_number">real</a>
+values (\c float or \c double types).
+
+A real field class is an \em abstract field class: you cannot create
+one. The concrete real field classes are:
+
+<dl>
+  <dt>Single-precision real field class</dt>
+  <dd>
+    Its instances (single-precision real fields) contain a \c float
+    value.
+
+    Create with bt_field_class_real_single_precision_create().
+  </dd>
+
+  <dt>Double-precision real field class</dt>
+  <dd>
+    Its instances (double-precision real fields) contain a \c double
+    value.
+
+    Create with bt_field_class_real_double_precision_create().
+  </dd>
+</dl>
+
+Real field classes have no specific properties.
+
+<h1>\anchor api-tir-fc-string String field class</h1>
+
+@image html fc-string.png
+
+A <strong><em>string field class</em></strong> is the class
+of \bt_p_string_field.
+
+A string field contains an UTF-8 string value.
+
+Create a string field class with bt_field_class_string_create().
+
+A string field class has no specific properties.
+
+<h1>\anchor api-tir-fc-array Array field classes</h1>
+
+@image html fc-array.png
+
+<strong><em>Array field classes</em></strong> are classes
+of \bt_p_array_field.
+
+Array fields contain zero or more fields which have the same class.
+
+An array field class is an \em abstract field class: you cannot create
+one. The concrete array field classes are:
+
+<dl>
+  <dt>Static array field class</dt>
+  <dd>
+    Its instances (static array fields) contain a fixed number of
+    fields.
+
+    Create with bt_field_class_array_static_create().
+
+    A static array field class has the following specific property:
+
+    <dl>
+      <dt>
+        \anchor api-tir-fc-sarray-prop-len
+        Length
+      </dt>
+      <dd>
+        Number of fields contained in the instances (static array
+        fields) of the static array field class.
+
+        You cannot change the length once the static array field class
+        is created.
+
+        Get a static array field class's length with
+        bt_field_class_array_static_get_length().
+      </dd>
+    </dl>
+  </dd>
+
+  <dt>Dynamic array field class</dt>
+  <dd>
+    Its instances (dynamic array fields) contain a variable number array
+    of fields.
+
+    There are two types of dynamic array field classes: without or
+    with a length field. See
+    \ref api-tir-fc-link "Field classes with links to other field classes"
+    to learn more.
+
+    @image html darray-link.png "Dynamic array field class with a length field."
+
+    Create with bt_field_class_array_dynamic_create().
+
+    A dynamic array field class with a length field has the
+    specific property:
+
+    <dl>
+      <dt>
+        \anchor api-tir-fc-darray-prop-len-fp
+        Length field path
+      </dt>
+      <dd>
+        Field path of the linked length field class.
+
+        Get a dynamic array field class's length field path with
+        bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const().
+      </dd>
+    </dl>
+  </dd>
+</dl>
+
+Array field classes have the following common property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-array-prop-elem-fc
+    Element field class
+  </dt>
+  <dd>
+    Class of the fields contained in the instances (array fields) of the
+    array field class.
+
+    You cannot change the element field class once the array field class
+    is created.
+
+    Borrow an array field class's element field class with
+    Use bt_field_class_array_borrow_element_field_class() and
+    bt_field_class_array_borrow_element_field_class_const().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-fc-struct Structure field class</h1>
+
+@image html fc-struct.png
+
+A <strong><em>structure field class</em></strong> is the class
+of a \bt_struct_field.
+
+A structure field contains an ordered list of zero or more members. Each
+structure field member is the instance of a structure field class
+member. A structure field class member has a name, a field class,
+and user attributes.
+
+Create a structure field class with bt_field_class_structure_create().
+
+A structure field class has the following specific property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-struct-prop-members
+    Members
+  </dt>
+  <dd>
+    Ordered list of members (zero or more) of the structure field class.
+
+    Each member has:
+
+    - A name, unique amongst all the member names of the same
+      structure field class.
+    - A field class.
+    - User attributes.
+
+    The instances (structure fields) of a structure field class have
+    members which are instances of the corresponding structure field
+    class members.
+
+    Append a member to a structure field class with
+    bt_field_class_structure_append_member().
+
+    Borrow a member from a structure field class with
+    bt_field_class_structure_borrow_member_by_index(),
+    bt_field_class_structure_borrow_member_by_name(),
+    bt_field_class_structure_borrow_member_by_index_const(), and
+    bt_field_class_structure_borrow_member_by_name_const().
+
+    A structure field class member is a
+    \ref api-fund-unique-object "unique object": it
+    belongs to the structure field class which contains it.
+
+    The type of a structure field class member is
+    #bt_field_class_structure_member.
+
+    Get a structure field class member's name with
+    bt_field_class_structure_member_get_name().
+
+    Borrow a structure field class member's field class with
+    bt_field_class_structure_member_borrow_field_class() and
+    bt_field_class_structure_member_borrow_field_class_const().
+
+    Set a structure field class member's user attributes with
+    bt_field_class_structure_member_set_user_attributes().
+
+    Borrow a structure field class member's user attributes with
+    bt_field_class_structure_member_borrow_user_attributes() and
+    bt_field_class_structure_member_borrow_user_attributes_const().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-fc-opt Option field classes</h1>
+
+@image html fc-opt.png
+
+<strong><em>Option field classes</em></strong> are classes
+of \bt_p_opt_field.
+
+An option field either does or doesn't contain a field, called its
+optional field.
+
+An option field class is an \em abstract field class: you cannot create
+one. An option field class either has a selector field (it's linked to a
+selector field class; see
+\ref api-tir-fc-link "Field classes with links to other field classes")
+or none. Therefore, the concrete option field classes are:
+
+<dl>
+  <dt>Option field class without a selector field</dt>
+  <dd>
+    Create with bt_field_class_option_without_selector_create().
+
+    An option field class without a selector field has no specific
+    properties.
+  </dd>
+
+  <dt>Option field class with a boolean selector field</dt>
+  <dd>
+    The linked selector field of an option field class's instance
+    (an option field) is a \bt_bool_field.
+
+    Consequently, the option field class's selector field class is
+    a \bt_bool_fc.
+
+    @image html opt-link.png "Option field class with a boolean selector field."
+
+    Create with bt_field_class_option_with_selector_field_bool_create().
+
+    An option field class with a boolean selector field has the
+    following specific property:
+
+    <dl>
+      <dt>
+        \anchor api-tir-fc-opt-prop-sel-rev
+        Selector is reversed?
+      </dt>
+      <dd>
+        Whether or not the linked boolean selector field makes the
+        option field class's instance (an option field) contain a field
+        when it's #BT_TRUE or when it's #BT_FALSE.
+
+        If this property is #BT_TRUE, then if the linked selector field
+        has the value #BT_FALSE, the option field contains a field.
+
+        Use
+        bt_field_class_option_with_selector_field_bool_set_selector_is_reversed()
+        and
+        bt_field_class_option_with_selector_field_bool_selector_is_reversed().
+      </dd>
+    </dl>
+  </dd>
+
+  <dt>Option field class with an unsigned selector field</dt>
+  <dd>
+    The linked selector field of an option field class's instance
+    (an option field) is an \bt_uint_field.
+
+    Consequently, the option field class's selector field class is
+    an \bt_uint_fc.
+
+    Create with
+    bt_field_class_option_with_selector_field_integer_unsigned_create().
+
+    Pass an \bt_uint_rs on creation to set which values of the selector
+    field can make the option field contain a field.
+
+    An option field class with an unsigned integer selector field has
+    the following specific property:
+
+    <dl>
+      <dt>
+        \anchor api-tir-fc-opt-prop-uint-rs
+        Selector's unsigned integer ranges
+      </dt>
+      <dd>
+        If the linked unsigned integer selector field of an option
+        field class's instance (an option field) has a value which
+        intersects with the selector's unsigned integer ranges, then
+        the option field contains a field.
+
+        You cannot change the selector's unsigned integer ranges once
+        the option field class is created.
+
+        Borrow the selector's unsigned integer ranges from an
+        option field class with an unsigned integer selector field with
+        bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const().
+      </dd>
+    </dl>
+  </dd>
+
+  <dt>Option field class with a signed selector field</dt>
+  <dd>
+    The linked selector field of an option field class's instance
+    (an option field) is a \bt_sint_field.
+
+    Consequently, the option field class's selector field class is
+    a \bt_sint_fc.
+
+    Create with
+    bt_field_class_option_with_selector_field_integer_signed_create().
+
+    Pass a \bt_sint_rs on creation to set which values of the selector
+    field can make the option field contain a field.
+
+    An option field class with a signed integer selector field has
+    the following specific property:
+
+    <dl>
+      <dt>
+        \anchor api-tir-fc-opt-prop-sint-rs
+        Selector's signed integer ranges
+      </dt>
+      <dd>
+        If the linked signed integer selector field of an option
+        field class's instance (an option field) has a value which
+        intersects with the selector's signed integer ranges, then
+        the option field contains a field.
+
+        You cannot change the selector's signed integer ranges once
+        the option field class is created.
+
+        Borrow the selector's signed integer ranges from an
+        option field class with a signed integer selector field with
+        bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const().
+      </dd>
+    </dl>
+  </dd>
+</dl>
+
+Option field classes with a selector have the following common
+property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-opt-prop-sel-fp
+    Selector field path
+  </dt>
+  <dd>
+    Field path of the linked selector field class.
+
+    Borrow such an option field class's selector field path with
+    bt_field_class_option_with_selector_field_borrow_selector_field_path_const().
+  </dd>
+</dl>
+
+Option field classes have the following common property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-opt-prop-fc
+    Optional field class
+  </dt>
+  <dd>
+    Class of the optional field of an instance (option field) of the
+    option field class.
+
+    You cannot change the optional field class once the option field
+    class is created.
+
+    Borrow an option field class's optional field class with
+    Use bt_field_class_option_borrow_field_class() and
+    bt_field_class_option_borrow_field_class_const().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-fc-var Variant field classes</h1>
+
+@image html fc-var.png
+
+<strong><em>Variant field classes</em></strong> are classes
+of \bt_p_var_field.
+
+A variant field contains a field amongst one or more possible fields.
+
+Variant field classes contain one or more options. Each variant field
+class option has a name, a field class, user attributes, and integer
+ranges, depending on the exact type.
+
+A variant field class is an \em abstract field class: you cannot create
+one. A variant field class either has a selector field (it's linked to a
+selector field class; see
+\ref api-tir-fc-link "Field classes with links to other field classes")
+or none. Therefore, the concrete variant field classes are:
+
+<dl>
+  <dt>Variant field class without a selector field</dt>
+  <dd>
+    Create with bt_field_class_variant_create(), passing \c NULL as
+    the selector field class.
+
+    Append an option to such a variant field class with
+    bt_field_class_variant_without_selector_append_option().
+
+    A variant field class without a selector field has no specific
+    properties.
+  </dd>
+
+  <dt>Variant field class with an unsigned selector field</dt>
+  <dd>
+    The linked selector field of a variant field class's instance
+    (a variant field) is an \bt_uint_field.
+
+    Consequently, the variant field class's selector field class is
+    an \bt_uint_fc.
+
+    @image html var-link.png "Variant field class with an unsigned integer selector field."
+
+    Create with bt_field_class_variant_create(), passing an
+    unsigned integer field class as the selector field class.
+
+    Append an option to such a variant field class with
+    bt_field_class_variant_with_selector_field_integer_unsigned_append_option().
+
+    Pass an \bt_uint_rs when you append an option to set which values of
+    the selector field can make the variant field have a given
+    current option.
+
+    Borrow such a variant field class's option with
+    bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const()
+    and
+    bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const().
+  </dd>
+
+  <dt>Variant field class with a signed selector field</dt>
+  <dd>
+    The linked selector field of a variant field class's instance
+    (a variant field) is a \bt_sint_field.
+
+    Consequently, the variant field class's selector field class is
+    a \bt_sint_fc.
+
+    Create with bt_field_class_variant_create(), passing a
+    signed integer field class as the selector field class.
+
+    Append an option to such a variant field class with
+    bt_field_class_variant_with_selector_field_integer_signed_append_option().
+
+    Pass a \bt_sint_rs when you append an option to set which values of
+    the selector field can make the variant field have a given
+    current option.
+
+    Borrow such a variant field class's option with
+    bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const()
+    and
+    bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const().
+  </dd>
+</dl>
+
+Variant field classes with a selector have the following common
+property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-var-prop-sel-fp
+    Selector field path
+  </dt>
+  <dd>
+    Field path of the linked selector field class.
+
+    Borrow such a variant field class's selector field path with
+    bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
+  </dd>
+</dl>
+
+Variant field classes have the following common property:
+
+<dl>
+  <dt>
+    \anchor api-tir-fc-var-prop-opts
+    Options
+  </dt>
+  <dd>
+    Options of the variant field class.
+
+    Each option has:
+
+    - A name, unique amongst all the option names of the same
+      variant field class.
+    - A field class.
+    - User attributes.
+
+    If the variant field class is linked to a selector field class, then
+    each option also has an \bt_int_rs. In that case, the ranges of a
+    given option cannot overlap any range of any other option.
+
+    A variant field class must contain at least one option.
+
+    Depending on whether or not the variant field class has a selector
+    field class, append an option to a variant field class
+    with bt_field_class_variant_without_selector_append_option(),
+    bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
+    or
+    bt_field_class_variant_with_selector_field_integer_signed_append_option().
+
+    Get the number of options contained in a variant field class
+    with bt_field_class_variant_get_option_count().
+
+    A variant field class option is a
+    \ref api-fund-unique-object "unique object": it
+    belongs to the variant field class which contains it.
+
+    Borrow any variant field class's option with
+    bt_field_class_variant_borrow_option_by_index(),
+    bt_field_class_variant_borrow_option_by_name(),
+    bt_field_class_variant_borrow_option_by_index_const(), and
+    bt_field_class_variant_borrow_option_by_name_const().
+
+    Those functions return the common #bt_field_class_variant_option
+    type. Get the name of a variant field class option with
+    bt_field_class_variant_option_get_name(). Borrow a variant field
+    class option's field class with
+    bt_field_class_variant_option_borrow_field_class() and
+    bt_field_class_variant_option_borrow_field_class_const().
+
+    Borrow the option of a variant field classes with a selector field
+    class with
+    bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(),
+    bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(),
+    bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or
+    bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(),
+    depending on the selector field class's type.
+
+    Those functions return the
+    #bt_field_class_variant_with_selector_field_integer_unsigned_option or
+    #bt_field_class_variant_with_selector_field_integer_signed_option type.
+    \ref api-fund-c-typing "Upcast" those types to the
+    #bt_field_class_variant_option type with
+    bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const()
+    or
+    bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const().
+
+    Borrow the option's ranges from a variant field class with a
+    selector field class with
+    bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const()
+    or
+    bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const().
+
+    Set a variant field class option's user attributes with
+    bt_field_class_variant_option_set_user_attributes().
+
+    Borrow a variant field class option's user attributes with
+    bt_field_class_variant_option_borrow_user_attributes() and
+    bt_field_class_variant_option_borrow_user_attributes_const().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-fc-link Field classes with links to other field classes</h1>
+
+\bt_cp_darray_fc, \bt_p_opt_fc, and \bt_p_var_fc \em can have links to
+other, preceding field classes.
+
+When a field class&nbsp;A has a link to another field class&nbsp;B, then
+an instance (\bt_field) of A has a link to an instance of B.
+
+This feature exists so that the linked field can contain the value of a
+dynamic property of the field. Those properties are:
+
+<dl>
+  <dt>\bt_c_darray_field</dt>
+  <dd>
+    The linked field, a \bt_uint_field, contains the \b length of the
+    dynamic array field.
+  </dd>
+
+  <dt>\bt_c_opt_field</dt>
+  <dd>
+    The linked field, either a \bt_bool_field or an \bt_int_field,
+    indicates whether or not the option field has a field.
+  </dd>
+
+  <dt>\bt_c_var_field</dt>
+  <dd>
+    The linked field, an \bt_int_field, indicates the variant field's
+    current selected field.
+  </dd>
+</dl>
+
+Having a linked field class is <em>optional</em>: you always set the
+field properties with a dedicated function anyway. For example, even if
+a dynamic array field is linked to a preceding length field, you must
+still set its length with bt_field_array_dynamic_set_length(). In that
+case, the value of the length field must match what you pass to
+bt_field_array_dynamic_set_length().
+
+The purpose of this feature is to eventually save space when a
+\bt_sink_comp writes trace files: if the trace format can convey that
+a preceding, existing field represents the length of a dynamic array
+field, then the sink component doesn't need to write the dynamic array
+field's length twice. This is the case of the
+<a href="https://diamon.org/ctf/">Common Trace Format</a>, for
+example.
+
+@image html darray-link.png "A dynamic array field class linked to an unsigned integer field class."
+
+To link a field class&nbsp;A to a preceding field class&nbsp;B, pass
+field class&nbsp;B when you create field class&nbsp;A. For example, pass
+the \bt_uint_fc to bt_field_class_array_dynamic_create() to create a
+\bt_darray_fc with a length field.
+
+When you call bt_stream_class_set_packet_context_field_class(),
+bt_stream_class_set_event_common_context_field_class(),
+bt_event_class_set_specific_context_field_class(), or
+bt_event_class_set_payload_field_class() with a field class containing
+a field class&nbsp;A with a linked field class&nbsp;B, the path to
+B becomes available in A. The functions to borrow this field path are:
+
+- bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
+- bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
+- bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
+
+A field path indicates how to reach a linked field from a given
+root <em>scope</em>. The available scopes are:
+
+<dl>
+  <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
+  <dd>
+    Packet context field.
+
+    See bt_packet_borrow_context_field_const().
+  </dd>
+
+  <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
+  <dd>
+    Event common context field.
+
+    See bt_event_borrow_common_context_field_const().
+  </dd>
+
+  <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
+  <dd>
+    Event specific context field.
+
+    See bt_event_borrow_specific_context_field_const().
+  </dd>
+
+  <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
+  <dd>
+    Event payload field.
+
+    See bt_event_borrow_payload_field_const().
+  </dd>
+</dl>
+
+The rules regarding field class&nbsp;A vs. field class&nbsp;B (linked
+field class) are:
+
+- If A is within a packet context field class, B must also be in the
+  same packet context field class.
+
+  See bt_stream_class_set_packet_context_field_class().
+
+- If A is within a event common context field class, B must be in one
+  of:
+
+  - The same event common context field class.
+  - The packet context field class of the same \bt_stream_cls.
+
+  See bt_stream_class_set_event_common_context_field_class().
+
+- If A is within an event specific context field class, B must be in
+  one of:
+
+  - The same event specific context field class.
+  - The event common context field class of the same stream class.
+  - The packet context field class of the same stream class.
+
+  See bt_event_class_set_specific_context_field_class().
+
+- If A is within an event payload field class, B must be in one of:
+
+  - The same event payload field class.
+  - The event specific context field class of the same \bt_ev_cls.
+  - The event common context field class of the same stream class.
+  - The packet context field class of the same stream class.
+
+  See bt_event_class_set_payload_field_class().
+
+- If both A and B are in the same scope, then:
+
+  - The lowest common ancestor field class of A and B must be a
+    \bt_struct_fc.
+
+  - B must precede A.
+
+    Considering that the members of a structure field class are ordered,
+    then B must be part of a member that's before the member which
+    contains A in their lowest common ancestor structure field class.
+
+  - The path from the lowest common ancestor structure field class of A
+    and B to A and to B must only contain structure field classes.
+
+- If A is in a different scope than B, the path from the root scope of B
+  to B must only contain structure field classes.
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_field_class bt_field_class;
+
+@brief
+    Field class.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+    Field class type enumerators.
+*/
+typedef enum bt_field_class_type {
+       /*!
+       @brief
+           \bt_c_bool_fc.
+       */
+       BT_FIELD_CLASS_TYPE_BOOL                                                = 1ULL << 0,
+
+       /*!
+       @brief
+           \bt_c_ba_fc.
+       */
+       BT_FIELD_CLASS_TYPE_BIT_ARRAY                                           = 1ULL << 1,
+
+       /*!
+       @brief
+           \bt_c_int_fc.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_INTEGER                                             = 1ULL << 2,
+
+       /*!
+       @brief
+           \bt_c_uint_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
+       */
+       BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER                                    = (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER,
+
+       /*!
+       @brief
+           \bt_c_sint_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
+       */
+       BT_FIELD_CLASS_TYPE_SIGNED_INTEGER                                      = (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER,
+
+       /*!
+       @brief
+           \bt_c_enum_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_INTEGER.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_ENUMERATION                                         = 1ULL << 5,
+
+       /*!
+       @brief
+           \bt_c_uenum_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
+       and #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER.
+       */
+       BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION                                = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER,
+
+       /*!
+       @brief
+           \bt_c_senum_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_ENUMERATION
+       and #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER.
+       */
+       BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION                                  = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_SIGNED_INTEGER,
+
+       /*!
+       @brief
+           \bt_c_real_fc.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_REAL                                                = 1ULL << 6,
+
+       /*!
+       @brief
+           Single-precision \bt_real_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
+       */
+       BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL                               = (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL,
+
+       /*!
+       @brief
+           Double-precision \bt_real_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_REAL.
+       */
+       BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL                               = (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL,
+
+       /*!
+       @brief
+           \bt_c_string_fc..
+       */
+       BT_FIELD_CLASS_TYPE_STRING                                              = 1ULL << 9,
+
+       /*!
+       @brief
+           \bt_c_struct_fc.
+       */
+       BT_FIELD_CLASS_TYPE_STRUCTURE                                           = 1ULL << 10,
+
+       /*!
+       @brief
+           \bt_c_array_fc.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_ARRAY                                               = 1ULL << 11,
+
+       /*!
+       @brief
+           \bt_c_sarray_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
+       */
+       BT_FIELD_CLASS_TYPE_STATIC_ARRAY                                        = (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY,
+
+       /*!
+       @brief
+           \bt_c_darray_fc.
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_ARRAY.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY                                       = (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY,
+
+       /*!
+       @brief
+           \bt_c_darray_fc (without a length field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
+       */
+       BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD                  = (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY,
+
+       /*!
+       @brief
+           \bt_c_darray_fc (with a length field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
+       */
+       BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD                     = (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY,
+
+       /*!
+       @brief
+           \bt_c_opt_fc.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_OPTION                                              = 1ULL << 16,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (without a selector field).
+       */
+       BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD                       = (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (with a selector field).
+
+       This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD                          = (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (with a boolean selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
+       */
+       BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD                     = (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (with an integer selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD                  = (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (with an unsigned integer selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
+       */
+       BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD         = (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (with a signed integer selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
+       */
+       BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD           = (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD,
+
+       /*!
+       @brief
+           \bt_c_var_fc.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_VARIANT                                             = 1ULL << 23,
+
+       /*!
+       @brief
+           \bt_c_var_fc (without a selector field).
+       */
+       BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD                      = (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT,
+
+       /*!
+       @brief
+           \bt_c_var_fc (with a selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_VARIANT.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD                         = (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT,
+
+       /*!
+       @brief
+           \bt_c_var_fc (with an integer selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD.
+
+       No field class has this type: use it with
+       bt_field_class_type_is().
+       */
+       BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD                 = (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (with an unsigned integer selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
+       */
+       BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD        = (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD,
+
+       /*!
+       @brief
+           \bt_c_opt_fc (with a signed integer selector field).
+
+       This type conceptually inherits
+       #BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
+       */
+       BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD          = (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD,
+
+       /*
+        * Make sure the enumeration type is a 64-bit integer in case
+        * the project needs field class types in the future.
+        *
+        * This is not part of the API.
+        */
+       __BT_FIELD_CLASS_TYPE_BIG_VALUE                                         = 1ULL << 62,
+} bt_field_class_type;
+
+/*!
+@brief
+    Returns the type enumerator of the field class \bt_p{field_class}.
+
+@param[in] field_class
+    Field class of which to get the type enumerator
+
+@returns
+    Type enumerator of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+
+@sa bt_field_class_type_is() &mdash;
+    Returns whether or not the type of a field class conceptually is a
+    given type.
+*/
+extern bt_field_class_type bt_field_class_get_type(
+               const bt_field_class *field_class);
+
+/*!
+@brief
+    Returns whether or not the field class type \bt_p{type} conceptually
+    \em is the field class type \bt_p{other_type}.
+
+For example, an \bt_uint_fc conceptually \em is an integer field class,
+so
+
+@code
+bt_field_class_type_is(BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, BT_FIELD_CLASS_TYPE_INTEGER)
+@endcode
+
+returns #BT_TRUE.
+
+@param[in] type
+    Field class type to check against \bt_p{other_type}.
+@param[in] other_type
+    Field class type against which to check \bt_p{type}.
+
+@returns
+    #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
+
+@sa bt_field_class_get_type() &mdash;
+    Returns the type enumerator of a field class.
+*/
+static inline
+bt_bool bt_field_class_type_is(const bt_field_class_type type,
+               const bt_field_class_type other_type)
+{
+       return (type & other_type) == other_type;
+}
+
+/*! @} */
+
+/*!
+@name Common property
+@{
+*/
+
+/*!
+@brief
+    Sets the user attributes of the field class \bt_p{field_class} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
+
+@note
+    When you create a field class with one of the
+    <code>bt_field_class_*_create()</code> functions, the field class's
+    initial user attributes is an empty \bt_map_val. Therefore you can
+    borrow it with bt_field_class_borrow_user_attributes() and fill it
+    directly instead of setting a new one with this function.
+
+@param[in] field_class
+    Field class of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_field_class_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a field class.
+*/
 extern void bt_field_class_set_user_attributes(
                bt_field_class *field_class, const bt_value *user_attributes);
 
-extern bt_value *bt_field_class_borrow_user_attributes(
-               bt_field_class *field_class);
+/*!
+@brief
+    Borrows the user attributes of the field class \bt_p{field_class}.
+
+See the \ref api-tir-fc-prop-user-attrs "user attributes" property.
+
+@note
+    When you create a field class with one of the
+    <code>bt_field_class_*_create()</code> functions, the field class's
+    initial user attributes is an empty \bt_map_val.
+
+@param[in] field_class
+    Field class from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{field_class} (a \bt_map_val).
+
+@bt_pre_not_null{field_class}
+
+@sa bt_field_class_set_user_attributes() &mdash;
+    Sets the user attributes of a field class.
+@sa bt_field_class_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_field_class_borrow_user_attributes(
+               bt_field_class *field_class);
+
+/*!
+@brief
+    Borrows the user attributes of the field class \bt_p{field_class}
+    (\c const version).
+
+See bt_field_class_borrow_user_attributes().
+*/
+extern const bt_value *bt_field_class_borrow_user_attributes_const(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Boolean field class
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_bool_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned boolean field class has the following
+property value:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a boolean field class.
+
+@returns
+    New boolean field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_bool_create(
+               bt_trace_class *trace_class);
+
+/*!
+@}
+*/
+
+/*!
+@name Bit array field class
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_ba_fc with the length \bt_p{length} from the trace
+    class \bt_p{trace_class}.
+
+On success, the returned bit array field class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-ba-prop-len "Length"
+    <td>\bt_p{length}
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a bit array field class.
+@param[in] length
+    Length (number of bits) of the instances of the bit array field
+    class to create.
+
+@returns
+    New bit array field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@pre
+    0 < \bt_p{length} ≤ 64.
+*/
+extern bt_field_class *bt_field_class_bit_array_create(
+               bt_trace_class *trace_class, uint64_t length);
+
+/*!
+@brief
+    Returns the length of the \bt_ba_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-ba-prop-len "length" property.
+
+@param[in] field_class
+    Bit array field class of which to get the length.
+
+@returns
+    Length of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_ba_fc{field_class}
+*/
+extern uint64_t bt_field_class_bit_array_get_length(
+               const bt_field_class *field_class);
+
+/*!
+@}
+*/
+
+/*!
+@name Integer field class
+@{
+*/
+
+/*!
+@brief
+    Sets the field value range of the \bt_int_fc \bt_p{field_class}
+    to \bt_p{n}.
+
+See the \ref api-tir-fc-int-prop-size "field value range" property.
+
+@param[in] field_class
+    Integer field class of which to set the field value range to
+    \bt_p{n}.
+@param[in] n
+    @parblock
+    \em N in:
+
+    <dl>
+      <dt>Unsigned integer field class</dt>
+      <dd>[0,&nbsp;2<sup><em>N</em></sup>&nbsp;-&nbsp;1]</dd>
+
+      <dt>Signed integer field class</dt>
+      <dd>[-2<sup><em>N</em></sup>,&nbsp;2<sup><em>N</em></sup>&nbsp;-&nbsp;1]</dd>
+    </dl>
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_int_fc{field_class}
+@pre
+    \bt_p{n} ⩽ 64.
+
+@sa bt_field_class_integer_get_field_value_range() &mdash;
+    Returns the field value range of an integer field class.
+*/
+extern void bt_field_class_integer_set_field_value_range(
+               bt_field_class *field_class, uint64_t n);
+
+/*!
+@brief
+    Returns the field value range of the \bt_int_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-int-prop-size "field value range" property.
+
+@param[in] field_class
+    Integer field class of which to get the field value range.
+
+@returns
+    @parblock
+    Field value range of \bt_p{field_class}, that is, \em N in:
+
+    <dl>
+      <dt>Unsigned integer field class</dt>
+      <dd>[0,&nbsp;2<sup><em>N</em></sup>&nbsp;-&nbsp;1]</dd>
+
+      <dt>Signed integer field class</dt>
+      <dd>[-2<sup><em>N</em></sup>,&nbsp;2<sup><em>N</em></sup>&nbsp;-&nbsp;1]</dd>
+    </dl>
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_int_fc{field_class}
+
+@sa bt_field_class_integer_set_field_value_range() &mdash;
+    Sets the field value range of an integer field class.
+*/
+extern uint64_t bt_field_class_integer_get_field_value_range(
+               const bt_field_class *field_class);
+
+/*!
+@brief
+    Integer field class preferred display bases.
+*/
+typedef enum bt_field_class_integer_preferred_display_base {
+       /*!
+       @brief
+           Binary (2).
+       */
+       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY            = 2,
+
+       /*!
+       @brief
+           Octal (8).
+       */
+       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL             = 8,
+
+       /*!
+       @brief
+           Decimal (10).
+       */
+       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL           = 10,
+
+       /*!
+       @brief
+           Hexadecimal (16).
+       */
+       BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL       = 16,
+} bt_field_class_integer_preferred_display_base;
+
+/*!
+@brief
+    Sets the preferred display base of the \bt_int_fc \bt_p{field_class}
+    to \bt_p{preferred_display_base}.
+
+See the \ref api-tir-fc-int-prop-base "preferred display base" property.
+
+@param[in] field_class
+    Integer field class of which to set the preferred display base to
+    \bt_p{preferred_display_base}.
+@param[in] preferred_display_base
+    New preferred display base of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_int_fc{field_class}
+
+@sa bt_field_class_integer_get_preferred_display_base() &mdash;
+    Returns the preferred display base of an integer field class.
+*/
+extern void bt_field_class_integer_set_preferred_display_base(
+               bt_field_class *field_class,
+               bt_field_class_integer_preferred_display_base preferred_display_base);
+
+/*!
+@brief
+    Returns the preferred display base of the \bt_int_fc
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-int-prop-base "preferred display base" property.
+
+@param[in] field_class
+    Integer field class of which to get the preferred display base.
+
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY
+    2 (binary)
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL
+    8 (octal)
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+    10 (decimal)
+@retval #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL
+    16 (hexadecimal)
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_int_fc{field_class}
+
+@sa bt_field_class_integer_set_preferred_display_base() &mdash;
+    Sets the preferred display base of an integer field class.
+*/
+extern bt_field_class_integer_preferred_display_base
+bt_field_class_integer_get_preferred_display_base(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Unsigned integer field class
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_uint_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned unsigned integer field class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-int-prop-size "Field value range"
+    <td>[0,&nbsp;2<sup>64</sup>&nbsp;-&nbsp;1]
+  <tr>
+    <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+    <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create an unsigned integer field class.
+
+@returns
+    New unsigned integer field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_integer_unsigned_create(
+               bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Signed integer field class
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_sint_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned signed integer field class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-int-prop-size "Field value range"
+    <td>[-2<sup>63</sup>,&nbsp;2<sup>63</sup>&nbsp;-&nbsp;1]
+  <tr>
+    <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+    <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a signed integer field class.
+
+@returns
+    New signed integer field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_integer_signed_create(
+               bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Single-precision real field class
+@{
+*/
+
+/*!
+@brief
+    Creates a single-precision \bt_real_fc from the trace class
+    \bt_p{trace_class}.
+
+On success, the returned single-precision real field class has the
+following property value:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a single-preicision real
+    field class.
+
+@returns
+    New single-precision real field class reference, or \c NULL on
+    memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_real_single_precision_create(
+               bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Double-precision real field class
+@{
+*/
+
+/*!
+@brief
+    Creates a double-precision \bt_real_fc from the trace class
+    \bt_p{trace_class}.
+
+On success, the returned double-precision real field class has the
+following property value:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a double-preicision real
+    field class.
+
+@returns
+    New double-precision real field class reference, or \c NULL on
+    memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_real_double_precision_create(
+               bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Enumeration field class
+@{
+*/
+
+/*!
+@brief
+    Array of \c const \bt_enum_fc labels.
+
+Returned by bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
+and bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+*/
+typedef char const * const *bt_field_class_enumeration_mapping_label_array;
+
+/*!
+@brief
+    Status codes for
+    bt_field_class_enumeration_unsigned_get_mapping_labels_for_value()
+    and
+    bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+*/
+typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_class_enumeration_get_mapping_labels_for_value_status;
+
+/*!
+@brief
+    Status codes for bt_field_class_enumeration_unsigned_add_mapping()
+    and bt_field_class_enumeration_signed_add_mapping().
+*/
+typedef enum bt_field_class_enumeration_add_mapping_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_class_enumeration_add_mapping_status;
+
+/*! @} */
+
+/*!
+@name Enumeration field class mapping
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_enumeration_mapping bt_field_class_enumeration_mapping;
+
+@brief
+    Enumeration field class mapping.
+*/
+
+/*!
+@brief
+    Returns the number of mappings contained in the \bt_enum_fc
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+    Enumeration field class of which to get the number of contained
+    mappings.
+
+@returns
+    Number of contained mappings in \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_enum_fc{field_class}
+*/
+extern uint64_t bt_field_class_enumeration_get_mapping_count(
+               const bt_field_class *field_class);
+
+/*!
+@brief
+    Returns the label of the \bt_enum_fc mapping \bt_p{mapping}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+    Enumeration field class mapping of which to get the label.
+
+@returns
+    @parblock
+    Label of \bt_p{mapping}.
+
+    The returned pointer remains valid as long as \bt_p{mapping} exists.
+    @endparblock
+
+@bt_pre_not_null{mapping}
+*/
+extern const char *bt_field_class_enumeration_mapping_get_label(
+               const bt_field_class_enumeration_mapping *mapping);
+
+/*! @} */
+
+/*!
+@name Unsigned enumeration field class
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_uenum_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned unsigned enumeration field class has the
+following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-int-prop-size "Field value range"
+    <td>[0,&nbsp;2<sup>64</sup>&nbsp;-&nbsp;1]
+  <tr>
+    <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+    <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+  <tr>
+    <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create an unsigned enumeration field
+    class.
+
+@returns
+    New unsigned enumeration field class reference, or \c NULL on memory
+    error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_enumeration_unsigned_create(
+               bt_trace_class *trace_class);
+
+/*!
+@brief
+    Adds a mapping to the \bt_uenum_fc \bt_p{field_class} having the
+    label \bt_p{label} and the unsigned integer ranges \bt_p{ranges}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+    Unsigned enumeration field class to which to add a mapping having
+    the label \bt_p{label} and the integer ranges \bt_p{ranges}.
+@param[in] label
+    Label of the mapping to add to \bt_p{field_class} (copied).
+@param[in] ranges
+    Unsigned integer ranges of the mapping to add to
+    \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@bt_pre_not_null{label}
+@pre
+    \bt_p{field_class} has no mapping with the label \bt_p{label}.
+@bt_pre_not_null{ranges}
+@pre
+    \bt_p{ranges} contains one or more unsigned integer ranges.
+*/
+extern bt_field_class_enumeration_add_mapping_status
+bt_field_class_enumeration_unsigned_add_mapping(
+               bt_field_class *field_class, const char *label,
+               const bt_integer_range_set_unsigned *ranges);
+
+/*!
+@brief
+    Borrows the mapping at index \bt_p{index} from the
+    \bt_uenum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+    Unsigned enumeration field class from which to borrow the mapping at
+    index \bt_p{index}.
+@param[in] index
+    Index of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the mapping of
+    \bt_p{field_class} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@pre
+    \bt_p{index} is less than the number of mappings in
+    \bt_p{field_class} (as returned by
+    bt_field_class_enumeration_get_mapping_count()).
+
+@sa bt_field_class_enumeration_get_mapping_count() &mdash;
+    Returns the number of mappings contained in an
+    enumeration field class.
+*/
+extern const bt_field_class_enumeration_unsigned_mapping *
+bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const(
+               const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the mapping having the label \bt_p{label} from the
+    \bt_uenum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+If there's no mapping having the label \bt_p{label} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+    Unsigned enumeration field class from which to borrow the mapping
+    having the label \bt_p{label}.
+@param[in] label
+    Label of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the mapping of
+    \bt_p{field_class} having the label \bt_p{label}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@bt_pre_not_null{label}
+*/
+extern const bt_field_class_enumeration_unsigned_mapping *
+bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const(
+               const bt_field_class *field_class, const char *label);
+
+/*!
+@brief
+    Returns an array of all the labels of the mappings of the
+    \bt_uenum_fc \bt_p{field_class} of which the \bt_p_uint_rg contain
+    the integral value \bt_p{value}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+This function sets \bt_p{*labels} to the resulting array and
+\bt_p{*count} to the number of labels in \bt_p{*labels}.
+
+On success, if there's no mapping ranges containing the value
+\bt_p{value}, \bt_p{*count} is 0.
+
+@param[in] field_class
+    Unsigned enumeration field class from which to get the labels of the
+    mappings of which the ranges contain \bt_p{value}.
+@param[in] value
+    Value for which to get the mapped labels in \bt_p{field_class}.
+@param[out] labels
+    @parblock
+    <strong>On success</strong>, \bt_p{*labels}
+    is an array of labels of the mappings of \bt_p{field_class}
+    containing \bt_p{value}.
+
+    The number of labels in \bt_p{*labels} is \bt_p{*count}.
+
+    The array is owned by \bt_p{field_class} and remains valid as long
+    as \bt_p{field_class} is not modified.
+    @endparblock
+@param[out] count
+    <strong>On success</strong>, \bt_p{*count} is the number of labels
+    in \bt_p{*labels} (can be 0).
+
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_uenum_fc{field_class}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_class_enumeration_get_mapping_labels_for_value_status
+bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
+               const bt_field_class *field_class, uint64_t value,
+               bt_field_class_enumeration_mapping_label_array *labels,
+               uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Unsigned enumeration field class mapping
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_enumeration_unsigned_mapping bt_field_class_enumeration_unsigned_mapping;
+
+@brief
+    Unsigned enumeration field class mapping.
+*/
+
+/*!
+@brief
+    Borrows the \bt_p_uint_rg from the \bt_uenum_fc mapping
+    \bt_p{mapping}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+    Unsigned enumeration field class mapping from which to borrow the
+    unsigned integer ranges.
+
+@returns
+    Unsigned integer ranges of \bt_p{mapping}.
+
+@bt_pre_not_null{mapping}
+*/
+extern const bt_integer_range_set_unsigned *
+bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const(
+               const bt_field_class_enumeration_unsigned_mapping *mapping);
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_uenum_fc mapping
+    \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
+    type.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+    @parblock
+    Unsigned enumeration field class mapping to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{mapping} as a common enumeration field class mapping.
+*/
+static inline
+const bt_field_class_enumeration_mapping *
+bt_field_class_enumeration_unsigned_mapping_as_mapping_const(
+               const bt_field_class_enumeration_unsigned_mapping *mapping)
+{
+       return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping);
+}
+
+/*! @} */
+
+/*!
+@name Signed enumeration field class
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_senum_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned signed enumeration field class has the
+following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-int-prop-size "Field value range"
+    <td>[-2<sup>63</sup>,&nbsp;2<sup>63</sup>&nbsp;-&nbsp;1]
+  <tr>
+    <td>\ref api-tir-fc-int-prop-base "Preferred display base"
+    <td>#BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL
+  <tr>
+    <td>\ref api-tir-fc-enum-prop-mappings "Mappings"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a signed enumeration field
+    class.
+
+@returns
+    New signed enumeration field class reference, or \c NULL on memory
+    error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_enumeration_signed_create(
+               bt_trace_class *trace_class);
+
+/*!
+@brief
+    Adds a mapping to the \bt_senum_fc \bt_p{field_class} having the
+    label \bt_p{label} and the \bt_p_sint_rg \bt_p{ranges}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+    Signed enumeration field class to which to add a mapping having
+    the label \bt_p{label} and the integer ranges \bt_p{ranges}.
+@param[in] label
+    Label of the mapping to add to \bt_p{field_class} (copied).
+@param[in] ranges
+    Signed integer ranges of the mapping to add to
+    \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_senum_fc{field_class}
+@bt_pre_not_null{label}
+@pre
+    \bt_p{field_class} has no mapping with the label \bt_p{label}.
+@bt_pre_not_null{ranges}
+@pre
+    \bt_p{ranges} contains one or more signed integer ranges.
+*/
+extern bt_field_class_enumeration_add_mapping_status
+bt_field_class_enumeration_signed_add_mapping(
+               bt_field_class *field_class, const char *label,
+               const bt_integer_range_set_signed *ranges);
+
+/*!
+@brief
+    Borrows the mapping at index \bt_p{index} from the
+    \bt_senum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] field_class
+    Signed enumeration field class from which to borrow the mapping at
+    index \bt_p{index}.
+@param[in] index
+    Index of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the mapping of
+    \bt_p{field_class} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_senum_fc{field_class}
+@pre
+    \bt_p{index} is less than the number of mappings in
+    \bt_p{field_class} (as returned by
+    bt_field_class_enumeration_get_mapping_count()).
+
+@sa bt_field_class_enumeration_get_mapping_count() &mdash;
+    Returns the number of mappings contained in an
+    enumeration field class.
+*/
+extern const bt_field_class_enumeration_signed_mapping *
+bt_field_class_enumeration_signed_borrow_mapping_by_index_const(
+               const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the mapping having the label \bt_p{label} from the
+    \bt_senum_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+If there's no mapping having the label \bt_p{label} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+    Signed enumeration field class from which to borrow the mapping
+    having the label \bt_p{label}.
+@param[in] label
+    Label of the mapping to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the mapping of
+    \bt_p{field_class} having the label \bt_p{label}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_senum_fc{field_class}
+@bt_pre_not_null{label}
+*/
+extern const bt_field_class_enumeration_signed_mapping *
+bt_field_class_enumeration_signed_borrow_mapping_by_label_const(
+               const bt_field_class *field_class, const char *label);
+
+/*!
+@brief
+    Returns an array of all the labels of the mappings of the
+    \bt_senum_fc \bt_p{field_class} of which the \bt_p_sint_rg contain
+    the integral value \bt_p{value}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+This function sets \bt_p{*labels} to the resulting array and
+\bt_p{*count} to the number of labels in \bt_p{*labels}.
+
+On success, if there's no mapping ranges containing the value
+\bt_p{value}, \bt_p{*count} is 0.
+
+@param[in] field_class
+    Signed enumeration field class from which to get the labels of the
+    mappings of which the ranges contain \bt_p{value}.
+@param[in] value
+    Value for which to get the mapped labels in \bt_p{field_class}.
+@param[out] labels
+    @parblock
+    <strong>On success</strong>, \bt_p{*labels}
+    is an array of labels of the mappings of \bt_p{field_class}
+    containing \bt_p{value}.
+
+    The number of labels in \bt_p{*labels} is \bt_p{*count}.
+
+    The array is owned by \bt_p{field_class} and remains valid as long
+    as \bt_p{field_class} is not modified.
+    @endparblock
+@param[out] count
+    <strong>On success</strong>, \bt_p{*count} is the number of labels
+    in \bt_p{*labels} (can be 0).
+
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_senum_fc{field_class}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_class_enumeration_get_mapping_labels_for_value_status
+bt_field_class_enumeration_signed_get_mapping_labels_for_value(
+               const bt_field_class *field_class, int64_t value,
+               bt_field_class_enumeration_mapping_label_array *labels,
+               uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Signed enumeration field class mapping
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_enumeration_signed_mapping bt_field_class_enumeration_signed_mapping;
+
+@brief
+    Signed enumeration field class mapping.
+*/
+
+/*!
+@brief
+    Borrows the \bt_p_sint_rg from the \bt_senum_fc mapping
+    \bt_p{mapping}.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+    Signed enumeration field class mapping from which to borrow the
+    signed integer ranges.
+
+@returns
+    Signed integer ranges of \bt_p{mapping}.
+
+@bt_pre_not_null{mapping}
+*/
+extern const bt_integer_range_set_signed *
+bt_field_class_enumeration_signed_mapping_borrow_ranges_const(
+               const bt_field_class_enumeration_signed_mapping *mapping);
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_senum_fc mapping
+    \bt_p{mapping} to the common #bt_field_class_enumeration_mapping
+    type.
+
+See the \ref api-tir-fc-enum-prop-mappings "mappings" property.
+
+@param[in] mapping
+    @parblock
+    Signed enumeration field class mapping to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{mapping} as a common enumeration field class mapping.
+*/
+static inline
+const bt_field_class_enumeration_mapping *
+bt_field_class_enumeration_signed_mapping_as_mapping_const(
+               const bt_field_class_enumeration_signed_mapping *mapping)
+{
+       return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping);
+}
+
+/*! @} */
+
+/*!
+@name String field class
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_string_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned string field class has the following property
+value:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a string field class.
+
+@returns
+    New string field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_string_create(
+               bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Array field class
+@{
+*/
+
+/*!
+@brief
+    Borrows the element field class from the \bt_array_fc
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-array-prop-elem-fc "element field class"
+property.
+
+@param[in] field_class
+    Array field class from which to borrow the element field class.
+
+@returns
+    Element field class of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_array_fc{field_class}
+
+@sa bt_field_class_array_borrow_element_field_class_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class *bt_field_class_array_borrow_element_field_class(
+               bt_field_class *field_class);
+
+/*!
+@brief
+    Borrows the element field class from the \bt_array_fc
+    \bt_p{field_class} (\c const version).
+
+See bt_field_class_array_borrow_element_field_class().
+*/
+extern const bt_field_class *
+bt_field_class_array_borrow_element_field_class_const(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Static array field class
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_sarray_fc having the element field class
+    \bt_p{element_field_class} and the length \bt_p{length} from the
+    trace class \bt_p{trace_class}.
+
+On success, the returned static array field class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
+    <td>\bt_p{element_field_class}
+  <tr>
+    <td>\ref api-tir-fc-sarray-prop-len "Length"
+    <td>\bt_p{length}
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a static array field class.
+@param[in] element_field_class
+    Class of the element fields of the instances of the static array
+    field class to create.
+@param[in] length
+    Length of the instances of the static array field class to create.
+
+@returns
+    New static array field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{element_field_class}
+bt_pre_fc_not_in_tc{element_field_class}
+
+@bt_post_success_frozen{element_field_class}
+*/
+extern bt_field_class *bt_field_class_array_static_create(
+               bt_trace_class *trace_class,
+               bt_field_class *element_field_class, uint64_t length);
+
+/*!
+@brief
+    Returns the length of the \bt_sarray_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-sarray-prop-len "length" property.
+
+@param[in] field_class
+    Static array field class of which to get the length.
+
+@returns
+    Length of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_sarray_fc{field_class}
+*/
+extern uint64_t bt_field_class_array_static_get_length(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Dynamic array field class
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_darray_fc having the element field class
+    \bt_p{element_field_class} from the trace class \bt_p{trace_class}.
+
+If \bt_p{length_field_class} is not \c NULL, then the created dynamic
+array field class has a linked length field class.
+See
+\ref api-tir-fc-link "Field classes with links to other field classes"
+to learn more.
+
+On success, the returned dynamic array field class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
+    <td>\bt_p{element_field_class}
+  <tr>
+    <td>\ref api-tir-fc-darray-prop-len-fp "Length field path"
+    <td>
+      \em None (if \bt_p{length_field_class} is not \c NULL, this
+      property becomes available when the returned field class becomes
+      part of an \bt_ev_cls or of a \bt_stream_cls)
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a dynamic array field class.
+@param[in] element_field_class
+    Class of the element fields of the instances of the dynamic array
+    field class to create.
+@param[in] length_field_class
+    @parblock
+    Linked length field class of the dynamic array field class to
+    create.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    New dynamic array field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{element_field_class}
+@bt_pre_fc_not_in_tc{element_field_class}
+@pre
+    <strong>If \bt_p{length_field_class} is not \c NULL</strong>,
+    \bt_p{length_field_class} is an \bt_uint_fc.
+
+@bt_post_success_frozen{element_field_class}
+@bt_post_success_frozen{length_field_class}
+*/
+extern bt_field_class *bt_field_class_array_dynamic_create(
+               bt_trace_class *trace_class,
+               bt_field_class *element_field_class,
+               bt_field_class *length_field_class);
+
+/*! @} */
+
+/*!
+@name Dynamic array field class with length field
+@{
+*/
+
+/*!
+@brief
+    Borrows the length field path from the \bt_darray_fc (with a length
+    field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
+
+This property is only available when a \bt_struct_fc containing
+(recursively) \bt_p{field_class} is passed to one of:
+
+- bt_stream_class_set_packet_context_field_class()
+- bt_stream_class_set_event_common_context_field_class()
+- bt_event_class_set_specific_context_field_class()
+- bt_event_class_set_payload_field_class()
+
+In the meantime, this function returns \c NULL.
+
+@param[in] field_class
+    Dynamic array field class from which to borrow the length
+    field path.
+
+@returns
+    Length field path of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_darray_wl_fc{field_class}
+*/
+extern const bt_field_path *
+bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Structure field class
+@{
+*/
+
+/*!
+@brief
+    Creates a \bt_struct_fc from the trace class \bt_p{trace_class}.
+
+On success, the returned structure field class has the following
+property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-struct-prop-members "Members"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create a structure field class.
+
+@returns
+    New structure field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+*/
+extern bt_field_class *bt_field_class_structure_create(
+    bt_trace_class *trace_class);
+
+/*!
+@brief
+    Status codes for bt_field_class_structure_append_member().
+*/
+typedef enum bt_field_class_structure_append_member_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK    = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_class_structure_append_member_status;
+
+/*!
+@brief
+    Appends a member to the \bt_struct_fc \bt_p{field_class} having the
+    name \bt_p{name} and the field class \bt_p{member_field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] field_class
+    Structure field class to which to append a member having
+    the name \bt_p{name} and the field class \bt_p{member_field_class}.
+@param[in] name
+    Name of the member to append to \bt_p{field_class} (copied).
+@param[in] member_field_class
+    Field class of the member to append to \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+    \bt_p{field_class} has no member with the name \bt_p{name}.
+@bt_pre_not_null{name}
+@bt_pre_not_null{member_field_class}
+@bt_pre_fc_not_in_tc{member_field_class}
+
+@bt_post_success_frozen{member_field_class}
+*/
+extern bt_field_class_structure_append_member_status
+bt_field_class_structure_append_member(
+    bt_field_class *field_class,
+    const char *name, bt_field_class *member_field_class);
+
+/*!
+@brief
+    Returns the number of members contained in the \bt_struct_fc
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] field_class
+    Structure field class of which to get the number of contained
+    members.
+
+@returns
+    Number of contained members in \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+*/
+extern uint64_t bt_field_class_structure_get_member_count(
+    const bt_field_class *field_class);
+
+/*!
+@brief
+    Borrows the member at index \bt_p{index} from the
+    \bt_struct_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] field_class
+    Structure field class from which to borrow the member at
+    index \bt_p{index}.
+@param[in] index
+    Index of the member to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the member of
+    \bt_p{field_class} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+    \bt_p{index} is less than the number of members in
+    \bt_p{field_class} (as returned by
+    bt_field_class_structure_get_member_count()).
+
+@sa bt_field_class_structure_get_member_count() &mdash;
+    Returns the number of members contained in a structure field class.
+@sa bt_field_class_structure_borrow_member_by_index_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_index(
+    bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the member at index \bt_p{index} from the
+    \bt_struct_fc \bt_p{field_class} (\c const version).
+
+See bt_field_class_structure_borrow_member_by_index().
+*/
+extern const bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_index_const(
+    const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the member having the name \bt_p{name} from the
+    \bt_struct_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+If there's no member having the name \bt_p{name} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+    Structure field class from which to borrow the member having the
+    name \bt_p{name}.
+@param[in] name
+    Name of the member to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the member of
+    \bt_p{field_class} having the name \bt_p{name}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@bt_pre_not_null{name}
+
+@sa bt_field_class_structure_borrow_member_by_name_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_name(
+    bt_field_class *field_class, const char *name);
+
+/*!
+@brief
+    Borrows the member having the name \bt_p{name} from the
+    \bt_struct_fc \bt_p{field_class} (\c const version).
+
+See bt_field_class_structure_borrow_member_by_name().
+*/
+extern const bt_field_class_structure_member *
+bt_field_class_structure_borrow_member_by_name_const(
+    const bt_field_class *field_class, const char *name);
+
+/*! @} */
+
+/*!
+@name Structure field class member
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_structure_member bt_field_class_structure_member;
+
+@brief
+    Structure field class member.
+*/
+
+/*!
+@brief
+    Returns the name of the \bt_struct_fc member \bt_p{member}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] member
+    Structure field class member of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{member}.
+
+    The returned pointer remains valid as long as \bt_p{member} exists.
+    @endparblock
+
+@bt_pre_not_null{member}
+*/
+extern const char *bt_field_class_structure_member_get_name(
+    const bt_field_class_structure_member *member);
+
+/*!
+@brief
+    Borrows the field class from the \bt_struct_fc member
+    \bt_p{member}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@param[in] member
+    Structure field class member from which to borrow the field class.
+
+@returns
+    Field class of \bt_p{member}.
+
+@bt_pre_not_null{member}
+
+@sa bt_field_class_structure_member_borrow_field_class_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class *
+bt_field_class_structure_member_borrow_field_class(
+    bt_field_class_structure_member *member);
+
+/*!
+@brief
+    Borrows the field class from the \bt_struct_fc member
+    \bt_p{member} (\c const version).
+
+See bt_field_class_structure_member_borrow_field_class().
+*/
+extern const bt_field_class *
+bt_field_class_structure_member_borrow_field_class_const(
+    const bt_field_class_structure_member *member);
+
+/*!
+@brief
+    Sets the user attributes of the \bt_struct_fc member \bt_p{member}
+    to \bt_p{user_attributes}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@note
+    When you append a member to a structure field class with
+    bt_field_class_structure_append_member(), the member's
+    initial user attributes is an empty \bt_map_val. Therefore you can
+    borrow it with
+    bt_field_class_structure_member_borrow_user_attributes() and fill it
+    directly instead of setting a new one with this function.
+
+@param[in] member
+    Structure field class member of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{member}.
+
+@bt_pre_not_null{member}
+@bt_pre_hot{member}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_field_class_structure_member_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a structure field class member.
+*/
+extern void bt_field_class_structure_member_set_user_attributes(
+    bt_field_class_structure_member *member,
+    const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the \bt_struct_fc member
+    \bt_p{member}.
+
+See the \ref api-tir-fc-struct-prop-members "members" property.
+
+@note
+    When you append a member to a structure field class with
+    bt_field_class_structure_append_member(), the member's
+    initial user attributes is an empty \bt_map_val.
+
+@param[in] member
+    Structure field class member from which to borrow the user
+    attributes.
+
+@returns
+    User attributes of \bt_p{member} (a \bt_map_val).
+
+@bt_pre_not_null{member}
+
+@sa bt_field_class_structure_member_set_user_attributes() &mdash;
+    Sets the user attributes of a structure field class member.
+@sa bt_field_class_structure_member_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *
+bt_field_class_structure_member_borrow_user_attributes(
+    bt_field_class_structure_member *member);
+
+/*!
+@brief
+    Borrows the user attributes of the \bt_struct_fc member
+    \bt_p{member} (\c const version).
+
+See bt_field_class_structure_member_borrow_user_attributes().
+*/
+extern const bt_value *
+bt_field_class_structure_member_borrow_user_attributes_const(
+    const bt_field_class_structure_member *member);
+
+/*! @} */
+
+/*!
+@name Option field class
+@{
+*/
+
+/*!
+@brief
+    Borrows the optional field class from the \bt_opt_fc
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-opt-prop-fc "optional field class" property.
+
+@param[in] field_class
+    Option field class from which to borrow the optional field class.
+
+@returns
+    Optional field class of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_fc{field_class}
+
+@sa bt_field_class_option_borrow_field_class_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class *bt_field_class_option_borrow_field_class(
+               bt_field_class *field_class);
+
+/*!
+@brief
+    Borrows the optional field class from the \bt_opt_fc
+    \bt_p{field_class} (\c const version).
+
+See bt_field_class_option_borrow_field_class().
+*/
+extern const bt_field_class *
+bt_field_class_option_borrow_field_class_const(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class without a selector field
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_opt_fc (without a selector field) having the optional
+    field class \bt_p{optional_field_class} from the trace class
+    \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+    <td>\bt_p{optional_field_class}
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create an option field class.
+@param[in] optional_field_class
+    Class of the optional fields of the instances of the option field
+    class to create.
+
+@returns
+    New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+
+@bt_post_success_frozen{optional_field_class}
+*/
+extern bt_field_class *bt_field_class_option_without_selector_create(
+               bt_trace_class *trace_class,
+               bt_field_class *optional_field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with a selector field
+@{
+*/
+
+/*!
+@brief
+    Borrows the selector field path from the \bt_opt_fc (with a selector
+    field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
+
+This property is only available when a \bt_struct_fc containing
+(recursively) \bt_p{field_class} is passed to one of:
+
+- bt_stream_class_set_packet_context_field_class()
+- bt_stream_class_set_event_common_context_field_class()
+- bt_event_class_set_specific_context_field_class()
+- bt_event_class_set_payload_field_class()
+
+In the meantime, this function returns \c NULL.
+
+@param[in] field_class
+    Option field class from which to borrow the selector field path.
+
+@returns
+    Selector field path of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_ws_fc{field_class}
+*/
+extern const bt_field_path *
+bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with a boolean selector field
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_opt_fc (with a boolean selector field) having the
+    optional field class \bt_p{optional_field_class} from the trace
+    class \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+    <td>\bt_p{optional_field_class}
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
+    <td>
+      \em None (this property becomes available when the returned field
+      class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
+    <td>#BT_FALSE
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create an option field class.
+@param[in] optional_field_class
+    Class of the optional fields of the instances of the option field
+    class to create.
+@param[in] selector_field_class
+    Linked selector field class of the option field class to create.
+
+@returns
+    New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_class}
+@pre
+    \bt_p{selector_field_class} is a \bt_bool_fc.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+*/
+extern bt_field_class *bt_field_class_option_with_selector_field_bool_create(
+               bt_trace_class *trace_class,
+               bt_field_class *optional_field_class,
+               bt_field_class *selector_field_class);
+
+/*!
+@brief
+    Sets whether or not the selector of the \bt_opt_fc (with a boolean
+    selector field) \bt_p{field_class} is reversed.
+
+See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
+property.
+
+@param[in] field_class
+    Option field class of which to set whether or not its selector
+    is reversed.
+@param[in] selector_is_reversed
+    #BT_TRUE to make \bt_p{field_class} have a reversed selector.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_opt_wbs_fc{field_class}
+
+@sa bt_field_class_option_with_selector_field_bool_selector_is_reversed() &mdash;
+    Returns whether or not the selector of an option field class (with
+    a boolean selector field) is reversed.
+*/
+extern void
+bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
+               bt_field_class *field_class, bt_bool selector_is_reversed);
+
+/*!
+@brief
+    Returns whether or not the selector of the
+    \bt_opt_fc (with a boolean selector field) is reversed.
+
+See the \ref api-tir-fc-opt-prop-sel-rev "selector is reversed?"
+property.
+
+@param[in] field_class
+    Option field class of which to get whether or not its selector is
+    reversed.
+
+@returns
+    #BT_TRUE if the selector of \bt_p{field_class} is reversed.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_wbs_fc{field_class}
+
+@sa bt_field_class_option_with_selector_field_bool_set_selector_is_reversed() &mdash;
+    Sets whether or not the selector of an option field class (with
+    a boolean selector field) is reversed.
+*/
+extern bt_bool
+bt_field_class_option_with_selector_field_bool_selector_is_reversed(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with an unsigned integer selector field
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_opt_fc (with an unsigned integer selector field)
+    having the optional field class \bt_p{optional_field_class} from the
+    trace class \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+    <td>\bt_p{optional_field_class}
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
+    <td>
+      \em None (this property becomes available when the returned field
+      class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
+    <td>\bt_p{ranges}
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create an option field class.
+@param[in] optional_field_class
+    Class of the optional fields of the instances of the option field
+    class to create.
+@param[in] selector_field_class
+    Linked selector field class of the option field class to create.
+@param[in] ranges
+    Selector's unsigned integer ranges of the option field class to
+    create.
+
+@returns
+    New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_class}
+@pre
+    \bt_p{selector_field_class} is a \bt_uint_fc.
+@bt_pre_not_null{ranges}
+@pre
+    \bt_p{ranges} contains one or more \bt_p_uint_rg.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+@bt_post_success_frozen{ranges}
+*/
+extern bt_field_class *
+bt_field_class_option_with_selector_field_integer_unsigned_create(
+               bt_trace_class *trace_class,
+               bt_field_class *optional_field_class,
+               bt_field_class *selector_field_class,
+               const bt_integer_range_set_unsigned *ranges);
+
+/*!
+@brief
+    Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
+    integer selector field) \bt_p{field_class}.
+
+See the
+\ref api-tir-fc-opt-prop-uint-rs "selector's unsigned integer ranges"
+property.
+
+@param[in] field_class
+    Option field class from which to borrow the unsigned integer ranges.
+
+@returns
+    Unsigned integer ranges of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_wuis_fc{field_class}
+*/
+extern const bt_integer_range_set_unsigned *
+bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Option field class with a signed integer selector field
+@{
+*/
+
+/*!
+@brief
+    Creates an \bt_opt_fc (with a signed integer selector field)
+    having the optional field class \bt_p{optional_field_class} from the
+    trace class \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+    <td>\bt_p{optional_field_class}
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
+    <td>
+      \em None (this property becomes available when the returned field
+      class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
+  <tr>
+    <td>\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges"
+    <td>\bt_p{ranges}
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create an option field class.
+@param[in] optional_field_class
+    Class of the optional fields of the instances of the option field
+    class to create.
+@param[in] selector_field_class
+    Linked selector field class of the option field class to create.
+@param[in] ranges
+    Selector's signed integer ranges of the option field class to
+    create.
+
+@returns
+    New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_class}
+@pre
+    \bt_p{selector_field_class} is a \bt_uint_fc.
+@bt_pre_not_null{ranges}
+@pre
+    \bt_p{ranges} contains one or more \bt_p_uint_rg.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+@bt_post_success_frozen{ranges}
+*/
+extern bt_field_class *
+bt_field_class_option_with_selector_field_integer_signed_create(
+               bt_trace_class *trace_class,
+               bt_field_class *optional_field_class,
+               bt_field_class *selector_field_class,
+               const bt_integer_range_set_signed *ranges);
+
+/*!
+@brief
+    Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
+    integer selector field) \bt_p{field_class}.
 
-extern bt_field_class *bt_field_class_bool_create(
-               bt_trace_class *trace_class);
+See the
+\ref api-tir-fc-opt-prop-sint-rs "selector's signed integer ranges"
+property.
 
-extern bt_field_class *bt_field_class_bit_array_create(
-               bt_trace_class *trace_class, uint64_t length);
+@param[in] field_class
+    Option field class from which to borrow the signed integer ranges.
 
-extern bt_field_class *bt_field_class_integer_unsigned_create(
-               bt_trace_class *trace_class);
+@returns
+    Signed integer ranges of \bt_p{field_class}.
 
-extern bt_field_class *bt_field_class_integer_signed_create(
-               bt_trace_class *trace_class);
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_wsis_fc{field_class}
+*/
+extern const bt_integer_range_set_signed *
+bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const(
+               const bt_field_class *field_class);
 
-extern void bt_field_class_integer_set_field_value_range(
-               bt_field_class *field_class, uint64_t size);
+/*! @} */
 
-extern void bt_field_class_integer_set_preferred_display_base(
-               bt_field_class *field_class,
-               bt_field_class_integer_preferred_display_base base);
+/*!
+@name Variant field class
+@{
+*/
 
-extern bt_field_class *bt_field_class_real_single_precision_create(
-               bt_trace_class *trace_class);
+/*!
+@brief
+    Creates a \bt_var_fc from the trace class \bt_p{trace_class}.
 
-extern bt_field_class *bt_field_class_real_double_precision_create(
-               bt_trace_class *trace_class);
+If \bt_p{selector_field_class} is not \c NULL, then the created variant
+field class has a linked selector field class.
+See
+\ref api-tir-fc-link "Field classes with links to other field classes"
+to learn more.
 
-extern bt_field_class *bt_field_class_enumeration_unsigned_create(
-               bt_trace_class *trace_class);
+On success, the returned variant field class has the following
+property values:
 
-extern bt_field_class *bt_field_class_enumeration_signed_create(
-               bt_trace_class *trace_class);
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-fc-var-prop-sel-fp "Selector field path"
+    <td>
+      \em None (if \bt_p{selector_field_class} is not \c NULL, this
+      property becomes available when the returned field class becomes
+      part of an \bt_ev_cls or of a \bt_stream_cls)
+  <tr>
+    <td>\ref api-tir-fc-var-prop-opts "Options"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
 
-typedef enum bt_field_class_enumeration_add_mapping_status {
-       BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_FIELD_CLASS_ENUMERATION_ADD_MAPPING_STATUS_OK                = __BT_FUNC_STATUS_OK,
-} bt_field_class_enumeration_add_mapping_status;
+@param[in] trace_class
+    Trace class from which to create a variant field class.
+@param[in] selector_field_class
+    @parblock
+    Linked selector field class of the variant field class to create.
 
-extern bt_field_class_enumeration_add_mapping_status
-bt_field_class_enumeration_unsigned_add_mapping(
-               bt_field_class *field_class, const char *label,
-               const bt_integer_range_set_unsigned *range_set);
+    Can be \c NULL.
+    @endparblock
 
-extern bt_field_class_enumeration_add_mapping_status
-bt_field_class_enumeration_signed_add_mapping(
-               bt_field_class *field_class, const char *label,
-               const bt_integer_range_set_signed *range_set);
+@returns
+    New variant field class reference, or \c NULL on memory error.
 
-extern bt_field_class *bt_field_class_string_create(
-               bt_trace_class *trace_class);
+@bt_pre_not_null{trace_class}
+@pre
+    <strong>If \bt_p{selector_field_class} is not \c NULL</strong>,
+    \bt_p{selector_field_class} is an \bt_int_fc.
 
-extern bt_field_class *bt_field_class_structure_create(
-               bt_trace_class *trace_class);
+@bt_post_success_frozen{element_field_class}
+@bt_post_success_frozen{selector_field_class}
+*/
+extern bt_field_class *bt_field_class_variant_create(
+               bt_trace_class *trace_class,
+               bt_field_class *selector_field_class);
 
-typedef enum bt_field_class_structure_append_member_status {
-       BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_FIELD_CLASS_STRUCTURE_APPEND_MEMBER_STATUS_OK                = __BT_FUNC_STATUS_OK,
-} bt_field_class_structure_append_member_status;
+/*!
+@brief
+    Returns the number of options contained in the \bt_var_fc
+    \bt_p{field_class}.
 
-extern bt_field_class_structure_append_member_status
-bt_field_class_structure_append_member(
-               bt_field_class *struct_field_class,
-               const char *name, bt_field_class *field_class);
+See the \ref api-tir-fc-var-prop-opts "options" property.
 
-extern bt_field_class_structure_member *
-bt_field_class_structure_borrow_member_by_index(
+@param[in] field_class
+    Variant field class of which to get the number of contained
+    options.
+
+@returns
+    Number of contained options in \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_fc{field_class}
+*/
+extern uint64_t bt_field_class_variant_get_option_count(
+               const bt_field_class *field_class);
+
+/*!
+@brief
+    Borrows the option at index \bt_p{index} from the
+    \bt_var_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] field_class
+    Variant field class from which to borrow the option at
+    index \bt_p{index}.
+@param[in] index
+    Index of the option to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the option of
+    \bt_p{field_class} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_fc{field_class}
+@pre
+    \bt_p{index} is less than the number of options in
+    \bt_p{field_class} (as returned by
+    bt_field_class_variant_get_option_count()).
+
+@sa bt_field_class_variant_get_option_count() &mdash;
+    Returns the number of options contained in a variant field class.
+@sa bt_field_class_variant_borrow_option_by_index_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class_variant_option *
+bt_field_class_variant_borrow_option_by_index(
                bt_field_class *field_class, uint64_t index);
 
-extern bt_field_class_structure_member *
-bt_field_class_structure_borrow_member_by_name(
+/*!
+@brief
+    Borrows the option at index \bt_p{index} from the
+    \bt_var_fc \bt_p{field_class} (\c const version).
+
+See bt_field_class_variant_borrow_option_by_index().
+*/
+extern const bt_field_class_variant_option *
+bt_field_class_variant_borrow_option_by_index_const(
+               const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the option having the name \bt_p{name} from the
+    \bt_var_fc \bt_p{field_class}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+If there's no option having the name \bt_p{name} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+    Variant field class from which to borrow the option having the
+    name \bt_p{name}.
+@param[in] name
+    Name of the option to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the option of
+    \bt_p{field_class} having the name \bt_p{name}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_fc{field_class}
+@bt_pre_not_null{name}
+
+@sa bt_field_class_variant_borrow_option_by_name_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class_variant_option *
+bt_field_class_variant_borrow_option_by_name(
                bt_field_class *field_class, const char *name);
 
-extern bt_field_class *
-bt_field_class_structure_member_borrow_field_class(
-               bt_field_class_structure_member *member);
+/*!
+@brief
+    Borrows the option having the name \bt_p{name} from the
+    \bt_var_fc \bt_p{field_class} (\c const version).
 
-extern bt_value *bt_field_class_structure_member_borrow_user_attributes(
-               bt_field_class_structure_member *member);
+See bt_field_class_variant_borrow_option_by_name().
+*/
+extern const bt_field_class_variant_option *
+bt_field_class_variant_borrow_option_by_name_const(
+               const bt_field_class *field_class, const char *name);
 
-extern void bt_field_class_structure_member_set_user_attributes(
-               bt_field_class_structure_member *member,
+/*! @} */
+
+/*!
+@name Variant field class option
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_variant_option bt_field_class_variant_option;
+
+@brief
+    Variant field class option.
+*/
+
+/*!
+@brief
+    Returns the name of the \bt_var_fc option \bt_p{option}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] option
+    Variant field class option of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{option}.
+
+    The returned pointer remains valid as long as \bt_p{option} exists.
+    @endparblock
+
+@bt_pre_not_null{option}
+*/
+extern const char *bt_field_class_variant_option_get_name(
+               const bt_field_class_variant_option *option);
+
+/*!
+@brief
+    Borrows the field class from the \bt_var_fc option
+    \bt_p{option}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] option
+    Variant field class option from which to borrow the field class.
+
+@returns
+    Field class of \bt_p{option}.
+
+@bt_pre_not_null{option}
+
+@sa bt_field_class_variant_option_borrow_field_class_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field_class *bt_field_class_variant_option_borrow_field_class(
+               bt_field_class_variant_option *option);
+
+/*!
+@brief
+    Borrows the field class from the \bt_var_fc option
+    \bt_p{option} (\c const version).
+
+See bt_field_class_variant_option_borrow_field_class().
+*/
+extern const bt_field_class *
+bt_field_class_variant_option_borrow_field_class_const(
+               const bt_field_class_variant_option *option);
+
+/*!
+@brief
+    Sets the user attributes of the \bt_var_fc option \bt_p{option}
+    to \bt_p{user_attributes}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@note
+    When you append an option to a variant field class with
+    bt_field_class_variant_without_selector_append_option(),
+    bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
+    or
+    bt_field_class_variant_with_selector_field_integer_signed_append_option(),
+    the option's initial user attributes is an empty \bt_map_val.
+    Therefore you can borrow it with
+    bt_field_class_variant_option_borrow_user_attributes() and fill it
+    directly instead of setting a new one with this function.
+
+@param[in] option
+    Variant field class option of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{option}.
+
+@bt_pre_not_null{option}
+@bt_pre_hot{option}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_field_class_variant_option_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a variant field class option.
+*/
+extern void bt_field_class_variant_option_set_user_attributes(
+               bt_field_class_variant_option *option,
                const bt_value *user_attributes);
 
-extern bt_field_class *bt_field_class_array_static_create(
-               bt_trace_class *trace_class,
-               bt_field_class *elem_field_class, uint64_t length);
+/*!
+@brief
+    Borrows the user attributes of the \bt_var_fc option \bt_p{option}.
 
-extern bt_field_class *bt_field_class_array_dynamic_create(
-               bt_trace_class *trace_class,
-               bt_field_class *elem_field_class,
-               bt_field_class *length_field_class);
+See the \ref api-tir-fc-var-prop-opts "options" property.
 
-extern bt_field_class *bt_field_class_array_borrow_element_field_class(
-               bt_field_class *field_class);
+@note
+    When you append an option to a variant field class with
+    bt_field_class_variant_without_selector_append_option(),
+    bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
+    or
+    bt_field_class_variant_with_selector_field_integer_signed_append_option(),
+    the option's initial user attributes is an empty \bt_map_val.
 
-extern bt_field_class *bt_field_class_option_without_selector_create(
-               bt_trace_class *trace_class,
-               bt_field_class *content_field_class);
+@param[in] option
+    Variant field class option from which to borrow the user
+    attributes.
 
-extern bt_field_class *bt_field_class_option_with_selector_field_bool_create(
-               bt_trace_class *trace_class,
-               bt_field_class *content_field_class,
-               bt_field_class *selector_field_class);
+@returns
+    User attributes of \bt_p{option} (a \bt_map_val).
 
-extern void bt_field_class_option_with_selector_field_bool_set_selector_is_reversed(
-               bt_field_class *field_class, bt_bool selector_is_reversed);
+@bt_pre_not_null{option}
 
-extern bt_field_class *
-bt_field_class_option_with_selector_field_integer_unsigned_create(
-               bt_trace_class *trace_class,
-               bt_field_class *content_field_class,
-               bt_field_class *selector_field_class,
-               const bt_integer_range_set_unsigned *range_set);
+@sa bt_field_class_variant_option_set_user_attributes() &mdash;
+    Sets the user attributes of a variant field class option.
+@sa bt_field_class_variant_option_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_field_class_variant_option_borrow_user_attributes(
+               bt_field_class_variant_option *option);
 
-extern bt_field_class *
-bt_field_class_option_with_selector_field_integer_signed_create(
-               bt_trace_class *trace_class,
-               bt_field_class *content_field_class,
-               bt_field_class *selector_field_class,
-               const bt_integer_range_set_signed *range_set);
+/*!
+@brief
+    Borrows the user attributes of the \bt_var_fc option \bt_p{option}
+    (\c const version).
 
-extern bt_field_class *bt_field_class_option_borrow_field_class(
-               bt_field_class *field_class);
+See bt_field_class_variant_option_borrow_user_attributes().
+*/
+extern const bt_value *bt_field_class_variant_option_borrow_user_attributes_const(
+               const bt_field_class_variant_option *option);
 
-extern bt_field_class *bt_field_class_variant_create(
-               bt_trace_class *trace_class,
-               bt_field_class *selector_field_class);
+/*! @} */
+
+/*!
+@name Variant field class without a selector field
+@{
+*/
 
+/*!
+@brief
+    Status codes for
+    bt_field_class_variant_without_selector_append_option().
+*/
 typedef enum bt_field_class_variant_without_selector_append_option_status {
-       BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK                   = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_class_variant_without_selector_append_option_status;
 
+/*!
+@brief
+    Appends an option to the \bt_var_fc (without a selector field)
+    \bt_p{field_class} having the name \bt_p{name} and the
+    field class \bt_p{option_field_class}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] field_class
+    Variant field class to which to append an option having
+    the name \bt_p{name} and the field class \bt_p{option_field_class}.
+@param[in] name
+    Name of the option to append to \bt_p{field_class} (copied).
+@param[in] option_field_class
+    Field class of the option to append to \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_VARIANT_WITHOUT_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_var_wos_fc{field_class}
+@pre
+    \bt_p{field_class} has no option with the name \bt_p{name}.
+@bt_pre_not_null{name}
+@bt_pre_not_null{option_field_class}
+@bt_pre_fc_not_in_tc{option_field_class}
+
+@bt_post_success_frozen{option_field_class}
+*/
 extern bt_field_class_variant_without_selector_append_option_status
 bt_field_class_variant_without_selector_append_option(
-               bt_field_class *var_field_class, const char *name,
-               bt_field_class *field_class);
+               bt_field_class *field_class, const char *name,
+               bt_field_class *option_field_class);
+
+/*! @} */
 
+/*!
+@name Variant field class with a selector field
+@{
+*/
+
+/*!
+@brief
+    Status codes for
+    bt_field_class_variant_with_selector_field_integer_unsigned_append_option()
+    and
+    bt_field_class_variant_with_selector_field_integer_signed_append_option().
+*/
 typedef enum bt_field_class_variant_with_selector_field_integer_append_option_status {
-       BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_class_variant_with_selector_field_integer_append_option_status;
 
+/*!
+@brief
+    Borrows the selector field path from the \bt_var_fc (with a selector
+    field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-var-prop-sel-fp "selector field path" property.
+
+This property is only available when a \bt_struct_fc containing
+(recursively) \bt_p{field_class} is passed to one of:
+
+- bt_stream_class_set_packet_context_field_class()
+- bt_stream_class_set_event_common_context_field_class()
+- bt_event_class_set_specific_context_field_class()
+- bt_event_class_set_payload_field_class()
+
+In the meantime, this function returns \c NULL.
+
+@param[in] field_class
+    Variant field class from which to borrow the selector field path.
+
+@returns
+    Selector field path of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_ws_fc{field_class}
+*/
+extern const bt_field_path *
+bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
+               const bt_field_class *field_class);
+
+/*! @} */
+
+/*!
+@name Variant field class with an unsigned integer selector field
+@{
+*/
+
+/*!
+@brief
+    Appends an option to the \bt_var_fc (with an unsigned integer
+    selector field) \bt_p{field_class} having the name \bt_p{name},
+    the field class \bt_p{option_field_class}, and the
+    \bt_p_uint_rg \bt_p{ranges}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] field_class
+    Variant field class to which to append an option having
+    the name \bt_p{name}, the field class \bt_p{option_field_class},
+    and the unsigned integer ranges \bt_p{ranges}.
+@param[in] name
+    Name of the option to append to \bt_p{field_class} (copied).
+@param[in] option_field_class
+    Field class of the option to append to \bt_p{field_class}.
+@param[in] ranges
+    Unsigned integer ranges of the option to append to
+    \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_var_wuis_fc{field_class}
+@pre
+    \bt_p{field_class} has no option with the name \bt_p{name}.
+@bt_pre_not_null{name}
+@bt_pre_not_null{option_field_class}
+@bt_pre_fc_not_in_tc{option_field_class}
+@bt_pre_not_null{ŗanges}
+@pre
+    \bt_p{ranges} contains one or more unsigned integer ranges.
+@pre
+    The unsigned integer ranges in \bt_p{ranges} do not overlap
+    any unsigned integer range of any existing option in
+    \bt_p{field_class}.
+
+@bt_post_success_frozen{option_field_class}
+*/
 extern bt_field_class_variant_with_selector_field_integer_append_option_status
 bt_field_class_variant_with_selector_field_integer_unsigned_append_option(
-               bt_field_class *var_field_class, const char *name,
-               bt_field_class *field_class,
-               const bt_integer_range_set_unsigned *range_set);
+               bt_field_class *field_class, const char *name,
+               bt_field_class *option_field_class,
+               const bt_integer_range_set_unsigned *ranges);
+
+/*!
+@brief
+    Borrows the option at index \bt_p{index} from the
+    \bt_var_fc (with an unsigned integer selector field)
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] field_class
+    Variant field class from which to borrow the option at
+    index \bt_p{index}.
+@param[in] index
+    Index of the option to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the option of
+    \bt_p{field_class} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_wuis_fc{field_class}
+@pre
+    \bt_p{index} is less than the number of options in
+    \bt_p{field_class} (as returned by
+    bt_field_class_variant_get_option_count()).
+
+@sa bt_field_class_variant_get_option_count() &mdash;
+    Returns the number of options contained in a variant field class.
+*/
+extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
+bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
+               const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the option having the name \bt_p{name} from the
+    \bt_var_fc (with an unsigned integer selector field)
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+If there's no option having the name \bt_p{name} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+    Variant field class from which to borrow the option having the
+    name \bt_p{name}.
+@param[in] name
+    Name of the option to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the option of
+    \bt_p{field_class} having the name \bt_p{name}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_wuis_fc{field_class}
+@bt_pre_not_null{name}
+
+@sa bt_field_class_variant_borrow_option_by_name_const() &mdash;
+    Borrows an option by name from a variant field class.
+*/
+extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
+bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(
+               const bt_field_class *field_class, const char *name);
+
+/*! @} */
+
+/*!
+@name Variant field class (with an unsigned integer selector field) option
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option;
+
+@brief
+    Variant field class (with an unsigned integer selector field) option.
+*/
+
+/*!
+@brief
+    Borrows the \bt_p_uint_rg from the \bt_var_fc (with an unsigned
+    integer selector field) option \bt_p{option}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] option
+    Variant field class option from which to borrow the
+    unsigned integer ranges.
+
+@returns
+    Unsigned integer ranges of \bt_p{option}.
+
+@bt_pre_not_null{option}
+*/
+extern const bt_integer_range_set_unsigned *
+bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const(
+               const bt_field_class_variant_with_selector_field_integer_unsigned_option *option);
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with an
+    unsigned integer selector field) option \bt_p{option} to the
+    common #bt_field_class_variant_option type.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] option
+    @parblock
+    Variant field class option to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{option} as a common variant field class option.
+*/
+static inline
+const bt_field_class_variant_option *
+bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const(
+               const bt_field_class_variant_with_selector_field_integer_unsigned_option *option)
+{
+       return __BT_UPCAST_CONST(bt_field_class_variant_option, option);
+}
+
+/*! @} */
+
+/*!
+@name Variant field class with a signed integer selector field
+@{
+*/
+
+/*!
+@brief
+    Appends an option to the \bt_var_fc (with a signed integer
+    selector field) \bt_p{field_class} having the name \bt_p{name},
+    the field class \bt_p{option_field_class}, and the
+    \bt_p_sint_rg \bt_p{ranges}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
 
+@param[in] field_class
+    Variant field class to which to append an option having
+    the name \bt_p{name} and the field class \bt_p{option_field_class},
+    and the signed integer ranges \bt_p{ranges}.
+@param[in] name
+    Name of the option to append to \bt_p{field_class} (copied).
+@param[in] option_field_class
+    Field class of the option to append to \bt_p{field_class}.
+@param[in] ranges
+    Signed integer ranges of the option to append to
+    \bt_p{field_class}.
+
+@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_OK
+    Success.
+@retval #BT_FIELD_CLASS_VARIANT_WITH_SELECTOR_FIELD_APPEND_OPTION_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field_class}
+@bt_pre_hot{field_class}
+@bt_pre_is_var_wsis_fc{field_class}
+@pre
+    \bt_p{field_class} has no option with the name \bt_p{name}.
+@bt_pre_not_null{name}
+@bt_pre_not_null{option_field_class}
+@bt_pre_fc_not_in_tc{option_field_class}
+@bt_pre_not_null{ŗanges}
+@pre
+    \bt_p{ranges} contains one or more signed integer ranges.
+@pre
+    The signed integer ranges in \bt_p{ranges} do not overlap with
+    any signed integer range of any existing option in
+    \bt_p{field_class}.
+
+@bt_post_success_frozen{option_field_class}
+*/
 extern bt_field_class_variant_with_selector_field_integer_append_option_status
 bt_field_class_variant_with_selector_field_integer_signed_append_option(
-               bt_field_class *var_field_class, const char *name,
-               bt_field_class *field_class,
-               const bt_integer_range_set_signed *range_set);
+               bt_field_class *field_class, const char *name,
+               bt_field_class *option_field_class,
+               const bt_integer_range_set_signed *ranges);
 
-extern bt_field_class_variant_option *
-bt_field_class_variant_borrow_option_by_index(
-               bt_field_class *field_class, uint64_t index);
+/*!
+@brief
+    Borrows the option at index \bt_p{index} from the
+    \bt_var_fc (with a signed integer selector field)
+    \bt_p{field_class}.
 
-extern bt_field_class_variant_option *
-bt_field_class_variant_borrow_option_by_name(
-               bt_field_class *field_class, const char *name);
+See the \ref api-tir-fc-var-prop-opts "options" property.
 
-extern bt_field_class *bt_field_class_variant_option_borrow_field_class(
-               bt_field_class_variant_option *option);
+@param[in] field_class
+    Variant field class from which to borrow the option at
+    index \bt_p{index}.
+@param[in] index
+    Index of the option to borrow from \bt_p{field_class}.
 
-extern bt_value *bt_field_class_variant_option_borrow_user_attributes(
-               bt_field_class_variant_option *option);
+@returns
+    @parblock
+    \em Borrowed reference of the option of
+    \bt_p{field_class} at index \bt_p{index}.
 
-extern void bt_field_class_variant_option_set_user_attributes(
-               bt_field_class_variant_option *option,
-               const bt_value *user_attributes);
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_wsis_fc{field_class}
+@pre
+    \bt_p{index} is less than the number of options in
+    \bt_p{field_class} (as returned by
+    bt_field_class_variant_get_option_count()).
+
+@sa bt_field_class_variant_get_option_count() &mdash;
+    Returns the number of options contained in a variant field class.
+*/
+extern const bt_field_class_variant_with_selector_field_integer_signed_option *
+bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
+               const bt_field_class *field_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the option having the name \bt_p{name} from the
+    \bt_var_fc (with a signed integer selector field)
+    \bt_p{field_class}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+If there's no option having the name \bt_p{name} in
+\bt_p{field_class}, this function returns \c NULL.
+
+@param[in] field_class
+    Variant field class from which to borrow the option having the
+    name \bt_p{name}.
+@param[in] name
+    Name of the option to borrow from \bt_p{field_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the option of
+    \bt_p{field_class} having the name \bt_p{name}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{field_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_wsis_fc{field_class}
+@bt_pre_not_null{name}
+
+@sa bt_field_class_variant_borrow_option_by_name_const() &mdash;
+    Borrows an option by name from a variant field class.
+*/
+extern const bt_field_class_variant_with_selector_field_integer_signed_option *
+bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const(
+               const bt_field_class *field_class, const char *name);
+
+/*! @} */
+
+/*!
+@name Variant field class (with a signed integer selector field) option
+@{
+*/
+
+/*!
+@typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option;
+
+@brief
+    Variant field class (with a signed integer selector field) option.
+*/
+
+/*!
+@brief
+    Borrows the \bt_p_sint_rg from the \bt_var_fc (with a signed
+    integer selector field) option \bt_p{option}.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] option
+    Variant field class option from which to borrow the
+    signed integer ranges.
+
+@returns
+    Signed integer ranges of \bt_p{option}.
+
+@bt_pre_not_null{option}
+*/
+extern const bt_integer_range_set_signed *
+bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const(
+               const bt_field_class_variant_with_selector_field_integer_signed_option *option);
+
+/*!
+@brief
+    \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with a signed
+    integer selector field) option \bt_p{option} to the
+    common #bt_field_class_variant_option type.
+
+See the \ref api-tir-fc-var-prop-opts "options" property.
+
+@param[in] option
+    @parblock
+    Variant field class option to upcast.
+
+    Can be \c NULL.
+    @endparblock
+
+@returns
+    \bt_p{option} as a common variant field class option.
+*/
+static inline
+const bt_field_class_variant_option *
+bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const(
+               const bt_field_class_variant_with_selector_field_integer_signed_option *option)
+{
+       return __BT_UPCAST_CONST(bt_field_class_variant_option, option);
+}
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the field class \bt_p{field_class}.
+
+@param[in] field_class
+    @parblock
+    Field class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_field_class_put_ref() &mdash;
+    Decrements the reference count of a field class.
+*/
+extern void bt_field_class_get_ref(const bt_field_class *field_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the field class \bt_p{field_class}.
+
+@param[in] field_class
+    @parblock
+    Field class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_field_class_get_ref() &mdash;
+    Increments the reference count of a field class.
+*/
+extern void bt_field_class_put_ref(const bt_field_class *field_class);
+
+/*!
+@brief
+    Decrements the reference count of the field class
+    \bt_p{_field_class}, and then sets \bt_p{_field_class} to \c NULL.
+
+@param _field_class
+    @parblock
+    Field class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_field_class}
+*/
+#define BT_FIELD_CLASS_PUT_REF_AND_RESET(_field_class) \
+       do {                                            \
+               bt_field_class_put_ref(_field_class);   \
+               (_field_class) = NULL;                  \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the field class \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a field class reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_FIELD_CLASS_MOVE_REF(_dst, _src)    \
+       do {                                    \
+               bt_field_class_put_ref(_dst);   \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/trace-ir/field-const.h b/include/babeltrace2/trace-ir/field-const.h
deleted file mode 100644 (file)
index c6529df..0000000
--- a/include/babeltrace2/trace-ir/field-const.h
+++ /dev/null
@@ -1,118 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_FIELD_CONST_H
-#define BABELTRACE2_TRACE_IR_FIELD_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/trace-ir/field-class.h>
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_field_class *bt_field_borrow_class_const(
-               const bt_field *field);
-
-extern bt_field_class_type bt_field_get_class_type(
-               const bt_field *field);
-
-extern bt_bool bt_field_bool_get_value(const bt_field *field);
-
-extern uint64_t bt_field_bit_array_get_value_as_integer(
-               const bt_field *field);
-
-extern int64_t bt_field_integer_signed_get_value(const bt_field *field);
-
-extern uint64_t bt_field_integer_unsigned_get_value(
-               const bt_field *field);
-
-extern float bt_field_real_single_precision_get_value(const bt_field *field);
-
-extern double bt_field_real_double_precision_get_value(const bt_field *field);
-
-typedef enum bt_field_enumeration_get_mapping_labels_status {
-       BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK               = __BT_FUNC_STATUS_OK,
-} bt_field_enumeration_get_mapping_labels_status;
-
-extern bt_field_enumeration_get_mapping_labels_status
-bt_field_enumeration_unsigned_get_mapping_labels(const bt_field *field,
-               bt_field_class_enumeration_mapping_label_array *label_array,
-               uint64_t *count);
-
-extern bt_field_enumeration_get_mapping_labels_status
-bt_field_enumeration_signed_get_mapping_labels(const bt_field *field,
-               bt_field_class_enumeration_mapping_label_array *label_array,
-               uint64_t *count);
-
-extern const char *bt_field_string_get_value(const bt_field *field);
-
-extern uint64_t bt_field_string_get_length(const bt_field *field);
-
-extern const bt_field *
-bt_field_structure_borrow_member_field_by_index_const(
-               const bt_field *field, uint64_t index);
-
-extern const bt_field *
-bt_field_structure_borrow_member_field_by_name_const(
-               const bt_field *field, const char *name);
-
-extern uint64_t bt_field_array_get_length(const bt_field *field);
-
-extern const bt_field *
-bt_field_array_borrow_element_field_by_index_const(
-               const bt_field *field, uint64_t index);
-
-extern const bt_field *
-bt_field_option_borrow_field_const(const bt_field *field);
-
-extern uint64_t bt_field_variant_get_selected_option_index(
-               const bt_field *field);
-
-extern const bt_field *
-bt_field_variant_borrow_selected_option_field_const(
-               const bt_field *field);
-
-extern const bt_field_class_variant_option *
-bt_field_variant_borrow_selected_option_class_const(
-               const bt_field *field);
-
-extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
-bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
-               const bt_field *field);
-
-extern const bt_field_class_variant_with_selector_field_integer_signed_option *
-bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
-               const bt_field *field);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_FIELD_CONST_H */

diff --git a/include/babeltrace2/trace-ir/field-path-const.h b/include/babeltrace2/trace-ir/field-path-const.h
deleted file mode 100644 (file)
index 06dfe05..0000000
--- a/include/babeltrace2/trace-ir/field-path-const.h
+++ /dev/null
@@ -1,87 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_CONST_H
-#define BABELTRACE2_TRACE_IR_FIELD_PATH_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_field_path_item_type {
-       BT_FIELD_PATH_ITEM_TYPE_INDEX                           = 1 << 0,
-       BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT           = 1 << 1,
-       BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT          = 1 << 2,
-} bt_field_path_item_type;
-
-typedef enum bt_field_path_scope {
-       BT_FIELD_PATH_SCOPE_PACKET_CONTEXT              = 0,
-       BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT        = 1,
-       BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT      = 2,
-       BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD               = 3,
-} bt_field_path_scope;
-
-extern bt_field_path_scope bt_field_path_get_root_scope(
-               const bt_field_path *field_path);
-
-extern uint64_t bt_field_path_get_item_count(
-               const bt_field_path *field_path);
-
-extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const(
-               const bt_field_path *field_path, uint64_t index);
-
-extern bt_field_path_item_type bt_field_path_item_get_type(
-               const bt_field_path_item *field_path_item);
-
-extern uint64_t bt_field_path_item_index_get_index(
-               const bt_field_path_item *field_path_item);
-
-extern void bt_field_path_get_ref(const bt_field_path *field_path);
-
-extern void bt_field_path_put_ref(const bt_field_path *field_path);
-
-#define BT_FIELD_PATH_PUT_REF_AND_RESET(_var)          \
-       do {                                            \
-               bt_field_path_put_ref(_var);            \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_FIELD_PATH_MOVE_REF(_var_dst, _var_src)     \
-       do {                                            \
-               bt_field_path_put_ref(_var_dst);        \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_CONST_H */

diff --git a/include/babeltrace2/trace-ir/field-path.h b/include/babeltrace2/trace-ir/field-path.h
new file mode 100644 (file)
index 0000000..fdb17e7
--- /dev/null
+++ b/include/babeltrace2/trace-ir/field-path.h
@@ -0,0 +1,471 @@
+#ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H
+#define BABELTRACE2_TRACE_IR_FIELD_PATH_H
+
+/*
+ * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
+ *
+ * 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.
+ */
+
+#ifndef __BT_IN_BABELTRACE_H
+# error "Please include <babeltrace2/babeltrace.h> instead."
+#endif
+
+#include <stdint.h>
+
+#include <babeltrace2/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+@defgroup api-tir-field-path Field path
+@ingroup api-tir
+
+@brief
+    Path to a \bt_field.
+
+A <strong><em>field path</em></strong> indicates how to reach a given
+\bt_field from a given <em>root scope</em>.
+
+More specifically, a field path indicates how to reach:
+
+- The length field of a \bt_darray_field (with a length field).
+- The selector field of a \bt_opt_field (with a selector field).
+- The selector field of a \bt_var_field (with a selector field).
+
+You can borrow the field path from the \ref api-tir-fc "classes" of such
+fields with
+bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(),
+bt_field_class_option_with_selector_field_borrow_selector_field_path_const(),
+and
+bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
+Note that the field path properties of those field classes only becomes
+available when the field class becomes part of an \bt_ev_cls or of a
+\bt_stream_cls. See
+\ref api-tir-fc-link "Field classes with links to other field classes".
+
+A field path is a \ref api-tir "trace IR" metadata object.
+
+A field path is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_field_path_get_ref() and put an existing
+reference with bt_field_path_put_ref().
+
+The type of a field path is #bt_field_path.
+
+<h1>Properties</h1>
+
+A field path has the following properties:
+
+<dl>
+  <dt>
+    \anchor api-tir-field-path-prop-root
+    Root scope
+  </dt>
+  <dd>
+    Indicates from which \bt_struct_field to start a lookup.
+
+    See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
+    learn more.
+
+    Get a field path's root scope with bt_field_path_get_root_scope().
+  </dd>
+
+  <dt>
+    \anchor api-tir-field-path-prop-items
+    Items
+  </dt>
+  <dd>
+    Each item in a field path's item list indicates which action to take
+    to follow the path to the linked \bt_field.
+
+    See \ref api-tir-field-path-lookup-algo "Lookup algorithm" to
+    learn more.
+
+    Get the number of items in a field path with
+    bt_field_path_get_item_count().
+
+    Borrow an item from a field path with
+    bt_field_path_borrow_item_by_index_const(). This function
+    returns the #bt_field_path_item type.
+
+    A field path item is a \ref api-fund-unique-object "unique object":
+    it belongs to the field path which contains it.
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-field-path-lookup-algo Lookup algorithm</h1>
+
+The field resolution algorithm using a field path is:
+
+-# Use the appropriate function to set a <em>current field</em> variable
+   from the root scope (as returned by bt_field_path_get_root_scope()):
+
+   <dl>
+     <dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
+     <dd>
+       bt_packet_borrow_context_field_const().
+     </dd>
+     <dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
+     <dd>
+       bt_event_borrow_common_context_field_const().
+     </dd>
+     <dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
+     <dd>
+       bt_event_borrow_specific_context_field_const().
+     </dd>
+     <dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
+     <dd>
+       bt_event_borrow_payload_field_const().
+     </dd>
+   </dl>
+
+-# For each field path item (use bt_field_path_get_item_count()
+   and bt_field_path_borrow_item_by_index_const()), depending on
+   the item's type (as returned by bt_field_path_item_get_type()):
+
+   <dl>
+     <dt>#BT_FIELD_PATH_ITEM_TYPE_INDEX</dt>
+     <dd>
+       Call bt_field_path_item_index_get_index() to get the item's
+       index value.
+
+       Depending on the current field's class's type (as
+       returned by bt_field_get_class_type()):
+
+       <dl>
+         <dt>\bt_c_struct_fc</dt>
+         <dd>
+           Call bt_field_structure_borrow_member_field_by_index_const()
+           with the current field and with the item's index to set the
+           new current field.
+         </dd>
+
+         <dt>\bt_c_var_fc</dt>
+         <dd>
+           Call bt_field_variant_borrow_selected_option_field_const()
+           with the current field to set the new current field.
+         </dd>
+       </dl>
+     </dd>
+
+     <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT</dt>
+     <dd>
+       Call bt_field_array_borrow_element_field_by_index_const()
+       with the index of the field eventually containing the
+       field with a link (\bt_darray_field, \bt_opt_field, or
+       \bt_var_field) and the current field to set the new current
+       field.
+     </dd>
+
+     <dt>#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT</dt>
+     <dd>
+       Call bt_field_option_borrow_field_const() with the current
+       field to set the new current field.
+     </dd>
+   </dl>
+
+After applying this procedure, the current field is the linked
+field.
+*/
+
+/*! @{ */
+
+/*!
+@name Field path
+@{
+
+@typedef struct bt_field_path bt_field_path;
+
+@brief
+    Field path.
+
+*/
+
+/*!
+@brief
+    Field path scopes.
+*/
+typedef enum bt_field_path_scope {
+       /*!
+       @brief
+           Packet context.
+       */
+       BT_FIELD_PATH_SCOPE_PACKET_CONTEXT              = 0,
+
+       /*!
+       @brief
+           Event common context.
+       */
+       BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT        = 1,
+
+       /*!
+       @brief
+           Event specific context.
+       */
+       BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT      = 2,
+
+       /*!
+       @brief
+           Event payload.
+       */
+       BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD               = 3,
+} bt_field_path_scope;
+
+/*!
+@brief
+    Returns the root scope of the field path \bt_p{field_path}.
+
+See the \ref api-tir-field-path-prop-root "root scope" property.
+
+@param[in] field_path
+    Field path of which to get the root scope.
+
+@returns
+    Root scope of \bt_p{field_path}.
+
+@bt_pre_not_null{field_path}
+*/
+extern bt_field_path_scope bt_field_path_get_root_scope(
+               const bt_field_path *field_path);
+
+/*!
+@brief
+    Returns the number of items contained in the field path
+    \bt_p{field_path}.
+
+See the \ref api-tir-field-path-prop-items "items" property.
+
+@param[in] field_path
+    Field path of which to get the number of contained items.
+
+@returns
+    Number of contained items in \bt_p{field_path}.
+
+@bt_pre_not_null{field_path}
+*/
+extern uint64_t bt_field_path_get_item_count(
+               const bt_field_path *field_path);
+
+/*!
+@brief
+    Borrows the item at index \bt_p{index} from the
+    field path \bt_p{field_path}.
+
+See the \ref api-tir-field-path-prop-items "items" property.
+
+@param[in] field_path
+    Field path from which to borrow the item at index \bt_p{index}.
+@param[in] index
+    Index of the item to borrow from \bt_p{field_path}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the item of
+    \bt_p{field_path} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field_path}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{field_path}
+@pre
+    \bt_p{index} is less than the number of items in
+    \bt_p{field_path} (as returned by bt_field_path_get_item_count()).
+
+@sa bt_field_path_get_item_count() &mdash;
+    Returns the number of items contained in a field path.
+*/
+extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const(
+               const bt_field_path *field_path, uint64_t index);
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the field path \bt_p{field_path}.
+
+@param[in] field_path
+    @parblock
+    Field path of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_field_path_put_ref() &mdash;
+    Decrements the reference count of a field path.
+*/
+extern void bt_field_path_get_ref(const bt_field_path *field_path);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the field path \bt_p{field_path}.
+
+@param[in] field_path
+    @parblock
+    Field path of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_field_path_get_ref() &mdash;
+    Increments the reference count of a field path.
+*/
+extern void bt_field_path_put_ref(const bt_field_path *field_path);
+
+/*!
+@brief
+    Decrements the reference count of the field path
+    \bt_p{_field_path}, and then sets \bt_p{_field_path} to \c NULL.
+
+@param _field_path
+    @parblock
+    Field path of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_field_path}
+*/
+#define BT_FIELD_PATH_PUT_REF_AND_RESET(_field_path)   \
+       do {                                            \
+               bt_field_path_put_ref(_field_path);     \
+               (_field_path) = NULL;                   \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the field path \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a field path reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_FIELD_PATH_MOVE_REF(_dst, _src)     \
+       do {                                    \
+               bt_field_path_put_ref(_dst);    \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*!
+@name Field path item
+@{
+
+@typedef struct bt_field_path_item bt_field_path_item;
+
+@brief
+    Field path item.
+
+*/
+
+/*!
+@brief
+    Field path item type enumerators.
+*/
+typedef enum bt_field_path_item_type {
+       /*!
+       @brief
+           Index of a \bt_struct_field member or selected \bt_var_field
+           option's field.
+       */
+       BT_FIELD_PATH_ITEM_TYPE_INDEX                           = 1 << 0,
+
+       /*!
+       @brief
+           Common field of an \bt_array_field.
+       */
+       BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT           = 1 << 1,
+
+       /*!
+       @brief
+           Current field of an \bt_opt_field.
+       */
+       BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT          = 1 << 2,
+} bt_field_path_item_type;
+
+/*!
+@brief
+    Returns the type enumerator of the field path item
+    \bt_p{item}.
+
+See the \ref api-tir-field-path-prop-items "items" property.
+
+@param[in] item
+    Field path item of which to get the type enumerator
+
+@returns
+    Type enumerator of \bt_p{item}.
+
+@bt_pre_not_null{item}
+*/
+extern bt_field_path_item_type bt_field_path_item_get_type(
+               const bt_field_path_item *item);
+
+/*!
+@brief
+    Returns the index value of the index field path item
+    \bt_p{item}.
+
+See the \ref api-tir-field-path-prop-items "items" property.
+
+@param[in] item
+    Index field path item of which to get the index value.
+
+@returns
+    Index value of \bt_p{item}.
+
+@bt_pre_not_null{item}
+@pre
+    \bt_p{item} is an index field path item
+    (bt_field_path_item_get_type() returns
+    #BT_FIELD_PATH_ITEM_TYPE_INDEX).
+*/
+extern uint64_t bt_field_path_item_index_get_index(
+               const bt_field_path_item *item);
+
+/*! @} */
+
+/*! @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_H */

diff --git a/include/babeltrace2/trace-ir/field.h b/include/babeltrace2/trace-ir/field.h
index f95298deec5f75c748e1c130a1485fc4173a290a..572118eedb05c3744adc155a51d7e886a5e9fe29 100644 (file)
--- a/include/babeltrace2/trace-ir/field.h
+++ b/include/babeltrace2/trace-ir/field.h
@@ -35,79 +35,1502 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-field Fields
+@ingroup api-tir
+
+@brief
+    Containers of trace data.
+
+<strong><em>Fields</em></strong> are containers of trace data: they are
+found in \bt_p_ev and \bt_p_pkt.
+
+Fields are instances of \bt_p_fc:
+
+@image html field-class-zoom.png
+
+Borrow the class of a field with bt_field_borrow_class() and
+bt_field_borrow_class_const().
+
+Fields are \ref api-tir "trace IR" data objects.
+
+There are many types of fields. They can be divided into two main
+categories:
+
+<dl>
+  <dt>Scalar</dt>
+  <dd>
+    Fields which contain a simple value.
+
+    The scalar fields are:
+
+    - \ref api-tir-field-bool "Boolean"
+    - \ref api-tir-field-ba "Bit array"
+    - \ref api-tir-field-int "Integer" (unsigned and signed)
+    - \ref api-tir-field-enum "Enumeration" (unsigned and signed)
+    - \ref api-tir-field-real "Real" (single-precision and double-precision)
+    - \ref api-tir-field-string "String"
+  </dd>
+
+  <dt>Container</dt>
+  <dd>
+    Fields which contain other fields.
+
+    The container fields are:
+
+    - \ref api-tir-field-array "Array" (static and dynamic)
+    - \ref api-tir-field-struct "Structure"
+    - \ref api-tir-field-opt "Option"
+    - \ref api-tir-field-var "Variant"
+  </dd>
+</dl>
+
+@image html fc-to-field.png "Fields (green) are instances of field classes (orange)."
+
+You cannot directly create a field: there are no
+<code>bt_field_*_create()</code> functions. The \bt_name library
+creates fields within an \bt_ev or a \bt_pkt from \bt_p_fc.
+Therefore, to fill the payload fields of an \bt_ev, you must first
+borrow the event's existing payload \bt_struct_field with
+bt_event_borrow_payload_field() and then borrow each field, recursively,
+to set their values.
+
+The functions to borrow a field from an event or a packet are:
+
+- bt_packet_borrow_context_field() and
+  bt_packet_borrow_context_field_const()
+- bt_event_borrow_common_context_field() and
+  bt_event_borrow_common_context_field_const()
+- bt_event_borrow_specific_context_field() and
+  bt_event_borrow_specific_context_field_const()
+- bt_event_borrow_payload_field() and
+  bt_event_borrow_payload_field_const()
+
+Some fields conceptually inherit other fields, eventually
+making an inheritance hierarchy. For example, an \bt_enum_field
+\em is an \bt_int_field. Therefore, an enumeration field holds an
+integral value, just like an integer field does.
+
+The complete field inheritance hierarchy is:
+
+@image html all-fields.png
+
+This is the same inheritance hierarchy as the \bt_fc inheritance
+hierarchy.
+
+In the illustration above:
+
+- A field with a dark background is instantiated from a concrete \bt_fc,
+  which you can directly create with a dedicated
+  <code>bt_field_class_*_create()</code> function.
+
+- A field with a pale background is an \em abstract field: it's not a
+  concrete instance, but it can have properties, therefore there can be
+  functions which apply to it.
+
+  For example, bt_field_integer_signed_set_value() applies to any
+  \bt_sint_field.
+
+Fields are \ref api-fund-unique-object "unique objects": they belong
+to an \bt_ev or to a \bt_pkt.
+
+Some library functions \ref api-fund-freezing "freeze" fields on
+success. The documentation of those functions indicate this
+postcondition.
+
+All the field types share the same C type, #bt_field.
+
+Get the type enumerator of a field's class with bt_field_get_class_type().
+Get whether or not a field class type conceptually \em is a given type
+with the inline bt_field_class_type_is() function.
+
+<h1>\anchor api-tir-field-bool Boolean field</h1>
+
+A <strong><em>boolean field</em></strong> is a \bt_bool_fc instance.
+
+A boolean field contains a boolean value (#BT_TRUE or #BT_FALSE).
+
+Set the value of a boolean field with bt_field_bool_set_value().
+
+Get the value of a boolean field with bt_field_bool_get_value().
+
+<h1>\anchor api-tir-field-ba Bit array field</h1>
+
+A <strong><em>bit array field</em></strong> is a \bt_ba_fc instance.
+
+A bit array field contains a fixed-length array of bits. Its length
+is \ref api-tir-fc-ba-prop-len "given by its class".
+
+The bit array field API interprets the array as an unsigned integer
+value: the least significant bit's index is 0.
+
+For example, to get whether or not bit&nbsp;3 of a bit array field is
+set:
+
+@code
+uint64_t value = bt_field_bit_array_get_value_as_integer(field);
+
+if (value & (UINT64_C(1) << UINT64_C(3))) {
+    // Bit 3 is set
+}
+@endcode
+
+Set the bits of a bit array field with
+bt_field_bit_array_set_value_as_integer().
+
+Get the bits of a bit array field with
+bt_field_bit_array_get_value_as_integer().
+
+<h1>\anchor api-tir-field-int Integer fields</h1>
+
+<strong><em>Integer fields</em></strong> are \bt_int_fc instances.
+
+Integer fields contain integral values.
+
+An integer field is an \em abstract field. The concrete integer fields
+are:
+
+<dl>
+  <dt>Unsigned integer field</dt>
+  <dd>
+    An \bt_uint_fc instance.
+
+    An unsigned integer field contains an unsigned integral value
+    (\c uint64_t).
+
+    Set the value of an unsigned integer field with
+    bt_field_integer_unsigned_set_value().
+
+    Get the value of an unsigned integer field with
+    bt_field_integer_unsigned_get_value().
+  </dd>
+
+  <dt>Signed integer field</dt>
+  <dd>
+    A \bt_sint_fc instance.
+
+    A signed integer field contains a signed integral value (\c int64_t).
+
+    Set the value of a signed integer field with
+    bt_field_integer_signed_set_value().
+
+    Get the value of a signed integer field with
+    bt_field_integer_signed_get_value().
+  </dd>
+</dl>
+
+<h2>\anchor api-tir-field-enum Enumeration fields</h2>
+
+<strong><em>Enumeration fields</em></strong> are \bt_enum_fc instances.
+
+Enumeration fields \em are \bt_p_int_field: they contain integral
+values.
+
+An enumeration field is an \em abstract field.
+The concrete enumeration fields are:
+
+<dl>
+  <dt>Unsigned enumeration field</dt>
+  <dd>
+    An \bt_uenum_fc instance.
+
+    An unsigned enumeration field contains an unsigned integral value
+    (\c uint64_t).
+
+    Set the value of an unsigned enumeration field with
+    bt_field_integer_unsigned_set_value().
+
+    Get the value of an unsigned enumeration field with
+    bt_field_integer_unsigned_get_value().
+
+    Get all the enumeration field class labels mapped to the value of a
+    given unsigned enumeration field with
+    bt_field_enumeration_unsigned_get_mapping_labels().
+  </dd>
+
+  <dt>Signed enumeration field</dt>
+  <dd>
+    A \bt_senum_fc instance.
+
+    A signed enumeration field contains a signed integral value
+    (\c int64_t).
+
+    Set the value of a signed enumeration field with
+    bt_field_integer_signed_set_value().
+
+    Get the value of a signed enumeration field with
+    bt_field_integer_signed_get_value().
+
+    Get all the enumeration field class labels mapped to the value of a
+    given signed enumeration field with
+    bt_field_enumeration_signed_get_mapping_labels().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-field-real Real fields</h1>
+
+<strong><em>Real fields</em></strong> are \bt_real_fc instances.
+
+Real fields contain
+<a href="https://en.wikipedia.org/wiki/Real_number">real</a>
+values (\c float or \c double types).
+
+A real field is an \em abstract field. The concrete real fields are:
+
+<dl>
+  <dt>Single-precision real field</dt>
+  <dd>
+    A single-precision real field class instance.
+
+    A single-precision real field contains a \c float value.
+
+    Set the value of a single-precision real field with
+    bt_field_real_single_precision_set_value().
+
+    Get the value of a single-precision real field with
+    bt_field_real_single_precision_get_value().
+  </dd>
+
+  <dt>Double-precision real field</dt>
+  <dd>
+    A double-precision real field class instance.
+
+    A double-precision real field contains a \c double value.
+
+    Set the value of a double-precision real field with
+    bt_field_real_double_precision_set_value().
+
+    Get the value of a double-precision real field with
+    bt_field_real_double_precision_get_value().
+  </dd>
+</dl>
+
+<h1>\anchor api-tir-field-string String field</h1>
+
+A <strong><em>string field</em></strong> is a \bt_string_fc instance.
+
+A string field contains an UTF-8 string value.
+
+Set the value of a string field with
+bt_field_string_set_value().
+
+Get the value of a string field with
+bt_field_string_get_value().
+
+Get the length of a string field with
+bt_field_string_get_length().
+
+Append a string to a string field's current value with
+bt_field_string_append() and bt_field_string_append_with_length().
+
+Clear a string field with bt_field_string_clear().
+
+<h1>\anchor api-tir-field-array Array fields</h1>
+
+<strong><em>Array fields</em></strong> are \bt_array_fc instances.
+
+Array fields contain zero or more fields which have the same class.
+
+An array field is an \em abstract field. The concrete array fields are:
+
+<dl>
+  <dt>Static array field</dt>
+  <dd>
+    A \bt_sarray_fc instance.
+
+    A static array field contains a fixed number of fields. Its length
+    is \ref api-tir-fc-sarray-prop-len "given by its class".
+  </dd>
+
+  <dt>Dynamic array field class</dt>
+  <dd>
+    A \bt_darray_fc instance.
+
+    A dynamic array field contains a variable number of fields, that is,
+    each instance of the same dynamic array field class can contain a
+    different number of elements.
+
+    Set a dynamic array field's length with
+    bt_field_array_dynamic_set_length() before you borrow any of its
+    fields.
+  </dd>
+</dl>
+
+Get an array field's length with bt_field_array_get_length().
+
+Borrow a field from an array field at a given index with
+bt_field_array_borrow_element_field_by_index() and
+bt_field_array_borrow_element_field_by_index_const().
+
+<h1>\anchor api-tir-field-struct Structure field</h1>
+
+A <strong><em>structure field</em></strong> is a \bt_struct_fc instance.
+
+A structure field contains an ordered list of zero or more members. A
+structure field member contains a field: it's an instance of a structure
+field class member.
+
+Borrow a member's field from a structure field at a given index with
+bt_field_structure_borrow_member_field_by_index() and
+bt_field_structure_borrow_member_field_by_index_const().
+
+Borrow a member's field from a structure field by name with
+bt_field_structure_borrow_member_field_by_name() and
+bt_field_structure_borrow_member_field_by_name_const().
+
+<h1>\anchor api-tir-field-opt Option field</h1>
+
+An <strong><em>option field</em></strong> is an \bt_opt_fc instance.
+
+An option field either does or doesn't contain a field.
+
+Set whether or not an option field has a field with
+bt_field_option_set_has_field().
+
+Borrow the field from an option field with
+bt_field_option_borrow_field() or
+bt_field_option_borrow_field_const().
+
+<h1>\anchor api-tir-field-var Variant field</h1>
+
+A <strong><em>variant field</em></strong> is a \bt_var_fc instance.
+
+A variant field has a single selected option amongst one or more
+possible options. A variant field option contains a field: it's an
+instance of a variant field class option.
+
+Set the current option of a variant field with
+bt_field_variant_select_option_by_index().
+
+Get a variant field's selected option's index with
+bt_field_variant_get_selected_option_index().
+
+Borrow a variant field's selected option's field with
+bt_field_variant_borrow_selected_option_field() and
+bt_field_variant_borrow_selected_option_field_const().
+
+Borrow the class of a variant field's selected
+option with bt_field_variant_borrow_selected_option_class_const(),
+bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(),
+and
+bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const().
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_field bt_field;
+
+@brief
+    Field.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+    Returns the type enumerator of the \ref api-tir-fc "class" of the
+    field \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_get_type(bt_field_borrow_class(field))
+@endcode
+
+@param[in] field
+    Field of which to get the class's type enumerator
+
+@returns
+    Type enumerator of the class of \bt_p{field}.
+
+@bt_pre_not_null{field}
+
+@sa bt_field_class_get_type() &mdash;
+    Returns the type enumerator of a \bt_fc.
+*/
+extern bt_field_class_type bt_field_get_class_type(
+               const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-tir-fc "class" of the field \bt_p{field}.
+
+@param[in] field
+    Field of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{field}.
+
+@bt_pre_not_null{field}
+
+@sa bt_field_borrow_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field_class *bt_field_borrow_class(bt_field *field);
 
+/*!
+@brief
+    Borrows the \ref api-tir-fc "class" of the field \bt_p{field}
+    (\c const version).
+
+See bt_field_borrow_class().
+*/
+extern const bt_field_class *bt_field_borrow_class_const(
+               const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Boolean field
+@{
+*/
+
+/*!
+@brief
+    Sets the value of the \bt_bool_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Boolean field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_bool_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_bool_get_value() &mdash;
+    Returns the value of a boolean field.
+*/
 extern void bt_field_bool_set_value(bt_field *field, bt_bool value);
 
+/*!
+@brief
+    Returns the value of the \bt_bool_field \bt_p{field}.
+
+@param[in] field
+    Boolean field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_bool_field{field}
+
+@sa bt_field_bool_set_value() &mdash;
+    Sets the value of a boolean field.
+*/
+extern bt_bool bt_field_bool_get_value(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Bit array field
+@{
+*/
+
+/*!
+@brief
+    Sets the bits of the \bt_ba_field \bt_p{field} to the bits of
+    \bt_p{bits}.
+
+The least significant bit's index is 0.
+
+See \bt_c_ba_field to learn more.
+
+@param[in] field
+    Bit array field of which to set the bits to \bt_p{bits}.
+@param[in] bits
+    New bits of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_ba_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_bit_array_get_value_as_integer() &mdash;
+    Returns the bits of a bit array field as an integer.
+*/
 extern void bt_field_bit_array_set_value_as_integer(bt_field *field,
+               uint64_t bits);
+
+/*!
+@brief
+    Returns the bits of the \bt_ba_field \bt_p{field} as an
+    unsigned integer.
+
+The least significant bit's index is 0.
+
+See \bt_c_ba_field to learn more.
+
+@param[in] field
+    Bit array field of which to get the bits.
+
+@returns
+    Bits of \bt_p{field} as an unsigned integer.
+
+@bt_pre_not_null{field}
+@bt_pre_is_ba_field{field}
+
+@sa bt_field_bit_array_set_value_as_integer() &mdash;
+    Sets the bits of a bit array field from an integer.
+*/
+extern uint64_t bt_field_bit_array_get_value_as_integer(
+               const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Integer field
+@{
+*/
+
+/*!
+@brief
+    Sets the value of the \bt_uint_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Unsigned integer field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_uint_field{field}
+@bt_pre_hot{field}
+@pre
+    \bt_p{value} is within the
+    \ref api-tir-fc-int-prop-size "field value range" of the
+    class of \bt_p{field}.
+
+@sa bt_field_integer_unsigned_get_value() &mdash;
+    Returns the value of an unsigned integer field.
+*/
+extern void bt_field_integer_unsigned_set_value(bt_field *field,
                uint64_t value);
 
+/*!
+@brief
+    Returns the value of the \bt_uint_field \bt_p{field}.
+
+@param[in] field
+    Unsigned integer field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_uint_field{field}
+
+@sa bt_field_integer_unsigned_set_value() &mdash;
+    Sets the value of an unsigned integer field.
+*/
+extern uint64_t bt_field_integer_unsigned_get_value(
+               const bt_field *field);
+
+/*!
+@brief
+    Sets the value of the \bt_sint_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Signed integer field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sint_field{field}
+@bt_pre_hot{field}
+@pre
+    \bt_p{value} is within the
+    \ref api-tir-fc-int-prop-size "field value range" of the
+    class of \bt_p{field}.
+
+@sa bt_field_integer_signed_get_value() &mdash;
+    Returns the value of an signed integer field.
+*/
 extern void bt_field_integer_signed_set_value(bt_field *field,
                int64_t value);
 
-extern void bt_field_integer_unsigned_set_value(bt_field *field,
-               uint64_t value);
+/*!
+@brief
+    Returns the value of the \bt_sint_field \bt_p{field}.
+
+@param[in] field
+    Signed integer field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sint_field{field}
+
+@sa bt_field_integer_signed_set_value() &mdash;
+    Sets the value of an signed integer field.
+*/
+extern int64_t bt_field_integer_signed_get_value(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Enumeration field
+@{
+*/
+
+/*!
+@brief
+    Status codes for
+    bt_field_enumeration_unsigned_get_mapping_labels() and
+    bt_field_enumeration_signed_get_mapping_labels().
+*/
+typedef enum bt_field_enumeration_get_mapping_labels_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_field_enumeration_get_mapping_labels_status;
+
+/*!
+@brief
+    Returns an array of all the labels of the mappings of the
+    \ref api-tir-fc-enum "class" of the \bt_uenum_field \bt_p{field}
+    of which the \bt_p_uint_rg contain the integral value
+    of \bt_p{field}.
+
+This function returns
+
+@code
+(bt_field_enumeration_get_mapping_labels_status)
+bt_field_class_enumeration_unsigned_get_mapping_labels_for_value(
+    bt_field_borrow_class_const(field),
+    bt_field_integer_unsigned_get_value(field),
+    labels, count)
+@endcode
+
+@param[in] field
+    Unsigned enumeration field having the class from which to get the
+    labels of the mappings of which the ranges contain its
+    integral value.
+@param[out] labels
+    See
+    bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
+@param[out] count
+    See
+    bt_field_class_enumeration_unsigned_get_mapping_labels_for_value().
+
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
+    Success.
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_uenum_field{field}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_enumeration_get_mapping_labels_status
+bt_field_enumeration_unsigned_get_mapping_labels(const bt_field *field,
+               bt_field_class_enumeration_mapping_label_array *labels,
+               uint64_t *count);
+
+/*!
+@brief
+    Returns an array of all the labels of the mappings of the
+    \ref api-tir-fc-enum "class" of the \bt_senum_field \bt_p{field}
+    of which the \bt_p_sint_rg contain the integral value
+    of \bt_p{field}.
+
+This function returns
 
+@code
+(bt_field_enumeration_get_mapping_labels_status)
+bt_field_class_enumeration_signed_get_mapping_labels_for_value(
+    bt_field_borrow_class_const(field),
+    bt_field_integer_signed_get_value(field),
+    labels, count)
+@endcode
+
+@param[in] field
+    Signed enumeration field having the class from which to get the
+    labels of the mappings of which the ranges contain its
+    integral value.
+@param[out] labels
+    See
+    bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+@param[out] count
+    See
+    bt_field_class_enumeration_signed_get_mapping_labels_for_value().
+
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK
+    Success.
+@retval #BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_senum_field{field}
+@bt_pre_not_null{labels}
+@bt_pre_not_null{count}
+*/
+extern bt_field_enumeration_get_mapping_labels_status
+bt_field_enumeration_signed_get_mapping_labels(const bt_field *field,
+               bt_field_class_enumeration_mapping_label_array *labels,
+               uint64_t *count);
+
+/*! @} */
+
+/*!
+@name Real field
+@{
+*/
+
+/*!
+@brief
+    Sets the value of the \bt_sreal_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Single-precision real field of which to set the value to
+    \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sreal_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_real_single_precision_get_value() &mdash;
+    Returns the value of a single-precision real field.
+*/
 extern void bt_field_real_single_precision_set_value(bt_field *field,
                float value);
 
+/*!
+@brief
+    Returns the value of the \bt_sreal_field \bt_p{field}.
+
+@param[in] field
+    Single-precision real field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_sreal_field{field}
+
+@sa bt_field_real_single_precision_set_value() &mdash;
+    Sets the value of a single-precision real field.
+*/
+extern float bt_field_real_single_precision_get_value(const bt_field *field);
+
+/*!
+@brief
+    Sets the value of the \bt_dreal_field \bt_p{field} to
+    \bt_p{value}.
+
+@param[in] field
+    Double-precision real field of which to set the value to
+    \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_dreal_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_real_double_precision_get_value() &mdash;
+    Returns the value of a double-precision real field.
+*/
 extern void bt_field_real_double_precision_set_value(bt_field *field,
                double value);
 
+/*!
+@brief
+    Returns the value of the \bt_dreal_field \bt_p{field}.
+
+@param[in] field
+    Double-precision real field of which to get the value.
+
+@returns
+    Value of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_dreal_field{field}
+
+@sa bt_field_real_double_precision_set_value() &mdash;
+    Sets the value of a double-precision real field.
+*/
+extern double bt_field_real_double_precision_get_value(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name String field
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_field_string_set_value().
+*/
 typedef enum bt_field_string_set_value_status {
-       BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_FIELD_STRING_SET_VALUE_STATUS_OK             = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_string_set_value_status;
 
+/*!
+@brief
+    Sets the value of the \bt_string_field \bt_p{field} to
+    a copy of \bt_p{value}.
+
+@param[in] field
+    String field of which to set the value to \bt_p{value}.
+@param[in] value
+    New value of \bt_p{field} (copied).
+
+@retval #BT_FIELD_STRING_SET_VALUE_STATUS_OK
+    Success.
+@retval #BT_FIELD_STRING_SET_VALUE_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+@bt_pre_not_null{value}
+
+@sa bt_field_string_get_value() &mdash;
+    Returns the value of a string field.
+@sa bt_field_string_append() &mdash;
+    Appends a string to a string field.
+@sa bt_field_string_clear() &mdash;
+    Clears a string field.
+*/
 extern bt_field_string_set_value_status bt_field_string_set_value(
                bt_field *field, const char *value);
 
+/*!
+@brief
+    Returns the length of the \bt_string_field \bt_p{field}.
+
+@param[in] field
+    String field of which to get the length.
+
+@returns
+    Length of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+*/
+extern uint64_t bt_field_string_get_length(const bt_field *field);
+
+/*!
+@brief
+    Returns the value of the \bt_string_field \bt_p{field}.
+
+@param[in] field
+    String field of which to get the value.
+
+@returns
+    @parblock
+    Value of \bt_p{field}.
+
+    The returned pointer remains valid until \bt_p{field} is modified.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
+extern const char *bt_field_string_get_value(const bt_field *field);
+
+/*!
+@brief
+    Status codes for bt_field_string_append() and
+    bt_field_string_append_with_length().
+*/
 typedef enum bt_field_string_append_status {
-       BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_FIELD_STRING_APPEND_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_string_append_status;
 
+/*!
+@brief
+    Appends a copy of the string \bt_p{value} to the current value of
+    the \bt_string_field \bt_p{field}.
+
+@attention
+    If you didn't set the value of \bt_p{field} yet, you must call
+    bt_field_string_clear() before you call this function.
+
+@param[in] field
+    String field to which to append the string \bt_p{value}.
+@param[in] value
+    String to append to \bt_p{field} (copied).
+
+@retval #BT_FIELD_STRING_APPEND_STATUS_OK
+    Success.
+@retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+@bt_pre_not_null{value}
+
+@sa bt_field_string_append_with_length() &mdash;
+    Appends a string with a given length to a string field.
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
 extern bt_field_string_append_status bt_field_string_append(
                bt_field *field, const char *value);
 
+/*!
+@brief
+    Appends a copy of the first \bt_p{length} bytes of the string
+    \bt_p{value} to the current value of the \bt_string_field
+    \bt_p{field}.
+
+@attention
+    If you didn't set the value of \bt_p{field} yet, you must call
+    bt_field_string_clear() before you call this function.
+
+@param[in] field
+    String field to which to append the first \bt_p{length} bytes of
+    the string \bt_p{value}.
+@param[in] value
+    String of which to append the first \bt_p{length} bytes to
+    \bt_p{field} (copied).
+@param[in] length
+    Number of bytes of \bt_p{value} to append to \bt_p{field}.
+
+@retval #BT_FIELD_STRING_APPEND_STATUS_OK
+    Success.
+@retval #BT_FIELD_STRING_APPEND_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+@bt_pre_not_null{value}
+
+@sa bt_field_string_append() &mdash;
+    Appends a string to a string field.
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
 extern bt_field_string_append_status bt_field_string_append_with_length(
                bt_field *field, const char *value, uint64_t length);
 
+/*!
+@brief
+    Clears the \bt_string_field \bt_p{field}, making its value an empty
+    string.
+
+@param[in] field
+    String field to clear.
+
+@bt_pre_not_null{field}
+@bt_pre_is_string_field{field}
+@bt_pre_hot{field}
+
+@sa bt_field_string_set_value() &mdash;
+    Sets the value of a string field.
+*/
 extern void bt_field_string_clear(bt_field *field);
 
-extern bt_field *bt_field_structure_borrow_member_field_by_index(
-               bt_field *field, uint64_t index);
+/*! @} */
 
-extern bt_field *bt_field_structure_borrow_member_field_by_name(
-               bt_field *field, const char *name);
+/*!
+@name Array field
+@{
+*/
+
+/*!
+@brief
+    Returns the length of the \bt_array_field \bt_p{field}.
+
+@param[in] field
+    Array field of which to get the length.
+
+@returns
+    Length of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_array_field{field}
+*/
+extern uint64_t bt_field_array_get_length(const bt_field *field);
+
+/*!
+@brief
+    Borrows the field at index \bt_p{index} from the \bt_array_field
+    \bt_p{field}.
 
+@attention
+    If \bt_p{field} is a dynamic array field, it must have a length
+    (call bt_field_array_dynamic_set_length()) before you call this
+    function.
+
+@param[in] field
+    Array field from which to borrow the field at index \bt_p{index}.
+@param[in] index
+    Index of the field to borrow from \bt_p{field}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of \bt_p{field} at index
+    \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_array_field{field}
+@pre
+    \bt_p{index} is less than the length of \bt_p{field} (as returned by
+    bt_field_array_get_length()).
+
+@sa bt_field_array_borrow_element_field_by_index_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field *bt_field_array_borrow_element_field_by_index(
                bt_field *field, uint64_t index);
 
+/*!
+@brief
+    Borrows the field at index \bt_p{index} from the \bt_array_field
+    \bt_p{field} (\c const version).
+
+See bt_field_array_borrow_element_field_by_index().
+*/
+extern const bt_field *
+bt_field_array_borrow_element_field_by_index_const(
+               const bt_field *field, uint64_t index);
+
+/*!
+@brief
+    Status codes for bt_field_array_dynamic_set_length().
+*/
 typedef enum bt_field_array_dynamic_set_length_status {
-       BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK             = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_field_array_dynamic_set_length_status;
 
+/*!
+@brief
+    Sets the length of the \bt_darray_field \bt_p{field}.
+
+@param[in] field
+    Dynamic array field of which to set the length.
+@param[in] length
+    New length of \bt_p{field}.
+
+@retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_OK
+    Success.
+@retval #BT_FIELD_DYNAMIC_ARRAY_SET_LENGTH_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{field}
+@bt_pre_is_darray_field{field}
+@bt_pre_hot{field}
+*/
 extern bt_field_array_dynamic_set_length_status
-bt_field_array_dynamic_set_length(
-               bt_field *field, uint64_t length);
+bt_field_array_dynamic_set_length(bt_field *field, uint64_t length);
+
+/*! @} */
+
+/*!
+@name Structure field
+@{
+*/
+
+/*!
+@brief
+    Borrows the field of the member at index \bt_p{index} from the
+    \bt_struct_field \bt_p{field}.
+
+@param[in] field
+    Structure field from which to borrow the field of the member at
+    index \bt_p{index}.
+@param[in] index
+    Index of the member containing the field to borrow from
+    \bt_p{field}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of the member of \bt_p{field} at
+    index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_struct_field{field}
+@pre
+    \bt_p{index} is less than the number of members in the
+    \ref api-tir-fc-struct "class" of \bt_p{field} (as
+    returned by bt_field_class_structure_get_member_count()).
+
+@sa bt_field_structure_borrow_member_field_by_index_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field *bt_field_structure_borrow_member_field_by_index(
+               bt_field *field, uint64_t index);
+
+/*!
+@brief
+    Borrows the field of the member at index \bt_p{index} from the
+    \bt_struct_field \bt_p{field} (\c const version).
+
+See bt_field_structure_borrow_member_field_by_index().
+*/
+extern const bt_field *
+bt_field_structure_borrow_member_field_by_index_const(
+               const bt_field *field, uint64_t index);
+
+/*!
+@brief
+    Borrows the field of the member having the name \bt_p{name} from the
+    \bt_struct_field \bt_p{field}.
+
+If there's no member having the name \bt_p{name} in the
+\ref api-tir-fc-struct "class" of \bt_p{field}, this function
+returns \c NULL.
+
+@param[in] field
+    Structure field from which to borrow the field of the member having
+    the name \bt_p{name}.
+@param[in] name
+    Name of the member containing the field to borrow from \bt_p{field}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of the member of \bt_p{field}
+    having the name \bt_p{name}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_struct_field{field}
+@bt_pre_not_null{name}
+
+@sa bt_field_structure_borrow_member_field_by_name_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_field *bt_field_structure_borrow_member_field_by_name(
+               bt_field *field, const char *name);
+
+/*!
+@brief
+    Borrows the field of the member having the name \bt_p{name} from the
+    \bt_struct_field \bt_p{field} (\c const version).
+
+See bt_field_structure_borrow_member_field_by_name().
+*/
+extern const bt_field *
+bt_field_structure_borrow_member_field_by_name_const(
+               const bt_field *field, const char *name);
+
+/*! @} */
+
+/*!
+@name Option field
+@{
+*/
+
+/*!
+@brief
+    Sets whether or not the \bt_opt_field \bt_p{field}
+    has a field.
 
+@param[in] field
+    Option field of which to set whether or not it has a field.
+@param[in] has_field
+    #BT_TRUE to make \bt_p{field} have a field.
+
+@bt_pre_not_null{field}
+@bt_pre_is_opt_field{field}
+*/
 extern void bt_field_option_set_has_field(bt_field *field, bt_bool has_field);
 
+/*!
+@brief
+    Borrows the field of the \bt_opt_field \bt_p{field}.
+
+@attention
+    You must call bt_field_option_set_has_field() before you call
+    this function.
+
+If \bt_p{field} has no field, this function returns \c NULL.
+
+@param[in] field
+    Option field from which to borrow the field.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of \bt_p{field},
+    or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_opt_field{field}
+
+@sa bt_field_option_set_has_field() &mdash;
+    Sets whether or not an option field has a field.
+@sa bt_field_option_borrow_field_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field *bt_field_option_borrow_field(bt_field *field);
 
+/*!
+@brief
+    Borrows the field of the \bt_opt_field \bt_p{field}
+    (\c const version).
+
+See bt_field_option_borrow_field().
+*/
+extern const bt_field *
+bt_field_option_borrow_field_const(const bt_field *field);
+
+/*! @} */
+
+/*!
+@name Variant field
+@{
+*/
+
+/*!
+@brief
+    Status code for bt_field_variant_select_option_by_index().
+*/
 typedef enum bt_field_variant_select_option_by_index_status {
-       BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK                = __BT_FUNC_STATUS_OK,
+       /*!
+       @brief
+           Success.
+       */
+       BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK        = __BT_FUNC_STATUS_OK,
 } bt_field_variant_select_option_by_index_status;
 
+/*!
+@brief
+    Sets the selected option of the \bt_var_field \bt_p{field}
+    to the option at index \bt_p{index}.
+
+@param[in] field
+    Variant field of which to set the selected option.
+@param[in] index
+    Index of the option to set as the selected option of \bt_p{field}.
+
+@retval #BT_FIELD_VARIANT_SELECT_OPTION_STATUS_OK
+    Success.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+@pre
+    \bt_p{index} is less than the number of options in the
+    \ref api-tir-fc-var "class" of \bt_p{field} (as
+    returned by bt_field_class_variant_get_option_count()).
+*/
 extern bt_field_variant_select_option_by_index_status
 bt_field_variant_select_option_by_index(
                bt_field *field, uint64_t index);
 
+/*!
+@brief
+    Borrows the field of the selected option of the \bt_var_field
+    \bt_p{field}.
+
+@attention
+    You must call bt_field_variant_select_option_by_index() before
+    you call this function.
+
+@param[in] field
+    Variant field from which to borrow the selected option's field.
+
+@returns
+    @parblock
+    \em Borrowed reference of the field of the selected option of
+    \bt_p{field}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{field} exists.
+    @endparblock
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+
+@sa bt_field_variant_select_option_by_index() &mdash;
+    Sets a variant field's selected option.
+@sa bt_field_variant_get_selected_option_index() &mdash;
+    Returns the index of a variant field's selected option.
+@sa bt_field_variant_borrow_selected_option_field_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field *bt_field_variant_borrow_selected_option_field(
                bt_field *field);
 
+/*!
+@brief
+    Borrows the field of the selected option of the \bt_var_field
+    \bt_p{field} (\c const version).
+
+See bt_field_variant_borrow_selected_option_field().
+*/
+extern const bt_field *
+bt_field_variant_borrow_selected_option_field_const(
+               const bt_field *field);
+
+/*!
+@brief
+    Returns the index of the selected option of the \bt_var_field
+    \bt_p{field}.
+
+@param[in] field
+    Variant field of which to get the index of the selected option.
+
+@returns
+    Index of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+
+@sa bt_field_variant_borrow_selected_option_field_const() &mdash;
+    Borrows the field of a variant field's selected option.
+*/
+extern uint64_t bt_field_variant_get_selected_option_index(
+               const bt_field *field);
+
+/*!
+@brief
+    Borrows the class of the selected option of the \bt_var_field
+    \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_variant_borrow_option_by_index(
+    bt_field_variant_get_selected_option_index(field))
+@endcode
+
+@param[in] field
+    Variant field of which to get the selected option's class.
+
+@returns
+    Class of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_field{field}
+*/
+extern const bt_field_class_variant_option *
+bt_field_variant_borrow_selected_option_class_const(
+               const bt_field *field);
+
+/*!
+@brief
+    Borrows the class of the selected option of the \bt_var_field
+    (with an unsigned integer selector field) \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(
+    bt_field_variant_get_selected_option_index(field))
+@endcode
+
+@param[in] field
+    Variant field of which to get the selected option's class.
+
+@returns
+    Class of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_wuis_field{field}
+*/
+extern const bt_field_class_variant_with_selector_field_integer_unsigned_option *
+bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const(
+               const bt_field *field);
+
+/*!
+@brief
+    Borrows the class of the selected option of the \bt_var_field
+    (with a signed integer selector field) \bt_p{field}.
+
+This function returns
+
+@code
+bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(
+    bt_field_variant_get_selected_option_index(field))
+@endcode
+
+@param[in] field
+    Variant field of which to get the selected option's class.
+
+@returns
+    Class of the selected option of \bt_p{field}.
+
+@bt_pre_not_null{field}
+@bt_pre_is_var_wsis_field{field}
+*/
+extern const bt_field_class_variant_with_selector_field_integer_signed_option *
+bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const(
+               const bt_field *field);
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/trace-ir/packet-const.h b/include/babeltrace2/trace-ir/packet-const.h
deleted file mode 100644 (file)
index f3fdd2d..0000000
--- a/include/babeltrace2/trace-ir/packet-const.h
+++ /dev/null
@@ -1,67 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_PACKET_CONST_H
-#define BABELTRACE2_TRACE_IR_PACKET_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/property.h>
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_stream *bt_packet_borrow_stream_const(
-               const bt_packet *packet);
-
-extern
-const bt_field *bt_packet_borrow_context_field_const(
-               const bt_packet *packet);
-
-extern void bt_packet_get_ref(const bt_packet *packet);
-
-extern void bt_packet_put_ref(const bt_packet *packet);
-
-#define BT_PACKET_PUT_REF_AND_RESET(_var)              \
-       do {                                            \
-               bt_packet_put_ref(_var);                \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_PACKET_MOVE_REF(_var_dst, _var_src)         \
-       do {                                            \
-               bt_packet_put_ref(_var_dst);            \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_PACKET_CONST_H */

diff --git a/include/babeltrace2/trace-ir/packet.h b/include/babeltrace2/trace-ir/packet.h
index 6a310854b89545a11842c3fb4baa66e9f56e3f6f..52d110ee1372d893eb1ee1c91fccc4362771ef09 100644 (file)
--- a/include/babeltrace2/trace-ir/packet.h
+++ b/include/babeltrace2/trace-ir/packet.h
@@ -35,13 +35,306 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-pkt Packet
+@ingroup api-tir
+
+@brief
+    Trace packet.
+
+A <strong><em>packet</em></strong> is a conceptual container of
+\bt_p_ev within a \bt_stream.
+
+Some trace formats group events together within packets. This is the
+case, for example, of the
+<a href="https://diamon.org/ctf/">Common Trace Format</a>.
+
+Because a packet could contain millions of events, there are no actual
+links from a packet to its events. However, there are links from a
+packet's events to it (see bt_event_borrow_packet() and
+bt_event_borrow_packet_const()).
+
+A packet can contain a context \bt_field which is data associated to
+all the events of the packet.
+
+A packet is a \ref api-tir "trace IR" data object.
+
+A packet conceptually belongs to a \bt_stream. Borrow the stream of a
+packet with bt_packet_borrow_stream() and
+bt_packet_borrow_stream_const().
+
+Before you create a packet for a given stream, the stream's class must
+\ref api-tir-stream-cls-prop-supports-pkt "support packets".
+
+Create a packet with bt_packet_create(). You can then use this packet to
+create a \bt_pb_msg and a \bt_pe_msg.
+
+A packet is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_packet_get_ref() and put an existing
+reference with bt_packet_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" packets on
+success. The documentation of those functions indicate this
+postcondition.
+
+The type of a packet is #bt_packet.
+
+<h1>Property</h1>
+
+A packet has the following property:
+
+<dl>
+  <dt>\anchor api-tir-pkt-prop-ctx Context field</dt>
+  <dd>
+    Packet's context \bt_field.
+
+    The context of a packet contains data associated to all its
+    events.
+
+    The \ref api-tir-fc "class" of a packet's context field is set
+    at the packet's \bt_stream_cls level. See
+    bt_stream_class_set_packet_context_field_class()
+    bt_stream_class_borrow_packet_context_field_class(),
+    and bt_stream_class_borrow_packet_context_field_class_const()
+
+    Use bt_packet_borrow_context_field() and
+    bt_packet_borrow_context_field_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_packet bt_packet;
+
+@brief
+    Packet.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a packet for the \bt_stream \bt_p{stream}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))
+    @endcode
+
+    returns #BT_TRUE.
+    @endparblock
+
+On success, the returned packet has the following property value:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-pkt-prop-ctx "Context field"
+    <td>
+      Unset instance of the
+      \ref api-tir-stream-cls-prop-pc-fc "packet context field class" of
+      the \ref api-tir-stream-cls "class" of \bt_p{stream}.
+</table>
+
+@param[in] stream
+    Stream for which to create the packet.
+
+@returns
+    New packet reference, or \c NULL on memory error.
+
+@pre
+    <code>bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream))</code>
+    returns #BT_TRUE.
+*/
 extern bt_packet *bt_packet_create(const bt_stream *stream);
 
+/*! @} */
+
+/*!
+@name Stream access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_stream conceptually containing the packet
+    \bt_p{packet}.
+
+@param[in] packet
+    Packet of which to borrow the stream conceptually containing it.
+
+@returns
+    \em Borrowed reference of the stream conceptually containing
+    \bt_p{packet}.
+
+@bt_pre_not_null{packet}
+
+@sa bt_packet_borrow_stream_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_stream *bt_packet_borrow_stream(bt_packet *packet);
 
+/*!
+@brief
+    Borrows the \bt_stream conceptually containing the packet
+    \bt_p{packet} (\c const version).
+
+See bt_packet_borrow_stream().
+*/
+extern const bt_stream *bt_packet_borrow_stream_const(
+               const bt_packet *packet);
+
+/*! @} */
+
+/*!
+@name Property
+@{
+*/
+
+/*!
+@brief
+    Borrows the context \bt_field of the packet \bt_p{packet}.
+
+See the \ref api-tir-pkt-prop-ctx "context field" property.
+
+@param[in] packet
+    Packet of which to borrow the context field.
+
+@returns
+    \em Borrowed reference of the context field of
+    \bt_p{packet}, or \c NULL if none.
+
+@bt_pre_not_null{packet}
+
+@sa bt_packet_borrow_context_field_const() &mdash;
+    \c const version of this function.
+*/
 extern
 bt_field *bt_packet_borrow_context_field(bt_packet *packet);
 
+/*!
+@brief
+    Borrows the context \bt_field of the packet \bt_p{packet}
+    (\c const version).
+
+See bt_packet_borrow_context_field().
+*/
+extern
+const bt_field *bt_packet_borrow_context_field_const(
+               const bt_packet *packet);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the packet \bt_p{packet}.
+
+@param[in] packet
+    @parblock
+    Packet of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_packet_put_ref() &mdash;
+    Decrements the reference count of a packet.
+*/
+extern void bt_packet_get_ref(const bt_packet *packet);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the packet \bt_p{packet}.
+
+@param[in] packet
+    @parblock
+    Packet of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_packet_get_ref() &mdash;
+    Increments the reference count of a packet.
+*/
+extern void bt_packet_put_ref(const bt_packet *packet);
+
+/*!
+@brief
+    Decrements the reference count of the packet
+    \bt_p{_packet}, and then sets \bt_p{_packet} to \c NULL.
+
+@param _packet
+    @parblock
+    Packet of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_packet}
+*/
+#define BT_PACKET_PUT_REF_AND_RESET(_packet)           \
+       do {                                            \
+               bt_packet_put_ref(_packet);             \
+               (_packet) = NULL;                       \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the packet \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a packet reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_PACKET_MOVE_REF(_dst, _src)         \
+       do {                                    \
+               bt_packet_put_ref(_dst);        \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/trace-ir/stream-class-const.h b/include/babeltrace2/trace-ir/stream-class-const.h
deleted file mode 100644 (file)
index 7a7077b..0000000
--- a/include/babeltrace2/trace-ir/stream-class-const.h
+++ /dev/null
@@ -1,121 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_STREAM_CLASS_CONST_H
-#define BABELTRACE2_TRACE_IR_STREAM_CLASS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_value *bt_stream_class_borrow_user_attributes_const(
-               const bt_stream_class *stream_class);
-
-extern const bt_trace_class *bt_stream_class_borrow_trace_class_const(
-               const bt_stream_class *stream_class);
-
-extern const char *bt_stream_class_get_name(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_assigns_automatic_event_class_id(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_assigns_automatic_stream_id(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_supports_packets(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_packets_have_beginning_default_clock_snapshot(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_packets_have_end_default_clock_snapshot(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_supports_discarded_events(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_supports_discarded_packets(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_discarded_events_have_default_clock_snapshots(
-               const bt_stream_class *stream_class);
-
-extern bt_bool bt_stream_class_discarded_packets_have_default_clock_snapshots(
-               const bt_stream_class *stream_class);
-
-extern uint64_t bt_stream_class_get_id(
-               const bt_stream_class *stream_class);
-
-extern const bt_field_class *
-bt_stream_class_borrow_packet_context_field_class_const(
-               const bt_stream_class *stream_class);
-
-extern const bt_field_class *
-bt_stream_class_borrow_event_common_context_field_class_const(
-               const bt_stream_class *stream_class);
-
-extern uint64_t bt_stream_class_get_event_class_count(
-               const bt_stream_class *stream_class);
-
-extern const bt_event_class *
-bt_stream_class_borrow_event_class_by_index_const(
-               const bt_stream_class *stream_class, uint64_t index);
-
-extern const bt_event_class *
-bt_stream_class_borrow_event_class_by_id_const(
-               const bt_stream_class *stream_class, uint64_t id);
-
-extern const bt_clock_class *
-bt_stream_class_borrow_default_clock_class_const(
-               const bt_stream_class *stream_class);
-
-extern void bt_stream_class_get_ref(const bt_stream_class *stream_class);
-
-extern void bt_stream_class_put_ref(const bt_stream_class *stream_class);
-
-#define BT_STREAM_CLASS_PUT_REF_AND_RESET(_var)                \
-       do {                                            \
-               bt_stream_class_put_ref(_var);          \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_STREAM_CLASS_MOVE_REF(_var_dst, _var_src)   \
-       do {                                            \
-               bt_stream_class_put_ref(_var_dst);      \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_STREAM_CLASS_CONST_H */

diff --git a/include/babeltrace2/trace-ir/stream-class.h b/include/babeltrace2/trace-ir/stream-class.h
index 58bdbdc49cfd3e631715845d1b0bc6cffc2b4fee..d05d47358e66201d27a5f8b6bdbd66dc7da31185 100644 (file)
--- a/include/babeltrace2/trace-ir/stream-class.h
+++ b/include/babeltrace2/trace-ir/stream-class.h
@@ -35,92 +35,1789 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-stream-cls Stream class
+@ingroup api-tir
+
+@brief
+    Class of \bt_p_stream.
+
+A <strong><em>stream class</em></strong> is the class of \bt_p_stream:
+
+@image html trace-structure.png
+
+In the illustration above, notice that:
+
+- A \bt_stream is a conceptual \ref api-msg-seq "sequence of messages".
+
+  The sequence always starts with a \bt_sb_msg and ends with a
+  \bt_se_msg.
+
+- A stream is an instance of a stream class.
+
+A stream class is a \ref api-tir "trace IR" metadata object.
+
+A stream class is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_stream_class_get_ref() and put an existing
+reference with bt_stream_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" stream classes on
+success. The documentation of those functions indicate this
+postcondition. You can still create and add an \bt_p_ev_cls to a frozen
+stream class with bt_event_class_create() or
+bt_event_class_create_with_id().
+
+The type of a stream class is #bt_stream_class.
+
+A \bt_trace_cls contains stream classes. All the stream classes of a
+given trace class have unique
+\ref api-tir-stream-cls-prop-id "numeric IDs". Borrow the trace class
+which contains a stream class with bt_stream_class_borrow_trace_class()
+or bt_stream_class_borrow_trace_class_const().
+
+A stream class contains \bt_p_ev_cls. All the event classes of a given
+stream class have unique \ref api-tir-ev-cls-prop-id "numeric IDs". Get
+the number of event classes in a stream class with
+bt_stream_class_get_event_class_count(). Borrow a specific event class
+from a stream class with bt_stream_class_borrow_event_class_by_index(),
+bt_stream_class_borrow_event_class_by_index_const(),
+bt_stream_class_borrow_event_class_by_id(), and
+bt_stream_class_borrow_event_class_by_id_const().
+
+A stream class controls what its instances (\bt_p_stream) support:
+
+<dl>
+  <dt>Default clock</dt>
+  <dd>
+    By default, a stream class's streams do not have default clocks.
+
+    Set the default \bt_clock_cls of a stream class with
+    bt_stream_class_set_default_clock_class(). This makes all its
+    streams have their own default clock.
+  </dd>
+
+  <dt>\anchor api-tir-stream-cls-pkt-support Packets</dt>
+  <dd>
+    By default, a stream class's streams do not support \bt_p_pkt.
+
+    In other words, you cannot create a packet for such a stream,
+    therefore you cannot create \bt_p_pb_msg and \bt_p_pe_msg for this
+    stream either.
+
+    Enable packet support for a stream class's streams with
+    bt_stream_class_set_supports_packets().
+
+    bt_stream_class_set_supports_packets() also configures whether or
+    not the packets of the stream class's instances have beginning
+    and/or end default \bt_p_cs.
+  </dd>
+
+  <dt>Discarded events</dt>
+  <dd>
+    By default, a stream class's streams do not support discarded
+    events.
+
+    In other words, you cannot create \bt_p_disc_ev_msg for such a
+    stream.
+
+    Enable discarded events support for a stream class's streams with
+    bt_stream_class_set_supports_discarded_events().
+
+    bt_stream_class_set_supports_discarded_events() also configures
+    whether or not the discarded events messages of the stream class's
+    instances have beginning and end default \bt_p_cs to indicate the
+    discarded events time range.
+  </dd>
+
+  <dt>Discarded packets</dt>
+  <dd>
+    By default, a stream class's streams do not support discarded
+    packets.
+
+    In other words, you cannot create \bt_p_disc_pkt_msg for such a
+    stream.
+
+    Enable discarded packets support for a stream class's streams with
+    bt_stream_class_set_supports_discarded_packets(). This also implies
+    that you must enable packet support with
+    bt_stream_class_set_supports_packets().
+
+    bt_stream_class_set_supports_discarded_packets() also configures
+    whether or not the discarded packets messages of the stream class's
+    instances have beginning and end \bt_p_cs to indicate the
+    discarded packets time range.
+  </dd>
+</dl>
+
+Set whether or not the \bt_p_ev_cls and \bt_p_stream you create for a
+stream class get automatic numeric IDs with
+bt_stream_class_set_assigns_automatic_event_class_id() and
+bt_stream_class_set_assigns_automatic_stream_id().
+
+To create a default stream class:
+
+<dl>
+  <dt>
+    If bt_trace_class_assigns_automatic_stream_class_id() returns
+    #BT_TRUE (the default) for the trace class to use
+  </dt>
+  <dd>Use bt_stream_class_create().</dd>
+
+  <dt>
+    If bt_trace_class_assigns_automatic_stream_class_id() returns
+    #BT_FALSE for the trace class to use
+  </dt>
+  <dd>Use bt_stream_class_create_with_id().</dd>
+</dl>
+
+<h1>Properties</h1>
+
+A stream class has the following properties:
+
+<dl>
+  <dt>\anchor api-tir-stream-cls-prop-id Numeric ID</dt>
+  <dd>
+    Numeric ID, unique amongst the numeric IDs of the stream class's
+    \bt_trace_cls's stream classes.
+
+    Depending on whether or not the stream class's trace class
+    automatically assigns \bt_ev_cls IDs
+    (see bt_trace_class_assigns_automatic_stream_class_id()),
+    set the stream class's numeric ID on creation with
+    bt_stream_class_create() or bt_stream_class_create_with_id().
+
+    You cannot change the numeric ID once the stream class is created.
+
+    Get a stream class's numeric ID with bt_stream_class_get_id().
+  </dd>
+
+  <dt>\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name</dt>
+  <dd>
+    Name of the stream class.
+
+    Use bt_stream_class_set_name() and bt_stream_class_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-def-clock-cls
+    \bt_dt_opt Default clock class
+  </dt>
+  <dd>
+    Default \bt_clock_cls of the stream class.
+
+    As of \bt_name_version_min_maj, a stream class either has a default
+    clock class or none: it cannot have more than one clock class.
+
+    When a stream class has a default clock class, then all its
+    instances (\bt_p_stream) have a default clock which is an instance
+    of the stream class's default clock class.
+
+    Use bt_stream_class_set_default_clock_class(),
+    bt_stream_class_borrow_default_clock_class(), and
+    bt_stream_class_borrow_default_clock_class_const().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-pc-fc
+    \bt_dt_opt Packet context field class
+  </dt>
+  <dd>
+    \bt_c_pkt context \bt_fc of the stream class.
+
+    This property is only relevant if the stream class
+    \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
+
+    The context of a \bt_pkt contains data which is common to all the
+    packet's \bt_p_ev.
+
+    Use bt_stream_class_set_packet_context_field_class()
+    bt_stream_class_borrow_packet_context_field_class(),
+    and bt_stream_class_borrow_packet_context_field_class_const().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-ecc-fc
+    \bt_dt_opt Event common context field class
+  </dt>
+  <dd>
+    \bt_c_ev common context \bt_fc of the stream class.
+
+    The common context of an \bt_ev contains contextual data of which
+    the layout is common to all the stream class's \bt_p_ev_cls.
+
+    Use bt_stream_class_set_event_common_context_field_class()
+    bt_stream_class_borrow_event_common_context_field_class(),
+    and bt_stream_class_borrow_event_common_context_field_class_const().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-auto-ec-id
+    Assigns automatic event class IDs?
+  </dt>
+  <dd>
+    Whether or not the \bt_p_ev_cls you create and add to the stream
+    class get \ref api-tir-ev-cls-prop-id "numeric IDs" automatically.
+
+    Depending on the value of this property, to create an event class
+    and add it to the stream class:
+
+    <dl>
+      <dt>#BT_TRUE</dt>
+      <dd>
+        Use bt_event_class_create().
+      </dd>
+
+      <dt>#BT_FALSE</dt>
+      <dd>
+        Use bt_event_class_create_with_id().
+      </dd>
+    </dl>
+
+    Use bt_stream_class_set_assigns_automatic_event_class_id()
+    and bt_stream_class_assigns_automatic_event_class_id().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-auto-stream-id
+    Assigns automatic stream IDs?
+  </dt>
+  <dd>
+    Whether or not the streams you create from the stream class
+    get \ref api-tir-stream-prop-id "numeric IDs" automatically.
+
+    Depending on the value of this property, to create a stream
+    from the stream class:
+
+    <dl>
+      <dt>#BT_TRUE</dt>
+      <dd>
+        Use bt_stream_create().
+      </dd>
+
+      <dt>#BT_FALSE</dt>
+      <dd>
+        Use bt_stream_create_with_id().
+      </dd>
+    </dl>
+
+    Use bt_stream_class_set_assigns_automatic_stream_id()
+    and bt_stream_class_assigns_automatic_stream_id().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-supports-pkt
+    Supports packets?
+  </dt>
+  <dd>
+    Whether or not the streams you create from the stream class
+    have \bt_p_pkt.
+
+    If a stream has packets, then all the stream's \bt_p_ev are
+    conceptually contained within packets, which means you must
+    create \bt_p_ev_msg for such streams with
+    bt_message_event_create_with_packet() or
+    bt_message_event_create_with_packet_and_default_clock_snapshot()
+    instead of bt_message_event_create() or
+    bt_message_event_create_with_default_clock_snapshot().
+
+    It also means you must create \bt_p_pb_msg and \bt_p_pe_msg to
+    indicate where packets begin and end within the stream's
+    \ref api-msg-seq "message sequence".
+
+    Use bt_stream_class_set_supports_packets() and
+    bt_stream_class_supports_packets().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-pkt-beg-cs
+    Packets have a beginning default clock snapshot?
+  </dt>
+  <dd>
+    Whether or not the \bt_p_pkt of the streams you create from the
+    stream class have beginning default \bt_p_cs.
+
+    This property is only relevant if the stream class
+    \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
+    has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    If the stream packets have a beginning default clock snapshot, then
+    you must create \bt_p_pb_msg with
+    bt_message_packet_beginning_create_with_default_clock_snapshot()
+    instead of bt_message_packet_beginning_create().
+
+    Use bt_stream_class_set_supports_packets() and
+    bt_stream_class_packets_have_beginning_default_clock_snapshot().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-pkt-end-cs
+    Packets have an end default clock snapshot?
+  </dt>
+  <dd>
+    Whether or not the \bt_p_pkt of the streams you create from the
+    stream class have end default \bt_p_cs.
+
+    This property is only relevant if the stream class
+    \ref api-tir-stream-cls-prop-supports-pkt "supports packets" and
+    has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    If the stream packets have an end default clock snapshot, then you
+    must create \bt_p_pe_msg with
+    bt_message_packet_end_create_with_default_clock_snapshot() instead
+    of bt_message_packet_end_create().
+
+    Use bt_stream_class_set_supports_packets() and
+    bt_stream_class_packets_have_end_default_clock_snapshot().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-supports-disc-ev
+    Supports discarded events?
+  </dt>
+  <dd>
+    Whether or not the streams you create from the stream class can have
+    discarded events.
+
+    If the stream class supports discarded events, then you can create
+    \bt_p_disc_ev_msg for this stream.
+
+    Use bt_stream_class_set_supports_discarded_events()
+    and bt_stream_class_supports_discarded_events().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-disc-ev-cs
+    Discarded events have default clock snapshots?
+  </dt>
+  <dd>
+    Whether or not the stream's \bt_p_disc_ev_msg have
+    default beginning and end \bt_p_cs to indicate the discarded events
+    time range.
+
+    This property is only relevant if the stream class
+    \ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events"
+    and has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    If the stream's discarded events messages have beginning and end
+    default clock snapshots, then you must create them with
+    bt_message_discarded_events_create_with_default_clock_snapshots()
+    instead of bt_message_discarded_events_create().
+
+    Use bt_stream_class_set_supports_discarded_events()
+    and bt_stream_class_discarded_events_have_default_clock_snapshots().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-supports-disc-pkt
+    Supports discarded packets?
+  </dt>
+  <dd>
+    Whether or not the streams you create from the stream class can have
+    discarded packets.
+
+    This property is only relevant if the stream class
+    \ref api-tir-stream-cls-prop-supports-pkt "supports packets".
+
+    If the stream class supports discarded packets, then you can create
+    \bt_p_disc_pkt_msg for this stream.
+
+    Use bt_stream_class_set_supports_discarded_packets()
+    and bt_stream_class_supports_discarded_packets().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-disc-pkt-cs
+    Discarded packets have default clock snapshots?
+  </dt>
+  <dd>
+    Whether or not the stream's \bt_p_disc_pkt_msg have
+    default beginning and end \bt_p_cs to indicate the discarded
+    packets time range.
+
+    This property is only relevant if the stream class
+    \ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets"
+    and has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+    If the stream's discarded packets messages have default clock
+    snapshots, then you must create them with
+    bt_message_discarded_packets_create_with_default_clock_snapshots()
+    instead of bt_message_discarded_packets_create().
+
+    Use bt_stream_class_set_supports_discarded_packets()
+    and bt_stream_class_discarded_packets_have_default_clock_snapshots().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-cls-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the stream class.
+
+    User attributes are custom attributes attached to a stream class.
+
+    Use bt_stream_class_set_user_attributes(),
+    bt_stream_class_borrow_user_attributes(), and
+    bt_stream_class_borrow_user_attributes_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_stream_class bt_stream_class;
+
+@brief
+    Stream class.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a default stream class and adds it to the \bt_trace_cls
+    \bt_p{trace_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_trace_class_assigns_automatic_stream_class_id(trace_class)
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use bt_stream_class_create_with_id().
+    @endparblock
+
+On success, the returned stream class has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
+    <td>Automatically assigned by \bt_p{trace_class}
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
+    <td>Yes
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
+    <td>Yes
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class to add the created stream class to.
+
+@returns
+    New stream class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@pre
+    <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
+    returns #BT_TRUE.
+
+@bt_post_success_frozen{trace_class}
+
+@sa bt_stream_class_create_with_id() &mdash;
+    Creates a stream class with a specific numeric ID and adds it to a
+    trace class.
+*/
 extern bt_stream_class *bt_stream_class_create(
                bt_trace_class *trace_class);
 
+/*!
+@brief
+    Creates a default stream class with the numeric ID \bt_p{id} and adds
+    it to the \bt_trace_cls \bt_p{trace_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_trace_class_assigns_automatic_stream_class_id(trace_class)
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use bt_stream_class_create().
+    @endparblock
+
+On success, the returned stream class has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-id "Numeric ID"
+    <td>\bt_p{id}
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-pc-fc "Packet context field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?"
+    <td>Yes
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?"
+    <td>Yes
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?"
+    <td>No
+  <tr>
+    <td>\ref api-tir-stream-cls-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class to add the created stream class to.
+@param[in] id
+    Numeric ID of the stream class to create and add to
+    \bt_p{trace_class}.
+
+@returns
+    New stream class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@pre
+    <code>bt_trace_class_assigns_automatic_stream_class_id(trace_class)</code>
+    returns #BT_FALSE.
+@pre
+    \bt_p{trace_class} does not contain a stream class with the numeric
+    ID \bt_p{id}.
+
+@bt_post_success_frozen{trace_class}
+
+@sa bt_stream_class_create() &mdash;
+    Creates a stream class with an automatic numeric ID and adds it to a
+    trace class.
+*/
 extern bt_stream_class *bt_stream_class_create_with_id(
                bt_trace_class *trace_class, uint64_t id);
 
-extern bt_value *bt_stream_class_borrow_user_attributes(
-               bt_stream_class *stream_class);
+/*! @} */
 
-extern void bt_stream_class_set_user_attributes(
-               bt_stream_class *stream_class, const bt_value *user_attributes);
+/*!
+@name Trace class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_trace_cls which contains the stream class
+    \bt_p{stream_class}.
+
+@param[in] stream_class
+    Stream class from which to borrow the trace class which contains it.
 
+@returns
+    Trace class which contains \bt_p{stream_class}.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_borrow_trace_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_trace_class *bt_stream_class_borrow_trace_class(
                bt_stream_class *stream_class);
 
+/*!
+@brief
+    Borrows the \bt_trace_cls which contains the stream class
+    \bt_p{stream_class} (\c const version).
+
+See bt_stream_class_borrow_trace_class().
+*/
+extern const bt_trace_class *bt_stream_class_borrow_trace_class_const(
+               const bt_stream_class *stream_class);
+
+/*! @} */
+
+/*!
+@name Event class access
+@{
+*/
+
+/*!
+@brief
+    Returns the number of \bt_p_ev_cls contained in the stream
+    class \bt_p{stream_class}.
+
+@param[in] stream_class
+    Stream class of which to get the number of contained event classes.
+
+@returns
+    Number of contained event classes in \bt_p{stream_class}.
+
+@bt_pre_not_null{stream_class}
+*/
+extern uint64_t bt_stream_class_get_event_class_count(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Borrows the \bt_ev_cls at index \bt_p{index} from the
+    stream class \bt_p{stream_class}.
+
+@param[in] stream_class
+    Stream class from which to borrow the event class at index
+    \bt_p{index}.
+@param[in] index
+    Index of the event class to borrow from \bt_p{stream_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the event class of
+    \bt_p{stream_class} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{stream_class}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{stream_class}
+@pre
+    \bt_p{index} is less than the number of event classes in
+    \bt_p{stream_class} (as returned by
+    bt_stream_class_get_event_class_count()).
+
+@sa bt_stream_class_get_event_class_count() &mdash;
+    Returns the number of event classes contained in a stream class.
+@sa bt_stream_class_borrow_event_class_by_index_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_event_class *
+bt_stream_class_borrow_event_class_by_index(
+               bt_stream_class *stream_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_ev_cls at index \bt_p{index} from the
+    stream class \bt_p{stream_class} (\c const version).
+
+See bt_stream_class_borrow_event_class_by_index().
+*/
+extern const bt_event_class *
+bt_stream_class_borrow_event_class_by_index_const(
+               const bt_stream_class *stream_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
+    stream class \bt_p{stream_class}.
+
+If there's no event class having the numeric ID \bt_p{id} in
+\bt_p{stream_class}, this function returns \c NULL.
+
+@param[in] stream_class
+    Stream class from which to borrow the event class having the
+    numeric ID \bt_p{id}.
+@param[in] id
+    ID of the event class to borrow from \bt_p{stream_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the event class of
+    \bt_p{stream_class} having the numeric ID \bt_p{id}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{stream_class}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_borrow_event_class_by_id_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_event_class *
+bt_stream_class_borrow_event_class_by_id(
+               bt_stream_class *stream_class, uint64_t id);
+
+/*!
+@brief
+    Borrows the \bt_ev_cls having the numeric ID \bt_p{id} from the
+    stream class \bt_p{stream_class} (\c const version).
+
+See bt_stream_class_borrow_event_class_by_id().
+*/
+extern const bt_event_class *
+bt_stream_class_borrow_event_class_by_id_const(
+               const bt_stream_class *stream_class, uint64_t id);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Returns the numeric ID of the stream class \bt_p{stream_class}.
+
+See the \ref api-tir-stream-cls-prop-id "numeric ID" property.
+
+@param[in] stream_class
+    Stream class of which to get the numeric ID.
+
+@returns
+    Numeric ID of \bt_p{stream_class}.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_create_with_id() &mdash;
+    Creates a stream class with a specific numeric ID and adds it to a
+    trace class.
+*/
+extern uint64_t bt_stream_class_get_id(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Status codes for bt_stream_class_set_name().
+*/
 typedef enum bt_stream_class_set_name_status {
-       BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_STREAM_CLASS_SET_NAME_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_stream_class_set_name_status;
 
+/*!
+@brief
+    Sets the name of the stream class \bt_p{stream_class} to
+    a copy of \bt_p{name}.
+
+See the \ref api-tir-stream-cls-prop-name "name" property.
+
+@param[in] stream_class
+    Stream class of which to set the name to \bt_p{name}.
+@param[in] name
+    New name of \bt_p{stream_class} (copied).
+
+@retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
+    Success.
+@retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@bt_pre_not_null{name}
+
+@sa bt_stream_class_get_name() &mdash;
+    Returns the name of a stream class.
+*/
 extern bt_stream_class_set_name_status bt_stream_class_set_name(
                bt_stream_class *stream_class, const char *name);
 
-extern void bt_stream_class_set_assigns_automatic_event_class_id(
-               bt_stream_class *stream_class, bt_bool value);
+/*!
+@brief
+    Returns the name of the stream class \bt_p{stream_class}.
 
-extern void bt_stream_class_set_assigns_automatic_stream_id(
-               bt_stream_class *stream_class, bt_bool value);
+See the \ref api-tir-stream-cls-prop-name "name" property.
 
-extern void bt_stream_class_set_supports_discarded_events(
-               bt_stream_class *stream_class,
-               bt_bool supports_discarded_events,
-               bt_bool with_default_clock_snapshots);
+If \bt_p{stream_class} has no name, this function returns \c NULL.
 
-extern void bt_stream_class_set_supports_discarded_packets(
+@param[in] stream_class
+    Stream class of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{stream_class}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{stream_class}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_name() &mdash;
+    Sets the name of a stream class.
+*/
+extern const char *bt_stream_class_get_name(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Status codes for bt_stream_class_set_default_clock_class().
+*/
+typedef enum bt_stream_class_set_default_clock_class_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK       = __BT_FUNC_STATUS_OK,
+} bt_stream_class_set_default_clock_class_status;
+
+/*!
+@brief
+    Sets the default \bt_clock_cls of the stream class
+    \bt_p{stream_class} to \bt_p{clock_class}.
+
+See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
+
+@param[in] stream_class
+    Stream class of which to set the default clock class to
+    \bt_p{clock_class}.
+@param[in] clock_class
+    New default clock class of \bt_p{stream_class}.
+
+@retval #BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK
+    Success.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@bt_pre_not_null{clock_class}
+
+@sa bt_stream_class_borrow_default_clock_class() &mdash;
+    Borrows the default clock class of a stream class.
+@sa bt_stream_class_borrow_default_clock_class_const() &mdash;
+    Borrows the default clock class of a stream class (\c const version).
+*/
+extern bt_stream_class_set_default_clock_class_status
+bt_stream_class_set_default_clock_class(
                bt_stream_class *stream_class,
-               bt_bool supports_discarded_packets,
-               bt_bool with_default_clock_snapshots);
+               bt_clock_class *clock_class);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls from the stream class
+    \bt_p{stream_class}.
+
+See the \ref api-tir-stream-cls-prop-def-clock-cls "default clock class"
+property.
 
+If \bt_p{stream_class} has no default clock class, this function
+returns \c NULL.
+
+@param[in] stream_class
+    Stream class from which to borrow the default clock class.
+
+@returns
+    \em Borrowed reference of the default clock class of
+    \bt_p{stream_class}, or \c NULL if none.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_default_clock_class() &mdash;
+    Sets the default clock class of a stream class.
+@sa bt_stream_class_borrow_default_clock_class_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_clock_class *bt_stream_class_borrow_default_clock_class(
+               bt_stream_class *stream_class);
+
+/*!
+@brief
+    Borrows the default \bt_clock_cls from the stream class
+    \bt_p{stream_class} (\c const version).
+
+See bt_stream_class_borrow_default_clock_class().
+*/
+extern const bt_clock_class *
+bt_stream_class_borrow_default_clock_class_const(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Status codes for bt_stream_class_set_packet_context_field_class()
+    and bt_stream_class_set_event_common_context_field_class().
+*/
 typedef enum bt_stream_class_set_field_class_status {
-       BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK               = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_stream_class_set_field_class_status;
 
-extern void bt_stream_class_set_supports_packets(
-               bt_stream_class *stream_class, bt_bool supports_packets,
-               bt_bool with_beginning_default_clock_snapshot,
-               bt_bool with_end_default_clock_snapshot);
+/*!
+@brief
+    Sets the packet context \bt_fc of the stream class
+    \bt_p{stream_class} to \bt_p{field_class}.
+
+See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
+property.
+
+\bt_p{stream_class} must support packets (see
+bt_stream_class_set_supports_packets()).
 
+@param[in] stream_class
+    Stream class of which to set the packet context field class to
+    \bt_p{field_class}.
+@param[in] field_class
+    New packet context field class of \bt_p{stream_class}.
+
+@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
+    Success.
+@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@pre
+    <code>bt_stream_class_supports_packets(stream_class)</code>
+    returns #BT_TRUE.
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+    \bt_p{field_class}, or any of its contained field classes,
+    is not already part of a stream class or of an \bt_ev_cls.
+@pre
+    If any of the field classes recursively contained in
+    \bt_p{field_class} has a
+    \ref api-tir-fc-link "link to another field class", it must honor
+    the field class link rules.
+@pre
+    If any of the field classes recursively contained in
+    \bt_p{field_class} has a
+    \ref api-tir-fc-link "link to another field class", it must honor
+    the field class link rules.
+
+@bt_post_success_frozen{field_class}
+
+@sa bt_stream_class_borrow_packet_context_field_class() &mdash;
+    Borrows the packet context field class of a stream class.
+@sa bt_stream_class_borrow_packet_context_field_class_const() &mdash;
+    Borrows the packet context field class of a stream class
+    (\c const version).
+*/
 extern bt_stream_class_set_field_class_status
 bt_stream_class_set_packet_context_field_class(
                bt_stream_class *stream_class,
                bt_field_class *field_class);
 
+/*!
+@brief
+    Borrows the packet context \bt_fc from the stream class
+    \bt_p{stream_class}.
+
+See the \ref api-tir-stream-cls-prop-pc-fc "packet context field class"
+property.
+
+If \bt_p{stream_class} has no packet context field class, this function
+returns \c NULL.
+
+@param[in] stream_class
+    Stream class from which to borrow the packet context field class.
+
+@returns
+    \em Borrowed reference of the packet context field class of
+    \bt_p{stream_class}, or \c NULL if none.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_packet_context_field_class() &mdash;
+    Sets the packet context field class of a stream class.
+@sa bt_stream_class_borrow_packet_context_field_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_field_class *
 bt_stream_class_borrow_packet_context_field_class(
                bt_stream_class *stream_class);
 
+/*!
+@brief
+    Borrows the packet context \bt_fc from the stream class
+    \bt_p{stream_class} (\c const version).
+
+See bt_stream_class_borrow_packet_context_field_class().
+*/
+extern const bt_field_class *
+bt_stream_class_borrow_packet_context_field_class_const(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Sets the event common context \bt_fc of the stream class
+    \bt_p{stream_class} to \bt_p{field_class}.
+
+See the \ref api-tir-stream-cls-prop-ecc-fc "event common context field class"
+property.
+
+@param[in] stream_class
+    Stream class of which to set the event common context field class to
+    \bt_p{field_class}.
+@param[in] field_class
+    New event common context field class of \bt_p{stream_class}.
+
+@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_OK
+    Success.
+@retval #BT_STREAM_CLASS_SET_FIELD_CLASS_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@bt_pre_not_null{field_class}
+@bt_pre_is_struct_fc{field_class}
+@pre
+    \bt_p{field_class}, or any of its contained field classes,
+    is not already part of a stream class or of an \bt_ev_cls.
+@pre
+    If any of the field classes recursively contained in
+    \bt_p{field_class} has a
+    \ref api-tir-fc-link "link to another field class", it must honor
+    the field class link rules.
+
+@bt_post_success_frozen{field_class}
+
+@sa bt_stream_class_borrow_event_common_context_field_class() &mdash;
+    Borrows the event common context field class of a stream class.
+@sa bt_stream_class_borrow_event_common_context_field_class_const() &mdash;
+    Borrows the event common context field class of a stream class
+    (\c const version).
+*/
 extern bt_stream_class_set_field_class_status
 bt_stream_class_set_event_common_context_field_class(
                bt_stream_class *stream_class,
                bt_field_class *field_class);
 
+/*!
+@brief
+    Borrows the event common context \bt_fc from the stream class
+    \bt_p{stream_class}.
+
+See the \ref api-tir-stream-cls-prop-pc-fc "event common context field class"
+property.
+
+If \bt_p{stream_class} has no event common context field class, this
+function returns \c NULL.
+
+@param[in] stream_class
+    Stream class from which to borrow the event common context
+    field class.
+
+@returns
+    \em Borrowed reference of the event common context field class of
+    \bt_p{stream_class}, or \c NULL if none.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_event_common_context_field_class() &mdash;
+    Sets the event common context field class of a stream class.
+@sa bt_stream_class_borrow_event_common_context_field_class_const() &mdash;
+    \c const version of this function.
+*/
+
 extern bt_field_class *
 bt_stream_class_borrow_event_common_context_field_class(
                bt_stream_class *stream_class);
 
-extern bt_event_class *
-bt_stream_class_borrow_event_class_by_index(
-               bt_stream_class *stream_class, uint64_t index);
+/*!
+@brief
+    Borrows the event common context \bt_fc from the stream class
+    \bt_p{stream_class} (\c const version()).
 
-extern bt_event_class *
-bt_stream_class_borrow_event_class_by_id(
-               bt_stream_class *stream_class, uint64_t id);
+See bt_stream_class_borrow_event_common_context_field_class().
+*/
+extern const bt_field_class *
+bt_stream_class_borrow_event_common_context_field_class_const(
+               const bt_stream_class *stream_class);
 
-extern bt_clock_class *bt_stream_class_borrow_default_clock_class(
-               bt_stream_class *stream_class);
+/*!
+@brief
+    Sets whether or not the stream class \bt_p{stream_class}
+    automatically assigns a numeric ID to an \bt_ev_cls you create and
+    add to it.
 
-typedef enum bt_stream_class_set_default_clock_class_status {
-       BT_STREAM_CLASS_SET_DEFAULT_CLOCK_CLASS_STATUS_OK       = __BT_FUNC_STATUS_OK,
-} bt_stream_class_set_default_clock_class_status;
+See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
+property.
 
-extern bt_stream_class_set_default_clock_class_status
-bt_stream_class_set_default_clock_class(
+@param[in] stream_class
+    Stream class of which to set whether or not it assigns automatic
+    event class IDs.
+@param[in] assigns_automatic_event_class_id
+    #BT_TRUE to make \bt_p{stream_class} assign automatic event class
+    IDs.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+
+@sa bt_stream_class_assigns_automatic_event_class_id() &mdash;
+    Returns whether or not a stream class automatically assigns
+    event class IDs.
+*/
+extern void bt_stream_class_set_assigns_automatic_event_class_id(
                bt_stream_class *stream_class,
-               bt_clock_class *clock_class);
+    bt_bool assigns_automatic_event_class_id);
+
+/*!
+@brief
+    Returns whether or not the stream class \bt_p{stream_class}
+    automatically assigns a numeric ID to an \bt_ev_cls you create
+    and add to it.
+
+See the \ref api-tir-stream-cls-prop-auto-ec-id "assigns automatic event class IDs?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not it assigns automatic
+    event class IDs.
+
+@returns
+    #BT_TRUE if \bt_p{stream_class} automatically
+    assigns event class IDs.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_assigns_automatic_event_class_id() &mdash;
+    Sets whether or not a stream class automatically assigns
+    event class IDs.
+*/
+extern bt_bool bt_stream_class_assigns_automatic_event_class_id(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Sets whether or not the stream class \bt_p{stream_class}
+    automatically assigns a numeric ID to a \bt_stream you create from
+    it.
+
+See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
+property.
+
+@param[in] stream_class
+    Stream class of which to set whether or not it assigns automatic
+    stream IDs.
+@param[in] assigns_automatic_stream_id
+    #BT_TRUE to make \bt_p{stream_class} assign automatic stream
+    IDs.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+
+@sa bt_stream_class_assigns_automatic_stream_id() &mdash;
+    Returns whether or not a stream class automatically assigns
+    stream IDs.
+*/
+extern void bt_stream_class_set_assigns_automatic_stream_id(
+               bt_stream_class *stream_class, bt_bool assigns_automatic_stream_id);
+
+/*!
+@brief
+    Returns whether or not the stream class \bt_p{stream_class}
+    automatically assigns a numeric ID to a \bt_stream you create
+    from it.
+
+See the \ref api-tir-stream-cls-prop-auto-stream-id "assigns automatic stream IDs?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not it assigns automatic
+    stream IDs.
+
+@returns
+    #BT_TRUE if \bt_p{stream_class} automatically assigns stream IDs.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_assigns_automatic_stream_id() &mdash;
+    Sets whether or not a stream class automatically assigns
+    stream IDs.
+*/
+extern bt_bool bt_stream_class_assigns_automatic_stream_id(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Sets whether or not the instances (\bt_p_stream) of the
+    stream class \bt_p{stream_class} have \bt_p_pkt and, if so,
+    if those packets have beginning and/or end default
+    \bt_p_cs.
+
+See the
+\ref api-tir-stream-cls-prop-supports-pkt "supports packets?",
+\ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?",
+and
+\ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
+properties.
+
+@param[in] stream_class
+    Stream class of which to set whether or not its streams have
+    packets.
+@param[in] supports_packets
+    #BT_TRUE to make the streams of \bt_p{stream_class} have packets.
+@param[in] with_beginning_default_clock_snapshot
+    #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
+    have a beginning default clock snapshot.
+@param[in] with_end_default_clock_snapshot
+    #BT_TRUE to make the packets of the streams of \bt_p{stream_class}
+    have an end default clock snapshot.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@pre
+    <strong>If \bt_p{with_beginning_default_clock_snapshot} is
+    #BT_TRUE</strong>,
+    \bt_p{supports_packets} is also #BT_TRUE.
+@pre
+    <strong>If \bt_p{with_beginning_default_clock_snapshot} is
+    #BT_TRUE</strong>,
+    \bt_p{supports_packets} is also #BT_TRUE.
+@pre
+    <strong>If \bt_p{with_beginning_default_clock_snapshot} or
+    \bt_p{with_end_default_clock_snapshot} is #BT_TRUE</strong>,
+    \bt_p{stream_class} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+@sa bt_stream_class_supports_packets() &mdash;
+    Returns whether or not a stream class's streams have packets.
+@sa bt_stream_class_packets_have_beginning_default_clock_snapshot() &mdash;
+    Returns whether or not the packets of a stream class's streams
+    have a beginning default clock snapshot.
+@sa bt_stream_class_packets_have_end_default_clock_snapshot() &mdash;
+    Returns whether or not the packets of a stream class's streams
+    have an end default clock snapshot.
+*/
+extern void bt_stream_class_set_supports_packets(
+               bt_stream_class *stream_class, bt_bool supports_packets,
+               bt_bool with_beginning_default_clock_snapshot,
+               bt_bool with_end_default_clock_snapshot);
+
+/*!
+@brief
+    Returns whether or not the instances (\bt_p_stream) of the
+    stream class \bt_p{stream_class} have \bt_p_pkt.
+
+See the \ref api-tir-stream-cls-prop-supports-pkt "supports packets?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not its streams have
+    packets.
+
+@returns
+    #BT_TRUE if the streams of \bt_p{stream_class} have packets.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_supports_packets() &mdash;
+    Sets whether or not a stream class's streams have packets.
+*/
+extern bt_bool bt_stream_class_supports_packets(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
+    of the stream class \bt_p{stream_class} have a beginning
+    default \bt_cs.
+
+See the
+\ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not its streams's packets
+    have a beginning default clock snapshot.
+
+@returns
+    #BT_TRUE if the packets of the streams of \bt_p{stream_class} have a
+    beginning default clock snapshot.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_supports_packets() &mdash;
+    Sets whether or not a stream class's streams have packets.
+@sa bt_stream_class_packets_have_end_default_clock_snapshot() &mdash;
+    Returns whether or not the packets of a stream class's streams
+    have an end default clock snapshot.
+*/
+extern bt_bool bt_stream_class_packets_have_beginning_default_clock_snapshot(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Returns whether or not the \bt_p_pkt of the instances (\bt_p_stream)
+    of the stream class \bt_p{stream_class} have an end
+    default \bt_cs.
+
+See the
+\ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not its streams's packets
+    have an end default clock snapshot.
+
+@returns
+    #BT_TRUE if the packets of the streams of \bt_p{stream_class} have
+    an end default clock snapshot.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_supports_packets() &mdash;
+    Sets whether or not a stream class's streams have packets.
+@sa bt_stream_class_packets_have_beginning_default_clock_snapshot() &mdash;
+    Returns whether or not the packets of a stream class's streams
+    have a beginning default clock snapshot.
+*/
+extern bt_bool bt_stream_class_packets_have_end_default_clock_snapshot(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Sets whether or not the instances (\bt_p_stream) of the
+    stream class \bt_p{stream_class} can have discarded events and,
+    if so, if the \bt_p_disc_ev_msg of those streams have
+    beginning and end default \bt_p_cs.
+
+See the
+\ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
+and
+\ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
+properties.
+
+@param[in] stream_class
+    Stream class of which to set whether or not its streams can have
+    discarded events.
+@param[in] supports_discarded_events
+    #BT_TRUE to make the streams of \bt_p{stream_class} be able to
+    have discarded events.
+@param[in] with_default_clock_snapshots
+    #BT_TRUE to make the discarded events messages the streams of
+    \bt_p{stream_class} have beginning and end default clock snapshots.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@pre
+    <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+    \bt_p{supports_discarded_events} is also #BT_TRUE.
+@pre
+    <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+    \bt_p{stream_class} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+@sa bt_stream_class_supports_discarded_events() &mdash;
+    Returns whether or not a stream class's streams can have
+    discarded events.
+@sa bt_stream_class_discarded_events_have_default_clock_snapshots() &mdash;
+    Returns whether or not the discarded events messages of a
+    stream class's streams have beginning and end default clock
+    snapshots.
+*/
+extern void bt_stream_class_set_supports_discarded_events(
+               bt_stream_class *stream_class,
+               bt_bool supports_discarded_events,
+               bt_bool with_default_clock_snapshots);
+
+/*!
+@brief
+    Returns whether or not the instances (\bt_p_stream) of the
+    stream class \bt_p{stream_class} can have discarded events.
+
+See the
+\ref api-tir-stream-cls-prop-supports-disc-ev "supports discarded events?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not its streams can have
+    discarded events.
+
+@returns
+    #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
+    events.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_supports_discarded_events() &mdash;
+    Sets whether or not a stream class's streams can have discarded
+    events.
+*/
+extern bt_bool bt_stream_class_supports_discarded_events(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Returns whether or not the \bt_p_disc_ev_msg of the instances
+    (\bt_p_stream) of the stream class \bt_p{stream_class} have
+    beginning and end default \bt_p_cs.
+
+See the
+\ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not its streams's discarded
+    events messages have a beginning and end default clock snapshots.
+
+@returns
+    #BT_TRUE if the discarded events messages of the streams of
+    \bt_p{stream_class} have beginning and end default clock snapshots.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_supports_discarded_events() &mdash;
+    Sets whether or not a stream class's streams can have discarded
+    events.
+*/
+extern bt_bool bt_stream_class_discarded_events_have_default_clock_snapshots(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Sets whether or not the instances (\bt_p_stream) of the
+    stream class \bt_p{stream_class} can have discarded packets and,
+    if so, if the \bt_p_disc_pkt_msg of those streams have
+    beginning and end default \bt_p_cs.
+
+See the
+\ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
+and
+\ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots?"
+properties.
+
+\bt_p{stream_class} must support packets (see
+bt_stream_class_set_supports_packets()).
+
+@param[in] stream_class
+    Stream class of which to set whether or not its streams can have
+    discarded packets.
+@param[in] supports_discarded_packets
+    #BT_TRUE to make the streams of \bt_p{stream_class} be able to
+    have discarded packets.
+@param[in] with_default_clock_snapshots
+    #BT_TRUE to make the discarded packets messages the streams of
+    \bt_p{stream_class} have beginning and end default clock snapshots.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@pre
+    <code>bt_stream_class_supports_packets(stream_class)</code>
+    returns #BT_TRUE.
+@pre
+    <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+    \bt_p{supports_discarded_packets} is also #BT_TRUE.
+@pre
+    <strong>If \bt_p{with_default_clock_snapshots} is #BT_TRUE</strong>,
+    \bt_p{stream_class} has a
+    \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+
+@sa bt_stream_class_supports_discarded_packets() &mdash;
+    Returns whether or not a stream class's streams can have
+    discarded packets.
+@sa bt_stream_class_discarded_packets_have_default_clock_snapshots() &mdash;
+    Returns whether or not the discarded packets messages of a
+    stream class's streams have beginning and end default clock
+    snapshots.
+*/
+extern void bt_stream_class_set_supports_discarded_packets(
+               bt_stream_class *stream_class,
+               bt_bool supports_discarded_packets,
+               bt_bool with_default_clock_snapshots);
+
+/*!
+@brief
+    Returns whether or not the instances (\bt_p_stream) of the
+    stream class \bt_p{stream_class} can have discarded packets.
+
+See the
+\ref api-tir-stream-cls-prop-supports-disc-pkt "supports discarded packets?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not its streams can have
+    discarded packets.
+
+@returns
+    #BT_TRUE if the streams of \bt_p{stream_class} can have discarded
+    packets.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_supports_discarded_packets() &mdash;
+    Sets whether or not a stream class's streams can have discarded
+    packets.
+*/
+extern bt_bool bt_stream_class_supports_discarded_packets(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Returns whether or not the \bt_p_disc_pkt_msg of the instances
+    (\bt_p_stream) of the stream class \bt_p{stream_class} have
+    beginning and end default \bt_p_cs.
+
+See the
+\ref api-tir-stream-cls-prop-disc-ev-cs "discarded packets have default clock snapshots?"
+property.
+
+@param[in] stream_class
+    Stream class of which to get whether or not its streams's discarded
+    packets messages have a beginning and end default clock snapshots.
+
+@returns
+    #BT_TRUE if the discarded packets messages of the streams of
+    \bt_p{stream_class} have beginning and end default clock snapshots.
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_supports_discarded_packets() &mdash;
+    Sets whether or not a stream class's streams can have discarded
+    packets.
+*/
+extern bt_bool bt_stream_class_discarded_packets_have_default_clock_snapshots(
+               const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Sets the user attributes of the stream class \bt_p{stream_class} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default stream class with bt_stream_class_create()
+    or bt_stream_class_create_with_id(), the stream class's initial user
+    attributes is an empty \bt_map_val. Therefore you can borrow it with
+    bt_stream_class_borrow_user_attributes() and fill it directly
+    instead of setting a new one with this function.
+
+@param[in] stream_class
+    Stream class of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{stream_class}.
+
+@bt_pre_not_null{stream_class}
+@bt_pre_hot{stream_class}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_stream_class_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a stream class.
+*/
+extern void bt_stream_class_set_user_attributes(
+               bt_stream_class *stream_class, const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the stream class \bt_p{stream_class}.
+
+See the \ref api-tir-stream-cls-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default stream class with bt_stream_class_create()
+    or bt_stream_class_create_with_id(), the stream class's initial user
+    attributes is an empty \bt_map_val.
+
+@param[in] stream_class
+    Stream class from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{stream_class} (a \bt_map_val).
+
+@bt_pre_not_null{stream_class}
+
+@sa bt_stream_class_set_user_attributes() &mdash;
+    Sets the user attributes of a stream class.
+@sa bt_stream_class_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_stream_class_borrow_user_attributes(
+               bt_stream_class *stream_class);
+
+/*!
+@brief
+    Borrows the user attributes of the stream class \bt_p{stream_class}
+    (\c const version).
+
+See bt_stream_class_borrow_user_attributes().
+*/
+extern const bt_value *bt_stream_class_borrow_user_attributes_const(
+               const bt_stream_class *stream_class);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the stream class \bt_p{stream_class}.
+
+@param[in] stream_class
+    @parblock
+    Stream class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_stream_class_put_ref() &mdash;
+    Decrements the reference count of a stream class.
+*/
+extern void bt_stream_class_get_ref(const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the stream class \bt_p{stream_class}.
+
+@param[in] stream_class
+    @parblock
+    Stream class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_stream_class_get_ref() &mdash;
+    Increments the reference count of a stream class.
+*/
+extern void bt_stream_class_put_ref(const bt_stream_class *stream_class);
+
+/*!
+@brief
+    Decrements the reference count of the stream class
+    \bt_p{_stream_class}, and then sets \bt_p{_stream_class} to \c NULL.
+
+@param _stream_class
+    @parblock
+    Stream class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_stream_class}
+*/
+#define BT_STREAM_CLASS_PUT_REF_AND_RESET(_stream_class)       \
+       do {                                                    \
+               bt_stream_class_put_ref(_stream_class);         \
+               (_stream_class) = NULL;                         \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the stream class \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a stream class reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_STREAM_CLASS_MOVE_REF(_dst, _src)   \
+       do {                                    \
+               bt_stream_class_put_ref(_dst);  \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/trace-ir/stream-const.h b/include/babeltrace2/trace-ir/stream-const.h
deleted file mode 100644 (file)
index bf80983..0000000
--- a/include/babeltrace2/trace-ir/stream-const.h
+++ /dev/null
@@ -1,72 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_STREAM_CONST_H
-#define BABELTRACE2_TRACE_IR_STREAM_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-extern const bt_value *bt_stream_borrow_user_attributes_const(
-               const bt_stream *stream);
-
-extern const bt_stream_class *bt_stream_borrow_class_const(
-               const bt_stream *stream);
-
-extern const bt_trace *bt_stream_borrow_trace_const(
-               const bt_stream *stream);
-
-extern const char *bt_stream_get_name(const bt_stream *stream);
-
-extern uint64_t bt_stream_get_id(const bt_stream *stream);
-
-extern void bt_stream_get_ref(const bt_stream *stream);
-
-extern void bt_stream_put_ref(const bt_stream *stream);
-
-#define BT_STREAM_PUT_REF_AND_RESET(_var)              \
-       do {                                            \
-               bt_stream_put_ref(_var);                \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_STREAM_MOVE_REF(_var_dst, _var_src)         \
-       do {                                            \
-               bt_stream_put_ref(_var_dst);            \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_STREAM_CONST_H */

diff --git a/include/babeltrace2/trace-ir/stream.h b/include/babeltrace2/trace-ir/stream.h
index 416e42cec15c4c128d09a97622f80846b579fdb1..32bc98e1770decbad7e3db38da584a301d896899 100644 (file)
--- a/include/babeltrace2/trace-ir/stream.h
+++ b/include/babeltrace2/trace-ir/stream.h
@@ -35,30 +35,631 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-tir-stream Stream
+@ingroup api-tir
+
+@brief
+    Trace stream.
+
+A <strong><em>stream</em></strong> is a conceptual
+\ref api-msg-seq "sequence of messages" within a \bt_trace:
+
+@image html trace-structure.png
+
+In the illustration above, notice that:
+
+- A \bt_stream is a conceptual sequence of \bt_p_msg.
+
+  The sequence always starts with a \bt_sb_msg and ends with a
+  \bt_se_msg.
+
+- A stream is an instance of a \bt_stream_cls.
+
+- A \bt_trace contains one or more streams.
+
+A stream is a \ref api-tir "trace IR" data object.
+
+A stream is said to be a \em conceptual sequence of messages because the
+stream object itself does not contain messages: it only represents a
+common timeline to which messages are associated.
+
+\bt_cp_comp exchange messages, within a trace processing \bt_graph,
+which can belong to different streams, as long as the stream clocks are
+\ref api-tir-clock-cls-origin "correlatable".
+
+A typical use case for streams is to use one for each traced CPU. Then
+the messages related to a given stream are the ones which occured on a
+given CPU. Other schemes are possible: they are completely
+application-specific, and \bt_name does not enforce any specific
+stream arrangement pattern.
+
+A \bt_trace contains streams. All the streams of a
+given trace, for a given stream class, have unique numeric IDs. Borrow
+the trace which contains a stream with bt_stream_borrow_trace() or
+bt_stream_borrow_trace_const().
+
+A \bt_stream can conceptually contain a default clock if its class
+has a \ref api-tir-stream-cls-prop-def-clock-cls "default clock class".
+There's no function to access a stream's default clock because it's
+a stateful object: \bt_p_msg cannot refer to stateful objects
+because they must not change while being transported from one
+\bt_comp to the other. Instead of having a stream default clock object,
+\bt_p_msg have a default \bt_cs: this is a snapshot of the value of a
+stream's default clock (a \bt_clock_cls instance):
+
+@image html clocks.png
+
+In the illustration above, notice that:
+
+- Streams (horizontal blue rectangles) are instances of a
+  \bt_stream_cls (orange).
+
+- A stream class has a default \bt_clock_cls (orange bell alarm clock).
+
+- Each stream has a default clock (yellow bell alarm clock): this is an
+  instance of the stream's class's default clock class.
+
+- Each \bt_msg (objects in blue stream rectangles) created for a given
+  stream has a default \bt_cs (yellow star): this is a snapshot of the
+  stream's default clock.
+
+  In other words, a default clock snapshot contains the value of the
+  stream's default clock when this message occured.
+
+To create a stream:
+
+<dl>
+  <dt>
+    If bt_stream_class_assigns_automatic_stream_id() returns
+    #BT_TRUE (the default) for the stream class to use
+  </dt>
+  <dd>Use bt_stream_create().</dd>
+
+  <dt>
+    If bt_stream_class_assigns_automatic_stream_id() returns
+    #BT_FALSE for the stream class to use
+  </dt>
+  <dd>Use bt_stream_create_with_id().</dd>
+</dl>
+
+A stream is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_stream_get_ref() and put an existing
+reference with bt_stream_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" streams on
+success. The documentation of those functions indicate this
+postcondition.
+
+The type of a stream is #bt_stream.
+
+<h1>Properties</h1>
+
+A stream has the following property:
+
+<dl>
+  <dt>\anchor api-tir-stream-prop-id Numeric ID</dt>
+  <dd>
+    Numeric ID, unique amongst the numeric IDs of the stream's
+    \bt_trace's streams for a given \bt_stream_cls. In other words,
+    two streams which belong to the same trace can have the same numeric
+    ID if they aren't instances of the same class.
+
+    Depending on whether or not the stream's class
+    automatically assigns stream IDs
+    (see bt_stream_class_assigns_automatic_stream_id()),
+    set the stream's numeric ID on creation with
+    bt_stream_create() or bt_stream_create_with_id().
+
+    You cannot change the numeric ID once the stream is created.
+
+    Get a stream's numeric ID with bt_stream_get_id().
+  </dd>
+
+  <dt>\anchor api-tir-stream-prop-name \bt_dt_opt Name</dt>
+  <dd>
+    Name of the stream.
+
+    Use bt_stream_set_name() and bt_stream_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-tir-stream-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the stream.
+
+    User attributes are custom attributes attached to a stream.
+
+    Use bt_stream_set_user_attributes(),
+    bt_stream_borrow_user_attributes(), and
+    bt_stream_borrow_user_attributes_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_stream bt_stream;
+
+@brief
+    Stream.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a stream from the \bt_stream_cls \bt_p{stream_class} and
+    adds it to the \bt_trace \bt_p{trace}.
+
+This function instantiates \bt_p{stream_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_assigns_automatic_stream_id(stream_class)
+    @endcode
+
+    returns #BT_TRUE.
+
+    Otherwise, use bt_stream_create_with_id().
+    @endparblock
+
+On success, the returned stream has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-stream-prop-id "Numeric ID"
+    <td>Automatically assigned by \bt_p{stream_class} and \bt_p{trace}
+  <tr>
+    <td>\ref api-tir-stream-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] stream_class
+    Stream class from which to create the stream.
+@param[in] trace
+    Trace to add the created stream to.
+
+@returns
+    New stream reference, or \c NULL on memory error.
+
+@bt_pre_not_null{stream_class}
+@pre
+    <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
+    returns #BT_TRUE.
+@bt_pre_not_null{trace}
+
+@bt_post_success_frozen{stream_class}
+@bt_post_success_frozen{trace}
+
+@sa bt_stream_create_with_id() &mdash;
+    Creates a stream with a specific numeric ID and adds it to a
+    trace.
+*/
 extern bt_stream *bt_stream_create(bt_stream_class *stream_class,
                bt_trace *trace);
 
+/*!
+@brief
+    Creates a stream with the numeric ID \bt_p{id}
+    from the \bt_stream_cls \bt_p{stream_class} and adds
+    it to the \bt_trace \bt_p{trace}.
+
+This function instantiates \bt_p{stream_class}.
+
+@attention
+    @parblock
+    Only use this function if
+
+    @code
+    bt_stream_class_assigns_automatic_stream_id(stream_class)
+    @endcode
+
+    returns #BT_FALSE.
+
+    Otherwise, use bt_stream_create().
+    @endparblock
+
+On success, the returned stream has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-stream-prop-id "Numeric ID"
+    <td>\bt_p{id}
+  <tr>
+    <td>\ref api-tir-stream-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-stream-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] stream_class
+    Stream class from which to create the stream.
+@param[in] trace
+    Trace to add the created stream to.
+@param[in] id
+    Numeric ID of the stream to create and add to \bt_p{trace}.
+
+@returns
+    New stream reference, or \c NULL on memory error.
+
+@bt_pre_not_null{stream_class}
+@pre
+    <code>bt_stream_class_assigns_automatic_stream_id(stream_class)</code>
+    returns #BT_FALSE.
+@bt_pre_not_null{trace}
+@pre
+    \bt_p{trace} does not contain an instance of \bt_p{stream_class}
+    with the numeric ID \bt_p{id}.
+
+@bt_post_success_frozen{stream_class}
+@bt_post_success_frozen{trace}
+
+@sa bt_stream_create() &mdash;
+    Creates a stream with an automatic numeric ID and adds it to a
+    trace.
+*/
 extern bt_stream *bt_stream_create_with_id(
                bt_stream_class *stream_class,
                bt_trace *trace, uint64_t id);
 
-extern bt_value *bt_stream_borrow_user_attributes(bt_stream *stream);
+/*! @} */
 
-extern void bt_stream_set_user_attributes(
-               bt_stream *stream, const bt_value *user_attributes);
+/*!
+@name Class access
+@{
+*/
 
-extern bt_trace *bt_stream_borrow_trace(bt_stream *stream);
+/*!
+@brief
+    Borrows the \ref api-tir-stream-cls "class" of the stream
+    \bt_p{stream}.
+
+@param[in] stream
+    Stream of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{stream}.
+
+@bt_pre_not_null{stream}
 
+@sa bt_stream_borrow_class_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_stream_class *bt_stream_borrow_class(bt_stream *stream);
 
+/*!
+@brief
+    Borrows the \ref api-tir-stream-cls "class" of the stream
+    \bt_p{stream} (\c const version).
+
+See bt_stream_borrow_class().
+*/
+extern const bt_stream_class *bt_stream_borrow_class_const(
+               const bt_stream *stream);
+
+/*! @} */
+
+/*!
+@name Trace access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \bt_trace which contains the stream \bt_p{stream}.
+
+@param[in] stream
+    Stream of which to borrow the trace containing it.
+
+@returns
+    \em Borrowed reference of the trace containing \bt_p{stream}.
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_borrow_trace_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_trace *bt_stream_borrow_trace(bt_stream *stream);
+
+/*!
+@brief
+    Borrows the \bt_trace which contains the stream \bt_p{stream}
+    (\c const version).
+
+See bt_stream_borrow_trace().
+*/
+extern const bt_trace *bt_stream_borrow_trace_const(
+               const bt_stream *stream);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Returns the numeric ID of the stream \bt_p{stream}.
+
+See the \ref api-tir-stream-prop-id "numeric ID" property.
+
+@param[in] stream
+    Stream of which to get the numeric ID.
+
+@returns
+    Numeric ID of \bt_p{stream}.
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_create_with_id() &mdash;
+    Creates a stream with a specific numeric ID and adds it to a
+    trace.
+*/
+extern uint64_t bt_stream_get_id(const bt_stream *stream);
+
+/*!
+@brief
+    Status codes for bt_stream_set_name().
+*/
 typedef enum bt_stream_set_name_status {
-       BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_STREAM_SET_NAME_STATUS_OK            = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_STREAM_SET_NAME_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_stream_set_name_status;
 
+/*!
+@brief
+    Sets the name of the stream \bt_p{stream} to
+    a copy of \bt_p{name}.
+
+See the \ref api-tir-stream-prop-name "name" property.
+
+@param[in] stream
+    Stream of which to set the name to \bt_p{name}.
+@param[in] name
+    New name of \bt_p{stream} (copied).
+
+@retval #BT_STREAM_CLASS_SET_NAME_STATUS_OK
+    Success.
+@retval #BT_STREAM_CLASS_SET_NAME_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{stream}
+@bt_pre_hot{stream}
+@bt_pre_not_null{name}
+
+@sa bt_stream_get_name() &mdash;
+    Returns the name of a stream.
+*/
 extern bt_stream_set_name_status bt_stream_set_name(bt_stream *stream,
                const char *name);
 
+/*!
+@brief
+    Returns the name of the stream \bt_p{stream}.
+
+See the \ref api-tir-stream-prop-name "name" property.
+
+If \bt_p{stream} has no name, this function returns \c NULL.
+
+@param[in] stream
+    Stream of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{stream}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{stream}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_class_set_name() &mdash;
+    Sets the name of a stream.
+*/
+extern const char *bt_stream_get_name(const bt_stream *stream);
+
+/*!
+@brief
+    Sets the user attributes of the stream \bt_p{stream} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-stream-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default stream with bt_stream_create()
+    or bt_stream_create_with_id(), the stream's initial user
+    attributes is an empty \bt_map_val. Therefore you can borrow it with
+    bt_stream_borrow_user_attributes() and fill it directly
+    instead of setting a new one with this function.
+
+@param[in] stream
+    Stream of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{stream}.
+
+@bt_pre_not_null{stream}
+@bt_pre_hot{stream}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_stream_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a stream.
+*/
+extern void bt_stream_set_user_attributes(
+               bt_stream *stream, const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the stream \bt_p{stream}.
+
+See the \ref api-tir-stream-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default stream with bt_stream_create()
+    or bt_stream_create_with_id(), the stream's initial user
+    attributes is an empty \bt_map_val.
+
+@param[in] stream
+    Stream from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{stream} (a \bt_map_val).
+
+@bt_pre_not_null{stream}
+
+@sa bt_stream_set_user_attributes() &mdash;
+    Sets the user attributes of a stream.
+@sa bt_stream_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_stream_borrow_user_attributes(bt_stream *stream);
+
+/*!
+@brief
+    Borrows the user attributes of the stream \bt_p{stream}
+    (\c const version).
+
+See bt_stream_borrow_user_attributes().
+*/
+extern const bt_value *bt_stream_borrow_user_attributes_const(
+               const bt_stream *stream);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the stream \bt_p{stream}.
+
+@param[in] stream
+    @parblock
+    Stream of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_stream_put_ref() &mdash;
+    Decrements the reference count of a stream.
+*/
+extern void bt_stream_get_ref(const bt_stream *stream);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the stream \bt_p{stream}.
+
+@param[in] stream
+    @parblock
+    Stream of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_stream_get_ref() &mdash;
+    Increments the reference count of a stream.
+*/
+extern void bt_stream_put_ref(const bt_stream *stream);
+
+/*!
+@brief
+    Decrements the reference count of the stream
+    \bt_p{_stream}, and then sets \bt_p{_stream} to \c NULL.
+
+@param _stream
+    @parblock
+    Stream of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_stream}
+*/
+#define BT_STREAM_PUT_REF_AND_RESET(_stream)           \
+       do {                                            \
+               bt_stream_put_ref(_stream);             \
+               (_stream) = NULL;                       \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the stream \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a stream reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_STREAM_MOVE_REF(_dst, _src)         \
+       do {                                    \
+               bt_stream_put_ref(_dst);        \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/trace-ir/trace-class-const.h b/include/babeltrace2/trace-ir/trace-class-const.h
deleted file mode 100644 (file)
index 6ad9a9d..0000000
--- a/include/babeltrace2/trace-ir/trace-class-const.h
+++ /dev/null
@@ -1,98 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_CONST_H
-#define BABELTRACE2_TRACE_IR_TRACE_CLASS_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef void (* bt_trace_class_destruction_listener_func)(
-               const bt_trace_class *trace_class, void *data);
-
-extern const bt_value *bt_trace_class_borrow_user_attributes_const(
-               const bt_trace_class *trace_class);
-
-extern bt_bool bt_trace_class_assigns_automatic_stream_class_id(
-               const bt_trace_class *trace_class);
-
-extern uint64_t bt_trace_class_get_stream_class_count(
-               const bt_trace_class *trace_class);
-
-extern const bt_stream_class *
-bt_trace_class_borrow_stream_class_by_index_const(
-               const bt_trace_class *trace_class, uint64_t index);
-
-extern const bt_stream_class *bt_trace_class_borrow_stream_class_by_id_const(
-               const bt_trace_class *trace_class, uint64_t id);
-
-typedef enum bt_trace_class_add_listener_status {
-       BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK           = __BT_FUNC_STATUS_OK,
-} bt_trace_class_add_listener_status;
-
-extern bt_trace_class_add_listener_status
-bt_trace_class_add_destruction_listener(
-        const bt_trace_class *trace_class,
-        bt_trace_class_destruction_listener_func listener,
-        void *data, bt_listener_id *listener_id);
-
-typedef enum bt_trace_class_remove_listener_status {
-       BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK                = __BT_FUNC_STATUS_OK,
-} bt_trace_class_remove_listener_status;
-
-extern bt_trace_class_remove_listener_status
-bt_trace_class_remove_destruction_listener(
-        const bt_trace_class *trace_class, bt_listener_id listener_id);
-
-extern void bt_trace_class_get_ref(const bt_trace_class *trace_class);
-
-extern void bt_trace_class_put_ref(const bt_trace_class *trace_class);
-
-#define BT_TRACE_CLASS_PUT_REF_AND_RESET(_var)         \
-       do {                                            \
-               bt_trace_class_put_ref(_var);           \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_TRACE_CLASS_MOVE_REF(_var_dst, _var_src)    \
-       do {                                            \
-               bt_trace_class_put_ref(_var_dst);       \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_CONST_H */

diff --git a/include/babeltrace2/trace-ir/trace-class.h b/include/babeltrace2/trace-ir/trace-class.h
index d90ba2c9c825ce5c1308b29592f8b91b1185c008..3bfbe347823df323ebf8994de8b8ea7165560262 100644 (file)
--- a/include/babeltrace2/trace-ir/trace-class.h
+++ b/include/babeltrace2/trace-ir/trace-class.h
@@ -1,4 +1,4 @@
-#ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
+ #ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
 #define BABELTRACE2_TRACE_IR_TRACE_CLASS_H
 
 /*
@@ -35,23 +35,634 @@
 extern "C" {
 #endif
 
-extern bt_trace_class *bt_trace_class_create(bt_self_component *self_comp);
+/*!
+@defgroup api-tir-trace-cls Trace class
+@ingroup api-tir
 
-extern bt_value *bt_trace_class_borrow_user_attributes(
-               bt_trace_class *trace_class);
+@brief
+    Class of \bt_p_trace.
 
-extern void bt_trace_class_set_user_attributes(
-               bt_trace_class *trace_class, const bt_value *user_attributes);
+A <strong><em>trace class</em></strong> is the class of \bt_p_trace:
 
-extern void bt_trace_class_set_assigns_automatic_stream_class_id(
-               bt_trace_class *trace_class, bt_bool value);
+@image html trace-structure.png
+
+In the illustration above, notice that a trace is an instance of a
+trace class.
+
+A trace class is a \ref api-tir "trace IR" metadata object.
+
+A trace class is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_trace_class_get_ref() and put an existing
+reference with bt_trace_class_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" trace classes on
+success. The documentation of those functions indicate this
+postcondition. With a frozen trace class, you can still:
+
+- Create and add a \bt_p_stream_cls to it with
+  bt_stream_class_create() or bt_stream_class_create_with_id().
+- Add a destruction listener to it with
+  bt_trace_class_add_destruction_listener().
+
+The type of a trace class is #bt_trace_class.
+
+A trace class contains \bt_p_stream_cls. All the stream classes of a
+given trace class have unique
+\ref api-tir-stream-cls-prop-id "numeric IDs". Get the number of stream
+classes in a trace class with bt_trace_class_get_stream_class_count().
+Borrow a specific stream class from a trace class with
+bt_trace_class_borrow_stream_class_by_index(),
+bt_trace_class_borrow_stream_class_by_index_const(),
+bt_trace_class_borrow_stream_class_by_id(), or
+bt_trace_class_borrow_stream_class_by_id_const().
+
+Set whether or not the \bt_p_stream_cls you create for a trace class get
+automatic numeric IDs with
+bt_trace_class_set_assigns_automatic_stream_class_id().
+
+Create a default trace class from a \bt_self_comp with
+bt_trace_class_create().
+
+Add to and remove a destruction listener from a trace class with
+bt_trace_class_add_destruction_listener() and
+bt_trace_class_remove_destruction_listener().
+
+<h1>Properties</h1>
+
+A trace class has the following properties:
+
+<dl>
+  <dt>
+    \anchor api-tir-trace-cls-prop-auto-sc-id
+    Assigns automatic stream class IDs?
+  </dt>
+  <dd>
+    Whether or not the stream classes you create and add to the trace
+    class get \ref api-tir-stream-cls-prop-id "numeric IDs"
+    automatically.
+
+    Depending on the value of this property, to create a stream class
+    and add it to the trace class:
+
+    <dl>
+      <dt>#BT_TRUE</dt>
+      <dd>
+        Use bt_stream_class_create().
+      </dd>
+
+      <dt>#BT_FALSE</dt>
+      <dd>
+        Use bt_stream_class_create_with_id().
+      </dd>
+    </dl>
+
+    Use bt_trace_class_set_assigns_automatic_stream_class_id()
+    and bt_trace_class_assigns_automatic_stream_class_id().
+  </dd>
+
+  <dt>
+    \anchor api-tir-trace-cls-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the trace class.
+
+    User attributes are custom attributes attached to a trace class.
+
+    Use bt_trace_class_set_user_attributes(),
+    bt_trace_class_borrow_user_attributes(), and
+    bt_trace_class_borrow_user_attributes_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_trace_class bt_trace_class;
+
+@brief
+    Trace class.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a default trace class from the \bt_self_comp
+    \bt_p{self_component}.
+
+On success, the returned trace class has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?"
+    <td>Yes
+  <tr>
+    <td>\ref api-tir-trace-cls-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] self_component
+    Self component from which to create the default trace class.
 
+@returns
+    New trace class reference, or \c NULL on memory error.
+*/
+extern bt_trace_class *bt_trace_class_create(bt_self_component *self_component);
+
+/*! @} */
+
+/*!
+@name Stream class access
+@{
+*/
+
+/*!
+@brief
+    Returns the number of \bt_p_stream_cls contained in the trace
+    class \bt_p{trace_class}.
+
+@param[in] trace_class
+    Trace class of which to get the number of contained stream classes.
+
+@returns
+    Number of contained stream classes in \bt_p{trace_class}.
+
+@bt_pre_not_null{trace_class}
+*/
+extern uint64_t bt_trace_class_get_stream_class_count(
+               const bt_trace_class *trace_class);
+
+/*!
+@brief
+    Borrows the \bt_stream_cls at index \bt_p{index} from the
+    trace class \bt_p{trace_class}.
+
+@param[in] trace_class
+    Trace class from which to borrow the stream class at index
+    \bt_p{index}.
+@param[in] index
+    Index of the stream class to borrow from \bt_p{trace_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream class of
+    \bt_p{trace_class} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{trace_class}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{trace_class}
+@pre
+    \bt_p{index} is less than the number of stream classes in
+    \bt_p{trace_class} (as returned by
+    bt_trace_class_get_stream_class_count()).
+
+@sa bt_trace_class_get_stream_class_count() &mdash;
+    Returns the number of stream classes contained in a trace class.
+@sa bt_trace_class_borrow_stream_class_by_index_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_index(
                bt_trace_class *trace_class, uint64_t index);
 
+/*!
+@brief
+    Borrows the \bt_stream_cls at index \bt_p{index} from the
+    trace class \bt_p{trace_class} (\c const version).
+
+See bt_trace_class_borrow_stream_class_by_index().
+*/
+extern const bt_stream_class *
+bt_trace_class_borrow_stream_class_by_index_const(
+               const bt_trace_class *trace_class, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
+    trace class \bt_p{trace_class}.
+
+If there's no stream class having the numeric ID \bt_p{id} in
+\bt_p{trace_class}, this function returns \c NULL.
+
+@param[in] trace_class
+    Trace class from which to borrow the stream class having the
+    numeric ID \bt_p{id}.
+@param[in] id
+    ID of the stream class to borrow from \bt_p{trace_class}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream class of
+    \bt_p{trace_class} having the numeric ID \bt_p{id}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{trace_class}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{trace_class}
+
+@sa bt_trace_class_borrow_stream_class_by_id_const() &mdash;
+    \c const version of this function.
+*/
 extern bt_stream_class *bt_trace_class_borrow_stream_class_by_id(
                bt_trace_class *trace_class, uint64_t id);
 
+/*!
+@brief
+    Borrows the \bt_stream_cls having the numeric ID \bt_p{id} from the
+    trace class \bt_p{trace_class} (\c const version).
+
+See bt_trace_class_borrow_stream_class_by_id().
+*/
+extern const bt_stream_class *bt_trace_class_borrow_stream_class_by_id_const(
+               const bt_trace_class *trace_class, uint64_t id);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Sets whether or not the trace class \bt_p{trace_class} automatically
+    assigns a numeric ID to a \bt_stream_cls you create and add to it.
+
+See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
+property.
+
+@param[in] trace_class
+    Trace class of which to set whether or not it assigns automatic
+    stream class IDs.
+@param[in] assigns_automatic_stream_class_id
+    #BT_TRUE to make \bt_p{trace_class} assign automatic stream class
+    IDs.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_hot{trace_class}
+
+@sa bt_trace_class_assigns_automatic_stream_class_id() &mdash;
+    Returns whether or not a trace class automatically assigns
+    stream class IDs.
+*/
+extern void bt_trace_class_set_assigns_automatic_stream_class_id(
+               bt_trace_class *trace_class,
+               bt_bool assigns_automatic_stream_class_id);
+
+/*!
+@brief
+    Returns whether or not the trace class \bt_p{trace_class}
+    automatically assigns a numeric ID to a \bt_stream_cls you create
+    and add to it.
+
+See the \ref api-tir-trace-cls-prop-auto-sc-id "assigns automatic stream class IDs?"
+property.
+
+@param[in] trace_class
+    Trace class of which to get whether or not it assigns automatic
+    stream class IDs.
+
+@returns
+    #BT_TRUE if \bt_p{trace_class} automatically
+    assigns stream class IDs.
+
+@bt_pre_not_null{trace_class}
+
+@sa bt_trace_class_set_assigns_automatic_stream_class_id() &mdash;
+    Sets whether or not a trace class automatically assigns
+    stream class IDs.
+*/
+extern bt_bool bt_trace_class_assigns_automatic_stream_class_id(
+               const bt_trace_class *trace_class);
+
+/*!
+@brief
+    Sets the user attributes of the trace class \bt_p{trace_class} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default trace class with bt_trace_class_create()
+    or bt_trace_class_create_with_id(), the trace class's initial user
+    attributes is an empty \bt_map_val. Therefore you can borrow it with
+    bt_trace_class_borrow_user_attributes() and fill it directly
+    instead of setting a new one with this function.
+
+@param[in] trace_class
+    Trace class of which to set the user attributes to
+    \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{trace_class}.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_hot{trace_class}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_trace_class_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a trace class.
+*/
+extern void bt_trace_class_set_user_attributes(
+               bt_trace_class *trace_class, const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the trace class \bt_p{trace_class}.
+
+See the \ref api-tir-trace-cls-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default trace class with bt_trace_class_create()
+    or bt_trace_class_create_with_id(), the trace class's initial user
+    attributes is an empty \bt_map_val.
+
+@param[in] trace_class
+    Trace class from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{trace_class} (a \bt_map_val).
+
+@bt_pre_not_null{trace_class}
+
+@sa bt_trace_class_set_user_attributes() &mdash;
+    Sets the user attributes of a trace class.
+@sa bt_trace_class_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_trace_class_borrow_user_attributes(
+               bt_trace_class *trace_class);
+
+/*!
+@brief
+    Borrows the user attributes of the trace class \bt_p{trace_class}
+    (\c const version).
+
+See bt_trace_class_borrow_user_attributes().
+*/
+extern const bt_value *bt_trace_class_borrow_user_attributes_const(
+               const bt_trace_class *trace_class);
+
+/*! @} */
+
+/*!
+@name Listeners
+@{
+*/
+
+/*!
+@brief
+    User function for bt_trace_class_add_destruction_listener().
+
+This is the user function type for a trace class destruction listener.
+
+@param[in] trace_class
+    Trace class being destroyed (\ref api-fund-freezing "frozen").
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_trace_class_add_destruction_listener().
+
+@bt_pre_not_null{trace_class}
+
+@post
+    The reference count of \bt_p{trace_class} is not changed.
+@bt_post_no_error
+
+@sa bt_trace_class_add_destruction_listener() &mdash;
+    Adds a destruction listener to a trace class.
+*/
+typedef void (* bt_trace_class_destruction_listener_func)(
+               const bt_trace_class *trace_class, void *user_data);
+
+/*!
+@brief
+    Status codes for bt_trace_class_add_destruction_listener().
+*/
+typedef enum bt_trace_class_add_listener_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK           = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_trace_class_add_listener_status;
+
+/*!
+@brief
+    Adds a destruction listener having the function \bt_p{user_func}
+    to the trace class \bt_p{trace_class}.
+
+All the destruction listener user functions of a trace class are called
+when it's being destroyed.
+
+If \bt_p{listener_id} is not \c NULL, then this function, on success,
+sets \bt_p{*listener_id} to the ID of the added destruction listener
+within \bt_p{trace_class}. You can then use this ID to remove the
+added destruction listener with
+bt_trace_class_remove_destruction_listener().
+
+@param[in] trace_class
+    Trace class to add the destruction listener to.
+@param[in] user_func
+    User function of the destruction listener to add to
+    \bt_p{trace_class}.
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of
+    \bt_p{user_func}.
+@param[out] listener_id
+    <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+    is the ID of the added destruction listener within
+    \bt_p{trace_class}.
+
+@retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK
+    Success.
+@retval #BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_not_null{user_func}
+
+@sa bt_trace_class_remove_destruction_listener() &mdash;
+    Removes a destruction listener from a trace class.
+*/
+extern bt_trace_class_add_listener_status
+bt_trace_class_add_destruction_listener(
+        const bt_trace_class *trace_class,
+        bt_trace_class_destruction_listener_func user_func,
+        void *user_data, bt_listener_id *listener_id);
+
+/*!
+@brief
+    Status codes for bt_trace_class_remove_destruction_listener().
+*/
+typedef enum bt_trace_class_remove_listener_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_trace_class_remove_listener_status;
+
+/*!
+@brief
+    Removes the destruction listener having the ID \bt_p{listener_id}
+    from the trace class \bt_p{trace_class}.
+
+The destruction listener to remove from \bt_p{trace_class} was
+previously added with bt_trace_class_add_destruction_listener().
+
+You can call this function when \bt_p{trace_class} is
+\ref api-fund-freezing "frozen".
+
+@param[in] trace_class
+    Trace class from which to remove the destruction listener having
+    the ID \bt_p{listener_id}.
+@param[in] listener_id
+    ID of the destruction listener to remove from \bt_p{trace_class}­.
+
+@retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK
+    Success.
+@retval #BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{trace_class}
+@pre
+    \bt_p{listener_id} is the ID of an existing destruction listener
+    in \bt_p{trace_class}.
+
+@sa bt_trace_class_add_destruction_listener() &mdash;
+    Adds a destruction listener to a trace class.
+*/
+extern bt_trace_class_remove_listener_status
+bt_trace_class_remove_destruction_listener(
+        const bt_trace_class *trace_class, bt_listener_id listener_id);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the trace class \bt_p{trace_class}.
+
+@param[in] trace_class
+    @parblock
+    Trace class of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_trace_class_put_ref() &mdash;
+    Decrements the reference count of a trace class.
+*/
+extern void bt_trace_class_get_ref(const bt_trace_class *trace_class);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the trace class \bt_p{trace_class}.
+
+@param[in] trace_class
+    @parblock
+    Trace class of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_trace_class_get_ref() &mdash;
+    Increments the reference count of a trace class.
+*/
+extern void bt_trace_class_put_ref(const bt_trace_class *trace_class);
+
+/*!
+@brief
+    Decrements the reference count of the trace class
+    \bt_p{_trace_class}, and then sets \bt_p{_trace_class} to \c NULL.
+
+@param _trace_class
+    @parblock
+    Trace class of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_trace_class}
+*/
+#define BT_TRACE_CLASS_PUT_REF_AND_RESET(_trace_class)         \
+       do {                                                    \
+               bt_trace_class_put_ref(_trace_class);           \
+               (_trace_class) = NULL;                          \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the trace class \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a trace class reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_TRACE_CLASS_MOVE_REF(_dst, _src)    \
+       do {                                    \
+               bt_trace_class_put_ref(_dst);   \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/include/babeltrace2/trace-ir/trace-const.h b/include/babeltrace2/trace-ir/trace-const.h
deleted file mode 100644 (file)
index d4410a2..0000000
--- a/include/babeltrace2/trace-ir/trace-const.h
+++ /dev/null
@@ -1,107 +0,0 @@
-#ifndef BABELTRACE2_TRACE_IR_TRACE_CONST_H
-#define BABELTRACE2_TRACE_IR_TRACE_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef void (* bt_trace_destruction_listener_func)(
-               const bt_trace *trace, void *data);
-
-extern const bt_value *bt_trace_borrow_user_attributes_const(
-               const bt_trace *trace);
-
-extern const bt_trace_class *bt_trace_borrow_class_const(
-               const bt_trace *trace);
-
-extern const char *bt_trace_get_name(const bt_trace *trace);
-
-extern bt_uuid bt_trace_get_uuid(const bt_trace *trace);
-
-extern uint64_t bt_trace_get_environment_entry_count(const bt_trace *trace);
-
-extern void bt_trace_borrow_environment_entry_by_index_const(
-               const bt_trace *trace, uint64_t index,
-               const char **name, const bt_value **value);
-
-extern const bt_value *bt_trace_borrow_environment_entry_value_by_name_const(
-               const bt_trace *trace, const char *name);
-
-extern uint64_t bt_trace_get_stream_count(const bt_trace *trace);
-
-extern const bt_stream *bt_trace_borrow_stream_by_index_const(
-               const bt_trace *trace, uint64_t index);
-
-extern const bt_stream *bt_trace_borrow_stream_by_id_const(
-               const bt_trace *trace, uint64_t id);
-
-typedef enum bt_trace_add_listener_status {
-       BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_TRACE_ADD_LISTENER_STATUS_OK                 = __BT_FUNC_STATUS_OK,
-} bt_trace_add_listener_status;
-
-extern bt_trace_add_listener_status bt_trace_add_destruction_listener(
-               const bt_trace *trace,
-               bt_trace_destruction_listener_func listener,
-               void *data, bt_listener_id *listener_id);
-
-typedef enum bt_trace_remove_listener_status {
-       BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_TRACE_REMOVE_LISTENER_STATUS_OK              = __BT_FUNC_STATUS_OK,
-} bt_trace_remove_listener_status;
-
-extern bt_trace_remove_listener_status bt_trace_remove_destruction_listener(
-               const bt_trace *trace, bt_listener_id listener_id);
-
-extern void bt_trace_get_ref(const bt_trace *trace);
-
-extern void bt_trace_put_ref(const bt_trace *trace);
-
-#define BT_TRACE_PUT_REF_AND_RESET(_var)               \
-       do {                                            \
-               bt_trace_put_ref(_var);                 \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_TRACE_MOVE_REF(_var_dst, _var_src)          \
-       do {                                            \
-               bt_trace_put_ref(_var_dst);             \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_TRACE_IR_TRACE_CONST_H */

diff --git a/include/babeltrace2/trace-ir/trace.h b/include/babeltrace2/trace-ir/trace.h
index 4d17c48406ef9c9449643075d86745a6a612b015..a3f73dba82c77b8b5d5f1a87f72bbdf074dba593 100644 (file)
--- a/include/babeltrace2/trace-ir/trace.h
+++ b/include/babeltrace2/trace-ir/trace.h
@@ -35,43 +35,938 @@
 extern "C" {
 #endif
 
-extern bt_trace_class *bt_trace_borrow_class(bt_trace *trace);
+/*!
+@defgroup api-tir-trace Trace
+@ingroup api-tir
+
+@brief
+    Trace (set of \bt_p_stream).
+
+A <strong><em>trace</em></strong> is a set of \bt_p_stream with
+properties:
+
+@image html trace-structure.png
+
+In the illustration above, notice that a trace is an instance of a
+\bt_trace_cls and that it contains streams.
+
+Borrow the class of a trace with bt_trace_borrow_class() and
+bt_trace_borrow_class_const().
+
+A trace is a \ref api-tir "trace IR" data object.
+
+A trace is a \ref api-fund-shared-object "shared object": get a
+new reference with bt_trace_get_ref() and put an existing
+reference with bt_trace_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" traces on
+success. The documentation of those functions indicate this
+postcondition. With a frozen trace, you can still:
+
+- Create \bt_p_stream from it with bt_stream_create() or
+  bt_stream_create_with_id().
+- Add a destruction listener to it with
+  bt_trace_add_destruction_listener().
+
+The type of a trace is #bt_trace.
+
+A trace contains \bt_p_stream. All the streams of a
+given trace have unique \ref api-tir-stream-prop-id "numeric IDs".
+Get the number of streams in a trace with bt_trace_get_stream_count().
+Borrow a specific stream from a trace with
+bt_trace_borrow_stream_by_index(),
+bt_trace_borrow_stream_by_index_const(), bt_trace_borrow_stream_by_id(),
+or bt_trace_borrow_stream_by_id_const().
+
+Create a default trace from a \bt_trace_cls with bt_trace_create().
+
+Add to and remove a destruction listener from a trace with
+bt_trace_add_destruction_listener() and
+bt_trace_remove_destruction_listener().
+
+<h1>Properties</h1>
+
+A trace has the following properties:
+
+<dl>
+  <dt>
+    \anchor api-tir-trace-prop-name
+    \bt_dt_opt Name
+  </dt>
+  <dd>
+    Name of the trace.
+
+    Use bt_trace_set_name() and bt_trace_get_name().
+  </dd>
+
+  <dt>
+    \anchor api-tir-trace-prop-uuid
+    \bt_dt_opt UUID
+  </dt>
+  <dd>
+    <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
+    of the trace.
+
+    The trace's UUID uniquely identifies the trace.
+
+    Use bt_trace_set_uuid() and bt_trace_get_uuid().
+  </dd>
+
+  <dt>
+    \anchor api-tir-trace-prop-env
+    \bt_dt_opt Environment
+  </dt>
+  <dd>
+    Generic key-value store which describes the environment of the trace
+    (for example, the system's hostname, its network address, the
+    tracer's name and version, and the rest).
+
+    Trace environment keys are strings while values are signed integers
+    or strings.
+
+    Set a trace environment entry's value with
+    bt_trace_set_environment_entry_integer() and
+    bt_trace_set_environment_entry_string().
+
+    Get the number of environment entries in a trace with
+    bt_trace_get_environment_entry_count().
+
+    Borrow an environment entry from a trace with
+    bt_trace_borrow_environment_entry_value_by_name_const().
+  </dd>
+
+  <dt>
+    \anchor api-tir-trace-prop-user-attrs
+    \bt_dt_opt User attributes
+  </dt>
+  <dd>
+    User attributes of the trace.
 
+    User attributes are custom attributes attached to a trace.
+
+    Use bt_trace_set_user_attributes(),
+    bt_trace_borrow_user_attributes(), and
+    bt_trace_borrow_user_attributes_const().
+  </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_trace bt_trace;
+
+@brief
+    Trace.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+    Creates a default trace from the \bt_trace_cls \bt_p{trace_class}.
+
+This function instantiates \bt_p{trace_class}.
+
+On success, the returned trace has the following property values:
+
+<table>
+  <tr>
+    <th>Property
+    <th>Value
+  <tr>
+    <td>\ref api-tir-trace-prop-name "Name"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-trace-prop-uuid "UUID"
+    <td>\em None
+  <tr>
+    <td>\ref api-tir-trace-prop-env "Environment"
+    <td>Empty
+  <tr>
+    <td>\ref api-tir-trace-prop-user-attrs "User attributes"
+    <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+    Trace class from which to create the default trace.
+
+@returns
+    New trace reference, or \c NULL on memory error.
+*/
 extern bt_trace *bt_trace_create(bt_trace_class *trace_class);
 
-extern bt_value *bt_trace_borrow_user_attributes(bt_trace *trace);
+/*! @} */
 
-extern void bt_trace_set_user_attributes(
-               bt_trace *trace, const bt_value *user_attributes);
+/*!
+@name Class access
+@{
+*/
+
+/*!
+@brief
+    Borrows the \ref api-tir-trace-cls "class" of the trace
+    \bt_p{trace}.
+
+@param[in] trace
+    Trace of which to borrow the class.
+
+@returns
+    \em Borrowed reference of the class of \bt_p{trace}.
+
+@bt_pre_not_null{trace}
+
+@sa bt_trace_borrow_class_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_trace_class *bt_trace_borrow_class(bt_trace *trace);
+
+/*!
+@brief
+    Borrows the \ref api-tir-trace-cls "class" of the trace
+    \bt_p{trace} (\c const version).
+
+See bt_trace_borrow_class().
+*/
+extern const bt_trace_class *bt_trace_borrow_class_const(
+               const bt_trace *trace);
+
+/*! @} */
+
+/*!
+@name Stream access
+@{
+*/
 
+/*!
+@brief
+    Returns the number of \bt_p_stream contained in the trace
+    \bt_p{trace}.
+
+@param[in] trace
+    Trace of which to get the number of contained streams.
+
+@returns
+    Number of contained streams in \bt_p{trace}.
+
+@bt_pre_not_null{trace}
+*/
+extern uint64_t bt_trace_get_stream_count(const bt_trace *trace);
+
+/*!
+@brief
+    Borrows the \bt_stream at index \bt_p{index} from the
+    trace \bt_p{trace}.
+
+@param[in] trace
+    Trace from which to borrow the stream at index
+    \bt_p{index}.
+@param[in] index
+    Index of the stream to borrow from \bt_p{trace}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream of
+    \bt_p{trace} at index \bt_p{index}.
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{trace}
+@pre
+    \bt_p{index} is less than the number of streams in
+    \bt_p{trace} (as returned by
+    bt_trace_get_stream_count()).
+
+@sa bt_trace_get_stream_count() &mdash;
+    Returns the number of streams contained in a trace.
+@sa bt_trace_borrow_stream_by_index_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_stream *bt_trace_borrow_stream_by_index(bt_trace *trace,
+               uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_stream at index \bt_p{index} from the
+    trace \bt_p{trace} (\c const version).
+
+See bt_trace_borrow_stream_by_index().
+*/
+extern const bt_stream *bt_trace_borrow_stream_by_index_const(
+               const bt_trace *trace, uint64_t index);
+
+/*!
+@brief
+    Borrows the \bt_stream having the numeric ID \bt_p{id} from the
+    trace \bt_p{trace}.
+
+If there's no stream having the numeric ID \bt_p{id} in
+\bt_p{trace}, this function returns \c NULL.
+
+@param[in] trace
+    Trace from which to borrow the stream having the
+    numeric ID \bt_p{id}.
+@param[in] id
+    ID of the stream to borrow from \bt_p{trace}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the stream of
+    \bt_p{trace} having the numeric ID \bt_p{id}, or \c NULL
+    if none.
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    exists.
+    @endparblock
+
+@bt_pre_not_null{trace}
+
+@sa bt_trace_borrow_stream_by_id_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_stream *bt_trace_borrow_stream_by_id(bt_trace *trace,
+               uint64_t id);
+
+/*!
+@brief
+    Borrows the \bt_stream having the numeric ID \bt_p{id} from the
+    trace \bt_p{trace} (\c const version).
+
+See bt_trace_borrow_stream_by_id().
+*/
+extern const bt_stream *bt_trace_borrow_stream_by_id_const(
+               const bt_trace *trace, uint64_t id);
+
+/*! @} */
+
+/*!
+@name Properties
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_trace_set_name().
+*/
 typedef enum bt_trace_set_name_status {
-       BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_TRACE_SET_NAME_STATUS_OK             = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_trace_set_name_status;
 
+/*!
+@brief
+    Sets the name of the trace \bt_p{trace} to a copy of \bt_p{name}.
+
+See the \ref api-tir-trace-prop-name "name" property.
+
+@param[in] trace
+    Trace of which to set the name to \bt_p{name}.
+@param[in] name
+    New name of \bt_p{trace} (copied).
+
+@retval #BT_TRACE_SET_NAME_STATUS_OK
+    Success.
+@retval #BT_TRACE_SET_NAME_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{trace}
+@bt_pre_hot{trace}
+@bt_pre_not_null{name}
+
+@sa bt_trace_get_name() &mdash;
+    Returns the name of a trace.
+*/
 extern bt_trace_set_name_status bt_trace_set_name(bt_trace *trace,
                const char *name);
 
+/*!
+@brief
+    Returns the name of the trace \bt_p{trace}.
+
+See the \ref api-tir-trace-prop-name "name" property.
+
+If \bt_p{trace} has no name, this function returns \c NULL.
+
+@param[in] trace
+    Trace of which to get the name.
+
+@returns
+    @parblock
+    Name of \bt_p{trace}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{trace}
+
+@sa bt_trace_set_name() &mdash;
+    Sets the name of a trace.
+*/
+extern const char *bt_trace_get_name(const bt_trace *trace);
+
+/*!
+@brief
+    Sets the
+    <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>
+    of the trace \bt_p{trace} to a copy of \bt_p{uuid}.
+
+See the \ref api-tir-trace-prop-uuid "UUID" property.
+
+@param[in] trace
+    Trace of which to set the UUID to \bt_p{uuid}.
+@param[in] uuid
+    New UUID of \bt_p{trace} (copied).
+
+@bt_pre_not_null{trace}
+@bt_pre_hot{trace}
+@bt_pre_not_null{uuid}
+
+@sa bt_trace_get_uuid() &mdash;
+    Returns the UUID of a trace.
+*/
 extern void bt_trace_set_uuid(bt_trace *trace, bt_uuid uuid);
 
+/*!
+@brief
+    Returns the UUID of the trace \bt_p{trace}.
+
+See the \ref api-tir-trace-prop-uuid "UUID" property.
+
+If \bt_p{trace} has no UUID, this function returns \c NULL.
+
+@param[in] trace
+    Trace of which to get the UUID.
+
+@returns
+    @parblock
+    UUID of \bt_p{trace}, or \c NULL if none.
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{trace}
+
+@sa bt_trace_set_uuid() &mdash;
+    Sets the UUID of a trace.
+*/
+extern bt_uuid bt_trace_get_uuid(const bt_trace *trace);
+
+/*!
+@brief
+    Status codes for bt_trace_set_name().
+*/
 typedef enum bt_trace_set_environment_entry_status {
-       BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR      = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_trace_set_environment_entry_status;
 
+/*!
+@brief
+    Sets the value of the environment entry of the trace \bt_p{trace}
+    named \bt_p{name} to the signed integer \bt_p{value}.
+
+See the \ref api-tir-trace-prop-env "environment" property.
+
+On success, if \bt_p{trace} already contains an environment entry named
+\bt_p{name}, this function replaces the existing entry's value with
+\bt_p{value}.
+
+@param[in] trace
+    Trace in which to insert or replace an environment entry named
+    \bt_p{name} with the value \bt_p{value}.
+@param[in] name
+    Name of the entry to insert or replace in \bt_p{trace} (copied).
+@param[in] value
+    Value of the environment entry to insert or replace in \bt_p{trace}.
+
+@retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{trace}
+@bt_pre_hot{trace}
+@bt_pre_not_null{name}
+
+@sa bt_trace_set_environment_entry_string() &mdash;
+    Sets a trace environment entry's value to a string.
+*/
 extern bt_trace_set_environment_entry_status
 bt_trace_set_environment_entry_integer(bt_trace *trace, const char *name,
                int64_t value);
 
+/*!
+@brief
+    Sets the value of the environment entry of the trace \bt_p{trace}
+    named \bt_p{name} to the string \bt_p{value}.
+
+See the \ref api-tir-trace-prop-env "environment" property.
+
+On success, if \bt_p{trace} already contains an environment entry named
+\bt_p{name}, this function replaces the existing entry's value with
+\bt_p{value}.
+
+@param[in] trace
+    Trace in which to insert or replace an environment entry named
+    \bt_p{name} with the value \bt_p{value}.
+@param[in] name
+    Name of the entry to insert or replace in \bt_p{trace} (copied).
+@param[in] value
+    Value of the environment entry to insert or replace in \bt_p{trace}.
+
+@retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_TRACE_SET_ENVIRONMENT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{trace}
+@bt_pre_hot{trace}
+@bt_pre_not_null{name}
+@bt_pre_not_null{value}
+
+@sa bt_trace_set_environment_entry_integer() &mdash;
+    Sets a trace environment entry's value to a signed integer.
+*/
 extern bt_trace_set_environment_entry_status
 bt_trace_set_environment_entry_string(bt_trace *trace, const char *name,
                const char *value);
 
-extern bt_stream *bt_trace_borrow_stream_by_index(bt_trace *trace,
-               uint64_t index);
+/*!
+@brief
+    Returns the number of environment entries contained in the trace
+    \bt_p{trace}.
 
-extern bt_stream *bt_trace_borrow_stream_by_id(bt_trace *trace,
-               uint64_t id);
+See the \ref api-tir-trace-prop-env "environment" property.
+
+@param[in] trace
+    Trace of which to get the number of environment entries.
+
+@returns
+    Number of environment entries in \bt_p{trace}.
+
+@bt_pre_not_null{trace}
+*/
+extern uint64_t bt_trace_get_environment_entry_count(const bt_trace *trace);
+
+/*!
+@brief
+    Borrows the environment entry at index \bt_p{index} from the
+    trace \bt_p{trace}, setting \bt_p{*name} to its name and
+    \bt_p{*value} to its value.
+
+See the \ref api-tir-trace-prop-env "environment" property.
+
+@param[in] trace
+    Trace from which to borrow the environment entry at index
+    \bt_p{index}.
+@param[in] index
+    Index of the environment entry to borrow from \bt_p{trace}.
+@param[in] name
+    @parblock
+    <strong>On success</strong>, \bt_p{*name} is the name of the
+    environment entry at index \bt_p{index} in \bt_p{trace}.
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    is not modified.
+    @endparblock
+@param[in] value
+    @parblock
+    <strong>On success</strong>, \bt_p{*value} is a \em borrowed
+    reference of the environment entry at index \bt_p{index} in
+    \bt_p{trace}.
+
+    \bt_p{*value} is either a \bt_sint_val
+    (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
+    (#BT_VALUE_TYPE_STRING).
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{trace}
+@pre
+    \bt_p{index} is less than the number of environment entries in
+    \bt_p{trace} (as returned by
+    bt_trace_get_environment_entry_count()).
+@bt_pre_not_null{name}
+@bt_pre_not_null{value}
+
+@sa bt_trace_get_environment_entry_count() &mdash;
+    Returns the number of environment entries contained in a trace.
+*/
+extern void bt_trace_borrow_environment_entry_by_index_const(
+               const bt_trace *trace, uint64_t index,
+               const char **name, const bt_value **value);
+
+/*!
+@brief
+    Borrows the value of the environment entry named \bt_p{name}
+    in the trace \bt_p{trace}.
+
+See the \ref api-tir-trace-prop-env "environment" property.
+
+If there's no environment entry named \bt_p{name} in \bt_p{trace}, this
+function returns \c NULL.
+
+@param[in] trace
+    Trace from which to borrow the value of the environment entry
+    named \bt_p{name}.
+@param[in] name
+    Name of the environment entry to borrow from \bt_p{trace}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the value of the environment entry named
+    \bt_p{name} in \bt_p{trace}.
+
+    The returned value is either a \bt_sint_val
+    (#BT_VALUE_TYPE_SIGNED_INTEGER) or a \bt_string_val
+    (#BT_VALUE_TYPE_STRING).
+
+    The returned pointer remains valid as long as \bt_p{trace}
+    is not modified.
+    @endparblock
+
+@bt_pre_not_null{trace}
+@bt_pre_not_null{name}
+*/
+extern const bt_value *bt_trace_borrow_environment_entry_value_by_name_const(
+               const bt_trace *trace, const char *name);
+
+/*!
+@brief
+    Sets the user attributes of the trace \bt_p{trace} to
+    \bt_p{user_attributes}.
+
+See the \ref api-tir-trace-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default trace with bt_trace_create(), the trace's
+    initial user attributes is an empty \bt_map_val. Therefore you can
+    borrow it with bt_trace_borrow_user_attributes() and fill it
+    directly instead of setting a new one with this function.
+
+@param[in] trace
+    Trace of which to set the user attributes to \bt_p{user_attributes}.
+@param[in] user_attributes
+    New user attributes of \bt_p{trace}.
+
+@bt_pre_not_null{trace}
+@bt_pre_hot{trace}
+@bt_pre_not_null{user_attributes}
+@bt_pre_is_map_val{user_attributes}
+
+@sa bt_trace_borrow_user_attributes() &mdash;
+    Borrows the user attributes of a trace.
+*/
+extern void bt_trace_set_user_attributes(
+               bt_trace *trace, const bt_value *user_attributes);
+
+/*!
+@brief
+    Borrows the user attributes of the trace \bt_p{trace}.
+
+See the \ref api-tir-trace-prop-user-attrs "user attributes"
+property.
+
+@note
+    When you create a default trace with bt_trace_create(), the trace's
+    initial user attributes is an empty \bt_map_val.
+
+@param[in] trace
+    Trace from which to borrow the user attributes.
+
+@returns
+    User attributes of \bt_p{trace} (a \bt_map_val).
+
+@bt_pre_not_null{trace}
+
+@sa bt_trace_set_user_attributes() &mdash;
+    Sets the user attributes of a trace.
+@sa bt_trace_borrow_user_attributes_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_trace_borrow_user_attributes(bt_trace *trace);
+
+/*!
+@brief
+    Borrows the user attributes of the trace \bt_p{trace}
+    (\c const version).
+
+See bt_trace_borrow_user_attributes().
+*/
+extern const bt_value *bt_trace_borrow_user_attributes_const(
+               const bt_trace *trace);
+
+/*! @} */
+
+/*!
+@name Listeners
+@{
+*/
+
+/*!
+@brief
+    User function for bt_trace_add_destruction_listener().
+
+This is the user function type for a trace destruction listener.
+
+@param[in] trace
+    Trace being destroyed (\ref api-fund-freezing "frozen").
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_trace_add_destruction_listener().
+
+@bt_pre_not_null{trace}
+
+@post
+    The reference count of \bt_p{trace} is not changed.
+@bt_post_no_error
+
+@sa bt_trace_add_destruction_listener() &mdash;
+    Adds a destruction listener to a trace.
+*/
+typedef void (* bt_trace_destruction_listener_func)(
+               const bt_trace *trace, void *user_data);
+
+/*!
+@brief
+    Status codes for bt_trace_add_destruction_listener().
+*/
+typedef enum bt_trace_add_listener_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_TRACE_ADD_LISTENER_STATUS_OK                 = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_trace_add_listener_status;
+
+/*!
+@brief
+    Adds a destruction listener having the function \bt_p{user_func}
+    to the trace \bt_p{trace}.
+
+All the destruction listener user functions of a trace are called
+when it's being destroyed.
+
+If \bt_p{listener_id} is not \c NULL, then this function, on success,
+sets \bt_p{*listener_id} to the ID of the added destruction listener
+within \bt_p{trace}. You can then use this ID to remove the
+added destruction listener with bt_trace_remove_destruction_listener().
+
+@param[in] trace
+    Trace to add the destruction listener to.
+@param[in] user_func
+    User function of the destruction listener to add to
+    \bt_p{trace}.
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of
+    \bt_p{user_func}.
+@param[out] listener_id
+    <strong>On success and if not \c NULL</strong>, \bt_p{*listener_id}
+    is the ID of the added destruction listener within
+    \bt_p{trace}.
+
+@retval #BT_TRACE_ADD_LISTENER_STATUS_OK
+    Success.
+@retval #BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{trace}
+@bt_pre_not_null{user_func}
+
+@sa bt_trace_remove_destruction_listener() &mdash;
+    Removes a destruction listener from a trace.
+*/
+extern bt_trace_add_listener_status bt_trace_add_destruction_listener(
+               const bt_trace *trace,
+               bt_trace_destruction_listener_func user_func,
+               void *user_data, bt_listener_id *listener_id);
+
+/*!
+@brief
+    Status codes for bt_trace_remove_destruction_listener().
+*/
+typedef enum bt_trace_remove_listener_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_TRACE_REMOVE_LISTENER_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_trace_remove_listener_status;
+
+/*!
+@brief
+    Removes the destruction listener having the ID \bt_p{listener_id}
+    from the trace \bt_p{trace}.
+
+The destruction listener to remove from \bt_p{trace} was
+previously added with bt_trace_add_destruction_listener().
+
+You can call this function when \bt_p{trace} is
+\ref api-fund-freezing "frozen".
+
+@param[in] trace
+    Trace from which to remove the destruction listener having
+    the ID \bt_p{listener_id}.
+@param[in] listener_id
+    ID of the destruction listener to remove from \bt_p{trace}­.
+
+@retval #BT_TRACE_REMOVE_LISTENER_STATUS_OK
+    Success.
+@retval #BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{trace}
+@pre
+    \bt_p{listener_id} is the ID of an existing destruction listener
+    in \bt_p{trace}.
+
+@sa bt_trace_add_destruction_listener() &mdash;
+    Adds a destruction listener to a trace.
+*/
+extern bt_trace_remove_listener_status bt_trace_remove_destruction_listener(
+               const bt_trace *trace, bt_listener_id listener_id);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the trace \bt_p{trace}.
+
+@param[in] trace
+    @parblock
+    Trace of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_trace_put_ref() &mdash;
+    Decrements the reference count of a trace.
+*/
+extern void bt_trace_get_ref(const bt_trace *trace);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the trace \bt_p{trace}.
+
+@param[in] trace
+    @parblock
+    Trace of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_trace_get_ref() &mdash;
+    Increments the reference count of a trace.
+*/
+extern void bt_trace_put_ref(const bt_trace *trace);
+
+/*!
+@brief
+    Decrements the reference count of the trace
+    \bt_p{_trace}, and then sets \bt_p{_trace} to \c NULL.
+
+@param _trace
+    @parblock
+    Trace of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_trace}
+*/
+#define BT_TRACE_PUT_REF_AND_RESET(_trace)             \
+       do {                                            \
+               bt_trace_put_ref(_trace);               \
+               (_trace) = NULL;                        \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the trace \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a trace reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_TRACE_MOVE_REF(_dst, _src)          \
+       do {                                    \
+               bt_trace_put_ref(_dst);         \
+               (_dst) = (_src);                \
+               (_src) = NULL;                  \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/types.h b/include/babeltrace2/types.h
index 11c6e82425ae6681249f884efad90a7b47f8628f..521c603d522690abe035d73d46f437c6aa03333a 100644 (file)
--- a/include/babeltrace2/types.h
+++ b/include/babeltrace2/types.h
@@ -33,55 +33,6 @@
 extern "C" {
 #endif
 
-/**
-@defgroup ctypes Babeltrace C types
-@ingroup apiref
-@brief Babeltrace C types.
-
-@code
-#include <babeltrace2/types.h>
-@endcode
-
-This header contains custom type definitions used across the library.
-
-@file
-@brief Babeltrace C types.
-@sa ctypes
-
-@addtogroup ctypes
-@{
-*/
-
-/// False boolean value for the #bt_bool type.
-#define BT_FALSE       0
-
-/// True boolean value for the #bt_bool type.
-#define BT_TRUE                1
-
-/**
-@brief Babeltrace's boolean type.
-
-Use only the #BT_FALSE and #BT_TRUE definitions for #bt_bool parameters.
-It is guaranteed that the library functions which return a #bt_bool
-value return either #BT_FALSE or #BT_TRUE.
-
-You can always test the truthness of a #bt_bool value directly, without
-comparing it to #BT_TRUE directly:
-
-@code
-bt_bool ret = bt_some_function(...);
-
-if (ret) {
-       // ret is true
-}
-@endcode
-*/
-typedef int bt_bool;
-
-typedef uint64_t bt_listener_id;
-
-typedef const uint8_t *bt_uuid;
-
 typedef struct bt_clock_class bt_clock_class;
 typedef struct bt_clock_snapshot bt_clock_snapshot;
 typedef struct bt_component bt_component;
@@ -155,10 +106,96 @@ typedef struct bt_trace bt_trace;
 typedef struct bt_trace_class bt_trace_class;
 typedef struct bt_value bt_value;
 
-typedef const char * const *bt_field_class_enumeration_mapping_label_array;
-typedef const struct bt_message **bt_message_array_const;
+/*!
+@defgroup api-common-types Common C types
+
+@brief
+    C types common to many parts of the API.
+*/
+
+/*! @{ */
+
+/*!
+@brief
+    \em True value for #bt_bool.
+*/
+#define BT_TRUE                1
+
+/*!
+@brief
+    \em False value for #bt_bool.
+*/
+#define BT_FALSE       0
+
+/*!
+@brief
+    \bt_name boolean type.
+
+The API uses #bt_bool instead of the C99 \c bool type for
+<a href="https://en.wikipedia.org/wiki/Application_binary_interface">application binary interface</a>
+reasons.
+
+Use #BT_TRUE and #BT_FALSE to set and compare #bt_bool variables.
+*/
+typedef int bt_bool;
+
+/*!
+@brief
+    Numeric ID which identifies a user listener function.
+
+Some functions, such as bt_trace_add_destruction_listener(), return a
+listener ID when you add a user listener function to some object. You
+can then use this listener ID to remove the listener from the object.
+*/
+typedef uint64_t bt_listener_id;
+
+/*!
+@brief
+    A
+    <a href="https://en.wikipedia.org/wiki/Universally_unique_identifier">UUID</a>,
+    that is, an array of 16&nbsp;constant bytes.
+*/
+typedef uint8_t const *bt_uuid;
+
+/*!
+@brief
+    Availability of an object's property.
+
+Some getter functions of the API, such as
+bt_event_class_get_log_level(), return, by output parameter, an optional
+object property which is not a pointer. In that case, the function
+either:
+
+- Returns #BT_PROPERTY_AVAILABILITY_AVAILABLE and sets an output
+  parameter to the property's value.
+- Returns #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE.
+*/
+typedef enum bt_property_availability {
+       /*!
+       @brief
+           Property is available.
+       */
+       BT_PROPERTY_AVAILABILITY_AVAILABLE  = 1,
+
+       /*!
+       @brief
+           Property is not available.
+       */
+       BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE  = 0,
+} bt_property_availability;
+
+/*!
+@brief
+    Array of constant \bt_p_msg.
+
+Such an array is filled by the
+\link api-msg-iter-cls-meth-next "next" method\endlink of a
+\bt_msg_iter and consumed with bt_message_iterator_next() by another
+message iterator or by a \bt_sink_comp.
+*/
+typedef bt_message const **bt_message_array_const;
 
-/** @} */
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/util.h b/include/babeltrace2/util.h
index d4826541f4f7734d05f2921764745b74a9190d8b..6a76372dafdaa1d2fed3e9598d1f45951e7eb572 100644 (file)
--- a/include/babeltrace2/util.h
+++ b/include/babeltrace2/util.h
@@ -33,15 +33,113 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-util General purpose utilities
+
+@brief
+    General purpose utilities.
+
+This module contains general purpose utilities.
+*/
+
+/*! @{ */
+
+/*!
+@brief
+    Status codes for bt_util_clock_cycles_to_ns_from_origin().
+*/
 typedef enum bt_util_clock_cycles_to_ns_from_origin_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK                = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Integer overflow while computing the result.
+       */
        BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR    = __BT_FUNC_STATUS_OVERFLOW_ERROR,
 } bt_util_clock_cycles_to_ns_from_origin_status;
 
+/*!
+@brief
+    Converts the clock value \bt_p{cycles} from cycles to nanoseconds
+    from the clock's origin and sets \bt_p{*ns_from_origin} to the
+    result.
+
+This function considers the clock's frequency in Hz (\bt_p{frequency}),
+an offset from its origin in seconds (\bt_p{offset_seconds}) which
+can be negative, and an additional offset in cycles
+(\bt_p{offset_cycles}).
+
+This function:
+
+-# Converts the \bt_p{offset_cycles} value to seconds using
+   \bt_p{frequency}.
+-# Converts the \bt_p{cycles} value to seconds using \bt_p{frequency}.
+-# Adds the values of 1., 2., and \bt_p{offset_seconds}.
+-# Converts the value of 3. to nanoseconds and sets
+   \bt_p{*ns_from_origin} to this result.
+
+The following illustration shows the possible scenarios:
+
+@image html clock-terminology.png
+
+\bt_p{offset_seconds} can be negative. For example, considering:
+
+- A 1000 Hz clock.
+- \bt_p{offset_seconds} set to -10 seconds.
+- \bt_p{offset_cycles} set to 500 cycles
+  (that is, 0.5 seconds).
+- \bt_p{cycles} set to 2000 cycles (that is, 2 seconds).
+
+The computed value is -7.5 seconds, so this function sets
+\bt_p{*ns_from_origin} to -7,500,000,000.
+
+This function can fail and return the
+#BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
+code if any step of the computation process causes an integer overflow.
+
+@param[in] cycles
+    Clock's value (cycles).
+@param[in] frequency
+    Clock's frequency (Hz, or cycles/second).
+@param[in] offset_seconds
+    Offset, in seconds, from the clock's origin to add to
+    \bt_p{cycles} (once converted to seconds).
+@param[in] offset_cycles
+    Offset, in cycles, to add to \bt_p{cycles}.
+@param[out] ns_from_origin
+    <strong>On success</strong>, \bt_p{*ns_from_origin} is \bt_p{cycles}
+    converted to nanoseconds from origin considering the clock's
+    properties.
+
+@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
+    Success.
+@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
+    Integer overflow while computing the result.
+
+@pre
+    \bt_p{frequency} is not 0.
+@pre
+    \bt_p{frequency} is not <code>UINT64_C(-1)</code>.
+@pre
+    \bt_p{frequency} is greater than \bt_p{offset_cycles}.
+@pre
+    \bt_p{offset_cycles} is less than \bt_p{frequency}.
+@bt_pre_not_null{ns_from_origin}
+
+@sa bt_clock_class_cycles_to_ns_from_origin() &mdash;
+    Converts a stream clock value from cycles to nanoseconds from the
+    origin of a given clock class.
+*/
 bt_util_clock_cycles_to_ns_from_origin_status
 bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles,
                uint64_t frequency, int64_t offset_seconds,
-               uint64_t offset_cycles, int64_t *ns);
+               uint64_t offset_cycles, int64_t *ns_from_origin);
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/value-const.h b/include/babeltrace2/value-const.h
deleted file mode 100644 (file)
index f42f60d..0000000
--- a/include/babeltrace2/value-const.h
+++ /dev/null
@@ -1,214 +0,0 @@
-#ifndef BABELTRACE2_VALUE_CONST_H
-#define BABELTRACE2_VALUE_CONST_H
-
-/*
- * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
- *
- * 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.
- */
-
-#ifndef __BT_IN_BABELTRACE_H
-# error "Please include <babeltrace2/babeltrace.h> instead."
-#endif
-
-#include <stdint.h>
-#include <stddef.h>
-
-#include <babeltrace2/types.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum bt_value_type {
-       /// Null value object.
-       BT_VALUE_TYPE_NULL              = 1 << 0,
-
-       /// Boolean value object (holds #BT_TRUE or #BT_FALSE).
-       BT_VALUE_TYPE_BOOL              = 1 << 1,
-
-       BT_VALUE_TYPE_INTEGER           = 1 << 2,
-
-       /// Unsigned integer value object (holds an unsigned 64-bit integer raw value).
-       BT_VALUE_TYPE_UNSIGNED_INTEGER  = (1 << 3) | BT_VALUE_TYPE_INTEGER,
-
-       /// Signed integer value object (holds a signed 64-bit integer raw value).
-       BT_VALUE_TYPE_SIGNED_INTEGER    = (1 << 4) | BT_VALUE_TYPE_INTEGER,
-
-       /// Floating point number value object (holds a \c double raw value).
-       BT_VALUE_TYPE_REAL              = 1 << 5,
-
-       /// String value object.
-       BT_VALUE_TYPE_STRING            = 1 << 6,
-
-       /// Array value object.
-       BT_VALUE_TYPE_ARRAY             = 1 << 7,
-
-       /// Map value object.
-       BT_VALUE_TYPE_MAP               = 1 << 8,
-} bt_value_type;
-
-extern bt_value_type bt_value_get_type(const bt_value *object);
-
-static inline
-bt_bool bt_value_type_is(const bt_value_type type,
-               const bt_value_type type_to_check)
-{
-       return (type & type_to_check) == type_to_check;
-}
-
-static inline
-bt_bool bt_value_is_null(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_NULL;
-}
-
-static inline
-bt_bool bt_value_is_bool(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL;
-}
-
-static inline
-bt_bool bt_value_is_unsigned_integer(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_UNSIGNED_INTEGER;
-}
-
-static inline
-bt_bool bt_value_is_signed_integer(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_SIGNED_INTEGER;
-}
-
-static inline
-bt_bool bt_value_is_real(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_REAL;
-}
-
-static inline
-bt_bool bt_value_is_string(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_STRING;
-}
-
-static inline
-bt_bool bt_value_is_array(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY;
-}
-
-static inline
-bt_bool bt_value_is_map(const bt_value *object)
-{
-       return bt_value_get_type(object) == BT_VALUE_TYPE_MAP;
-}
-
-typedef enum bt_value_copy_status {
-       BT_VALUE_COPY_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_VALUE_COPY_STATUS_OK                 = __BT_FUNC_STATUS_OK,
-} bt_value_copy_status;
-
-extern bt_value_copy_status bt_value_copy(const bt_value *object,
-               bt_value **copy);
-
-extern bt_bool bt_value_is_equal(const bt_value *object_a,
-               const bt_value *object_b);
-
-extern bt_bool bt_value_bool_get(const bt_value *bool_obj);
-
-extern uint64_t bt_value_integer_unsigned_get(const bt_value *integer_obj);
-
-extern int64_t bt_value_integer_signed_get(const bt_value *integer_obj);
-
-extern double bt_value_real_get(const bt_value *real_obj);
-
-extern const char *bt_value_string_get(const bt_value *string_obj);
-
-extern uint64_t bt_value_array_get_length(const bt_value *array_obj);
-
-static inline
-bt_bool bt_value_array_is_empty(const bt_value *array_obj)
-{
-       return bt_value_array_get_length(array_obj) == 0;
-}
-
-extern const bt_value *bt_value_array_borrow_element_by_index_const(
-               const bt_value *array_obj, uint64_t index);
-
-extern uint64_t bt_value_map_get_size(const bt_value *map_obj);
-
-static inline
-bt_bool bt_value_map_is_empty(const bt_value *map_obj)
-{
-       return bt_value_map_get_size(map_obj) == 0;
-}
-
-extern const bt_value *bt_value_map_borrow_entry_value_const(
-               const bt_value *map_obj, const char *key);
-
-typedef enum bt_value_map_foreach_entry_const_func_status {
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK                 = __BT_FUNC_STATUS_OK,
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR              = __BT_FUNC_STATUS_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT          = __BT_FUNC_STATUS_INTERRUPTED,
-} bt_value_map_foreach_entry_const_func_status;
-
-typedef bt_value_map_foreach_entry_const_func_status
-               (* bt_value_map_foreach_entry_const_func)(const char *key,
-                       const bt_value *object, void *data);
-
-typedef enum bt_value_map_foreach_entry_const_status {
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK              = __BT_FUNC_STATUS_OK,
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR      = __BT_FUNC_STATUS_USER_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED     = __BT_FUNC_STATUS_INTERRUPTED,
-} bt_value_map_foreach_entry_const_status;
-
-extern bt_value_map_foreach_entry_const_status bt_value_map_foreach_entry_const(
-               const bt_value *map_obj,
-               bt_value_map_foreach_entry_const_func func, void *data);
-
-extern bt_bool bt_value_map_has_entry(const bt_value *map_obj,
-               const char *key);
-
-extern void bt_value_get_ref(const bt_value *value);
-
-extern void bt_value_put_ref(const bt_value *value);
-
-#define BT_VALUE_PUT_REF_AND_RESET(_var)               \
-       do {                                            \
-               bt_value_put_ref(_var);                 \
-               (_var) = NULL;                          \
-       } while (0)
-
-#define BT_VALUE_MOVE_REF(_var_dst, _var_src)          \
-       do {                                            \
-               bt_value_put_ref(_var_dst);             \
-               (_var_dst) = (_var_src);                \
-               (_var_src) = NULL;                      \
-       } while (0)
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* BABELTRACE2_VALUE_CONST_H */

diff --git a/include/babeltrace2/value.h b/include/babeltrace2/value.h
index 42e3cf96dd22496c406b7aaf2506ca9e67ed41e0..1bf683b5ce5037161c8e00862cc1076190307de6 100644 (file)
--- a/include/babeltrace2/value.h
+++ b/include/babeltrace2/value.h
@@ -31,166 +31,2435 @@
 #include <stddef.h>
 
 #include <babeltrace2/types.h>
-#include <babeltrace2/value-const.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/*!
+@defgroup api-val Values
+
+@brief
+    Generic, JSON-like basic data containers.
+
+<strong><em>Values</em></strong> are generic data containers. Except for
+the fact that integer values are explicitly unsigned or signed because
+of typing limitations,
+\bt_name values are very similar to <a href="https://json.org/">JSON</a>
+values.
+
+The value API is completely independent from the rest of the
+\bt_api.
+
+\bt_c_comp initialization parameters, \ref bt_query_executor_create()
+"query" parameters, as well as trace IR user attributes (for example,
+bt_event_class_set_user_attributes()) use values.
+
+The available value types are:
+
+<dl>
+  <dt>Scalar values</dt>
+  <dd>
+    - Null
+    - Boolean
+    - Unsigned integer (64-bit range)
+    - Signed integer (64-bit range)
+    - Real (\c double range)
+    - String
+  </dd>
+
+  <dt>Container values</dt>
+  <dd>
+     - Array
+     - Map (string to value)
+  </dd>
+</dl>
+
+Values are \ref api-fund-shared-object "shared objects": get a new
+reference with bt_value_get_ref() and put an existing reference with
+bt_value_put_ref().
+
+Some library functions \ref api-fund-freezing "freeze" values on
+success. The documentation of those functions indicate this
+postcondition.
+
+All the value types share the same C type, #bt_value.
+
+Get the type enumerator of a value with bt_value_get_type(). Get whether
+or not a value type conceptually \em is a given type with the inline
+bt_value_type_is() function. Get whether or not a value has a specific
+type with one of the <code>bt_value_is_*()</code> inline helpers.
+
+The \em null value is special in that it's a singleton variable,
+#bt_value_null. You can directly compare any value pointer to
+#bt_value_null to check if it's a null value. Like other types of
+values, the null value is a shared object: if you get a new null value
+reference, you must eventually put it.
+
+Create a value with one of the <code>bt_value_*_create()</code> or
+<code>bt_value_*_create_init()</code> functions.
+
+This documentation names the actual data that a scalar value wraps the
+<em>raw value</em>.
+
+Set and get the raw values of scalar values with functions that are
+named <code>bt_value_*_set()</code> and <code>bt_value_*_get()</code>.
+
+Check that two values are recursively equal with bt_value_is_equal().
+
+Deep-copy a value with bt_value_copy().
+
+Extend a map value with bt_value_map_extend().
+
+The following table shows the available functions and types for each
+type of value:
+
+<table>
+  <tr>
+    <th>Name
+    <th>Type enumerator
+    <th>Type query function
+    <th>Creation functions
+    <th>Writing functions
+    <th>Reading functions
+  <tr>
+    <th>\em Null
+    <td>#BT_VALUE_TYPE_NULL
+    <td>bt_value_is_null()
+    <td>\em N/A (use the #bt_value_null variable directly)
+    <td>\em N/A
+    <td>\em N/A
+  <tr>
+    <th>\em Boolean
+    <td>#BT_VALUE_TYPE_BOOL
+    <td>bt_value_is_bool()
+    <td>
+      bt_value_bool_create()<br>
+      bt_value_bool_create_init()
+    <td>bt_value_bool_set()
+    <td>bt_value_bool_get()
+  <tr>
+    <th><em>Unsigned integer</em>
+    <td>#BT_VALUE_TYPE_UNSIGNED_INTEGER
+    <td>bt_value_is_unsigned_integer()
+    <td>
+      bt_value_integer_unsigned_create()<br>
+      bt_value_integer_unsigned_create_init()
+    <td>bt_value_integer_unsigned_set()
+    <td>bt_value_integer_unsigned_get()
+  <tr>
+    <th><em>Signed integer</em>
+    <td>#BT_VALUE_TYPE_SIGNED_INTEGER
+    <td>bt_value_is_signed_integer()
+    <td>
+      bt_value_integer_signed_create()<br>
+      bt_value_integer_signed_create_init()
+    <td>bt_value_integer_signed_set()
+    <td>bt_value_integer_signed_get()
+  <tr>
+    <th>\em Real
+    <td>#BT_VALUE_TYPE_REAL
+    <td>bt_value_is_real()
+    <td>
+      bt_value_real_create()<br>
+      bt_value_real_create_init()
+    <td>bt_value_real_set()
+    <td>bt_value_real_get()
+  <tr>
+    <th>\em String
+    <td>#BT_VALUE_TYPE_STRING
+    <td>bt_value_is_string()
+    <td>
+      bt_value_string_create()<br>
+      bt_value_string_create_init()
+    <td>bt_value_string_set()
+    <td>bt_value_string_get()
+  <tr>
+    <th>\em Array
+    <td>#BT_VALUE_TYPE_ARRAY
+    <td>bt_value_is_array()
+    <td>
+      bt_value_array_create()
+    <td>
+      bt_value_array_append_element()<br>
+      bt_value_array_append_bool_element()<br>
+      bt_value_array_append_unsigned_integer_element()<br>
+      bt_value_array_append_signed_integer_element()<br>
+      bt_value_array_append_real_element()<br>
+      bt_value_array_append_string_element()<br>
+      bt_value_array_append_empty_array_element()<br>
+      bt_value_array_append_empty_map_element()<br>
+      bt_value_array_set_element_by_index()
+    <td>
+      bt_value_array_get_length()<br>
+      bt_value_array_is_empty()<br>
+      bt_value_array_borrow_element_by_index()<br>
+      bt_value_array_borrow_element_by_index_const()
+  <tr>
+    <th>\em Map
+    <td>#BT_VALUE_TYPE_MAP
+    <td>bt_value_is_map()
+    <td>
+      bt_value_map_create()
+    <td>
+      bt_value_map_insert_entry()<br>
+      bt_value_map_insert_bool_entry()<br>
+      bt_value_map_insert_unsigned_integer_entry()<br>
+      bt_value_map_insert_signed_integer_entry()<br>
+      bt_value_map_insert_real_entry()<br>
+      bt_value_map_insert_string_entry()<br>
+      bt_value_map_insert_empty_array_entry()<br>
+      bt_value_map_insert_empty_map_entry()<br>
+      bt_value_map_extend()
+    <td>
+      bt_value_map_get_size()<br>
+      bt_value_map_is_empty()<br>
+      bt_value_map_has_entry()<br>
+      bt_value_map_borrow_entry_value()<br>
+      bt_value_map_borrow_entry_value_const()<br>
+      bt_value_map_foreach_entry()<br>
+      bt_value_map_foreach_entry_const()
+</table>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_value bt_value;
+
+@brief
+    Value.
+
+@}
+*/
+
+/*!
+@name Type query
+@{
+*/
+
+/*!
+@brief
+    Value type enumerators.
+*/
+typedef enum bt_value_type {
+       /*!
+       @brief
+           Null value.
+       */
+       BT_VALUE_TYPE_NULL              = 1 << 0,
+
+       /*!
+       @brief
+           Boolean value.
+       */
+       BT_VALUE_TYPE_BOOL              = 1 << 1,
+
+       /*!
+       @brief
+           Integer value.
+
+       No value has this type: use it with bt_value_type_is().
+       */
+       BT_VALUE_TYPE_INTEGER           = 1 << 2,
+
+       /*!
+       @brief
+           Unsigned integer value.
+
+       This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
+       */
+       BT_VALUE_TYPE_UNSIGNED_INTEGER  = (1 << 3) | BT_VALUE_TYPE_INTEGER,
+
+       /*!
+       @brief
+           Signed integer value.
+
+       This type conceptually inherits #BT_VALUE_TYPE_INTEGER.
+       */
+       BT_VALUE_TYPE_SIGNED_INTEGER    = (1 << 4) | BT_VALUE_TYPE_INTEGER,
+
+       /*!
+       @brief
+           Real value.
+       */
+       BT_VALUE_TYPE_REAL              = 1 << 5,
+
+       /*!
+       @brief
+           String value.
+       */
+       BT_VALUE_TYPE_STRING            = 1 << 6,
+
+       /*!
+       @brief
+           Array value.
+       */
+       BT_VALUE_TYPE_ARRAY             = 1 << 7,
+
+       /*!
+       @brief
+           Map value.
+       */
+       BT_VALUE_TYPE_MAP               = 1 << 8,
+} bt_value_type;
+
+/*!
+@brief
+    Returns the type enumerator of the value \bt_p{value}.
+
+@param[in] value
+    Value of which to get the type enumerator
+
+@returns
+    Type enumerator of \bt_p{value}.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+@sa bt_value_is_null() &mdash;
+    Returns whether or not a value is a null value.
+@sa bt_value_is_bool() &mdash;
+    Returns whether or not a value is a boolean value.
+@sa bt_value_is_unsigned_integer() &mdash;
+    Returns whether or not a value is an unsigned integer value.
+@sa bt_value_is_signed_integer() &mdash;
+    Returns whether or not a value is a signed integer value.
+@sa bt_value_is_real() &mdash;
+    Returns whether or not a value is a real value.
+@sa bt_value_is_string() &mdash;
+    Returns whether or not a value is a string value.
+@sa bt_value_is_array() &mdash;
+    Returns whether or not a value is an array value.
+@sa bt_value_is_map() &mdash;
+    Returns whether or not a value is a map value.
+*/
+extern bt_value_type bt_value_get_type(const bt_value *value);
+
+/*!
+@brief
+    Returns whether or not the value type \bt_p{type} conceptually
+    \em is the value type \bt_p{other_type}.
+
+For example, an unsigned integer value conceptually \em is an integer
+value, so
+
+@code
+bt_value_type_is(BT_VALUE_TYPE_UNSIGNED_INTEGER, BT_VALUE_TYPE_INTEGER)
+@endcode
+
+returns #BT_TRUE.
+
+@param[in] type
+    Value type to check against \bt_p{other_type}.
+@param[in] other_type
+    Value type against which to check \bt_p{type}.
+
+@returns
+    #BT_TRUE if \bt_p{type} conceptually \em is \bt_p{other_type}.
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_is_null() &mdash;
+    Returns whether or not a value is a null value.
+@sa bt_value_is_bool() &mdash;
+    Returns whether or not a value is a boolean value.
+@sa bt_value_is_unsigned_integer() &mdash;
+    Returns whether or not a value is an unsigned integer value.
+@sa bt_value_is_signed_integer() &mdash;
+    Returns whether or not a value is a signed integer value.
+@sa bt_value_is_real() &mdash;
+    Returns whether or not a value is a real value.
+@sa bt_value_is_string() &mdash;
+    Returns whether or not a value is a string value.
+@sa bt_value_is_array() &mdash;
+    Returns whether or not a value is an array value.
+@sa bt_value_is_map() &mdash;
+    Returns whether or not a value is a map value.
+*/
+static inline
+bt_bool bt_value_type_is(const bt_value_type type,
+               const bt_value_type other_type)
+{
+       return (type & other_type) == other_type;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is a null value.
+
+@note
+    Because all null values point to the same null value singleton, you
+    can also directly compare \bt_p{value} to the #bt_value_null
+    variable.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is a null value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+@sa #bt_value_null &mdash;
+    The null value singleton.
+*/
+static inline
+bt_bool bt_value_is_null(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_NULL;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is a boolean value.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is a boolean value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+*/
+static inline
+bt_bool bt_value_is_bool(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_BOOL;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is an unsigned integer
+    value.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is an unsigned integer value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+*/
+static inline
+bt_bool bt_value_is_unsigned_integer(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_UNSIGNED_INTEGER;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is a signed integer
+    value.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is a signed integer value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+*/
+static inline
+bt_bool bt_value_is_signed_integer(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_SIGNED_INTEGER;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is a real value.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is a real value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+*/
+static inline
+bt_bool bt_value_is_real(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_REAL;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is a string value.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is a string value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+*/
+static inline
+bt_bool bt_value_is_string(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_STRING;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is an array value.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is an array value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+*/
+static inline
+bt_bool bt_value_is_array(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_ARRAY;
+}
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{value} is a map value.
+
+@param[in] value
+    Value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is a map value.
+
+@bt_pre_not_null{value}
+
+@sa bt_value_get_type() &mdash;
+    Returns the type enumerator of a value.
+@sa bt_value_type_is() &mdash;
+    Returns whether or not the type of a value conceptually is a given
+    type.
+*/
+static inline
+bt_bool bt_value_is_map(const bt_value *value)
+{
+       return bt_value_get_type(value) == BT_VALUE_TYPE_MAP;
+}
+
+/*! @} */
+
+/*!
+@name Null value
+@{
+*/
+
+/*!
+@brief
+    The null value singleton.
+
+This is the \em only instance of a null value.
+
+Like any type of value, the null value is a shared object: if you get a
+new null value reference with bt_value_get_ref(), you must eventually
+put it with bt_value_put_ref(). The null value singleton's reference
+count must never reach 0: libbabeltrace2 logs a warning message when
+this programming error occurs.
+
+Because all null values point to the same null value singleton, you can
+directly compare a value to the \c bt_value_null variable.
+
+@attention
+    @parblock
+    \c bt_value_null is different from \c NULL: the former is a true
+    \bt_name value object while the latter is a C definition which
+    usually means "no pointer".
+
+    For example, bt_value_map_borrow_entry_value() can return
+    \c bt_value_null if the requested key is mapped to a null value, but
+    it can also return \c NULL if the key is not found.
+    @endparblock
+
+@sa bt_value_is_null() &mdash;
+    Returns whether or not a value is a null value.
+*/
 extern bt_value *const bt_value_null;
 
+/*! @} */
+
+/*!
+@name Boolean value
+@{
+*/
+
+/*!
+@brief
+    Creates and returns a boolean value initialized to #BT_FALSE.
+
+The returned value has the type #BT_VALUE_TYPE_BOOL.
+
+@returns
+    New boolean value reference, or \c NULL on memory error.
+
+@sa bt_value_bool_create_init() &mdash;
+    Creates a boolean value with a given initial raw value.
+*/
 extern bt_value *bt_value_bool_create(void);
 
-extern bt_value *bt_value_bool_create_init(bt_bool val);
+/*!
+@brief
+    Creates and returns a boolean value initialized to \bt_p{raw_value}.
+
+The returned value has the type #BT_VALUE_TYPE_BOOL.
+
+@param[in] raw_value
+    Initial raw value of the boolean value to create.
+
+@returns
+    New boolean value reference, or \c NULL on memory error.
+
+@sa bt_value_bool_create() &mdash;
+    Creates a boolean value initialized to #BT_FALSE.
+*/
+extern bt_value *bt_value_bool_create_init(bt_bool raw_value);
+
+/*!
+@brief
+    Sets the raw value of the boolean value \bt_p{value} to
+    \bt_p{raw_value}.
+
+@param[in] value
+    Boolean value of which to set the raw value to \bt_p{raw_value}.
+@param[in] raw_value
+    New raw value of \bt_p{value}.
 
-extern void bt_value_bool_set(bt_value *bool_obj, bt_bool val);
+@bt_pre_not_null{value}
+@bt_pre_is_bool_val{value}
+@bt_pre_hot{value}
 
+@sa bt_value_bool_get() &mdash;
+    Returns the raw value of a boolean value.
+*/
+extern void bt_value_bool_set(bt_value *value, bt_bool raw_value);
+
+/*!
+@brief
+    Returns the raw value of the boolean value \bt_p{value}.
+
+@param[in] value
+    Boolean value of which to get the raw value.
+
+@returns
+    Raw value of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_bool_val{value}
+
+@sa bt_value_bool_set() &mdash;
+    Sets the raw value of a boolean value.
+*/
+extern bt_bool bt_value_bool_get(const bt_value *value);
+
+/*! @} */
+
+/*!
+@name Unsigned integer value
+@{
+*/
+
+/*!
+@brief
+    Creates and returns an unsigned integer value initialized to 0.
+
+The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
+
+@returns
+    New unsigned integer value reference, or \c NULL on memory error.
+
+@sa bt_value_integer_unsigned_create_init() &mdash;
+    Creates an unsigned integer value with a given initial raw value.
+*/
 extern bt_value *bt_value_integer_unsigned_create(void);
 
-extern bt_value *bt_value_integer_unsigned_create_init(uint64_t val);
+/*!
+@brief
+    Creates and returns an unsigned integer value initialized to
+    \bt_p{raw_value}.
+
+The returned value has the type #BT_VALUE_TYPE_UNSIGNED_INTEGER.
+
+@param[in] raw_value
+    Initial raw value of the unsigned integer value to create.
+
+@returns
+    New unsigned integer value reference, or \c NULL on memory error.
+
+@sa bt_value_bool_create() &mdash;
+    Creates an unsigned integer value initialized to 0.
+*/
+extern bt_value *bt_value_integer_unsigned_create_init(uint64_t raw_value);
 
-extern void bt_value_integer_unsigned_set(bt_value *integer_obj, uint64_t val);
+/*!
+@brief
+    Sets the raw value of the unsigned integer value \bt_p{value} to
+    \bt_p{raw_value}.
 
+@param[in] value
+    Unsigned integer value of which to set the raw value to
+    \bt_p{raw_value}.
+@param[in] raw_value
+    New raw value of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_uint_val{value}
+@bt_pre_hot{value}
+
+@sa bt_value_integer_unsigned_get() &mdash;
+    Returns the raw value of an unsigned integer value.
+*/
+extern void bt_value_integer_unsigned_set(bt_value *value,
+               uint64_t raw_value);
+
+/*!
+@brief
+    Returns the raw value of the unsigned integer value \bt_p{value}.
+
+@param[in] value
+    Unsigned integer value of which to get the raw value.
+
+@returns
+    Raw value of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_uint_val{value}
+
+@sa bt_value_integer_unsigned_set() &mdash;
+    Sets the raw value of an unsigned integer value.
+*/
+extern uint64_t bt_value_integer_unsigned_get(const bt_value *value);
+
+/*! @} */
+
+/*!
+@name Signed integer value
+@{
+*/
+
+/*!
+@brief
+    Creates and returns a signed integer value initialized to 0.
+
+The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
+
+@returns
+    New signed integer value reference, or \c NULL on memory error.
+
+@sa bt_value_integer_signed_create_init() &mdash;
+    Creates a signed integer value with a given initial raw value.
+*/
 extern bt_value *bt_value_integer_signed_create(void);
 
-extern bt_value *bt_value_integer_signed_create_init(int64_t val);
+/*!
+@brief
+    Creates and returns a signed integer value initialized to
+    \bt_p{raw_value}.
+
+The returned value has the type #BT_VALUE_TYPE_SIGNED_INTEGER.
+
+@param[in] raw_value
+    Initial raw value of the signed integer value to create.
 
-extern void bt_value_integer_signed_set(bt_value *integer_obj, int64_t val);
+@returns
+    New signed integer value reference, or \c NULL on memory error.
 
+@sa bt_value_bool_create() &mdash;
+    Creates a signed integer value initialized to 0.
+*/
+extern bt_value *bt_value_integer_signed_create_init(int64_t raw_value);
+
+/*!
+@brief
+    Sets the raw value of the signed integer value \bt_p{value} to
+    \bt_p{raw_value}.
+
+@param[in] value
+    Signed integer value of which to set the raw value to
+    \bt_p{raw_value}.
+@param[in] raw_value
+    New raw value of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_sint_val{value}
+@bt_pre_hot{value}
+
+@sa bt_value_integer_signed_get() &mdash;
+    Returns the raw value of a signed integer value.
+*/
+extern void bt_value_integer_signed_set(bt_value *value, int64_t raw_value);
+
+/*!
+@brief
+    Returns the raw value of the signed integer value \bt_p{value}.
+
+@param[in] value
+    Signed integer value of which to get the raw value.
+
+@returns
+    Raw value of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_sint_val{value}
+
+@sa bt_value_integer_signed_set() &mdash;
+    Sets the raw value of a signed integer value.
+*/
+extern int64_t bt_value_integer_signed_get(const bt_value *value);
+
+/*! @} */
+
+/*!
+@name Real value
+@{
+*/
+
+/*!
+@brief
+    Creates and returns a real value initialized to 0.
+
+The returned value has the type #BT_VALUE_TYPE_REAL.
+
+@returns
+    New real value reference, or \c NULL on memory error.
+
+@sa bt_value_real_create_init() &mdash;
+    Creates a real value with a given initial raw value.
+*/
 extern bt_value *bt_value_real_create(void);
 
-extern bt_value *bt_value_real_create_init(double val);
+/*!
+@brief
+    Creates and returns a real value initialized to \bt_p{raw_value}.
+
+The returned value has the type #BT_VALUE_TYPE_REAL.
+
+@param[in] raw_value
+    Initial raw value of the real value to create.
+
+@returns
+    New real value reference, or \c NULL on memory error.
+
+@sa bt_value_real_create() &mdash;
+    Creates a real value initialized to 0.
+*/
+extern bt_value *bt_value_real_create_init(double raw_value);
+
+/*!
+@brief
+    Sets the raw value of the real value \bt_p{value} to
+    \bt_p{raw_value}.
+
+@param[in] value
+    Real value of which to set the raw value to \bt_p{raw_value}.
+@param[in] raw_value
+    New raw value of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_real_val{value}
+@bt_pre_hot{value}
+
+@sa bt_value_real_get() &mdash;
+    Returns the raw value of a real value.
+*/
+extern void bt_value_real_set(bt_value *value, double raw_value);
+
+/*!
+@brief
+    Returns the raw value of the real value \bt_p{value}.
+
+@param[in] value
+    Real value of which to get the raw value.
+
+@returns
+    Raw value of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_real_val{value}
+
+@sa bt_value_real_set() &mdash;
+    Sets the raw value of a real value.
+*/
+extern double bt_value_real_get(const bt_value *value);
+
+/*! @} */
+
+/*!
+@name String value
+@{
+*/
 
-extern void bt_value_real_set(bt_value *real_obj, double val);
+/*!
+@brief
+    Creates and returns an empty string value.
 
+The returned value has the type #BT_VALUE_TYPE_STRING.
+
+@returns
+    New string value reference, or \c NULL on memory error.
+
+@sa bt_value_string_create_init() &mdash;
+    Creates a string value with a given initial raw value.
+*/
 extern bt_value *bt_value_string_create(void);
 
-extern bt_value *bt_value_string_create_init(const char *val);
+/*!
+@brief
+    Creates and returns a string value initialized to a copy of
+    \bt_p{raw_value}.
+
+The returned value has the type #BT_VALUE_TYPE_STRING.
+
+@param[in] raw_value
+    Initial raw value of the string value to create (copied).
 
+@returns
+    New string value reference, or \c NULL on memory error.
+
+@bt_pre_not_null{raw_value}
+
+@sa bt_value_string_create() &mdash;
+    Creates an empty string value.
+*/
+extern bt_value *bt_value_string_create_init(const char *raw_value);
+
+/*!
+@brief
+    Status codes for bt_value_string_set().
+*/
 typedef enum bt_value_string_set_status {
-       BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_VALUE_STRING_SET_STATUS_OK           = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_value_string_set_status;
 
-extern bt_value_string_set_status bt_value_string_set(bt_value *string_obj,
-               const char *val);
+/*!
+@brief
+    Sets the raw value of the string value \bt_p{value} to a copy of
+    \bt_p{raw_value}.
 
-extern bt_value *bt_value_array_create(void);
+@param[in] value
+    String value of which to set the raw value to a copy of
+    \bt_p{raw_value}.
+@param[in] raw_value
+    New raw value of \bt_p{value} (copied).
 
-extern bt_value *bt_value_array_borrow_element_by_index(bt_value *array_obj,
-               uint64_t index);
+@retval #BT_VALUE_STRING_SET_STATUS_OK
+    Success.
+@retval #BT_VALUE_STRING_SET_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_string_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{raw_value}
+
+@sa bt_value_string_get() &mdash;
+    Returns the raw value of a string value.
+*/
+extern bt_value_string_set_status bt_value_string_set(bt_value *value,
+               const char *raw_value);
+
+/*!
+@brief
+    Returns the raw value of the string value \bt_p{value}.
 
+@param[in] value
+    String value of which to get the raw value.
+
+@returns
+    @parblock
+    Raw value of \bt_p{value}.
+
+    The returned pointer remains valid until \bt_p{value} is modified.
+    @endparblock
+
+@bt_pre_not_null{value}
+@bt_pre_is_string_val{value}
+
+@sa bt_value_string_set() &mdash;
+    Sets the raw value of a string value.
+*/
+extern const char *bt_value_string_get(const bt_value *value);
+
+/*! @} */
+
+/*!
+@name Array value
+@{
+*/
+
+/*!
+@brief
+    Creates and returns an empty array value.
+
+The returned value has the type #BT_VALUE_TYPE_ARRAY.
+
+@returns
+    New array value reference, or \c NULL on memory error.
+*/
+extern bt_value *bt_value_array_create(void);
+
+/*!
+@brief
+    Status codes for the <code>bt_value_array_append_*()</code>
+    functions.
+*/
 typedef enum bt_value_array_append_element_status {
-       BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK                 = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_value_array_append_element_status;
 
+/*!
+@brief
+    Appends the value \bt_p{element_value} to the array value \bt_p{value}.
+
+To append a null value, pass #bt_value_null as \bt_p{element_value}.
+
+@param[in] value
+    Array value to which to append \bt_p{element_value}.
+@param[in] element_value
+    Value to append to \bt_p{value}.
+
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{element_value}
+@pre
+    \bt_p{element_value} does not contain \bt_p{value}, recursively.
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_bool_element() &mdash;
+    Creates and appends a boolean value to an array value.
+@sa bt_value_array_append_unsigned_integer_element() &mdash;
+    Creates and appends an unsigned integer value to an array value.
+@sa bt_value_array_append_signed_integer_element() &mdash;
+    Creates and appends a signed integer value to an array value.
+@sa bt_value_array_append_real_element() &mdash;
+    Creates and appends a real value to an array value.
+@sa bt_value_array_append_string_element() &mdash;
+    Creates and appends a string value to an array value.
+@sa bt_value_array_append_empty_array_element() &mdash;
+    Creates and appends an empty array value to an array value.
+@sa bt_value_array_append_empty_map_element() &mdash;
+    Creates and appends an empty map value to an array value.
+*/
 extern bt_value_array_append_element_status bt_value_array_append_element(
-               bt_value *array_obj, bt_value *element_obj);
+               bt_value *value, bt_value *element_value);
+
+/*!
+@brief
+    Creates a boolean value initialized to \bt_p{raw_value} and appends
+    it to the array value \bt_p{value}.
+
+@param[in] value
+    Array value to which to append the created boolean value.
+@param[in] raw_value
+    Raw value of the boolean value to create and append to \bt_p{value}.
+
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
 
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_element() &mdash;
+    Appends an existing value to an array value.
+*/
 extern bt_value_array_append_element_status
-bt_value_array_append_bool_element(bt_value *array_obj, bt_bool val);
+bt_value_array_append_bool_element(bt_value *value, bt_bool raw_value);
+
+/*!
+@brief
+    Creates an unsigned integer value initialized to \bt_p{raw_value}
+    and appends it to the array value \bt_p{value}.
+
+@param[in] value
+    Array value to which to append the created unsigned integer value.
+@param[in] raw_value
+    Raw value of the unsigned integer value to create and append to
+    \bt_p{value}.
+
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
 
+@sa bt_value_array_append_element() &mdash;
+    Appends an existing value to an array value.
+*/
 extern bt_value_array_append_element_status
-bt_value_array_append_unsigned_integer_element(bt_value *array_obj,
-               uint64_t val);
+bt_value_array_append_unsigned_integer_element(bt_value *value,
+               uint64_t raw_value);
 
+/*!
+@brief
+    Creates a signed integer value initialized to \bt_p{raw_value} and
+    appends it to the array value \bt_p{value}.
+
+@param[in] value
+    Array value to which to append the created signed integer value.
+@param[in] raw_value
+    Raw value of the signed integer value to create and append to
+    \bt_p{value}.
+
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_element() &mdash;
+    Appends an existing value to an array value.
+*/
 extern bt_value_array_append_element_status
-bt_value_array_append_signed_integer_element(bt_value *array_obj, int64_t val);
+bt_value_array_append_signed_integer_element(bt_value *value,
+               int64_t raw_value);
+
+/*!
+@brief
+    Creates a real value initialized to \bt_p{raw_value} and appends
+    it to the array value \bt_p{value}.
+
+@param[in] value
+    Array value to which to append the created real value.
+@param[in] raw_value
+    Raw value of the real value to create and append to \bt_p{value}.
 
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_element() &mdash;
+    Appends an existing value to an array value.
+*/
 extern bt_value_array_append_element_status
-bt_value_array_append_real_element(bt_value *array_obj, double val);
+bt_value_array_append_real_element(bt_value *value, double raw_value);
+
+/*!
+@brief
+    Creates a string value initialized to a copy of \bt_p{raw_value} and
+    appends it to the array value \bt_p{value}.
+
+@param[in] value
+    Array value to which to append the created string value.
+@param[in] raw_value
+    Raw value of the string value to create and append to \bt_p{value}
+    (copied).
+
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
 
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_element() &mdash;
+    Appends an existing value to an array value.
+*/
 extern bt_value_array_append_element_status
-bt_value_array_append_string_element(bt_value *array_obj, const char *val);
+bt_value_array_append_string_element(bt_value *value, const char *raw_value);
+
+/*!
+@brief
+    Creates an empty array value and appends it to the array
+    value \bt_p{value}.
+
+On success, if \bt_p{element_value} is not \c NULL, this function sets
+\bt_p{*element_value} to a \em borrowed reference of the created empty
+array value.
+
+@param[in] value
+    Array value to which to append the created empty array value.
+@param[out] element_value
+    <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
+    is a \em borrowed reference of the created empty array value.
 
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_element() &mdash;
+    Appends an existing value to an array value.
+*/
 extern bt_value_array_append_element_status
-bt_value_array_append_empty_array_element(bt_value *array_obj,
-               bt_value **element_obj);
+bt_value_array_append_empty_array_element(bt_value *value,
+               bt_value **element_value);
+
+/*!
+@brief
+    Creates an empty map value and appends it to the array
+    value \bt_p{value}.
 
+On success, if \bt_p{element_value} is not \c NULL, this function sets
+\bt_p{*element_value} to a \em borrowed reference of the created empty
+map value.
+
+@param[in] value
+    Array value to which to append the created empty array value.
+@param[out] element_value
+    <strong>On success, if not \c NULL</strong>, \bt_p{*element_value}
+    is a \em borrowed reference of the created empty map value.
+
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_APPEND_ELEMENT_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_element() &mdash;
+    Appends an existing value to an array value.
+*/
 extern bt_value_array_append_element_status
-bt_value_array_append_empty_map_element(bt_value *array_obj,
-               bt_value **element_obj);
+bt_value_array_append_empty_map_element(bt_value *value,
+               bt_value **element_value);
 
+/*!
+@brief
+    Status codes for bt_value_array_set_element_by_index().
+*/
 typedef enum bt_value_array_set_element_by_index_status {
-       BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK           = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_value_array_set_element_by_index_status;
 
+/*!
+@brief
+    Sets the element of the array value \bt_p{value} at index
+    \bt_p{index} to the value \bt_p{element_value}.
+
+On success, this function replaces the existing element of \bt_p{value}
+at index \bt_p{index}.
+
+@param[in] value
+    Array value of which to set the element at index \bt_p{index}.
+@param[in] index
+    Index of the element to set in \bt_p{value}.
+@param[in] element_value
+    Value to set as the element of \bt_p{value} at index \bt_p{index}.
+
+@retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_OK
+    Success.
+@retval #BT_VALUE_ARRAY_SET_ELEMENT_BY_INDEX_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_hot{value}
+@pre
+    \bt_p{index} is less than the length of \bt_p{value} (as returned by
+    bt_value_array_get_length()).
+@bt_pre_not_null{element_value}
+@pre
+    \bt_p{element_value} does not contain \bt_p{value}, recursively.
+
+@post
+    <strong>On success</strong>, the length of \bt_p{value} is
+    incremented.
+
+@sa bt_value_array_append_element() &mdash;
+    Appends a value to an array value.
+*/
 extern bt_value_array_set_element_by_index_status
-bt_value_array_set_element_by_index(bt_value *array_obj, uint64_t index,
-               bt_value *element_obj);
+bt_value_array_set_element_by_index(bt_value *value, uint64_t index,
+               bt_value *element_value);
+
+/*!
+@brief
+    Borrows the element at index \bt_p{index} from the array value
+    \bt_p{value}.
+
+@param[in] value
+    Array value from which to borrow the element at index \bt_p{index}.
+@param[in] index
+    Index of the element to borrow from \bt_p{value}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the element of \bt_p{value} at index
+    \bt_p{index}.
+
+    The returned pointer remains valid until \bt_p{value} is modified.
+    @endparblock
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@pre
+    \bt_p{index} is less than the length of \bt_p{value} (as returned by
+    bt_value_array_get_length()).
+
+@sa bt_value_array_borrow_element_by_index_const() &mdash;
+    \c const version of this function.
+*/
+extern bt_value *bt_value_array_borrow_element_by_index(bt_value *value,
+               uint64_t index);
+
+/*!
+@brief
+    Borrows the element at index \bt_p{index} from the array value
+    \bt_p{value} (\c const version).
 
+See bt_value_array_borrow_element_by_index().
+*/
+extern const bt_value *bt_value_array_borrow_element_by_index_const(
+               const bt_value *value, uint64_t index);
+
+/*!
+@brief
+    Returns the length of the array value \bt_p{value}.
+
+@param[in] value
+    Array value of which to get the length.
+
+@returns
+    Length (number of contained elements) of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+
+@sa bt_value_array_is_empty() &mdash;
+    Returns whether or not an array value is empty.
+*/
+extern uint64_t bt_value_array_get_length(const bt_value *value);
+
+/*!
+@brief
+    Returns whether or not the array value \bt_p{value} is empty.
+
+@param[in] value
+    Array value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is empty (has the length&nbsp;0).
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+
+@sa bt_value_array_get_length() &mdash;
+    Returns the length of an array value.
+*/
+static inline
+bt_bool bt_value_array_is_empty(const bt_value *value)
+{
+       return bt_value_array_get_length(value) == 0;
+}
+
+/*! @} */
+
+/*!
+@name Map value
+@{
+*/
+
+/*!
+@brief
+    Creates and returns an empty map value.
+
+The returned value has the type #BT_VALUE_TYPE_MAP.
+
+@returns
+    New map value reference, or \c NULL on memory error.
+*/
 extern bt_value *bt_value_map_create(void);
 
+/*!
+@brief
+    Status codes for the <code>bt_value_map_insert_*()</code> functions.
+*/
+typedef enum bt_value_map_insert_entry_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK             = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_value_map_insert_entry_status;
+
+/*!
+@brief
+    Inserts or replaces an entry with the key \bt_p{key} and the value
+    \bt_p{entry_value} in the map value \bt_p{value}.
+
+To insert an entry having a null value, pass #bt_value_null as
+\bt_p{entry_value}.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with
+\bt_p{entry_value}.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and value \bt_p{entry_value}.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[in] entry_value
+    Value of the entry to insert or replace in \bt_p{value}.
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+@bt_pre_not_null{entry_value}
+@pre
+    \bt_p{entry_value} does not contain \bt_p{value}, recursively.
+
+@sa bt_value_map_insert_bool_entry() &mdash;
+    Creates a boolean value and uses it to insert an entry in a map
+    value.
+@sa bt_value_map_insert_unsigned_integer_entry() &mdash;
+    Creates an unsigned integer value and uses it to insert an entry in
+    a map value.
+@sa bt_value_map_insert_signed_integer_entry() &mdash;
+    Creates a signed value and uses it to insert an entry in a map
+    value.
+@sa bt_value_map_insert_real_entry() &mdash;
+    Creates a real value and uses it to insert an entry in a map value.
+@sa bt_value_map_insert_string_entry() &mdash;
+    Creates a string value and uses it to insert an entry in a map
+    value.
+@sa bt_value_map_insert_empty_array_entry() &mdash;
+    Creates an empty array value and uses it to insert an entry in a map
+    value.
+@sa bt_value_map_insert_empty_map_entry() &mdash;
+    Creates a map value and uses it to insert an entry in a map value.
+*/
+extern bt_value_map_insert_entry_status bt_value_map_insert_entry(
+               bt_value *value, const char *key, bt_value *entry_value);
+
+/*!
+@brief
+    Creates a boolean value initialized to \bt_p{raw_value} and
+    inserts or replaces an entry with the key \bt_p{key} and this value
+    in the map value \bt_p{value}.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with the
+created boolean value.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and the created boolean value.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[in] raw_value
+    Initial raw value of the boolean value to create.
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_insert_entry() &mdash;
+    Inserts an entry with an existing value in a map value.
+*/
+extern bt_value_map_insert_entry_status bt_value_map_insert_bool_entry(
+               bt_value *value, const char *key, bt_bool raw_value);
+
+/*!
+@brief
+    Creates an unsigned integer value initialized to \bt_p{raw_value}
+    and inserts or replaces an entry with the key \bt_p{key} and this
+    value in the map value \bt_p{value}.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with the
+created unsigned integer value.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and the created unsigned integer value.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[in] raw_value
+    Initial raw value of the unsigned integer value to create.
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_insert_entry() &mdash;
+    Inserts an entry with an existing value in a map value.
+*/
+extern bt_value_map_insert_entry_status
+bt_value_map_insert_unsigned_integer_entry(bt_value *value, const char *key,
+               uint64_t raw_value);
+
+/*!
+@brief
+    Creates a signed integer value initialized to \bt_p{raw_value} and
+    inserts or replaces an entry with the key \bt_p{key} and this value
+    in the map value \bt_p{value}.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with the
+created signed integer value.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and the created signed integer value.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[in] raw_value
+    Initial raw value of the signed integer value to create.
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_insert_entry() &mdash;
+    Inserts an entry with an existing value in a map value.
+*/
+extern bt_value_map_insert_entry_status
+bt_value_map_insert_signed_integer_entry(bt_value *value, const char *key,
+               int64_t raw_value);
+
+/*!
+@brief
+    Creates a real value initialized to \bt_p{raw_value} and inserts or
+    replaces an entry with the key \bt_p{key} and this value in the map
+    value \bt_p{value}.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with the
+created real value.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and the created real value.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[in] raw_value
+    Initial raw value of the real value to create.
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_insert_entry() &mdash;
+    Inserts an entry with an existing value in a map value.
+*/
+extern bt_value_map_insert_entry_status bt_value_map_insert_real_entry(
+               bt_value *value, const char *key, double raw_value);
+
+/*!
+@brief
+    Creates a string value initialized to a copy of \bt_p{raw_value} and
+    inserts or replaces an entry with the key \bt_p{key} and this value
+    in the map value \bt_p{value}.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with the
+created string value.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and the created string value.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[in] raw_value
+    Initial raw value of the string value to create (copied).
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_insert_entry() &mdash;
+    Inserts an entry with an existing value in a map value.
+*/
+extern bt_value_map_insert_entry_status
+bt_value_map_insert_string_entry(bt_value *value, const char *key,
+               const char *raw_value);
+
+/*!
+@brief
+    Creates an empty array value and inserts or replaces an entry with
+    the key \bt_p{key} and this value in the map value \bt_p{value}.
+
+On success, if \bt_p{entry_value} is not \c NULL, this function sets
+\bt_p{*entry_value} to a \em borrowed reference of the created empty
+array value.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with the
+created empty array value.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and the created empty array value.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[out] entry_value
+    <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
+    a \em borrowed reference of the created empty array value.
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_insert_entry() &mdash;
+    Inserts an entry with an existing value in a map value.
+*/
+extern bt_value_map_insert_entry_status
+bt_value_map_insert_empty_array_entry(bt_value *value, const char *key,
+               bt_value **entry_value);
+
+/*!
+@brief
+    Creates an empty map value and inserts or replaces an entry with
+    the key \bt_p{key} and this value in the map value \bt_p{value}.
+
+On success, if \bt_p{entry_value} is not \c NULL, this function sets
+\bt_p{*entry_value} to a \em borrowed reference of the created empty map
+value.
+
+On success, if \bt_p{value} already contains an entry with key
+\bt_p{key}, this function replaces the existing entry's value with the
+created empty map value.
+
+@param[in] value
+    Map value in which to insert or replace an entry with key \bt_p{key}
+    and the created empty map value.
+@param[in] key
+    Key of the entry to insert or replace in \bt_p{value} (copied).
+@param[out] entry_value
+    <strong>On success, if not \c NULL</strong>, \bt_p{*entry_value} is
+    a \em borrowed reference of the created empty map value.
+
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_hot{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_insert_entry() &mdash;
+    Inserts an entry with an existing value in a map value.
+*/
+extern bt_value_map_insert_entry_status
+bt_value_map_insert_empty_map_entry(bt_value *value, const char *key,
+               bt_value **entry_value);
+
+/*!
+@brief
+    Borrows the value of the entry with the key \bt_p{key} in the map
+    value \bt_p{value}.
+
+If no entry with key \bt_p{key} exists in \bt_p{value}, this function
+returns \c NULL.
+
+@param[in] value
+    Map value from which to borrow the value of the entry with the
+    key \bt_p{key}.
+@param[in] key
+    Key of the entry from which to borrow the value in \bt_p{value}.
+
+@returns
+    @parblock
+    \em Borrowed reference of the value of the entry with key \bt_p{key}
+    in \bt_p{value}, or \c NULL if none.
+
+    The returned pointer remains valid until \bt_p{value} is modified.
+    @endparblock
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_borrow_entry_value_const() &mdash;
+    \c const version of this function.
+@sa bt_value_map_has_entry() &mdash;
+    Returns whether or not a map value has an entry with a given key.
+*/
 extern bt_value *bt_value_map_borrow_entry_value(
-               bt_value *map_obj, const char *key);
+               bt_value *value, const char *key);
+
+/*!
+@brief
+    Borrows the value of the entry with the key \bt_p{key} in the map
+    value \bt_p{value} (\c const version).
+
+See bt_value_map_borrow_entry_value().
+*/
+extern const bt_value *bt_value_map_borrow_entry_value_const(
+               const bt_value *value, const char *key);
 
+/*!
+@brief
+    Status codes for #bt_value_map_foreach_entry_func.
+*/
 typedef enum bt_value_map_foreach_entry_func_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK               = __BT_FUNC_STATUS_OK,
-       BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Interrupt the iteration process.
+       */
        BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT        = __BT_FUNC_STATUS_INTERRUPTED,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           User error.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
 } bt_value_map_foreach_entry_func_status;
 
+/*!
+@brief
+    User function for bt_value_map_foreach_entry().
+
+This is the type of the user function that bt_value_map_foreach_entry()
+calls for each entry of the map value.
+
+@param[in] key
+    Key of the map value entry.
+@param[in] value
+    Value of the map value entry.
+@param[in] user_data
+    User data, as passed as the \bt_p{user_data} parameter of
+    bt_value_map_foreach_entry().
+
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT
+    Interrupt the iteration process.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR
+    User error.
+
+@bt_pre_not_null{key}
+@bt_pre_not_null{value}
+
+@sa bt_value_map_foreach_entry() &mdash;
+    Iterates the entries of a map value.
+*/
 typedef bt_value_map_foreach_entry_func_status
                (* bt_value_map_foreach_entry_func)(const char *key,
-                       bt_value *object, void *data);
+                       bt_value *value, void *user_data);
 
+/*!
+@brief
+    Status codes for bt_value_map_foreach_entry().
+*/
 typedef enum bt_value_map_foreach_entry_status {
+       /*!
+       @brief
+           Success.
+       */
        BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK            = __BT_FUNC_STATUS_OK,
-       BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR    = __BT_FUNC_STATUS_USER_ERROR,
+
+       /*!
+       @brief
+           User function interrupted the iteration process.
+       */
        BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED   = __BT_FUNC_STATUS_INTERRUPTED,
+
+       /*!
+       @brief
+           User function error.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR    = __BT_FUNC_STATUS_USER_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR  = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR         = __BT_FUNC_STATUS_ERROR,
 } bt_value_map_foreach_entry_status;
 
+/*!
+@brief
+    Iterates the entries of the map value \bt_p{value}, calling
+    \bt_p{user_func} for each entry.
+
+This function iterates the entries of \bt_p{value} in no particular
+order.
+
+@attention
+    You must \em not modify \bt_p{value} during the iteration process.
+
+\bt_p{user_func} receives \bt_p{user_data} as its last parameter.
+
+The iteration process stops when one of:
+
+- \bt_p{user_func} was called for each entry.
+- \bt_p{user_func} does not return
+  #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_OK.
+
+@param[in] value
+    Map value of which to iterate the entries.
+@param[in] user_func
+    User function to call for each entry of \bt_p{value}.
+@param[in] user_data
+    User data to pass as the \bt_p{user_data} parameter of each call to
+    \bt_p{user_func}.
+
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_INTERRUPTED
+    \bt_p{user_func} returned
+    #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_INTERRUPT to interrupt the
+    iteration process.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_USER_ERROR
+    \bt_p{user_func} returned
+    #BT_VALUE_MAP_FOREACH_ENTRY_FUNC_STATUS_ERROR.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_STATUS_ERROR
+    Other error caused the <code>bt_value_map_foreach_entry()</code>
+    function itself.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_not_null{user_func}
+
+@sa bt_value_map_foreach_entry_const() &mdash;
+    \c const version of this function.
+@sa bt_value_map_borrow_entry_value() &mdash;
+    Borrows the value of a specific map value entry.
+*/
 extern bt_value_map_foreach_entry_status bt_value_map_foreach_entry(
-               bt_value *map_obj, bt_value_map_foreach_entry_func func,
-               void *data);
+               bt_value *value, bt_value_map_foreach_entry_func user_func,
+               void *user_data);
 
-typedef enum bt_value_map_insert_entry_status {
-       BT_VALUE_MAP_INSERT_ENTRY_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
-       BT_VALUE_MAP_INSERT_ENTRY_STATUS_OK             = __BT_FUNC_STATUS_OK,
-} bt_value_map_insert_entry_status;
+/*!
+@brief
+    Status codes for #bt_value_map_foreach_entry_const_func.
+*/
+typedef enum bt_value_map_foreach_entry_const_func_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK                 = __BT_FUNC_STATUS_OK,
 
-extern bt_value_map_insert_entry_status bt_value_map_insert_entry(
-               bt_value *map_obj, const char *key, bt_value *element_obj);
+       /*!
+       @brief
+           Interrupt the iteration process.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT          = __BT_FUNC_STATUS_INTERRUPTED,
 
-extern bt_value_map_insert_entry_status bt_value_map_insert_bool_entry(
-               bt_value *map_obj, const char *key, bt_bool val);
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR       = __BT_FUNC_STATUS_MEMORY_ERROR,
 
-extern bt_value_map_insert_entry_status
-bt_value_map_insert_unsigned_integer_entry(bt_value *map_obj, const char *key,
-               uint64_t val);
+       /*!
+       @brief
+           User error.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR              = __BT_FUNC_STATUS_ERROR,
+} bt_value_map_foreach_entry_const_func_status;
 
-extern bt_value_map_insert_entry_status
-bt_value_map_insert_signed_integer_entry(bt_value *map_obj, const char *key,
-               int64_t val);
+/*!
+@brief
+    User function for bt_value_map_foreach_entry_const_func().
 
-extern bt_value_map_insert_entry_status bt_value_map_insert_real_entry(
-               bt_value *map_obj, const char *key, double val);
+This is the type of the user function that
+bt_value_map_foreach_entry_const_func() calls for each entry of the map
+value.
 
-extern bt_value_map_insert_entry_status
-bt_value_map_insert_string_entry(bt_value *map_obj, const char *key,
-               const char *val);
+@param[in] key
+    Key of the map value entry.
+@param[in] value
+    Value of the map value entry.
+@param[in] user_data
+    User data.
 
-extern bt_value_map_insert_entry_status
-bt_value_map_insert_empty_array_entry(bt_value *map_obj, const char *key,
-               bt_value **entry_obj);
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT
+    Interrupt the iteration process.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR
+    Out of memory.
+@retval #BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR
+    User error.
 
-extern bt_value_map_insert_entry_status
-bt_value_map_insert_empty_map_entry(bt_value *map_obj, const char *key,
-               bt_value **entry_obj);
+@bt_pre_not_null{key}
+@bt_pre_not_null{value}
+
+@sa bt_value_map_foreach_entry_const() &mdash;
+    Iterates the entries of a \c const map value.
+*/
+typedef bt_value_map_foreach_entry_const_func_status
+               (* bt_value_map_foreach_entry_const_func)(const char *key,
+                       const bt_value *value, void *user_data);
+
+/*!
+@brief
+    Status codes for bt_value_map_foreach_entry_const().
+*/
+typedef enum bt_value_map_foreach_entry_const_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK              = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           User function interrupted the iteration process.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED     = __BT_FUNC_STATUS_INTERRUPTED,
+
+       /*!
+       @brief
+           User function error.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR      = __BT_FUNC_STATUS_USER_ERROR,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR    = __BT_FUNC_STATUS_MEMORY_ERROR,
+
+       /*!
+       @brief
+           Other error.
+       */
+       BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR           = __BT_FUNC_STATUS_ERROR,
+} bt_value_map_foreach_entry_const_status;
+
+/*!
+@brief
+    Iterates the entries of the map value \bt_p{value}, calling
+    \bt_p{user_func} for each entry (\c const version).
+
+See bt_value_map_foreach_entry().
+
+@sa bt_value_map_borrow_entry_value_const() &mdash;
+    Borrows the value of a specific map value entry.
+*/
+extern bt_value_map_foreach_entry_const_status bt_value_map_foreach_entry_const(
+               const bt_value *value,
+               bt_value_map_foreach_entry_const_func user_func,
+               void *user_data);
+
+/*!
+@brief
+    Returns the size of the map value \bt_p{value}.
+
+@param[in] value
+    Map value of which to get the size.
+
+@returns
+    Size (number of contained entries) of \bt_p{value}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+
+@sa bt_value_map_is_empty() &mdash;
+    Returns whether or not a map value is empty.
+*/
+extern uint64_t bt_value_map_get_size(const bt_value *value);
+
+/*!
+@brief
+    Returns whether or not the map value \bt_p{value} is empty.
+
+@param[in] value
+    Map value to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} is empty (has the size&nbsp;0).
 
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+
+@sa bt_value_map_get_size() &mdash;
+    Returns the size of a map value.
+*/
+static inline
+bt_bool bt_value_map_is_empty(const bt_value *value)
+{
+       return bt_value_map_get_size(value) == 0;
+}
+
+/*!
+@brief
+    Returns whether or not the map value \bt_p{value} has an entry with
+    the key \bt_p{key}.
+
+@param[in] value
+    Map value to check.
+@param[in] key
+    Key to check.
+
+@returns
+    #BT_TRUE if \bt_p{value} has an entry with the key \bt_p{key}.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_not_null{key}
+
+@sa bt_value_map_borrow_entry_value_const() &mdash;
+    Borrows the value of a specific map value entry.
+*/
+extern bt_bool bt_value_map_has_entry(const bt_value *value,
+               const char *key);
+
+/*!
+@brief
+    Status codes for bt_value_map_extend().
+*/
 typedef enum bt_value_map_extend_status {
-       BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+       /*!
+       @brief
+           Success.
+       */
        BT_VALUE_MAP_EXTEND_STATUS_OK           = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
 } bt_value_map_extend_status;
 
+/*!
+@brief
+    Extends the map value \bt_p{value} with the map value
+    \bt_p{extension_value}.
+
+For each entry in \bt_p{extension_value}, this function calls
+bt_value_map_insert_entry() to insert or replace it in the map value
+\bt_p{value}.
+
+For example, with:
+
+<dl>
+  <dt>
+    \bt_p{value}
+  </dt>
+  <dd>
+    @code{.json}
+    {
+        "man": "giant",
+        "strange": 23
+    }
+    @endcode
+  </dd>
+
+  <dt>
+    \bt_p{extension_value}
+  </dt>
+  <dd>
+    @code{.json}
+    {
+        "balance": -17
+        "strange": false
+    }
+    @endcode
+  </dd>
+</dl>
+
+The map value \bt_p{value} becomes:
+
+@code{.json}
+{
+    "man": "giant",
+    "strange": false,
+    "balance": -17
+}
+@endcode
+
+@param[in] value
+    Map value to extend.
+@param[in] extension_value
+    Extension map value.
+
+@retval #BT_VALUE_MAP_EXTEND_STATUS_OK
+    Success.
+@retval #BT_VALUE_MAP_EXTEND_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+@bt_pre_not_null{extension_value}
+@bt_pre_is_map_val{extension_value}
+
+@sa bt_value_copy() &mdash;
+    Deep-copies a value.
+*/
 extern bt_value_map_extend_status bt_value_map_extend(
-               bt_value *base_map_obj,
-               const bt_value *extension_map_obj);
+               bt_value *value, const bt_value *extension_value);
+
+/*! @} */
+
+/*!
+@name General
+@{
+*/
+
+/*!
+@brief
+    Status codes for bt_value_copy().
+*/
+typedef enum bt_value_copy_status {
+       /*!
+       @brief
+           Success.
+       */
+       BT_VALUE_COPY_STATUS_OK     = __BT_FUNC_STATUS_OK,
+
+       /*!
+       @brief
+           Out of memory.
+       */
+       BT_VALUE_COPY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
+} bt_value_copy_status;
+
+/*!
+@brief
+    Deep-copies a value object.
+
+This function deep-copies \bt_p{value} and sets \bt_p{*copy} to the
+result.
+
+Because \bt_p{*copy} is a deep copy, it does not contain, recursively,
+any reference that \bt_p{value} contains, but the raw values are
+identical.
+
+@param[in] value
+    Value to deep-copy.
+@param[in] copy_value
+    <strong>On success</strong>, \bt_p{*copy_value} is a deep copy of
+    \bt_p{value}.
+
+@retval #BT_VALUE_COPY_STATUS_OK
+    Success.
+@retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
+    Out of memory.
+
+@bt_pre_not_null{value}
+@bt_pre_not_null{copy_value}
+*/
+extern bt_value_copy_status bt_value_copy(const bt_value *value,
+               bt_value **copy_value);
+
+/*!
+@brief
+    Returns whether or not the value \bt_p{a_value} is equal,
+    recursively, to \bt_p{b_value}.
+
+@note
+    If you want to know whether or not a value is a null value, you can
+    also directly compare its pointer to the #bt_value_null variable.
+
+@param[in] a_value
+    Value A.
+@param[in] b_value
+    Value B.
+
+@returns
+    #BT_TRUE if \bt_p{a_value} is equal, recursively, to \bt_p{b_value}.
+
+@bt_pre_not_null{a_value}
+@bt_pre_not_null{b_value}
+*/
+extern bt_bool bt_value_is_equal(const bt_value *a_value,
+               const bt_value *b_value);
+
+/*! @} */
+
+/*!
+@name Reference count
+@{
+*/
+
+/*!
+@brief
+    Increments the \ref api-fund-shared-object "reference count" of
+    the value \bt_p{value}.
+
+@param[in] value
+    @parblock
+    Value of which to increment the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_value_put_ref() &mdash;
+    Decrements the reference count of a value.
+*/
+extern void bt_value_get_ref(const bt_value *value);
+
+/*!
+@brief
+    Decrements the \ref api-fund-shared-object "reference count" of
+    the value \bt_p{value}.
+
+@param[in] value
+    @parblock
+    Value of which to decrement the reference count.
+
+    Can be \c NULL.
+    @endparblock
+
+@sa bt_value_get_ref() &mdash;
+    Increments the reference count of a value.
+*/
+extern void bt_value_put_ref(const bt_value *value);
+
+/*!
+@brief
+    Decrements the reference count of the value \bt_p{_value}, and then
+    sets \bt_p{_value} to \c NULL.
+
+@param _value
+    @parblock
+    Value of which to decrement the reference count.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_value}
+*/
+#define BT_VALUE_PUT_REF_AND_RESET(_value)     \
+       do {                                    \
+               bt_value_put_ref(_value);       \
+               (_value) = NULL;                \
+       } while (0)
+
+/*!
+@brief
+    Decrements the reference count of the value \bt_p{_dst}, sets
+    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
+
+This macro effectively moves a value reference from the expression
+\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
+\bt_p{_dst} reference.
+
+@param _dst
+    @parblock
+    Destination expression.
+
+    Can contain \c NULL.
+    @endparblock
+@param _src
+    @parblock
+    Source expression.
+
+    Can contain \c NULL.
+    @endparblock
+
+@bt_pre_assign_expr{_dst}
+@bt_pre_assign_expr{_src}
+*/
+#define BT_VALUE_MOVE_REF(_dst, _src)  \
+       do {                            \
+               bt_value_put_ref(_dst); \
+               (_dst) = (_src);        \
+               (_src) = NULL;          \
+       } while (0)
+
+/*! @} */
+
+/*! @} */
 
 #ifdef __cplusplus
 }

diff --git a/include/babeltrace2/version.h b/include/babeltrace2/version.h
index 1a15af439fb8f304ff1c5ffe39f2bcb506cd060a..7cd0213f9b62952d297d4a3a679fd241f6cc18df 100644 (file)
--- a/include/babeltrace2/version.h
+++ b/include/babeltrace2/version.h
@@ -31,11 +31,79 @@
 extern "C" {
 #endif
 
+/*!
+@defgroup api-version Library version
+
+@brief
+    Library version getters.
+
+This module contains four functions to get the four parts of the
+library's version:
+
+<dl>
+  <dt>Major version</dt>
+  <dd>bt_version_get_major()</dd>
+
+  <dt>Minor version</dt>
+  <dd>bt_version_get_minor()</dd>
+
+  <dt>Patch version</dt>
+  <dd>bt_version_get_patch()</dd>
+
+  <dt>Extra information</dt>
+  <dd>bt_version_get_extra()</dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@brief
+    Returns the major version of libbabeltrace2.
+
+@returns
+    Major version of the library.
+*/
 extern unsigned int bt_version_get_major(void);
+
+/*!
+@brief
+    Returns the minor version of libbabeltrace2.
+
+@returns
+    Minor version of the library.
+*/
 extern unsigned int bt_version_get_minor(void);
+
+/*!
+@brief
+    Returns the patch version of libbabeltrace2.
+
+@returns
+    Patch version of the library.
+*/
 extern unsigned int bt_version_get_patch(void);
+
+/*!
+@brief
+    Returns extra information about the version of libbabeltrace2.
+
+This extra information can contain a version suffix such as
+<code>-pre5</code> or <code>-rc1</code>.
+
+@returns
+    @parblock
+    Extra information about the library's version.
+
+    Cannot be \c NULL.
+
+    Can be an empty string if there's no extra information.
+    @endparblock
+*/
 extern const char *bt_version_get_extra(void);
 
+/*! @} */
+
 #ifdef __cplusplus
 }
 #endif

diff --git a/src/bindings/python/bt2/bt2/native_bt.i b/src/bindings/python/bt2/bt2/native_bt.i
index 919fc1dc8988bd9683605704bd4cd84eb0db7fd4..2300cee42f65c856576a88166f65fb8871a6b5c2 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt.i
+++ b/src/bindings/python/bt2/bt2/native_bt.i
@@ -207,8 +207,8 @@ void bt_bt2_exit_handler(void);
  */
 #define __BT_IN_BABELTRACE_H
 
-/* Property enumeration */
-%include <babeltrace2/property.h>
+/* Common types */
+%include <babeltrace2/types.h>
 
 /* Common function status codes */
 %include <babeltrace2/func-status.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_clock_class.i b/src/bindings/python/bt2/bt2/native_bt_clock_class.i
index 4e7bfb224837c1a9fc1715b3ee2ea19faa036bd1..251722ff99dcabbc0af679e2c26fbc05bc911924 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_clock_class.i
+++ b/src/bindings/python/bt2/bt2/native_bt_clock_class.i
@@ -22,5 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/clock-class-const.h>
 %include <babeltrace2/trace-ir/clock-class.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i b/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i
index 5423bafe500f0d2b3cf5456f8232224a09946421..93408d3e8b4fe4d6e5e7963e9de4dbb8fec164b3 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i
+++ b/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i
@@ -22,4 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/clock-snapshot-const.h>
+%include <babeltrace2/trace-ir/clock-snapshot.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_component.i b/src/bindings/python/bt2/bt2/native_bt_component.i
index ae44579b557eafaf54817e584f2bf73d9d598b92..aa3f725213dd21bf0a1e11f61eb2841eb61c11d9 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_component.i
+++ b/src/bindings/python/bt2/bt2/native_bt_component.i
@@ -82,14 +82,8 @@
        }
 }
 
-%include <babeltrace2/graph/component-const.h>
-%include <babeltrace2/graph/component-source-const.h>
-%include <babeltrace2/graph/component-filter-const.h>
-%include <babeltrace2/graph/component-sink-const.h>
+%include <babeltrace2/graph/component.h>
 %include <babeltrace2/graph/self-component.h>
-%include <babeltrace2/graph/self-component-source.h>
-%include <babeltrace2/graph/self-component-filter.h>
-%include <babeltrace2/graph/self-component-sink.h>
 
 /*
  * This type map relies on the rather common "user_data" name, so don't pollute

diff --git a/src/bindings/python/bt2/bt2/native_bt_component_class.i b/src/bindings/python/bt2/bt2/native_bt_component_class.i
index 4c26660fe9c33bfbc1ed8375a7367d1c2bdf6599..06710faaef25dedf8ef01a8d1791da39fe7300e7 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_component_class.i
+++ b/src/bindings/python/bt2/bt2/native_bt_component_class.i
@@ -23,16 +23,8 @@
  */
 
 %include <babeltrace2/graph/component-class.h>
-%include <babeltrace2/graph/component-class-const.h>
-%include <babeltrace2/graph/component-class-source-const.h>
-%include <babeltrace2/graph/component-class-source.h>
-%include <babeltrace2/graph/component-class-filter-const.h>
-%include <babeltrace2/graph/component-class-filter.h>
-%include <babeltrace2/graph/component-class-sink-const.h>
-%include <babeltrace2/graph/component-class-sink.h>
-%include <babeltrace2/graph/self-component-class-source.h>
-%include <babeltrace2/graph/self-component-class-filter.h>
-%include <babeltrace2/graph/self-component-class-sink.h>
+%include <babeltrace2/graph/component-class-dev.h>
+%include <babeltrace2/graph/self-component-class.h>
 
 %{
 #include "native_bt_component_class.i.h"

diff --git a/src/bindings/python/bt2/bt2/native_bt_connection.i b/src/bindings/python/bt2/bt2/native_bt_connection.i
index bb22858303aa8781f2399071dba51a7e3ab52a53..042c71abad113bc8f9d776d43c1f2678e0446421 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_connection.i
+++ b/src/bindings/python/bt2/bt2/native_bt_connection.i
@@ -22,4 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/graph/connection-const.h>
+%include <babeltrace2/graph/connection.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_error.i b/src/bindings/python/bt2/bt2/native_bt_error.i
index 1ccf6c4abc1e48bcd12e07637feeb60070682a91..ad73753e1e1e89428ea24d4fbd1c637cf3432ec2 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_error.i
+++ b/src/bindings/python/bt2/bt2/native_bt_error.i
@@ -25,9 +25,7 @@
  * We include current-thread.h here, because for now, it only contains
  * error-related things.
  */
-%include <babeltrace2/current-thread.h>
-%include <babeltrace2/error-const.h>
-%include <babeltrace2/error-cause-const.h>
+%include <babeltrace2/error-reporting.h>
 
 %{
 #include "native_bt_error.i.h"

diff --git a/src/bindings/python/bt2/bt2/native_bt_event.i b/src/bindings/python/bt2/bt2/native_bt_event.i
index 7812b0cd1f3495684f20f1c5279562fdfb9dcbc9..ea3d81507d867a411293d73f07570779a559e16d 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_event.i
+++ b/src/bindings/python/bt2/bt2/native_bt_event.i
@@ -22,5 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/event-const.h>
 %include <babeltrace2/trace-ir/event.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_event_class.i b/src/bindings/python/bt2/bt2/native_bt_event_class.i
index 5bf6ebd293deec98f9a3b5fc944fa796d21eed65..14f51625a93e065b505523aa4c19c92dd69b9a2c 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_event_class.i
+++ b/src/bindings/python/bt2/bt2/native_bt_event_class.i
@@ -36,5 +36,4 @@
        $result = SWIG_Python_AppendOutput($result, SWIG_From_int(*$1));
 }
 
-%include <babeltrace2/trace-ir/event-class-const.h>
 %include <babeltrace2/trace-ir/event-class.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_field.i b/src/bindings/python/bt2/bt2/native_bt_field.i
index 8b944c63c20e8ea2bac1a8b5a944cf35f68670e4..d1429d557a8e6358474e13bb82bfd0ec7a54bf87 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_field.i
+++ b/src/bindings/python/bt2/bt2/native_bt_field.i
@@ -25,5 +25,4 @@
 /* For label type mappings. */
 %include "native_bt_field_class.i"
 
-%include <babeltrace2/trace-ir/field-const.h>
 %include <babeltrace2/trace-ir/field.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_field_class.i b/src/bindings/python/bt2/bt2/native_bt_field_class.i
index 5a84b8695df27f81340ecb50c16dd75529de8d60..48f48c08217a3b8a8a332e7e649733641b027ce6 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_field_class.i
+++ b/src/bindings/python/bt2/bt2/native_bt_field_class.i
@@ -24,14 +24,14 @@
 
 /* Parameter names seem to be required for multi-argument typemaps to match. */
 %typemap(in, numinputs=0)
-       (bt_field_class_enumeration_mapping_label_array *label_array, uint64_t *count)
+       (bt_field_class_enumeration_mapping_label_array *labels, uint64_t *count)
        (bt_field_class_enumeration_mapping_label_array temp_array, uint64_t temp_label_count = 0) {
        $1 = &temp_array;
        $2 = &temp_label_count;
 }
 
 %typemap(argout)
-       (bt_field_class_enumeration_mapping_label_array *label_array, uint64_t *count) {
+       (bt_field_class_enumeration_mapping_label_array *labels, uint64_t *count) {
        if (*$1) {
                PyObject *py_label_list = PyList_New(*$2);
                uint64_t i;
@@ -47,5 +47,4 @@
        }
 }
 
-%include <babeltrace2/trace-ir/field-class-const.h>
 %include <babeltrace2/trace-ir/field-class.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_field_path.i b/src/bindings/python/bt2/bt2/native_bt_field_path.i
index 562e9d5208685b5bcf68f78b59d7e9e72e558473..05313df2eb4abb7dc43c0b1ec2647ce448c8a87a 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_field_path.i
+++ b/src/bindings/python/bt2/bt2/native_bt_field_path.i
@@ -22,4 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/field-path-const.h>
+%include <babeltrace2/trace-ir/field-path.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_graph.i b/src/bindings/python/bt2/bt2/native_bt_graph.i
index 4a7b9f6dbce269b9f405541f9fa69f486d273af7..0bda11f7dffb2feea7fde4963bf4493c14700093 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_graph.i
+++ b/src/bindings/python/bt2/bt2/native_bt_graph.i
@@ -101,7 +101,6 @@
        }
 }
 
-%include <babeltrace2/graph/graph-const.h>
 %include <babeltrace2/graph/graph.h>
 
 /* Helper functions for Python */

diff --git a/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i b/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i
index 7cd26f004760e376c9281c33cf96cd95dd7cd8c4..2f13cc0d620877c95588a53ec736eb2428f8d58d 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i
+++ b/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i
@@ -23,4 +23,3 @@
  */
 
 %include <babeltrace2/integer-range-set.h>
-%include <babeltrace2/integer-range-set-const.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_interrupter.i b/src/bindings/python/bt2/bt2/native_bt_interrupter.i
index 43991446ce36ff225bcbee74fd24d87319368a6b..c338341667cae3e2bc1533b6d354b3febc515028 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_interrupter.i
+++ b/src/bindings/python/bt2/bt2/native_bt_interrupter.i
@@ -23,4 +23,3 @@
  */
 
 %include <babeltrace2/graph/interrupter.h>
-%include <babeltrace2/graph/interrupter-const.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_message.i b/src/bindings/python/bt2/bt2/native_bt_message.i
index 06726f42ae7a36bc2b2a86fed730eed8a690c73c..8cc90553fdda224bc6a1843420386d74acacc039 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_message.i
+++ b/src/bindings/python/bt2/bt2/native_bt_message.i
@@ -44,21 +44,4 @@
        }
 }
 
-%include <babeltrace2/graph/message-const.h>
-%include <babeltrace2/graph/message-discarded-events-const.h>
-%include <babeltrace2/graph/message-discarded-events.h>
-%include <babeltrace2/graph/message-discarded-packets-const.h>
-%include <babeltrace2/graph/message-discarded-packets.h>
-%include <babeltrace2/graph/message-event-const.h>
-%include <babeltrace2/graph/message-event.h>
-%include <babeltrace2/graph/message-message-iterator-inactivity-const.h>
-%include <babeltrace2/graph/message-message-iterator-inactivity.h>
-%include <babeltrace2/graph/message-packet-beginning-const.h>
-%include <babeltrace2/graph/message-packet-beginning.h>
-%include <babeltrace2/graph/message-packet-end-const.h>
-%include <babeltrace2/graph/message-packet-end.h>
-%include <babeltrace2/graph/message-stream-const.h>
-%include <babeltrace2/graph/message-stream-beginning-const.h>
-%include <babeltrace2/graph/message-stream-beginning.h>
-%include <babeltrace2/graph/message-stream-end-const.h>
-%include <babeltrace2/graph/message-stream-end.h>
+%include <babeltrace2/graph/message.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_mip.i b/src/bindings/python/bt2/bt2/native_bt_mip.i
index 77cd251cba032ed84a6660121471cde73b1a700b..41da5fd6d2d6c15f5b5a1983daca272b8e21ac3b 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_mip.i
+++ b/src/bindings/python/bt2/bt2/native_bt_mip.i
@@ -23,8 +23,7 @@
  */
 
 %include <babeltrace2/graph/component-descriptor-set.h>
-%include <babeltrace2/graph/component-descriptor-set-const.h>
-%include <babeltrace2/graph/mip.h>
+%include <babeltrace2/graph/graph.h>
 
 %{
 #include "native_bt_mip.i.h"

diff --git a/src/bindings/python/bt2/bt2/native_bt_packet.i b/src/bindings/python/bt2/bt2/native_bt_packet.i
index 10357937dabe32c24f26a5a169f390f69ddeaf0f..4b68d3c546181c74364f2f5ebd163658b1bf8d11 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_packet.i
+++ b/src/bindings/python/bt2/bt2/native_bt_packet.i
@@ -22,5 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/packet-const.h>
 %include <babeltrace2/trace-ir/packet.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_plugin.i b/src/bindings/python/bt2/bt2/native_bt_plugin.i
index e96ea6ed77a23e19deb12426a063469b870ec648..edd91e797689bfb1900d5a9fe223c65d4ac71ecf 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_plugin.i
+++ b/src/bindings/python/bt2/bt2/native_bt_plugin.i
@@ -64,8 +64,7 @@
        }
 }
 
-%include <babeltrace2/plugin/plugin-const.h>
-%include <babeltrace2/plugin/plugin-set-const.h>
+%include <babeltrace2/plugin/plugin-loading.h>
 
 /* Helpers */
 

diff --git a/src/bindings/python/bt2/bt2/native_bt_port.i b/src/bindings/python/bt2/bt2/native_bt_port.i
index 590ded69faf0da9a2b20f58e5d3d35773be09149..c8c0832e410264c0a9445ad02f8d09d823f653d1 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_port.i
+++ b/src/bindings/python/bt2/bt2/native_bt_port.i
@@ -35,12 +35,8 @@
        $result = $1;
 }
 
-%include <babeltrace2/graph/port-const.h>
-%include <babeltrace2/graph/port-output-const.h>
-%include <babeltrace2/graph/port-input-const.h>
+%include <babeltrace2/graph/port.h>
 %include <babeltrace2/graph/self-component-port.h>
-%include <babeltrace2/graph/self-component-port-output.h>
-%include <babeltrace2/graph/self-component-port-input.h>
 
 /*
  * Clear this typemap, since it is a bit broad and could apply to something we

diff --git a/src/bindings/python/bt2/bt2/native_bt_query_exec.i b/src/bindings/python/bt2/bt2/native_bt_query_exec.i
index a422ecbb6d8b55e0c00d8bf38601ce7d7a29bfb0..857c33632b4d8f224a8dd04523cfc608edf4cae3 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_query_exec.i
+++ b/src/bindings/python/bt2/bt2/native_bt_query_exec.i
@@ -23,7 +23,6 @@
  */
 
 %include <babeltrace2/graph/private-query-executor.h>
-%include <babeltrace2/graph/query-executor-const.h>
 %include <babeltrace2/graph/query-executor.h>
 
 %{

diff --git a/src/bindings/python/bt2/bt2/native_bt_stream.i b/src/bindings/python/bt2/bt2/native_bt_stream.i
index 95a9d36659335818a37757241a960c60fca51823..28f2a39a752b45315fc4a3a29169d70839503da6 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_stream.i
+++ b/src/bindings/python/bt2/bt2/native_bt_stream.i
@@ -22,5 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/stream-const.h>
 %include <babeltrace2/trace-ir/stream.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_stream_class.i b/src/bindings/python/bt2/bt2/native_bt_stream_class.i
index 69937babd6fcf6e2c78ca32670b804574f997029..1c93cbd54b3998b6cfe62224e9da0986be44de7b 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_stream_class.i
+++ b/src/bindings/python/bt2/bt2/native_bt_stream_class.i
@@ -22,5 +22,4 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/stream-class-const.h>
 %include <babeltrace2/trace-ir/stream-class.h>

diff --git a/src/bindings/python/bt2/bt2/native_bt_trace.i b/src/bindings/python/bt2/bt2/native_bt_trace.i
index 5ecccf0c5150fc369470f8579201a2f337c15789..0868055cfaefea34a462197f8e41805c56def67f 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_trace.i
+++ b/src/bindings/python/bt2/bt2/native_bt_trace.i
@@ -22,7 +22,6 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/trace-const.h>
 %include <babeltrace2/trace-ir/trace.h>
 
 %{

diff --git a/src/bindings/python/bt2/bt2/native_bt_trace_class.i b/src/bindings/python/bt2/bt2/native_bt_trace_class.i
index cc0793798f7d0245ccdb6f4360cd6aae23d7fd36..3e4916932caf24b5c2be68acf9de6a9a1de44c52 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_trace_class.i
+++ b/src/bindings/python/bt2/bt2/native_bt_trace_class.i
@@ -22,7 +22,6 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/trace-ir/trace-class-const.h>
 %include <babeltrace2/trace-ir/trace-class.h>
 
 /* Helper functions for Python */

diff --git a/src/bindings/python/bt2/bt2/native_bt_value.i b/src/bindings/python/bt2/bt2/native_bt_value.i
index f31a6d44325b399e604ba4331c5860d40780af71..c04bb7f5f8aa73ad71a23b302cff4158b3082d2c 100644 (file)
--- a/src/bindings/python/bt2/bt2/native_bt_value.i
+++ b/src/bindings/python/bt2/bt2/native_bt_value.i
@@ -22,7 +22,6 @@
  * THE SOFTWARE.
  */
 
-%include <babeltrace2/value-const.h>
 %include <babeltrace2/value.h>
 
 %{

diff --git a/src/cli/babeltrace2-cfg-cli-args.h b/src/cli/babeltrace2-cfg-cli-args.h
index 27ab45d13b2d91439214e114fd592e0e5eb1e9fe..d962145bc28ff8e07d38e6ec77c7b61133e88a56 100644 (file)
--- a/src/cli/babeltrace2-cfg-cli-args.h
+++ b/src/cli/babeltrace2-cfg-cli-args.h
@@ -29,7 +29,7 @@
 #include <babeltrace2/value.h>
 #include "lib/object.h"
 #include "compat/compiler.h"
-#include <babeltrace2/graph/component-class.h>
+#include <babeltrace2/graph/component.h>
 #include <glib.h>
 
 #include "babeltrace2-cfg.h"

diff --git a/src/lib/graph/component-class-sink-simple.c b/src/lib/graph/component-class-sink-simple.c
index e7ca81b9d4e28db486652f04d1bf0199476a797f..f8ac7ad1a2ff25b3dde46c5729a76946b29a005e 100644 (file)
--- a/src/lib/graph/component-class-sink-simple.c
+++ b/src/lib/graph/component-class-sink-simple.c
@@ -27,10 +27,10 @@
 #include "common/common.h"
 #include "lib/assert-pre.h"
 #include "lib/object.h"
-#include <babeltrace2/graph/component-class-sink.h>
-#include <babeltrace2/graph/self-component-sink.h>
+#include <babeltrace2/graph/component-class.h>
 #include <babeltrace2/graph/self-component-port.h>
 #include <babeltrace2/graph/self-component.h>
+#include <babeltrace2/graph/message-iterator.h>
 #include <glib.h>
 
 #include "component-class-sink-simple.h"

diff --git a/src/lib/graph/component-class-sink-simple.h b/src/lib/graph/component-class-sink-simple.h
index a6c527de3a9b6570af8e227bc78fd0959ef57098..91c03ed5107c751db402c67178f4677bdbece607 100644 (file)
--- a/src/lib/graph/component-class-sink-simple.h
+++ b/src/lib/graph/component-class-sink-simple.h
@@ -25,7 +25,7 @@
 
 #include <stdint.h>
 #include <babeltrace2/types.h>
-#include <babeltrace2/graph/message-const.h>
+#include <babeltrace2/graph/message.h>
 
 struct simple_sink_init_method_data {
        bt_graph_simple_sink_component_initialize_func init_func;

diff --git a/src/lib/graph/component-class.c b/src/lib/graph/component-class.c
index 1c1497db4c6e24981aa28ad40e690b139bc98825..be0fdf70bdaacb99856ee47b0448eaef39fc080c 100644 (file)
--- a/src/lib/graph/component-class.c
+++ b/src/lib/graph/component-class.c
@@ -28,13 +28,6 @@
 #include "lib/assert-pre.h"
 #include "compat/compiler.h"
 #include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/graph/component-class-const.h>
-#include <babeltrace2/graph/component-class-source.h>
-#include <babeltrace2/graph/component-class-source-const.h>
-#include <babeltrace2/graph/component-class-filter.h>
-#include <babeltrace2/graph/component-class-filter-const.h>
-#include <babeltrace2/graph/component-class-sink.h>
-#include <babeltrace2/graph/component-class-sink-const.h>
 #include <babeltrace2/types.h>
 #include <glib.h>
 

diff --git a/src/lib/graph/component-class.h b/src/lib/graph/component-class.h
index 5974d832a9a9ecc0cfee298f4f4a4fd2f8c1378d..b829672a9317ec333b376066e829f6944b8746e5 100644 (file)
--- a/src/lib/graph/component-class.h
+++ b/src/lib/graph/component-class.h
@@ -26,11 +26,8 @@
  * SOFTWARE.
  */
 
-#include <babeltrace2/graph/component-const.h>
 #include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/graph/component-class-source.h>
-#include <babeltrace2/graph/component-class-filter.h>
-#include <babeltrace2/graph/component-class-sink.h>
+#include <babeltrace2/graph/component.h>
 #include "common/macros.h"
 #include "lib/object.h"
 #include "common/list.h"

diff --git a/src/lib/graph/component-descriptor-set.c b/src/lib/graph/component-descriptor-set.c
index e6b0894d0d7f3c9c7e6896bf309231be97613b5d..14b6e70db1dd61f10609a12ce705bef4462f84cb 100644 (file)
--- a/src/lib/graph/component-descriptor-set.c
+++ b/src/lib/graph/component-descriptor-set.c
@@ -30,7 +30,6 @@
 #include "common/common.h"
 #include <babeltrace2/types.h>
 #include <babeltrace2/value.h>
-#include <babeltrace2/value-const.h>
 #include <unistd.h>
 #include <glib.h>
 

diff --git a/src/lib/graph/component-filter.c b/src/lib/graph/component-filter.c
index e805f8dadf95c29290057cd00f34fabb7d1a525c..5d8e5cabafd87594e2a062462524919e0f4923f5 100644 (file)
--- a/src/lib/graph/component-filter.c
+++ b/src/lib/graph/component-filter.c
@@ -28,8 +28,8 @@
 #include "lib/assert-pre.h"
 #include "compat/compiler.h"
 #include <babeltrace2/value.h>
-#include <babeltrace2/graph/self-component-filter.h>
-#include <babeltrace2/graph/component-filter-const.h>
+#include <babeltrace2/graph/self-component.h>
+#include <babeltrace2/graph/component.h>
 #include <babeltrace2/graph/graph.h>
 
 #include "component-filter.h"

diff --git a/src/lib/graph/component-filter.h b/src/lib/graph/component-filter.h
index 194bab0f5e38dd6d89ac00d6a7e95060b96ccf2b..87e5a01aac22d1f61294e9d426ed87acf86eea1e 100644 (file)
--- a/src/lib/graph/component-filter.h
+++ b/src/lib/graph/component-filter.h
@@ -25,7 +25,7 @@
  */
 
 #include "common/macros.h"
-#include <babeltrace2/graph/component-filter-const.h>
+#include <babeltrace2/graph/component.h>
 
 #include "component-class.h"
 #include "component.h"

diff --git a/src/lib/graph/component-sink.c b/src/lib/graph/component-sink.c
index 12ea8c2780103821d26c9a0cc10ec5e040ab470b..7a24fed9b39c1fb515c2142cb85da7998b63948c 100644 (file)
--- a/src/lib/graph/component-sink.c
+++ b/src/lib/graph/component-sink.c
@@ -29,8 +29,8 @@
 #include "lib/assert-post.h"
 #include "compat/compiler.h"
 #include <babeltrace2/value.h>
-#include <babeltrace2/graph/self-component-sink.h>
-#include <babeltrace2/graph/component-sink-const.h>
+#include <babeltrace2/graph/self-component.h>
+#include <babeltrace2/graph/component.h>
 #include <babeltrace2/graph/graph.h>
 
 #include "component-sink.h"

diff --git a/src/lib/graph/component-sink.h b/src/lib/graph/component-sink.h
index c523c7703568b128422557cc8c23f7b407b2cbb9..7aaafc21371c474b38d60d613d4ea91f6fdbd729 100644 (file)
--- a/src/lib/graph/component-sink.h
+++ b/src/lib/graph/component-sink.h
@@ -28,7 +28,7 @@
 
 #include "common/macros.h"
 #include "compat/compiler.h"
-#include <babeltrace2/graph/component-sink-const.h>
+#include <babeltrace2/graph/component.h>
 
 #include "component-class.h"
 #include "component.h"

diff --git a/src/lib/graph/component-source.c b/src/lib/graph/component-source.c
index 0e3eedc2246c791a4985d1743912ba9db8913fe0..1bbb0e73aa5fe9506a187f0174be5e3cf917a6f4 100644 (file)
--- a/src/lib/graph/component-source.c
+++ b/src/lib/graph/component-source.c
@@ -27,8 +27,8 @@
 #include "common/assert.h"
 #include "lib/assert-pre.h"
 #include "compat/compiler.h"
-#include <babeltrace2/graph/self-component-source.h>
-#include <babeltrace2/graph/component-source-const.h>
+#include <babeltrace2/graph/self-component.h>
+#include <babeltrace2/graph/component.h>
 #include <babeltrace2/graph/graph.h>
 
 #include "component-source.h"

diff --git a/src/lib/graph/component.c b/src/lib/graph/component.c
index c771e27870cd15ca40ca27736ca794a55a836374..65978e944cab83f5b1ce18f0070d437ee382ad2a 100644 (file)
--- a/src/lib/graph/component.c
+++ b/src/lib/graph/component.c
@@ -29,11 +29,8 @@
 #include "lib/assert-pre.h"
 #include "lib/assert-post.h"
 #include <babeltrace2/graph/self-component.h>
-#include <babeltrace2/graph/component-const.h>
-#include <babeltrace2/graph/component-source-const.h>
-#include <babeltrace2/graph/component-filter-const.h>
-#include <babeltrace2/graph/component-sink-const.h>
-#include <babeltrace2/graph/graph-const.h>
+#include <babeltrace2/graph/component.h>
+#include <babeltrace2/graph/graph.h>
 #include "common/macros.h"
 #include "compat/compiler.h"
 #include <babeltrace2/types.h>

diff --git a/src/lib/graph/component.h b/src/lib/graph/component.h
index 531bd63a34715e4c5b35935e42d10d9d31100a34..0925d5f265140321c200c17724e68a87c7b14029 100644 (file)
--- a/src/lib/graph/component.h
+++ b/src/lib/graph/component.h
@@ -25,7 +25,7 @@
  */
 
 #include "common/macros.h"
-#include <babeltrace2/graph/component-const.h>
+#include <babeltrace2/graph/component.h>
 #include <babeltrace2/graph/component-class.h>
 #include "lib/object.h"
 #include <babeltrace2/types.h>

diff --git a/src/lib/graph/connection.c b/src/lib/graph/connection.c
index 743553b96d0a4d6c0aeec942640c77c17218d97b..6552b5f2264ea4030a47bee31b1bb3c75241b481 100644 (file)
--- a/src/lib/graph/connection.c
+++ b/src/lib/graph/connection.c
@@ -27,7 +27,7 @@
 #include "common/assert.h"
 #include "lib/assert-pre.h"
 #include "lib/assert-post.h"
-#include <babeltrace2/graph/connection-const.h>
+#include <babeltrace2/graph/connection.h>
 #include "lib/object.h"
 #include "compat/compiler.h"
 #include <stdbool.h>

diff --git a/src/lib/graph/connection.h b/src/lib/graph/connection.h
index 2024244ddf3e6884903dde8b1b9d5d4c0bf386e2..1d89c9930ca9365a8143415123e3d7daa55c14ff 100644 (file)
--- a/src/lib/graph/connection.h
+++ b/src/lib/graph/connection.h
@@ -24,7 +24,7 @@
  * SOFTWARE.
  */
 
-#include <babeltrace2/graph/connection-const.h>
+#include <babeltrace2/graph/connection.h>
 #include "lib/object.h"
 #include "common/assert.h"
 #include "common/macros.h"

diff --git a/src/lib/graph/graph.c b/src/lib/graph/graph.c
index 9e7e8ffce188b0b156a067c40d0febb8d4365f0f..b545a8ef234b247e9a0731902c4fb9d732bd6d41 100644 (file)
--- a/src/lib/graph/graph.c
+++ b/src/lib/graph/graph.c
@@ -28,16 +28,13 @@
 #include "lib/assert-pre.h"
 #include "lib/assert-post.h"
 #include <babeltrace2/graph/graph.h>
-#include <babeltrace2/graph/graph-const.h>
-#include <babeltrace2/graph/component-source-const.h>
-#include <babeltrace2/graph/component-filter-const.h>
-#include <babeltrace2/graph/port-const.h>
+#include <babeltrace2/graph/component.h>
+#include <babeltrace2/graph/port.h>
 #include "lib/graph/message/message.h"
 #include "compat/compiler.h"
 #include "common/common.h"
 #include <babeltrace2/types.h>
 #include <babeltrace2/value.h>
-#include <babeltrace2/value-const.h>
 #include "lib/value.h"
 #include <unistd.h>
 #include <stdbool.h>

diff --git a/src/lib/graph/graph.h b/src/lib/graph/graph.h
index 7e927e7a751131926b6f5215a7d6e2893ad636f3..7fffd0ca3bc213c8cb093bbdf73205d9d4cbbe6f 100644 (file)
--- a/src/lib/graph/graph.h
+++ b/src/lib/graph/graph.h
@@ -30,7 +30,7 @@
 #endif
 
 #include <babeltrace2/graph/graph.h>
-#include <babeltrace2/graph/message-const.h>
+#include <babeltrace2/graph/message.h>
 #include "common/macros.h"
 #include "lib/object.h"
 #include "lib/object-pool.h"

diff --git a/src/lib/graph/iterator.c b/src/lib/graph/iterator.c
index 5b2ebfbdacaa43c0c45c0fc525343688cac97018..0beb69497d5e14b18e0b769f458dc740dd2a7022 100644 (file)
--- a/src/lib/graph/iterator.c
+++ b/src/lib/graph/iterator.c
@@ -29,30 +29,21 @@
 #include "lib/trace-ir/clock-class.h"
 #include "lib/trace-ir/clock-snapshot.h"
 #include <babeltrace2/trace-ir/field.h>
-#include <babeltrace2/trace-ir/event-const.h>
+#include <babeltrace2/trace-ir/event.h>
 #include "lib/trace-ir/event.h"
-#include <babeltrace2/trace-ir/packet-const.h>
+#include <babeltrace2/trace-ir/packet.h>
 #include "lib/trace-ir/packet.h"
 #include "lib/trace-ir/stream.h"
-#include <babeltrace2/trace-ir/clock-class-const.h>
-#include <babeltrace2/trace-ir/stream-class-const.h>
-#include <babeltrace2/trace-ir/stream-const.h>
-#include <babeltrace2/graph/connection-const.h>
-#include <babeltrace2/graph/component-const.h>
-#include <babeltrace2/graph/component-sink-const.h>
-#include <babeltrace2/graph/message-const.h>
-#include <babeltrace2/graph/message-iterator.h>
-#include <babeltrace2/graph/message-event-const.h>
-#include <babeltrace2/graph/message-message-iterator-inactivity-const.h>
-#include <babeltrace2/graph/message-packet-beginning.h>
-#include <babeltrace2/graph/message-packet-beginning-const.h>
-#include <babeltrace2/graph/message-packet-end-const.h>
-#include <babeltrace2/graph/message-stream-beginning.h>
-#include <babeltrace2/graph/message-stream-beginning-const.h>
-#include <babeltrace2/graph/message-stream-end-const.h>
-#include <babeltrace2/graph/port-const.h>
+#include <babeltrace2/trace-ir/clock-class.h>
+#include <babeltrace2/trace-ir/stream-class.h>
+#include <babeltrace2/trace-ir/stream.h>
+#include <babeltrace2/graph/connection.h>
+#include <babeltrace2/graph/component.h>
+#include <babeltrace2/graph/message.h>
+#include <babeltrace2/graph/self-component.h>
+#include <babeltrace2/graph/port.h>
 #include <babeltrace2/graph/graph.h>
-#include <babeltrace2/graph/graph-const.h>
+#include <babeltrace2/graph/message-iterator.h>
 #include <babeltrace2/types.h>
 #include "common/assert.h"
 #include "lib/assert-pre.h"

diff --git a/src/lib/graph/message/discarded-items.c b/src/lib/graph/message/discarded-items.c
index 0b19abc367de1704417921bfc20437d49f5896b7..e7646377648220e6f57b9ba7d66b163e7c72b2c6 100644 (file)
--- a/src/lib/graph/message/discarded-items.c
+++ b/src/lib/graph/message/discarded-items.c
@@ -34,10 +34,6 @@
 #include "lib/trace-ir/stream.h"
 #include "lib/property.h"
 #include "lib/graph/message/message.h"
-#include <babeltrace2/graph/message-discarded-events.h>
-#include <babeltrace2/graph/message-discarded-events-const.h>
-#include <babeltrace2/graph/message-discarded-packets.h>
-#include <babeltrace2/graph/message-discarded-packets-const.h>
 
 #include "discarded-items.h"
 

diff --git a/src/lib/graph/message/discarded-items.h b/src/lib/graph/message/discarded-items.h
index d9f3fb60d4ffc3a981267b1a81b51307c908d0e2..915cac168f0e9106ee0a187adda0d8b2583808d0 100644 (file)
--- a/src/lib/graph/message/discarded-items.h
+++ b/src/lib/graph/message/discarded-items.h
@@ -27,7 +27,7 @@
 #include "lib/trace-ir/clock-snapshot.h"
 #include "lib/trace-ir/stream.h"
 #include "lib/property.h"
-#include <babeltrace2/graph/message-const.h>
+#include <babeltrace2/graph/message.h>
 
 #include "message.h"
 

diff --git a/src/lib/graph/message/event.c b/src/lib/graph/message/event.c
index 8b211e10bfeaa82395c873b868ed14381ac062c6..0f7a8a0a561ffc05d2016bf50fa81e9015656ab5 100644 (file)
--- a/src/lib/graph/message/event.c
+++ b/src/lib/graph/message/event.c
@@ -36,8 +36,7 @@
 #include <babeltrace2/trace-ir/trace.h>
 #include "lib/trace-ir/clock-snapshot.h"
 #include "lib/graph/graph.h"
-#include <babeltrace2/graph/message-event-const.h>
-#include <babeltrace2/graph/message-event.h>
+#include <babeltrace2/graph/message.h>
 #include <babeltrace2/types.h>
 #include <stdbool.h>
 #include <inttypes.h>

diff --git a/src/lib/graph/message/iterator.h b/src/lib/graph/message/iterator.h
index 68bdc833433a849a71a28de6350850fc878defaa..f6e642b42650f31d4ba6e671cdfa95ec2ac95914 100644 (file)
--- a/src/lib/graph/message/iterator.h
+++ b/src/lib/graph/message/iterator.h
@@ -26,8 +26,8 @@
 
 #include "common/macros.h"
 #include "lib/object.h"
-#include <babeltrace2/graph/connection-const.h>
-#include <babeltrace2/graph/message-const.h>
+#include <babeltrace2/graph/connection.h>
+#include <babeltrace2/graph/message.h>
 #include <babeltrace2/types.h>
 #include "common/assert.h"
 #include <stdbool.h>

diff --git a/src/lib/graph/message/message-iterator-inactivity.c b/src/lib/graph/message/message-iterator-inactivity.c
index d0c27e3d7c083738144894e0b57db543f971de67..1754f385942d9ebbc2a43976eea9d05e0921e663 100644 (file)
--- a/src/lib/graph/message/message-iterator-inactivity.c
+++ b/src/lib/graph/message/message-iterator-inactivity.c
@@ -29,8 +29,7 @@
 #include <babeltrace2/trace-ir/clock-class.h>
 #include "lib/trace-ir/clock-snapshot.h"
 #include "lib/graph/message/message.h"
-#include <babeltrace2/graph/message-message-iterator-inactivity-const.h>
-#include <babeltrace2/graph/message-message-iterator-inactivity.h>
+#include <babeltrace2/graph/message.h>
 
 #include "message-iterator-inactivity.h"
 

diff --git a/src/lib/graph/message/message-iterator-inactivity.h b/src/lib/graph/message/message-iterator-inactivity.h
index 6e8c1fdd42d301afa3f89af197e0165d9ece28d4..942a798026ed9f9f33499e4be74d8472ba50ddcb 100644 (file)
--- a/src/lib/graph/message/message-iterator-inactivity.h
+++ b/src/lib/graph/message/message-iterator-inactivity.h
@@ -25,7 +25,7 @@
 
 #include <glib.h>
 #include "lib/trace-ir/clock-snapshot.h"
-#include <babeltrace2/graph/message-const.h>
+#include <babeltrace2/graph/message.h>
 
 struct bt_message_message_iterator_inactivity {
        struct bt_message parent;

diff --git a/src/lib/graph/message/message.c b/src/lib/graph/message/message.c
index 5d1d8139b41eb7afad891809949b3c174a7afb1b..98d2eab24950e9a7269a93cd9b506231d973b062 100644 (file)
--- a/src/lib/graph/message/message.c
+++ b/src/lib/graph/message/message.c
@@ -27,7 +27,7 @@
 #include "common/assert.h"
 #include "lib/assert-pre.h"
 #include "lib/assert-post.h"
-#include <babeltrace2/graph/message-const.h>
+#include <babeltrace2/graph/message.h>
 #include "lib/graph/message/message.h"
 #include "lib/graph/graph.h"
 
@@ -37,7 +37,6 @@ void bt_message_init(struct bt_message *message,
                bt_object_release_func release,
                struct bt_graph *graph)
 {
-       BT_ASSERT(type >= 0 && type <= BT_MESSAGE_TYPE_DISCARDED_PACKETS);
        message->type = type;
        bt_object_init_shared(&message->base, release);
        message->graph = graph;

diff --git a/src/lib/graph/message/message.h b/src/lib/graph/message/message.h
index f290e3fda6b2a8c0e99b4da52cc09f2204914a09..ec7d2a6ca695ed59d48a2641bf4c579582d1f6b3 100644 (file)
--- a/src/lib/graph/message/message.h
+++ b/src/lib/graph/message/message.h
@@ -33,7 +33,7 @@
 #include "lib/object.h"
 #include "common/assert.h"
 #include <babeltrace2/graph/graph.h>
-#include <babeltrace2/graph/message-const.h>
+#include <babeltrace2/graph/message.h>
 #include <babeltrace2/trace-ir/stream.h>
 #include "lib/object-pool.h"
 #include <babeltrace2/types.h>

diff --git a/src/lib/graph/message/packet.c b/src/lib/graph/message/packet.c
index 125e49f6c92e420a504102f32d3a90c8e1ab64fd..6798fe511b3f95dcd3b0eff4b06a806debb91e30 100644 (file)
--- a/src/lib/graph/message/packet.c
+++ b/src/lib/graph/message/packet.c
@@ -36,10 +36,7 @@
 #include "lib/trace-ir/stream.h"
 #include "lib/trace-ir/stream-class.h"
 #include "lib/graph/graph.h"
-#include <babeltrace2/graph/message-packet-beginning-const.h>
-#include <babeltrace2/graph/message-packet-end-const.h>
-#include <babeltrace2/graph/message-packet-beginning.h>
-#include <babeltrace2/graph/message-packet-end.h>
+#include <babeltrace2/graph/message.h>
 #include "common/assert.h"
 #include "lib/object.h"
 #include <inttypes.h>

diff --git a/src/lib/graph/message/stream.c b/src/lib/graph/message/stream.c
index 40903d001b39a7e164e35d0991e1bc0dd15422d7..1ecb452fbdec4ed7604142f6a69c3fc6cb789b6d 100644 (file)
--- a/src/lib/graph/message/stream.c
+++ b/src/lib/graph/message/stream.c
@@ -26,14 +26,11 @@
 
 #include "lib/assert-pre.h"
 #include "compat/compiler.h"
-#include <babeltrace2/trace-ir/clock-snapshot-const.h>
+#include <babeltrace2/trace-ir/clock-snapshot.h>
 #include "lib/trace-ir/stream.h"
 #include <babeltrace2/trace-ir/stream-class.h>
 #include "lib/trace-ir/stream-class.h"
-#include <babeltrace2/graph/message-stream-beginning.h>
-#include <babeltrace2/graph/message-stream-end.h>
-#include <babeltrace2/graph/message-stream-beginning-const.h>
-#include <babeltrace2/graph/message-stream-end-const.h>
+#include <babeltrace2/graph/message.h>
 #include "common/assert.h"
 #include <inttypes.h>
 

diff --git a/src/lib/graph/message/stream.h b/src/lib/graph/message/stream.h
index ed5d2816091f173f57acc004b50f2aa29bb0d405..6f261b05400ef59847e7495ddcaf9b3704676f3b 100644 (file)
--- a/src/lib/graph/message/stream.h
+++ b/src/lib/graph/message/stream.h
@@ -24,7 +24,7 @@
  * SOFTWARE.
  */
 
-#include <babeltrace2/graph/message-stream-const.h>
+#include <babeltrace2/graph/message.h>
 
 #include "compat/compiler.h"
 #include "lib/trace-ir/stream.h"

diff --git a/src/lib/graph/mip.c b/src/lib/graph/mip.c
index a4704c5d51a0efbe5f8fd247e0fa2aef92e8f7bd..27da722f28db6ef2d7aab7a547004411363d745d 100644 (file)
--- a/src/lib/graph/mip.c
+++ b/src/lib/graph/mip.c
@@ -28,7 +28,7 @@
 #include <stdbool.h>
 #include <unistd.h>
 #include <glib.h>
-#include <babeltrace2/graph/mip.h>
+#include <babeltrace2/graph/graph.h>
 
 #include "common/assert.h"
 #include "compat/compiler.h"

diff --git a/src/lib/graph/port.c b/src/lib/graph/port.c
index 7ca86abe5703a8754276721c378b1a3bbb099349..46735e2226025a419819f4f37952e37f215744c9 100644 (file)
--- a/src/lib/graph/port.c
+++ b/src/lib/graph/port.c
@@ -26,12 +26,8 @@
 
 #include "common/assert.h"
 #include "lib/assert-pre.h"
-#include <babeltrace2/graph/port-const.h>
-#include <babeltrace2/graph/port-input-const.h>
-#include <babeltrace2/graph/port-output-const.h>
+#include <babeltrace2/graph/port.h>
 #include <babeltrace2/graph/self-component-port.h>
-#include <babeltrace2/graph/self-component-port-input.h>
-#include <babeltrace2/graph/self-component-port-output.h>
 #include "lib/object.h"
 #include "compat/compiler.h"
 

diff --git a/src/lib/graph/port.h b/src/lib/graph/port.h
index 5ab277741cc38462be56566a387f5a6b4c1946ac..2592705e39f59d37b6c9b6ba5b3b237b53931756 100644 (file)
--- a/src/lib/graph/port.h
+++ b/src/lib/graph/port.h
@@ -24,7 +24,7 @@
  * SOFTWARE.
  */
 
-#include <babeltrace2/graph/port-const.h>
+#include <babeltrace2/graph/port.h>
 #include "common/macros.h"
 
 struct bt_port {

diff --git a/src/lib/graph/query-executor.c b/src/lib/graph/query-executor.c
index bc6f542a6226429a87184ab9113fb07d4084b031..e922d3ea1bd3c52c5c38e4d9b31605e9f05d3c9f 100644 (file)
--- a/src/lib/graph/query-executor.c
+++ b/src/lib/graph/query-executor.c
@@ -27,11 +27,10 @@
 #include "common/common.h"
 #include "lib/assert-pre.h"
 #include "lib/assert-post.h"
-#include <babeltrace2/graph/query-executor-const.h>
 #include <babeltrace2/graph/query-executor.h>
 #include <babeltrace2/graph/component-class.h>
+#include <babeltrace2/graph/query-executor.h>
 #include <babeltrace2/value.h>
-#include <babeltrace2/value-const.h>
 #include "lib/object.h"
 #include "compat/compiler.h"
 

diff --git a/src/lib/plugin/plugin-so.c b/src/lib/plugin/plugin-so.c
index ebdbf8239fa6b7d8112f9354c8d22c8a0010b066..3684acaedd930fa5b3948a375cb54d1c3067b6b2 100644 (file)
--- a/src/lib/plugin/plugin-so.c
+++ b/src/lib/plugin/plugin-so.c
@@ -32,9 +32,6 @@
 #include <babeltrace2/plugin/plugin-dev.h>
 #include "lib/graph/component-class.h"
 #include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/graph/component-class-source.h>
-#include <babeltrace2/graph/component-class-filter.h>
-#include <babeltrace2/graph/component-class-sink.h>
 #include <babeltrace2/types.h>
 #include "common/list.h"
 #include <string.h>

diff --git a/src/lib/plugin/plugin.c b/src/lib/plugin/plugin.c
index 16850d80ec2ab68bc8ca26c24138cdb4516e302d..838ceeff439a16d2cb9f8582454d8a4975b3ee11 100644 (file)
--- a/src/lib/plugin/plugin.c
+++ b/src/lib/plugin/plugin.c
@@ -31,9 +31,9 @@
 #include "common/macros.h"
 #include "compat/compiler.h"
 #include "common/common.h"
-#include <babeltrace2/plugin/plugin-const.h>
-#include <babeltrace2/graph/component-class-const.h>
-#include <babeltrace2/current-thread.h>
+#include <babeltrace2/plugin/plugin-loading.h>
+#include <babeltrace2/graph/component-class.h>
+#include <babeltrace2/error-reporting.h>
 #include "lib/graph/component-class.h"
 #include <babeltrace2/types.h>
 #include <glib.h>

diff --git a/src/lib/plugin/plugin.h b/src/lib/plugin/plugin.h
index b91adf4bf3ab4f5347c3cf662bdab6e412a04b37..5f8e6b11dbd0650ea1dfe132712ef0ebb8d54de3 100644 (file)
--- a/src/lib/plugin/plugin.h
+++ b/src/lib/plugin/plugin.h
@@ -27,7 +27,7 @@
 #include "common/macros.h"
 #include "common/common.h"
 #include "lib/graph/component-class.h"
-#include <babeltrace2/plugin/plugin-const.h>
+#include <babeltrace2/plugin/plugin-loading.h>
 #include <babeltrace2/plugin/plugin-dev.h>
 #include "lib/object.h"
 #include <babeltrace2/types.h>

diff --git a/src/lib/trace-ir/attributes.c b/src/lib/trace-ir/attributes.c
index 986ee3836531f4a1614ca2e9c49dbd628f32b3fc..fffedc3bd0cb73578e6d3d12eacdcd0e592fabc2 100644 (file)
--- a/src/lib/trace-ir/attributes.c
+++ b/src/lib/trace-ir/attributes.c
@@ -28,7 +28,7 @@
 #include <babeltrace2/value.h>
 #include "lib/assert-pre.h"
 #include "lib/object.h"
-#include <babeltrace2/value-const.h>
+#include <babeltrace2/value.h>
 #include "lib/value.h"
 #include "attributes.h"
 #include <inttypes.h>

diff --git a/src/lib/trace-ir/clock-class.c b/src/lib/trace-ir/clock-class.c
index 736e0b8e2d50f53810eec72c65e65d34b58ceebe..8a3640bcac56fc8592ced72f615782b33c9c0cc0 100644 (file)
--- a/src/lib/trace-ir/clock-class.c
+++ b/src/lib/trace-ir/clock-class.c
@@ -26,7 +26,6 @@
 
 #include "lib/assert-pre.h"
 #include "common/uuid.h"
-#include <babeltrace2/trace-ir/clock-class-const.h>
 #include <babeltrace2/trace-ir/clock-class.h>
 #include "clock-class.h"
 #include "clock-snapshot.h"

diff --git a/src/lib/trace-ir/clock-snapshot.c b/src/lib/trace-ir/clock-snapshot.c
index 19aab80aabdfc34f0e6a18515c9f394a32a31a84..9d20c9c1a0ff69e7b4e378702155224bc8d509e7 100644 (file)
--- a/src/lib/trace-ir/clock-snapshot.c
+++ b/src/lib/trace-ir/clock-snapshot.c
@@ -27,7 +27,7 @@
 #include "common/uuid.h"
 #include "clock-class.h"
 #include "clock-snapshot.h"
-#include <babeltrace2/trace-ir/clock-snapshot-const.h>
+#include <babeltrace2/trace-ir/clock-snapshot.h>
 #include "compat/compiler.h"
 #include <babeltrace2/types.h>
 #include "compat/string.h"

diff --git a/src/lib/trace-ir/event-class.c b/src/lib/trace-ir/event-class.c
index 22211cd1aae8a32d02d2801d5222bf06a01e01aa..20b8850d0c2a77c7b746a4ab97e75e6e8e2fad32 100644 (file)
--- a/src/lib/trace-ir/event-class.c
+++ b/src/lib/trace-ir/event-class.c
@@ -27,7 +27,6 @@
 #include "lib/assert-pre.h"
 #include <babeltrace2/trace-ir/field-class.h>
 #include <babeltrace2/trace-ir/event-class.h>
-#include <babeltrace2/trace-ir/event-class-const.h>
 #include <babeltrace2/trace-ir/stream-class.h>
 #include "compat/compiler.h"
 #include "compat/endian.h"

diff --git a/src/lib/trace-ir/event.c b/src/lib/trace-ir/event.c
index ed2e2f84911b88b1e150b805aae94ae74909b7d5..d110aed85397088277ae79731da4d54de424d5c9 100644 (file)
--- a/src/lib/trace-ir/event.c
+++ b/src/lib/trace-ir/event.c
@@ -25,10 +25,9 @@
 #include "lib/logging.h"
 
 #include "lib/assert-pre.h"
-#include <babeltrace2/trace-ir/event-const.h>
+#include <babeltrace2/trace-ir/event.h>
 #include <babeltrace2/trace-ir/event-class.h>
 #include <babeltrace2/trace-ir/stream-class.h>
-#include <babeltrace2/trace-ir/stream-class-const.h>
 #include <babeltrace2/trace-ir/packet.h>
 #include <babeltrace2/trace-ir/trace.h>
 #include "common/assert.h"

diff --git a/src/lib/trace-ir/field-class.c b/src/lib/trace-ir/field-class.c
index e036cfae2e41e69a6e55f538c43a1e5f91d64e3f..b4a542666752987d10b392a899cc1d863a615284 100644 (file)
--- a/src/lib/trace-ir/field-class.c
+++ b/src/lib/trace-ir/field-class.c
@@ -26,8 +26,6 @@
 
 #include "lib/assert-pre.h"
 #include <babeltrace2/trace-ir/field-class.h>
-#include <babeltrace2/trace-ir/field-class-const.h>
-#include <babeltrace2/trace-ir/field-const.h>
 #include <babeltrace2/trace-ir/field.h>
 #include <babeltrace2/trace-ir/clock-class.h>
 #include "lib/object.h"

diff --git a/src/lib/trace-ir/field-path.c b/src/lib/trace-ir/field-path.c
index 4e5b16f70a657c4de728557a9e9a184e9df3e1ef..d91db38bfbbee257fbf4981c4d136aca5450bb85 100644 (file)
--- a/src/lib/trace-ir/field-path.c
+++ b/src/lib/trace-ir/field-path.c
@@ -26,7 +26,7 @@
 
 #include "lib/assert-pre.h"
 #include <babeltrace2/trace-ir/field-class.h>
-#include <babeltrace2/trace-ir/field-path-const.h>
+#include <babeltrace2/trace-ir/field-path.h>
 #include <limits.h>
 #include <stdint.h>
 #include <inttypes.h>

diff --git a/src/lib/trace-ir/field-path.h b/src/lib/trace-ir/field-path.h
index 99c8f9582cefe7cd7b9eb3bec0bb4fb6e86bbf7b..cda0ba2dd0000c8e9a1963d8252f307ec8882807 100644 (file)
--- a/src/lib/trace-ir/field-path.h
+++ b/src/lib/trace-ir/field-path.h
@@ -27,7 +27,7 @@
  */
 
 #include "lib/object.h"
-#include <babeltrace2/trace-ir/field-path-const.h>
+#include <babeltrace2/trace-ir/field-path.h>
 #include "common/assert.h"
 #include "common/macros.h"
 #include <glib.h>

diff --git a/src/lib/trace-ir/field.c b/src/lib/trace-ir/field.c
index 9ab11aacbbc6e8884343c8d39174200b6a8a7f27..c53d7fafc5325fd5b48e356962315448911952e6 100644 (file)
--- a/src/lib/trace-ir/field.c
+++ b/src/lib/trace-ir/field.c
@@ -26,7 +26,6 @@
 
 #include "lib/assert-pre.h"
 #include <babeltrace2/trace-ir/field.h>
-#include <babeltrace2/trace-ir/field-const.h>
 #include "lib/object.h"
 #include "compat/compiler.h"
 #include "compat/fcntl.h"

diff --git a/src/lib/trace-ir/packet.c b/src/lib/trace-ir/packet.c
index 50304868bf5da33789a3efddbc1058894c1df40f..388e196f268f6b0451433ceab8099277b33a1bf8 100644 (file)
--- a/src/lib/trace-ir/packet.c
+++ b/src/lib/trace-ir/packet.c
@@ -24,7 +24,6 @@
 #include "lib/logging.h"
 
 #include "lib/assert-pre.h"
-#include <babeltrace2/trace-ir/packet-const.h>
 #include <babeltrace2/trace-ir/packet.h>
 #include <babeltrace2/trace-ir/trace.h>
 #include <babeltrace2/trace-ir/stream-class.h>

diff --git a/src/lib/trace-ir/packet.h b/src/lib/trace-ir/packet.h
index e2d825c6ed2b85137c42f038c548d80c18de1667..cf3d80c74fd80034a34b9697be6f4d67f15b75a8 100644 (file)
--- a/src/lib/trace-ir/packet.h
+++ b/src/lib/trace-ir/packet.h
@@ -25,7 +25,7 @@
 
 #include <stdbool.h>
 #include "common/assert.h"
-#include <babeltrace2/trace-ir/clock-snapshot-const.h>
+#include <babeltrace2/trace-ir/clock-snapshot.h>
 #include <babeltrace2/trace-ir/packet.h>
 #include <babeltrace2/trace-ir/field.h>
 #include <babeltrace2/trace-ir/stream.h>

diff --git a/src/lib/trace-ir/resolve-field-path.c b/src/lib/trace-ir/resolve-field-path.c
index 9e8e4729ae88d6ee8f2b55e22cf7db491bcd7a0f..d92a7f3d458fd020456f5d8d5f07d59e2cd33c44 100644 (file)
--- a/src/lib/trace-ir/resolve-field-path.c
+++ b/src/lib/trace-ir/resolve-field-path.c
@@ -25,7 +25,7 @@
 
 #include "lib/assert-pre.h"
 #include "common/assert.h"
-#include <babeltrace2/trace-ir/field-path-const.h>
+#include <babeltrace2/trace-ir/field-path.h>
 #include <limits.h>
 #include <stdbool.h>
 #include <stdint.h>

diff --git a/src/lib/trace-ir/resolve-field-path.h b/src/lib/trace-ir/resolve-field-path.h
index 92e277b89fcd8fd4361e9054e21953362d1af2bc..f44ef858f98816b092c0fcef481dd6a9e19fe7db 100644 (file)
--- a/src/lib/trace-ir/resolve-field-path.h
+++ b/src/lib/trace-ir/resolve-field-path.h
@@ -28,8 +28,8 @@
 
 #include "common/macros.h"
 #include "lib/object.h"
-#include <babeltrace2/trace-ir/field-class-const.h>
-#include <babeltrace2/trace-ir/field-path-const.h>
+#include <babeltrace2/trace-ir/field-class.h>
+#include <babeltrace2/trace-ir/field-path.h>
 #include <glib.h>
 
 struct bt_resolve_field_path_context {

diff --git a/src/lib/trace-ir/stream-class.c b/src/lib/trace-ir/stream-class.c
index e580b2a9e4f132619466c8c05252ff547b682274..e402f4151e40f6e8297e0c86763bb01158f01a15 100644 (file)
--- a/src/lib/trace-ir/stream-class.c
+++ b/src/lib/trace-ir/stream-class.c
@@ -25,7 +25,7 @@
 #include "lib/logging.h"
 
 #include "lib/assert-pre.h"
-#include <babeltrace2/trace-ir/trace-const.h>
+#include <babeltrace2/trace-ir/trace.h>
 #include "compat/compiler.h"
 #include "common/align.h"
 #include "compat/endian.h"

diff --git a/src/lib/trace-ir/stream.c b/src/lib/trace-ir/stream.c
index c35b9da99ea2851a71de06cf3e328e0e014fc559..18e8d093c834f7781a0a49bd1ab2543cf7246feb 100644 (file)
--- a/src/lib/trace-ir/stream.c
+++ b/src/lib/trace-ir/stream.c
@@ -25,7 +25,6 @@
 #include "lib/logging.h"
 
 #include "lib/assert-pre.h"
-#include <babeltrace2/trace-ir/stream-const.h>
 #include <babeltrace2/trace-ir/stream.h>
 #include <babeltrace2/trace-ir/stream-class.h>
 #include <babeltrace2/trace-ir/trace.h>

diff --git a/src/lib/trace-ir/trace-class.c b/src/lib/trace-ir/trace-class.c
index 153300998afd06f1e41bebe9818316adc4cf6199..593f390efac2d4dfd5bf9adcbf467af6db5eccb8 100644 (file)
--- a/src/lib/trace-ir/trace-class.c
+++ b/src/lib/trace-ir/trace-class.c
@@ -27,13 +27,11 @@
 #include "lib/assert-pre.h"
 #include "lib/assert-post.h"
 #include <babeltrace2/trace-ir/trace-class.h>
-#include <babeltrace2/trace-ir/trace-class-const.h>
 #include <babeltrace2/trace-ir/event-class.h>
 #include "ctf-writer/functor.h"
 #include "ctf-writer/clock.h"
 #include "compat/compiler.h"
 #include <babeltrace2/value.h>
-#include <babeltrace2/value-const.h>
 #include "lib/value.h"
 #include <babeltrace2/types.h>
 #include "compat/endian.h"

diff --git a/src/lib/trace-ir/trace.c b/src/lib/trace-ir/trace.c
index 57ebf67bf82257c4a3b57fe891da2e836506b9b1..688a113eb77f41862856c9403a7383455e54ba9b 100644 (file)
--- a/src/lib/trace-ir/trace.c
+++ b/src/lib/trace-ir/trace.c
@@ -27,13 +27,11 @@
 #include "lib/assert-pre.h"
 #include "lib/assert-post.h"
 #include <babeltrace2/trace-ir/trace.h>
-#include <babeltrace2/trace-ir/trace-const.h>
 #include <babeltrace2/trace-ir/event-class.h>
 #include "ctf-writer/functor.h"
 #include "ctf-writer/clock.h"
 #include "compat/compiler.h"
 #include <babeltrace2/value.h>
-#include <babeltrace2/value-const.h>
 #include "lib/value.h"
 #include <babeltrace2/types.h>
 #include "compat/endian.h"

diff --git a/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c b/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c
index 1b88e0f196a91e0051d9990de6706d0b00d6d69d..8faff7bcec6e1013263d211e374ad70cc4d62cea 100644 (file)
--- a/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c
+++ b/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c
@@ -32,8 +32,6 @@
 
 #include "common/assert.h"
 #include <babeltrace2/babeltrace.h>
-/* For bt_property_availability */
-#include <babeltrace2/property.h>
 
 #include "debug-info.h"
 #include "trace-ir-data-copy.h"

diff --git a/src/python-plugin-provider/python-plugin-provider.c b/src/python-plugin-provider/python-plugin-provider.c
index 71bedfc389bbaf9f8e34a1db851e13500712e92c..5d8d8b65455aba53d35f69241cdf8185f8bacbf8 100644 (file)
--- a/src/python-plugin-provider/python-plugin-provider.c
+++ b/src/python-plugin-provider/python-plugin-provider.c
@@ -31,10 +31,10 @@
 
 #include "common/macros.h"
 #include "compat/compiler.h"
-#include <babeltrace2/plugin/plugin-const.h>
+#include <babeltrace2/plugin/plugin-loading.h>
 #include "lib/plugin/plugin.h"
 #include <babeltrace2/graph/component-class.h>
-#include <babeltrace2/current-thread.h>
+#include <babeltrace2/error-reporting.h>
 #include "lib/graph/component-class.h"
 #include "py-common/py-common.h"
 #include <stdbool.h>