/src/babeltrace2-ctf-writer.pc
TAGS
cscope*
-doc/api/Doxyfile
*.gcno
*.gcda
*.gcov
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])]
)
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
+++ /dev/null
-output
\ No newline at end of file
+++ /dev/null
-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
+++ /dev/null
-<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>
-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
+++ /dev/null
-= 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.
+++ /dev/null
-/**
-@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
-*/
+++ /dev/null
-/**
-@page examples Examples
-
-<strong>List of examples</strong>:
-
-- @subpage ctfirexamples CTF IR examples
-*/
+++ /dev/null
-/**
-@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.
-*/
+++ /dev/null
-/**
-@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"
-*/
+++ /dev/null
-/**
-@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>
-*/
+++ /dev/null
-/**
-@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.
-*/
+++ /dev/null
-/**
-@page quickstart Quick start
-@tableofcontents
-
-lol lol
-*/
--- /dev/null
+output
+Doxyfile
+README.html
--- /dev/null
+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 *</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
--- /dev/null
+<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>
--- /dev/null
+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
--- /dev/null
+// 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 `+ +` 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() —
+ Does something else with a parameter.
+@sa bt_another_function() —
+ 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() —
+ Does something else with a parameter.
+
+@sa bt_another_function() —
+ 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.
--- /dev/null
+/*!
+@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.
+*/
--- /dev/null
+/*!
+@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
+*/
--- /dev/null
+/*!
+@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.
+*/
--- /dev/null
+/*!
+@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
+*/
--- /dev/null
+/*!
+@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 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>
+*/
--- /dev/null
+#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);
--- /dev/null
+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.
--- /dev/null
+#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]",
+ ×tamp, &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);
--- /dev/null
+#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);
--- /dev/null
+/* 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);
--- /dev/null
+.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;
+}
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
# 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
# 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
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
--- /dev/null
+#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() —
+ Releases (frees) an error.
+@sa bt_current_thread_move_error() —
+ 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() —
+ Releases (frees) an error.
+@sa BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET() —
+ 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() —
+ 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() —
+ Releases (frees) an error.
+@sa bt_current_thread_take_error —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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 */
+++ /dev/null
-#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 */
--- /dev/null
+#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, 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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, 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() —
+ 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, 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() —
+ 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, 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
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 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() —
+ Returns whether or not a component class is a \bt_src_comp_cls.
+@sa bt_component_class_is_filter() —
+ Returns whether or not a component class is a \bt_flt_comp_cls.
+@sa bt_component_class_is_sink() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
}
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
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() —
+ 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() —
+ 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
}
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
--- /dev/null
+#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 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() —
+ Returns whether or not a component is a \bt_src_comp.
+@sa bt_component_is_filter() —
+ Returns whether or not a component is a \bt_flt_comp.
+@sa bt_component_is_sink() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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 */
+++ /dev/null
-#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 */
--- /dev/null
+#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() —
+ 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() —
+ 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 */
+++ /dev/null
-#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 */
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 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 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 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
}
+++ /dev/null
-#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 */
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() —
+ Resets an interrupter.
+@sa bt_interrupter_is_set() —
+ 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() —
+ Sets an interrupter.
+@sa bt_interrupter_is_set() —
+ 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() —
+ Sets an interrupter.
+@sa bt_interrupter_reset() —
+ 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() —
+ 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() —
+ 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
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
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() —
+ 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() —
+ 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() —
+ 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() —
+ 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} ≥ 1.
+@post
+ <strong>On success</strong>,
+ \bt_p{*count} ≤ \bt_p{capacity}.
+
+@sa bt_message_iterator_class_create() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
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() —
+ 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() —
+ 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} ≥ 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() —
+ 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() —
+ 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() —
+ 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, ns_from_origin)</code>
+ returns #BT_TRUE.
+
+@sa bt_message_iterator_can_seek_ns_from_origin() —
+ 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() —
+ 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() —
+ 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() —
+ 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
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
--- /dev/null
+#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, 2<sup>64</sup> - 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 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() —
+ \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() —
+ 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() —
+ 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() —
+ \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() —
+ 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() —
+ 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() —
+ \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() —
+ \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() —
+ \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() —
+ \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() —
+ 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() —
+ 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() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
--- /dev/null
+#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 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() —
+ Returns whether or not a port is an \bt_iport.
+@sa bt_port_is_output() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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 */
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(
return __BT_UPCAST_CONST(bt_query_executor, query_executor);
}
+/*! @} */
+
+/*! @} */
+
#ifdef __cplusplus
}
#endif
+++ /dev/null
-#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 */
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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
}
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
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)
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
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
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
}
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Borrows a trace processing graph's default interrupter.
+@sa bt_graph_add_interrupter() —
+ 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)
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
}
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
+++ /dev/null
-#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 */
#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 value</em> ≤ <strong>𝑥</strong> ≤ <em>upper value</em>).
+
+For example, an unsigned integer range set could contain the ranges
+[5, 14], [199, 2001], and [1976, 3000].
+
+This integer range set API offers unsigned and signed 64-bit integer
+ranges and integer range sets with dedicated C 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, 9] and [10, 15]
+is \em not equal to an unsigned integer range containing [2, 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() —
+ 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() —
+ 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, 23] and [24, 42]
+is \em not equal to a signed integer range containing [-57, 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() —
+ 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() —
+ 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
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() —
+ 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() —
+ 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() —
+ 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
}
+++ /dev/null
-#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 */
#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>
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 */
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).
#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
--- /dev/null
+#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 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
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 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 Hz.
+- Offset in seconds: -10 seconds.
+- Offset in cycles: 500 cycles (that is, 0.5 seconds).
+- Stream clock's value: 2000 cycles (that is, 2 seconds).
+
+Then the computed value is -7.5 seconds from origin, or
+-7,500,000,000 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 cycles and the stream
+ clock value 42 cycles, the real stream clock value can be
+ anything between 35 cycles and 49 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 GHz
+ <tr>
+ <td>\ref api-tir-clock-cls-prop-offset "Offset" in seconds
+ <td>0 seconds
+ <tr>
+ <td>\ref api-tir-clock-cls-prop-offset "Offset" in cycles
+ <td>0 cycles
+ <tr>
+ <td>\ref api-tir-clock-cls-prop-precision "Precision"
+ <td>0 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Sets the user attributes of a clock class.
+@sa bt_clock_class_borrow_user_attributes_const() —
+ \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() —
+ 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() —
+ 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() —
+ 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
+++ /dev/null
-#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 */
--- /dev/null
+#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() —
+ 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() —
+ Converts a clock value from cycles to nanoseconds from the clock's
+ origin.
+@sa bt_clock_class_cycles_to_ns_from_origin() —
+ 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 */
+++ /dev/null
-#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 */
#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() —
+ 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() —
+ 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() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Borrows the payload field class of an event class.
+@sa bt_event_class_borrow_payload_field_class_const() —
+ 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() —
+ Sets the payload field class of an event class.
+@sa bt_event_class_borrow_payload_field_class_const() —
+ \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() —
+ Borrows the specific context field class of an event class.
+@sa bt_event_class_borrow_specific_context_field_class_const() —
+ 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() —
+ Sets the specific context field class of an event class.
+@sa bt_event_class_borrow_specific_context_field_class_const() —
+ \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() —
+ 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() —
+ Sets the user attributes of an event class.
+@sa bt_event_class_borrow_user_attributes_const() —
+ \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() —
+ 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() —
+ 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
+++ /dev/null
-#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 */
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() —
+ \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() —
+ \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() —
+ \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() —
+ \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() —
+ \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() —
+ \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
}
+++ /dev/null
-#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 */
#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, 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, 19] and [25, 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, 11], [15, 37]
+ - <code>SODIUM</code>: [7, 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 A has a link to another field class 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 A to a preceding field class B, pass
+field class B when you create field class 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 A with a linked field class 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 A vs. field class 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() —
+ 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() —
+ 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() —
+ 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() —
+ Sets the user attributes of a field class.
+@sa bt_field_class_borrow_user_attributes_const() —
+ \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, 2<sup><em>N</em></sup> - 1]</dd>
+
+ <dt>Signed integer field class</dt>
+ <dd>[-2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> - 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() —
+ 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, 2<sup><em>N</em></sup> - 1]</dd>
+
+ <dt>Signed integer field class</dt>
+ <dd>[-2<sup><em>N</em></sup>, 2<sup><em>N</em></sup> - 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() —
+ 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() —
+ 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() —
+ 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, 2<sup>64</sup> - 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>, 2<sup>63</sup> - 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, 2<sup>64</sup> - 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() —
+ 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>, 2<sup>63</sup> - 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() —
+ 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() —
+ \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() —
+ Returns the number of members contained in a structure field class.
+@sa bt_field_class_structure_borrow_member_by_index_const() —
+ \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() —
+ \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() —
+ \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() —
+ 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() —
+ Sets the user attributes of a structure field class member.
+@sa bt_field_class_structure_member_borrow_user_attributes_const() —
+ \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() —
+ \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() —
+ 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() —
+ 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() —
+ Returns the number of options contained in a variant field class.
+@sa bt_field_class_variant_borrow_option_by_index_const() —
+ \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() —
+ \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() —
+ \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() —
+ 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() —
+ Sets the user attributes of a variant field class option.
+@sa bt_field_class_variant_option_borrow_user_attributes_const() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
}
+++ /dev/null
-#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 */
+++ /dev/null
-#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 */
--- /dev/null
+#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() —
+ 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() —
+ 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() —
+ 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 */
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 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() —
+ 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() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Returns the value of a string field.
+@sa bt_field_string_append() —
+ Appends a string to a string field.
+@sa bt_field_string_clear() —
+ 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() —
+ 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() —
+ Appends a string with a given length to a string field.
+@sa bt_field_string_set_value() —
+ 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() —
+ Appends a string to a string field.
+@sa bt_field_string_set_value() —
+ 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() —
+ 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() —
+ \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() —
+ \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() —
+ \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() —
+ Sets whether or not an option field has a field.
+@sa bt_field_option_borrow_field_const() —
+ \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() —
+ Sets a variant field's selected option.
+@sa bt_field_variant_get_selected_option_index() —
+ Returns the index of a variant field's selected option.
+@sa bt_field_variant_borrow_selected_option_field_const() —
+ \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() —
+ 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
+++ /dev/null
-#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 */
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() —
+ \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() —
+ \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() —
+ 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() —
+ 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
+++ /dev/null
-#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 */
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() —
+ 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() —
+ 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() —
+ \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() —
+ Returns the number of event classes contained in a stream class.
+@sa bt_stream_class_borrow_event_class_by_index_const() —
+ \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() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ Borrows the default clock class of a stream class.
+@sa bt_stream_class_borrow_default_clock_class_const() —
+ 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() —
+ Sets the default clock class of a stream class.
+@sa bt_stream_class_borrow_default_clock_class_const() —
+ \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() —
+ Borrows the packet context field class of a stream class.
+@sa bt_stream_class_borrow_packet_context_field_class_const() —
+ 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() —
+ Sets the packet context field class of a stream class.
+@sa bt_stream_class_borrow_packet_context_field_class_const() —
+ \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() —
+ Borrows the event common context field class of a stream class.
+@sa bt_stream_class_borrow_event_common_context_field_class_const() —
+ 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() —
+ Sets the event common context field class of a stream class.
+@sa bt_stream_class_borrow_event_common_context_field_class_const() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Returns whether or not a stream class's streams have packets.
+@sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
+ 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() —
+ 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() —
+ 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() —
+ Sets whether or not a stream class's streams have packets.
+@sa bt_stream_class_packets_have_end_default_clock_snapshot() —
+ 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() —
+ Sets whether or not a stream class's streams have packets.
+@sa bt_stream_class_packets_have_beginning_default_clock_snapshot() —
+ 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() —
+ Returns whether or not a stream class's streams can have
+ discarded events.
+@sa bt_stream_class_discarded_events_have_default_clock_snapshots() —
+ 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() —
+ 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() —
+ 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() —
+ Returns whether or not a stream class's streams can have
+ discarded packets.
+@sa bt_stream_class_discarded_packets_have_default_clock_snapshots() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Sets the user attributes of a stream class.
+@sa bt_stream_class_borrow_user_attributes_const() —
+ \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() —
+ 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() —
+ 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
}
+++ /dev/null
-#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 */
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() —
+ 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() —
+ 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() —
+ \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() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Sets the user attributes of a stream.
+@sa bt_stream_borrow_user_attributes_const() —
+ \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() —
+ 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() —
+ 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
+++ /dev/null
-#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 */
-#ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
+ #ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H
#define BABELTRACE2_TRACE_IR_TRACE_CLASS_H
/*
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() —
+ Returns the number of stream classes contained in a trace class.
+@sa bt_trace_class_borrow_stream_class_by_index_const() —
+ \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() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ Sets the user attributes of a trace class.
+@sa bt_trace_class_borrow_user_attributes_const() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
+++ /dev/null
-#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 */
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() —
+ \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() —
+ Returns the number of streams contained in a trace.
+@sa bt_trace_borrow_stream_by_index_const() —
+ \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() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Sets the user attributes of a trace.
+@sa bt_trace_borrow_user_attributes_const() —
+ \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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
}
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;
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 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
}
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() —
+ 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
}
+++ /dev/null
-#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 */
#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() —
+ Returns whether or not the type of a value conceptually is a given
+ type.
+@sa bt_value_is_null() —
+ Returns whether or not a value is a null value.
+@sa bt_value_is_bool() —
+ Returns whether or not a value is a boolean value.
+@sa bt_value_is_unsigned_integer() —
+ Returns whether or not a value is an unsigned integer value.
+@sa bt_value_is_signed_integer() —
+ Returns whether or not a value is a signed integer value.
+@sa bt_value_is_real() —
+ Returns whether or not a value is a real value.
+@sa bt_value_is_string() —
+ Returns whether or not a value is a string value.
+@sa bt_value_is_array() —
+ Returns whether or not a value is an array value.
+@sa bt_value_is_map() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_is_null() —
+ Returns whether or not a value is a null value.
+@sa bt_value_is_bool() —
+ Returns whether or not a value is a boolean value.
+@sa bt_value_is_unsigned_integer() —
+ Returns whether or not a value is an unsigned integer value.
+@sa bt_value_is_signed_integer() —
+ Returns whether or not a value is a signed integer value.
+@sa bt_value_is_real() —
+ Returns whether or not a value is a real value.
+@sa bt_value_is_string() —
+ Returns whether or not a value is a string value.
+@sa bt_value_is_array() —
+ Returns whether or not a value is an array value.
+@sa bt_value_is_map() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ Returns whether or not the type of a value conceptually is a given
+ type.
+@sa #bt_value_null —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ 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() —
+ Returns the type enumerator of a value.
+@sa bt_value_type_is() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ Creates and appends a boolean value to an array value.
+@sa bt_value_array_append_unsigned_integer_element() —
+ Creates and appends an unsigned integer value to an array value.
+@sa bt_value_array_append_signed_integer_element() —
+ Creates and appends a signed integer value to an array value.
+@sa bt_value_array_append_real_element() —
+ Creates and appends a real value to an array value.
+@sa bt_value_array_append_string_element() —
+ Creates and appends a string value to an array value.
+@sa bt_value_array_append_empty_array_element() —
+ Creates and appends an empty array value to an array value.
+@sa bt_value_array_append_empty_map_element() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ \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() —
+ 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 0).
+
+@bt_pre_not_null{value}
+@bt_pre_is_array_val{value}
+
+@sa bt_value_array_get_length() —
+ 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() —
+ Creates a boolean value and uses it to insert an entry in a map
+ value.
+@sa bt_value_map_insert_unsigned_integer_entry() —
+ Creates an unsigned integer value and uses it to insert an entry in
+ a map value.
+@sa bt_value_map_insert_signed_integer_entry() —
+ Creates a signed value and uses it to insert an entry in a map
+ value.
+@sa bt_value_map_insert_real_entry() —
+ Creates a real value and uses it to insert an entry in a map value.
+@sa bt_value_map_insert_string_entry() —
+ Creates a string value and uses it to insert an entry in a map
+ value.
+@sa bt_value_map_insert_empty_array_entry() —
+ Creates an empty array value and uses it to insert an entry in a map
+ value.
+@sa bt_value_map_insert_empty_map_entry() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ \c const version of this function.
+@sa bt_value_map_has_entry() —
+ 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() —
+ 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() —
+ \c const version of this function.
+@sa bt_value_map_borrow_entry_value() —
+ 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() —
+ 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() —
+ 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() —
+ 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 0).
+@bt_pre_not_null{value}
+@bt_pre_is_map_val{value}
+
+@sa bt_value_map_get_size() —
+ 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() —
+ 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() —
+ 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() —
+ 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() —
+ 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
}
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
*/
#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>
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/clock-class-const.h>
%include <babeltrace2/trace-ir/clock-class.h>
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/clock-snapshot-const.h>
+%include <babeltrace2/trace-ir/clock-snapshot.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/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
*/
%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"
* THE SOFTWARE.
*/
-%include <babeltrace2/graph/connection-const.h>
+%include <babeltrace2/graph/connection.h>
* 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"
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/event-const.h>
%include <babeltrace2/trace-ir/event.h>
$result = SWIG_Python_AppendOutput($result, SWIG_From_int(*$1));
}
-%include <babeltrace2/trace-ir/event-class-const.h>
%include <babeltrace2/trace-ir/event-class.h>
/* For label type mappings. */
%include "native_bt_field_class.i"
-%include <babeltrace2/trace-ir/field-const.h>
%include <babeltrace2/trace-ir/field.h>
/* 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;
}
}
-%include <babeltrace2/trace-ir/field-class-const.h>
%include <babeltrace2/trace-ir/field-class.h>
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/field-path-const.h>
+%include <babeltrace2/trace-ir/field-path.h>
}
}
-%include <babeltrace2/graph/graph-const.h>
%include <babeltrace2/graph/graph.h>
/* Helper functions for Python */
*/
%include <babeltrace2/integer-range-set.h>
-%include <babeltrace2/integer-range-set-const.h>
*/
%include <babeltrace2/graph/interrupter.h>
-%include <babeltrace2/graph/interrupter-const.h>
}
}
-%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>
*/
%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"
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/packet-const.h>
%include <babeltrace2/trace-ir/packet.h>
}
}
-%include <babeltrace2/plugin/plugin-const.h>
-%include <babeltrace2/plugin/plugin-set-const.h>
+%include <babeltrace2/plugin/plugin-loading.h>
/* Helpers */
$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
*/
%include <babeltrace2/graph/private-query-executor.h>
-%include <babeltrace2/graph/query-executor-const.h>
%include <babeltrace2/graph/query-executor.h>
%{
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/stream-const.h>
%include <babeltrace2/trace-ir/stream.h>
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/stream-class-const.h>
%include <babeltrace2/trace-ir/stream-class.h>
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/trace-const.h>
%include <babeltrace2/trace-ir/trace.h>
%{
* THE SOFTWARE.
*/
-%include <babeltrace2/trace-ir/trace-class-const.h>
%include <babeltrace2/trace-ir/trace-class.h>
/* Helper functions for Python */
* THE SOFTWARE.
*/
-%include <babeltrace2/value-const.h>
%include <babeltrace2/value.h>
%{
#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"
#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"
#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;
#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>
* 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"
#include "common/common.h"
#include <babeltrace2/types.h>
#include <babeltrace2/value.h>
-#include <babeltrace2/value-const.h>
#include <unistd.h>
#include <glib.h>
#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"
*/
#include "common/macros.h"
-#include <babeltrace2/graph/component-filter-const.h>
+#include <babeltrace2/graph/component.h>
#include "component-class.h"
#include "component.h"
#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"
#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"
#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"
#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>
*/
#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>
#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>
* SOFTWARE.
*/
-#include <babeltrace2/graph/connection-const.h>
+#include <babeltrace2/graph/connection.h>
#include "lib/object.h"
#include "common/assert.h"
#include "common/macros.h"
#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>
#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"
#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"
#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"
#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"
#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>
#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>
#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"
#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;
#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"
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;
#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>
#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>
#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>
* SOFTWARE.
*/
-#include <babeltrace2/graph/message-stream-const.h>
+#include <babeltrace2/graph/message.h>
#include "compat/compiler.h"
#include "lib/trace-ir/stream.h"
#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"
#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"
* SOFTWARE.
*/
-#include <babeltrace2/graph/port-const.h>
+#include <babeltrace2/graph/port.h>
#include "common/macros.h"
struct bt_port {
#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"
#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>
#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>
#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>
#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>
#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"
#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"
#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"
#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"
#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"
#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>
*/
#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>
#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"
#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>
#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>
#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>
#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 {
#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"
#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>
#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"
#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"
#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"
#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>