From: Philippe Proulx Date: Sat, 21 Sep 2019 16:02:25 +0000 (-0400) Subject: Document libbabeltrace2's C API X-Git-Tag: v2.0.0~10 X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=7704a0af9f2275321f8294df8c02f8a299b3134e Document libbabeltrace2's C API This patch adds initial documentation for the Babeltrace 2 library's C API using Doxygen. The Doxygen project is located in `doc/api/libbabeltrace2`, as we can eventually add `doc/api/libbabeltrace2-ctf-writer`. To be able to use Doxygen's member grouping [1], I had to join some header files (`const` and non `const` headers, for example), because otherwise I could not get some functions in separate files to be in the same member group in the order I want. In the end, the library user includes ``, so how we organize the headers exactly is not so crucial. [1]: http://www.doxygen.nl/manual/grouping.html#memgroup Signed-off-by: Philippe Proulx Change-Id: I6d1dc2e7c5ee63fcd4220d0fd9f0931d361d2f31 Reviewed-on: https://review.lttng.org/c/babeltrace/+/2807 Tested-by: jenkins --- diff --git a/.gitignore b/.gitignore index f6ae6ec3..16baf519 100644 --- a/.gitignore +++ b/.gitignore @@ -61,7 +61,6 @@ __pycache__ /src/babeltrace2-ctf-writer.pc TAGS cscope* -doc/api/Doxyfile *.gcno *.gcda *.gcov diff --git a/configure.ac b/configure.ac index 7cbe3ba7..6bbedb03 100644 --- a/configure.ac +++ b/configure.ac @@ -563,7 +563,7 @@ AS_IF([test "x$enable_api_doc" = "xyes"], DX_XML_FEATURE(OFF) DX_PDF_FEATURE(OFF) DX_PS_FEATURE(OFF) - DX_INIT_DOXYGEN([Babeltrace], [$(srcdir)/Doxyfile], [output]) + DX_INIT_DOXYGEN([Babeltrace 2], [$(builddir)/Doxyfile], [output]) AS_IF([test -z "$DX_DOXYGEN"], [AC_MSG_ERROR([You need doxygen to enable the API documentation])] ) @@ -724,8 +724,9 @@ program_transform_name="s&babeltrace2\.bin&babeltrace2&;$program_transform_name" AC_SUBST(program_transform_name) AC_CONFIG_FILES([ - doc/api/Doxyfile doc/api/Makefile + doc/api/libbabeltrace2/Doxyfile + doc/api/libbabeltrace2/Makefile doc/bindings/Makefile doc/bindings/python/Makefile doc/contributing-images/Makefile diff --git a/doc/api/.gitignore b/doc/api/.gitignore deleted file mode 100644 index 6caf68af..00000000 --- a/doc/api/.gitignore +++ /dev/null @@ -1 +0,0 @@ -output \ No newline at end of file diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in deleted file mode 100644 index 376888ce..00000000 --- a/doc/api/Doxyfile.in +++ /dev/null @@ -1,239 +0,0 @@ -DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = "Babeltrace C API" -PROJECT_NUMBER = @PACKAGE_VERSION@ -PROJECT_BRIEF = "Trace converter with plugin support" -CREATE_SUBDIRS = NO -ALLOW_UNICODE_NAMES = NO -OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ALWAYS_DETAILED_SEC = NO -INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = YES -STRIP_FROM_PATH = "@top_srcdir@/include" -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = NO -QT_AUTOBRIEF = NO -MULTILINE_CPP_IS_BRIEF = YES -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 4 -ALIASES = -ALIASES += btversion="@PACKAGE_VERSION@" -ALIASES += postsuccessrefcountretinc="@post On success, the reference count of the returned object is incremented." -ALIASES += postsuccessrefcountret1="@post On success, the reference count of the returned object is 1." -ALIASES += postsuccessrefcountinc{1}="@post On success, 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 On success, \p \1 is frozen." -ALIASES += prenotnull{1}="@pre \p \1 is not \c NULL." -ALIASES += prehot{1}="@pre \p \1 is not frozen." -ALIASES += preisintft{1}="@pre \p \1 is a \link ctfirintfieldtype CTF IR integer field type\endlink." -ALIASES += preisfloatft{1}="@pre \p \1 is a \link ctfirfloatfieldtype CTF IR floating point number field type\endlink." -ALIASES += preisenumft{1}="@pre \p \1 is a \link ctfirenumfieldtype CTF IR enumeration field type\endlink." -ALIASES += preisstringft{1}="@pre \p \1 is a \link ctfirstringfieldtype CTF IR string field type\endlink." -ALIASES += preisstructft{1}="@pre \p \1 is a \link ctfirstructfieldtype CTF IR structure field type\endlink." -ALIASES += preisarrayft{1}="@pre \p \1 is a \link ctfirarrayfieldtype CTF IR array field type\endlink." -ALIASES += preisseqft{1}="@pre \p \1 is a \link ctfirseqfieldtype CTF IR sequence field type\endlink." -ALIASES += preisvarft{1}="@pre \p \1 is a \link ctfirvarfieldtype CTF IR variant field type\endlink." -ALIASES += preisintfield{1}="@pre \p \1 is a \link ctfirintfield CTF IR integer field\endlink." -ALIASES += preisfloatfield{1}="@pre \p \1 is a \link ctfirfloatfield CTF IR floating point number field\endlink." -ALIASES += preisenumfield{1}="@pre \p \1 is a \link ctfirenumfield CTF IR enumeration field\endlink." -ALIASES += preisstringfield{1}="@pre \p \1 is a \link ctfirstringfield CTF IR string field\endlink." -ALIASES += preisstructfield{1}="@pre \p \1 is a \link ctfirstructfield CTF IR structure field\endlink." -ALIASES += preisarrayfield{1}="@pre \p \1 is a \link ctfirarrayfield CTF IR array field\endlink." -ALIASES += preisseqfield{1}="@pre \p \1 is a \link ctfirseqfield CTF IR sequence field\endlink." -ALIASES += preisvarfield{1}="@pre \p \1 is a \link ctfirvarfield CTF IR variant field\endlink." -ALIASES += ft="\link ctfirfieldtypes CTF IR field type\endlink" -ALIASES += fts="\link ctfirfieldtypes CTF IR field types\endlink" -ALIASES += intft="\link ctfirintfieldtype CTF IR integer field type\endlink" -ALIASES += floatft="\link ctfirfloatfieldtype CTF IR floating point number field type\endlink" -ALIASES += enumft="\link ctfirenumfieldtype CTF IR enumeration field type\endlink" -ALIASES += enumftiter="\link ctfirenumftmappingiter CTF IR enumeration field type mapping iterator\endlink" -ALIASES += stringft="\link ctfirstringfieldtype CTF IR string field type\endlink" -ALIASES += structft="\link ctfirstructfieldtype CTF IR structure field type\endlink" -ALIASES += arrayft="\link ctfirarrayfieldtype CTF IR array field type\endlink" -ALIASES += seqft="\link ctfirseqfieldtype CTF IR sequence field type\endlink" -ALIASES += varft="\link ctfirvarfieldtype CTF IR variant field type\endlink" -ALIASES += intfts="\link ctfirintfieldtype CTF IR integer field types\endlink" -ALIASES += floatfts="\link ctfirfloatfieldtype CTF IR floating point number field types\endlink" -ALIASES += enumfts="\link ctfirenumfieldtype CTF IR enumeration field types\endlink" -ALIASES += stringfts="\link ctfirstringfieldtype CTF IR string field types\endlink" -ALIASES += structfts="\link ctfirstructfieldtype CTF IR structure field types\endlink" -ALIASES += arrayfts="\link ctfirarrayfieldtype CTF IR array field types\endlink" -ALIASES += seqfts="\link ctfirseqfieldtype CTF IR sequence field types\endlink" -ALIASES += varfts="\link ctfirvarfieldtype CTF IR variant field types\endlink" -ALIASES += field="\link ctfirfields CTF IR field\endlink" -ALIASES += fields="\link ctfirfields CTF IR fields\endlink" -ALIASES += intfield="\link ctfirintfield CTF IR integer field\endlink" -ALIASES += floatfield="\link ctfirfloatfield CTF IR floating point number field\endlink" -ALIASES += enumfield="\link ctfirenumfield CTF IR enumeration field\endlink" -ALIASES += stringfield="\link ctfirstringfield CTF IR string field\endlink" -ALIASES += structfield="\link ctfirstructfield CTF IR structure field\endlink" -ALIASES += arrayfield="\link ctfirarrayfield CTF IR array field\endlink" -ALIASES += seqfield="\link ctfirseqfield CTF IR sequence field\endlink" -ALIASES += varfield="\link ctfirvarfield CTF IR variant field\endlink" -ALIASES += intfields="\link ctfirintfield CTF IR integer fields\endlink" -ALIASES += floatfields="\link ctfirfloatfield CTF IR floating point number fields\endlink" -ALIASES += enumfields="\link ctfirenumfield CTF IR enumeration fields\endlink" -ALIASES += stringfields="\link ctfirstringfield CTF IR string fields\endlink" -ALIASES += structfields="\link ctfirstructfield CTF IR structure fields\endlink" -ALIASES += arrayfields="\link ctfirarrayfield CTF IR array fields\endlink" -ALIASES += seqfields="\link ctfirseqfield CTF IR sequence fields\endlink" -ALIASES += varfields="\link ctfirvarfield CTF IR variant fields\endlink" -ALIASES += imgpacketstructure="@image html ctf-stream-packet.png \"Structure of a CTF packet.\"" -ALIASES += imgtracestructure="@image html ctf-trace.png \"Structure of a CTF trace.\"" -ALIASES += noteexamplesassert="@note In the following examples, we use \c assert() to validate the results of the called functions." -OPTIMIZE_OUTPUT_FOR_C = YES -MARKDOWN_SUPPORT = YES -TOC_INCLUDE_HEADINGS = 0 -AUTOLINK_SUPPORT = YES -SUBGROUPING = YES -INLINE_GROUPED_CLASSES = NO -INLINE_SIMPLE_STRUCTS = NO -TYPEDEF_HIDES_STRUCT = NO -LOOKUP_CACHE_SIZE = 0 - -EXTRACT_ALL = NO -EXTRACT_PRIVATE = NO -EXTRACT_PACKAGE = NO -EXTRACT_STATIC = YES -EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = NO -EXTRACT_ANON_NSPACES = NO -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = YES -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = NO -HIDE_SCOPE_NAMES = NO -HIDE_COMPOUND_REFERENCE= NO -SHOW_INCLUDE_FILES = NO -SHOW_GROUPED_MEMB_INC = NO -FORCE_LOCAL_INCLUDES = NO -INLINE_INFO = YES -SORT_MEMBER_DOCS = NO -SORT_BRIEF_DOCS = NO -SORT_MEMBERS_CTORS_1ST = NO -SORT_GROUP_NAMES = NO -SORT_BY_SCOPE_NAME = NO -STRICT_PROTO_MATCHING = NO -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = YES -SHOW_FILES = YES -SHOW_NAMESPACES = NO -FILE_VERSION_FILTER = -LAYOUT_FILE = "@srcdir@/DoxygenLayout.xml" -CITE_BIB_FILES = - -QUIET = NO -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = YES -WARN_AS_ERROR = NO -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = - -INPUT = "@top_srcdir@/include/babeltrace2/ctf-ir" \ - "@top_srcdir@/include/babeltrace2/component" \ - "@top_srcdir@/include/babeltrace2/plugin" \ - "@top_srcdir@/include/babeltrace2/ref.h" \ - "@top_srcdir@/include/babeltrace2/values.h" \ - "@top_srcdir@/include/babeltrace2/logging.h" \ - "@top_srcdir@/include/babeltrace2/types.h" \ - "@srcdir@/dox/main-page.dox" \ - "@srcdir@/dox/includes-build.dox" \ - "@srcdir@/dox/write-plugin.dox" \ - "@srcdir@/dox/use-ctf-writer.dox" \ - "@srcdir@/dox/examples.dox" \ - "@srcdir@/dox/examples-ctfir.dox" \ - "@srcdir@/dox/group-api-ref.dox" \ - "@srcdir@/dox/group-ctf-ir.dox" -INPUT_ENCODING = UTF-8 -FILE_PATTERNS = *.h \ - *.hh \ - *.hpp \ - *.dox -RECURSIVE = NO -EXCLUDE = -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = * -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = "@srcdir@/images" -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -FILTER_SOURCE_PATTERNS = -USE_MDFILE_AS_MAINPAGE = - -SOURCE_BROWSER = NO -INLINE_SOURCES = NO -STRIP_CODE_COMMENTS = YES -REFERENCED_BY_RELATION = NO -REFERENCES_RELATION = NO -REFERENCES_LINK_SOURCE = YES -SOURCE_TOOLTIPS = YES -USE_HTAGS = NO -VERBATIM_HEADERS = YES - -ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = - -OUTPUT_DIRECTORY = output - -GENERATE_HTML = YES -HTML_FILE_EXTENSION = .html -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -HTML_EXTRA_STYLESHEET = -HTML_EXTRA_FILES = -HTML_COLORSTYLE_HUE = 220 -HTML_COLORSTYLE_SAT = 100 -HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = YES -HTML_DYNAMIC_SECTIONS = YES -HTML_INDEX_NUM_ENTRIES = 100 - -GENERATE_DOCSET = NO -GENERATE_HTMLHELP = NO -GENERATE_CHI = NO -GENERATE_QHP = NO -GENERATE_ECLIPSEHELP = NO - -DISABLE_INDEX = NO -GENERATE_TREEVIEW = YES -ENUM_VALUES_PER_LINE = 4 -TREEVIEW_WIDTH = 250 -EXT_LINKS_IN_WINDOW = NO -FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES -USE_MATHJAX = NO -MATHJAX_FORMAT = HTML-CSS -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest -MATHJAX_EXTENSIONS = -MATHJAX_CODEFILE = -SEARCHENGINE = YES -SERVER_BASED_SEARCH = NO -EXTERNAL_SEARCH = NO -SEARCHENGINE_URL = -SEARCHDATA_FILE = searchdata.xml -EXTERNAL_SEARCH_ID = -EXTRA_SEARCH_MAPPINGS = - -GENERATE_LATEX = NO -GENERATE_RTF = NO -GENERATE_MAN = NO -GENERATE_XML = NO -GENERATE_PERLMOD = NO diff --git a/doc/api/DoxygenLayout.xml b/doc/api/DoxygenLayout.xml deleted file mode 100644 index 0881dc84..00000000 --- a/doc/api/DoxygenLayout.xml +++ /dev/null @@ -1,194 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/api/Makefile.am b/doc/api/Makefile.am index c84bb770..18aeeba3 100644 --- a/doc/api/Makefile.am +++ b/doc/api/Makefile.am @@ -1,17 +1 @@ -API_DOC_INSTALL_DIR = "$(DESTDIR)$(docdir)/api" - -all-local: doxygen-doc - -install-data-local: doxygen-doc - $(mkdir_p) "$(API_DOC_INSTALL_DIR)" - cp -rv output/html "$(API_DOC_INSTALL_DIR)" - -@DX_RULES@ - -MOSTLYCLEANFILES = $(DX_CLEANFILES) -EXTRA_DIST = Doxyfile.in \ - README.adoc \ - dox/group-api-ref.dox \ - dox/group-ctf-ir.dox \ - dox/main-page.dox \ - dox/quick-start.dox +SUBDIRS = libbabeltrace2 diff --git a/doc/api/README.adoc b/doc/api/README.adoc deleted file mode 100644 index 3e6ce69f..00000000 --- a/doc/api/README.adoc +++ /dev/null @@ -1,351 +0,0 @@ -= Babeltrace C API documentation guidelines - -Please follow those guidelines when you add to or modify the existing -documentation of the Babeltrace C API. - - -== Syntax - -Syntax example to document a function (tabs are converted to spaces -in this example, but you really _must_ use tabs to indent): - ----- -/** -@brief Sets the name of the CTF IR stream class \p stream_class - to \p name. - -\p name must be unique amongst the names of all the stream classes -of the trace class to which you eventually add \p stream_class. - -@remarks -This is where you would put some remarks. Lorem ipsum dolor sit amet, -consectetur adipiscing elit. Vestibulum sagittis tristique velit vitae -tincidunt. - -@warning -Use a warning command if this message is really important. - -@param[in] stream_class Stream class of which to set the name. -@param[in] name Name of the stream class (copied on success). If - the description is too long, continue on the - next line like this. -@returns 0 on success, or a negative value on error. - -@prenotnull{stream_class} -@prenotnull{name} -@prehot{stream_class} -@pre Some custom precondition. -@postrefcountsame{stream_class} -@post Some custom postcondition. - -@sa btstream_class_get_name(): Returns the name of a given stream class. -*/ ----- - -**Rules**: - -* Try to stay behind the 72th column mark if possible, and behind the - 80th column otherwise. - -* Start the block with - https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdbrief[`@brief`] - followed by a tab followed by the brief description. If the brief - description needs more than one line, start the following lines with a - tab character. -+ -Try to always refer to all the function or macro parameters in the brief -description. The sentence _must_ begin with a verb, third-person -singular. The brief description _must_ contain a single sentence -which ends with a period. -+ -Follow the brief description by zero or more paragraphs giving more -details about the object you are documenting. -+ -You can also use the -https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdremark[`@remarks`] -and -https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdwarning[`@warning`] -commands as needed to add special paragraphs. - -* When you refer to parameters, use the - https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdp[`\p`] - command: -+ --- ----- -@brief Transfers the ownership of a Babeltrace object from variable - \p _var_src to variable \p _var_dst. ----- --- - -* When you refer to any keyword or definition, use the - https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdc[`\c`] - command if it's a single word, otherwise surround the words with - `` and ``: -+ --- ----- -@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 On success, 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 `` -and ``. 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 ``/``. In general, prefer -light emphasis to strong emphasis. - -Links to other parts of the documentation are very important. Consider -that the reader never knows that other functions exist other than the -current one. Use as many internal links as possible. Use the following -forms of links: - -* `func()`: automatic link to the function (or macro) `func()`. -* `file.h`: automatic link to the file named `file.h`. -* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref - group`]: link to the - https://www.stack.nl/\~dimitri/doxygen/manual/grouping.html[group] - named `group` (prefer this over a link to a file). -* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref - variable`]: link to the variable `variable`. -* https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdlink[`\link - reference some text\endlink`]: link to `reference` (file name, group - name, function or macro name, etc.) using the text `some text`. -+ -Example: -+ --- ----- -You can create a \link events CTF IR event\endlink using [...] -By calling \link func() said function\endlink, [...] ----- --- -+ --- -[NOTE] -.Doxygen limitation. -==== -Do not put a space between the end of the text and the `\endlink` -command, because this space becomes part of the hyperlink's text. - -Do _not_ do: - ----- -You can create a \link events CTF IR event \endlink using [...] -By calling \link func() said function \endlink, [...] ----- -==== --- - -See Doxygen's -https://www.stack.nl/\~dimitri/doxygen/manual/autolink.html[Automatic -link generation] for other ways to create automatic links. - -Try to follow as much as possible the -https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual of Style] -(4th edition) when you document the API. This includes: - -* Use an active voice. -* Use a gender-neutral language. -* Use the present tense (you should never need the future tense). -* Address your reader directly (use _you_). -* Avoid anthropomorphism. -* Ensure parallelism in lists, procedures, and sentences. -* Terminate list items with a period. -* Do not use Latin abbreviations. -* Use _and_ or _or_ instead of a slash. -* Avoid using negatives. -* Avoid using _should_: most of the time, you mean _must_. - - -== Babeltrace terminology - -Here are the official names of the Babeltrace objects that you must use -as is in the API documentation: - -* Value objects: -** The null value object (_the_, not _a_, since it's a singleton - variable) -** Boolean value object -** Integer value object -** Floating point number value object -** String value object -** Array value object -** Map value object -* CTF IR field path object -* CTF IR field types -** CTF IR integer field type -** CTF IR floating point number field type -** CTF IR enumeration field type -** CTF IR string field type -** CTF IR array field type -** CTF IR sequence field type -** CTF IR structure field type -** CTF IR variant field type -* CTF IR fields: -** CTF IR integer field -** CTF IR floating point number field -** CTF IR enumeration field -** CTF IR string field -** CTF IR array field -** CTF IR sequence field -** CTF IR structure field -** CTF IR variant field -* CTF IR clock class -* CTF IR event class -* CTF IR stream class -* CTF IR trace class -* CTF IR event -* CTF IR packet -* CTF IR stream -* CTF IR writer -* Component -* Source component -* Sink component -* Component class -* Source component class -* Sink component class -* Plugin -* Notification -* Iterator - -Note that once you mention _CTF IR_ in an object name, you can omit -it in the few following paragraphs. diff --git a/doc/api/dox/examples-ctfir.dox b/doc/api/dox/examples-ctfir.dox deleted file mode 100644 index 3c1850d3..00000000 --- a/doc/api/dox/examples-ctfir.dox +++ /dev/null @@ -1,139 +0,0 @@ -/** -@page ctfirexamples CTF IR examples - -List of CTF IR examples: - -- @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 -#include - -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 -#include - -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 -#include - -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 -#include - -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 -#include - -struct bt_field_type *create_float_field_type(void) -{ - int ret; - struct bt_field_type *field_type; - - field_type = bt_field_type_floating_point_create(); - assert(field_type); - - ret = bt_field_type_set_byte_order(field_type, - BT_BYTE_ORDER_LITTLE_ENDIAN); - assert(ret == 0); - - ret = bt_field_type_floating_point_set_exponent_digits(field_type, 11); - assert(ret == 0); - - ret = bt_field_type_floating_point_set_mantissa_digits(field_type, 53); - assert(ret == 0); - - return field_type; -} -@endcode -*/ diff --git a/doc/api/dox/examples.dox b/doc/api/dox/examples.dox deleted file mode 100644 index 34691ad4..00000000 --- a/doc/api/dox/examples.dox +++ /dev/null @@ -1,7 +0,0 @@ -/** -@page examples Examples - -List of examples: - -- @subpage ctfirexamples CTF IR examples -*/ diff --git a/doc/api/dox/group-api-ref.dox b/doc/api/dox/group-api-ref.dox deleted file mode 100644 index 23a838cb..00000000 --- a/doc/api/dox/group-api-ref.dox +++ /dev/null @@ -1,30 +0,0 @@ -/** -@defgroup apiref API reference -@brief Babeltrace C API reference. - -This module and its submodules accurately document the C API of the -Babeltrace library (v\btversion). See the \ref writeplugin and -\ref usectfwriter pages for official, procedural user guides to help -you get started with this API. See \ref examples for informal examples. - -The API is divided into the following modules: - -- \ref refs contains the macros and functions that you can use - to manage the reference count of Babeltrace objects. -- \ref values is a set of generic value objects which are used at - various locations of the API. -- \ref ctfir is an internal representation of the - CTF model which Babeltrace - uses as a common foundation between trace formats. -- \ref btcomponents is the Babeltrace component API. A component is an - instance of a specific component class within a trace conversion - graph of connected iterators. -- \ref ctfwriter is an API to write concrete CTF traces to the - file system. - -All the functions and macros documented here indicate their -\em preconditions and \em postconditions. Unless there is an -unexpected error (out of memory, resource not available, bug, etc.), -if you honor the preconditions when you call a function, you are -guaranteed that this function in turn honors the postconditions. -*/ diff --git a/doc/api/dox/group-ctf-ir.dox b/doc/api/dox/group-ctf-ir.dox deleted file mode 100644 index f7878da1..00000000 --- a/doc/api/dox/group-ctf-ir.dox +++ /dev/null @@ -1,21 +0,0 @@ -/** -@defgroup ctfir CTF IR -@ingroup apiref -@brief Common Trace Format Intermediate Representation. - -The Common Trace Format Intermediate Representation, -or CTF IR, is the representation of the -CTF model within Babeltrace. - -As with any Babeltrace object, all the CTF IR objects have -reference -counts. 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 -equivalent to another one, it means that -bt_field_type_compare() \em must return 0. - -@sa \ref ctfirexamples "Examples" -*/ diff --git a/doc/api/dox/includes-build.dox b/doc/api/dox/includes-build.dox deleted file mode 100644 index f7b42c1a..00000000 --- a/doc/api/dox/includes-build.dox +++ /dev/null @@ -1,74 +0,0 @@ -/** -@page includesbuild Include files and how to build - -@section includefiles Include files - -You can find all the Babeltrace library include files (C headers) in the -\c babeltrace2 directory under the include files directory chosen when -installing Babeltrace. By default, this is /usr/include. -If you build Babeltrace from source without specifying an installation -prefix, this is /usr/local/include. - -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 -@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: - -
    -
  1. Compile the source files which form your plugin: - -@verbatim -cc -c -fpic my-plugin.c -@endverbatim -
    2. - -
  2. Create the plugin shared object: - -@verbatim -cc -shared my-plugin.o -lbabeltrace2 -o my-plugin.so -@endverbatim -
    3. -
- -@subsection howtobuildapp Build an application - -To build an application which uses the Babeltrace library: - -
    -
  1. Compile the source files which form your application: - -@verbatim -cc -c my-app.c -@endverbatim -
    2. - -
  2. Create the executable application: - -@verbatim -cc my-app.o -lbabeltrace2 -o my-app -@endverbatim -
    3. -
-*/ diff --git a/doc/api/dox/main-page.dox b/doc/api/dox/main-page.dox deleted file mode 100644 index edc79d48..00000000 --- a/doc/api/dox/main-page.dox +++ /dev/null @@ -1,136 +0,0 @@ -/** -@mainpage Welcome! - -Welcome to the -Babeltrace \btversion C API documentation! - -Babeltrace is an open -source converter of -trace -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 plugins\endlink. - -A Babeltrace plugin contains one or more -\link btcomponents component classes\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 -(.so or .dll 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 Common Trace Format model. -Within the Babeltrace C API, this representation is called the -Common Trace Format Intermediate Representation, 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.

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 -JSON 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 Babeltrace objects have a -reference count -to make them shareable. -When you use a Babeltrace object creation function (for example, -bt_value_bool_create()), you get a new reference to the created -object. When you add this object to another one, the latter takes its -own reference using bt_get(), incrementing the shared object's reference -count. When you are done with an object, you must call bt_put() to drop -your reference, decrementing its reference count. When an object's -reference count reaches 0, the object is considered \em destroyed and -cannot be used anymore. - -See \ref refs for more details. - -The postconditions of the functions and macros documented here indicate -what you can expect from the reference counts of the Babeltrace objects -passed as parameters to and returned from API functions. - -@section mainpagefreeze Frozen objects - -The Babeltrace library can \em freeze almost all of the Babeltrace -objects. A frozen object is considered \em immutable, although you can -still get and put references to this object. - -The preconditions of the functions and macros documented here indicate -when they expect unfrozen objects. The postconditions indicate when -the functions and macros freeze an object. -*/ diff --git a/doc/api/dox/quick-start.dox b/doc/api/dox/quick-start.dox deleted file mode 100644 index 662bbc58..00000000 --- a/doc/api/dox/quick-start.dox +++ /dev/null @@ -1,6 +0,0 @@ -/** -@page quickstart Quick start -@tableofcontents - -lol lol -*/ diff --git a/doc/api/images/babeltrace-cli.png b/doc/api/images/babeltrace-cli.png deleted file mode 100644 index e21dc538..00000000 Binary files a/doc/api/images/babeltrace-cli.png and /dev/null differ diff --git a/doc/api/images/ctf-stream-packet.png b/doc/api/images/ctf-stream-packet.png deleted file mode 100644 index 0c41fcfb..00000000 Binary files a/doc/api/images/ctf-stream-packet.png and /dev/null differ diff --git a/doc/api/images/ctf-trace.png b/doc/api/images/ctf-trace.png deleted file mode 100644 index 64a389c2..00000000 Binary files a/doc/api/images/ctf-trace.png and /dev/null differ diff --git a/doc/api/images/ref-count-api-returns.png b/doc/api/images/ref-count-api-returns.png deleted file mode 100644 index e8f34717..00000000 Binary files a/doc/api/images/ref-count-api-returns.png and /dev/null differ diff --git a/doc/api/images/ref-count-callback.png b/doc/api/images/ref-count-callback.png deleted file mode 100644 index 4e758627..00000000 Binary files a/doc/api/images/ref-count-callback.png and /dev/null differ diff --git a/doc/api/images/ref-count-user-calls.png b/doc/api/images/ref-count-user-calls.png deleted file mode 100644 index 0502c8fb..00000000 Binary files a/doc/api/images/ref-count-user-calls.png and /dev/null differ diff --git a/doc/api/libbabeltrace2/.gitignore b/doc/api/libbabeltrace2/.gitignore new file mode 100644 index 00000000..15523a73 --- /dev/null +++ b/doc/api/libbabeltrace2/.gitignore @@ -0,0 +1,3 @@ +output +Doxyfile +README.html diff --git a/doc/api/libbabeltrace2/Doxyfile.in b/doc/api/libbabeltrace2/Doxyfile.in new file mode 100644 index 00000000..cd94819e --- /dev/null +++ b/doc/api/libbabeltrace2/Doxyfile.in @@ -0,0 +1,776 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "Babeltrace 2 C API" +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = "Open-source trace manipulation framework" +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = "@top_srcdir@/include" +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +ALIASES = + +# Aliases: general +ALIASES += bt_version_min_maj="2.0" +ALIASES += bt_version="@PACKAGE_VERSION@" +ALIASES += bt_max_mip_version="0" +ALIASES += bt_name="Babeltrace 2" +ALIASES += bt_name_version_min_maj="Babeltrace \bt_version_min_maj" +ALIASES += bt_api="Babeltrace 2 C API" +ALIASES += bt_p{1}="\1" +ALIASES += bt_dt_opt="Optional:" +ALIASES += bt_man{2}="\1(\2)" +ALIASES += bt_cli="babeltrace2" +ALIASES += bt_voidp="void *" + +# 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 printf()-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 On success, \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 printf()-like format string." +ALIASES += bt_pre_fc_not_in_tc{1}="@pre \bt_p{\1} is not already part of another field class, an \bt_ev_cls, or a \bt_stream_cls." + +# Aliases: preconditions: field class object type +ALIASES += bt_pre_is_ba_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-ba bit array field class\endlink." +ALIASES += bt_pre_is_bool_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-bool boolean field class\endlink." +ALIASES += bt_pre_is_int_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-int integer field class\endlink." +ALIASES += bt_pre_is_real_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-real real field class\endlink." +ALIASES += bt_pre_is_enum_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-enum enumeration field class\endlink." +ALIASES += bt_pre_is_uenum_fc{1}="@pre \bt_p{\1} is an unsigned \link api-tir-fc-enum enumeration field class\endlink." +ALIASES += bt_pre_is_senum_fc{1}="@pre \bt_p{\1} is a signed \link api-tir-fc-enum enumeration field class\endlink." +ALIASES += bt_pre_is_string_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-string string field class\endlink." +ALIASES += bt_pre_is_struct_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-struct structure field class\endlink." +ALIASES += bt_pre_is_array_fc{1}="@pre \bt_p{\1} is an array \link api-tir-fc-array field class\endlink." +ALIASES += bt_pre_is_sarray_fc{1}="@pre \bt_p{\1} is a static \link api-tir-fc-array array field class\endlink." +ALIASES += bt_pre_is_darray_fc{1}="@pre \bt_p{\1} is a dynamic \link api-tir-fc-array array field class\endlink." +ALIASES += bt_pre_is_darray_wl_fc{1}="@pre \bt_p{\1} is a dynamic \link api-tir-fc-array array field class\endlink (with a length field)." +ALIASES += bt_pre_is_opt_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink." +ALIASES += bt_pre_is_opt_ws_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with a selector field)." +ALIASES += bt_pre_is_opt_wbs_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with a boolean selector field)." +ALIASES += bt_pre_is_opt_wsis_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with a signed integer selector field)." +ALIASES += bt_pre_is_opt_wuis_fc{1}="@pre \bt_p{\1} is an \link api-tir-fc-opt option field class\endlink (with an unsigned integer selector field)." +ALIASES += bt_pre_is_var_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink." +ALIASES += bt_pre_is_var_wos_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (without a selector field)." +ALIASES += bt_pre_is_var_ws_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (with a selector field)." +ALIASES += bt_pre_is_var_wuis_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (with an unsigned integer selector field)." +ALIASES += bt_pre_is_var_wsis_fc{1}="@pre \bt_p{\1} is a \link api-tir-fc-var variant field class\endlink (with a signed integer selector field)." + +# Aliases: preconditions: field object type +ALIASES += bt_pre_is_ba_field{1}="@pre \bt_p{\1} is a \link api-tir-field-ba bit array field\endlink." +ALIASES += bt_pre_is_bool_field{1}="@pre \bt_p{\1} is a \link api-tir-field-bool boolean field\endlink." +ALIASES += bt_pre_is_sint_field{1}="@pre \bt_p{\1} is a signed \link api-tir-field-int integer field\endlink." +ALIASES += bt_pre_is_uint_field{1}="@pre \bt_p{\1} is an unsigned \link api-tir-field-int integer field\endlink." +ALIASES += bt_pre_is_sreal_field{1}="@pre \bt_p{\1} is a single-precision \link api-tir-field-real real field\endlink." +ALIASES += bt_pre_is_dreal_field{1}="@pre \bt_p{\1} is a double-precision \link api-tir-field-real real field\endlink." +ALIASES += bt_pre_is_enum_field{1}="@pre \bt_p{\1} is an \link api-tir-field-enum enumeration field\endlink." +ALIASES += bt_pre_is_uenum_field{1}="@pre \bt_p{\1} is an unsigned \link api-tir-field-enum enumeration field\endlink." +ALIASES += bt_pre_is_senum_field{1}="@pre \bt_p{\1} is a signed \link api-tir-field-enum enumeration field\endlink." +ALIASES += bt_pre_is_string_field{1}="@pre \bt_p{\1} is a \link api-tir-field-string string field\endlink." +ALIASES += bt_pre_is_struct_field{1}="@pre \bt_p{\1} is a \link api-tir-field-struct structure field\endlink." +ALIASES += bt_pre_is_array_field{1}="@pre \bt_p{\1} is an \link api-tir-field-array array field\endlink." +ALIASES += bt_pre_is_sarray_field{1}="@pre \bt_p{\1} is a static \link api-tir-field-array array field\endlink." +ALIASES += bt_pre_is_darray_field{1}="@pre \bt_p{\1} is a dynamic \link api-tir-field-array array field\endlink." +ALIASES += bt_pre_is_opt_field{1}="@pre \bt_p{\1} is an \link api-tir-field-opt option field\endlink." +ALIASES += bt_pre_is_var_field{1}="@pre \bt_p{\1} is a \link api-tir-field-var variant field\endlink." +ALIASES += bt_pre_is_var_wuis_field{1}="@pre \bt_p{\1} is a \link api-tir-field-var variant field\endlink (with an unsigned integer selector field)." +ALIASES += bt_pre_is_var_wsis_field{1}="@pre \bt_p{\1} is a \link api-tir-field-var variant field\endlink (with a signed integer selector field)." + +# Aliases: preconditions: value object type +ALIASES += bt_pre_is_null_val{1}="@pre \bt_p{\1} is a null \link api-val value\endlink (\bt_p{\1} is equal to #bt_value_null)." +ALIASES += bt_pre_is_bool_val{1}="@pre \bt_p{\1} is a boolean \link api-val value\endlink (bt_value_is_bool() returns #BT_TRUE)." +ALIASES += bt_pre_is_sint_val{1}="@pre \bt_p{\1} is a signed integer \link api-val value\endlink (bt_value_is_signed_integer() returns #BT_TRUE)." +ALIASES += bt_pre_is_uint_val{1}="@pre \bt_p{\1} is an unsigned integer \link api-val value\endlink (bt_value_is_unsigned_integer() returns #BT_TRUE)." +ALIASES += bt_pre_is_real_val{1}="@pre \bt_p{\1} is a real \link api-val value\endlink (bt_value_is_real() returns #BT_TRUE)." +ALIASES += bt_pre_is_string_val{1}="@pre \bt_p{\1} is a string \link api-val value\endlink (bt_value_is_string() returns #BT_TRUE)." +ALIASES += bt_pre_is_array_val{1}="@pre \bt_p{\1} is an array \link api-val value\endlink (bt_value_is_array() returns #BT_TRUE)." +ALIASES += bt_pre_is_map_val{1}="@pre \bt_p{\1} is a map \link api-val value\endlink (bt_value_is_map() returns #BT_TRUE)." + +# Aliases: preconditions: message object type +ALIASES += bt_pre_is_disc_ev_msg{1}="@pre \bt_p{\1} is a \link api-msg-disc-ev discarded events message\endlink." +ALIASES += bt_pre_is_disc_pkt_msg{1}="@pre \bt_p{\1} is a \link api-msg-disc-pkt discarded packets message\endlink." +ALIASES += bt_pre_is_ev_msg{1}="@pre \bt_p{\1} is an \link api-msg-ev event message\endlink." +ALIASES += bt_pre_is_inac_msg{1}="@pre \bt_p{\1} is a \link api-msg-inac message iterator inactivity message\endlink." +ALIASES += bt_pre_is_pb_msg{1}="@pre \bt_p{\1} is a \link api-msg-pb packet beginning message\endlink." +ALIASES += bt_pre_is_pe_msg{1}="@pre \bt_p{\1} is a \link api-msg-pe packet end message\endlink." +ALIASES += bt_pre_is_sb_msg{1}="@pre \bt_p{\1} is a \link api-msg-sb stream beginning message\endlink." +ALIASES += bt_pre_is_se_msg{1}="@pre \bt_p{\1} is a \link api-msg-se stream end message\endlink." + +# Aliases: field class object types: singular +ALIASES += bt_fc="\link api-tir-fc field class\endlink" +ALIASES += bt_ba_fc="\link api-tir-fc-ba bit array field class\endlink" +ALIASES += bt_bool_fc="\link api-tir-fc-bool boolean field class\endlink" +ALIASES += bt_int_fc="\link api-tir-fc-int integer field class\endlink" +ALIASES += bt_sint_fc="signed \link api-tir-fc-int integer field class\endlink" +ALIASES += bt_uint_fc="unsigned \link api-tir-fc-int integer field class\endlink" +ALIASES += bt_real_fc="\link api-tir-fc-real real field class\endlink" +ALIASES += bt_enum_fc="\link api-tir-fc-enum enumeration field class\endlink" +ALIASES += bt_senum_fc="signed \link api-tir-fc-enum enumeration field class\endlink" +ALIASES += bt_uenum_fc="unsigned \link api-tir-fc-enum enumeration field class\endlink" +ALIASES += bt_string_fc="\link api-tir-fc-string string field class\endlink" +ALIASES += bt_struct_fc="\link api-tir-fc-struct structure field class\endlink" +ALIASES += bt_array_fc="\link api-tir-fc-array array field class\endlink" +ALIASES += bt_sarray_fc="static \link api-tir-fc-array array field class\endlink" +ALIASES += bt_darray_fc="dynamic \link api-tir-fc-array array field class\endlink" +ALIASES += bt_opt_fc="\link api-tir-fc-opt option field class\endlink" +ALIASES += bt_var_fc="\link api-tir-fc-var variant field class\endlink" + +# Aliases: field class object types: singular, capitalized +ALIASES += bt_c_fc="\link api-tir-fc Field class\endlink" +ALIASES += bt_c_ba_fc="\link api-tir-fc-ba Bit array field class\endlink" +ALIASES += bt_c_bool_fc="\link api-tir-fc-bool Boolean field class\endlink" +ALIASES += bt_c_int_fc="\link api-tir-fc-int Integer field class\endlink" +ALIASES += bt_c_sint_fc="Signed \link api-tir-fc-int integer field class\endlink" +ALIASES += bt_c_uint_fc="Unsigned \link api-tir-fc-int integer field class\endlink" +ALIASES += bt_c_real_fc="\link api-tir-fc-real Real field class\endlink" +ALIASES += bt_c_enum_fc="\link api-tir-fc-enum Enumeration field class\endlink" +ALIASES += bt_c_senum_fc="Signed \link api-tir-fc-enum enumeration field class\endlink" +ALIASES += bt_c_uenum_fc="Unsigned \link api-tir-fc-enum enumeration field class\endlink" +ALIASES += bt_c_string_fc="\link api-tir-fc-string String field class\endlink" +ALIASES += bt_c_struct_fc="\link api-tir-fc-struct Structure field class\endlink" +ALIASES += bt_c_array_fc="\link api-tir-fc-array Array field class\endlink" +ALIASES += bt_c_sarray_fc="Static \link api-tir-fc-array array field class\endlink" +ALIASES += bt_c_darray_fc="Dynamic \link api-tir-fc-array array field class\endlink" +ALIASES += bt_c_opt_fc="\link api-tir-fc-opt Option field class\endlink" +ALIASES += bt_c_var_fc="\link api-tir-fc-var Variant field class\endlink" + +# Aliases: field class object types: plural +ALIASES += bt_p_fc="\link api-tir-fc field classes\endlink" +ALIASES += bt_p_ba_fc="\link api-tir-fc-ba bit array field classes\endlink" +ALIASES += bt_p_bool_fc="\link api-tir-fc-bool boolean field classes\endlink" +ALIASES += bt_p_int_fc="\link api-tir-fc-int integer field classes\endlink" +ALIASES += bt_p_sint_fc="signed \link api-tir-fc-int integer field classes\endlink" +ALIASES += bt_p_uint_fc="unsigned \link api-tir-fc-int integer field classes\endlink" +ALIASES += bt_p_real_fc="\link api-tir-fc-real real field classes\endlink" +ALIASES += bt_p_enum_fc="\link api-tir-fc-enum enumeration field classes\endlink" +ALIASES += bt_p_senum_fc="signed \link api-tir-fc-enum enumeration field classes\endlink" +ALIASES += bt_p_uenum_fc="unsigned \link api-tir-fc-enum enumeration field classes\endlink" +ALIASES += bt_p_string_fc="\link api-tir-fc-string string field classes\endlink" +ALIASES += bt_p_struct_fc="\link api-tir-fc-struct structure field classes\endlink" +ALIASES += bt_p_array_fc="\link api-tir-fc-array array field classes\endlink" +ALIASES += bt_p_sarray_fc="static \link api-tir-fc-array array field classes\endlink" +ALIASES += bt_p_darray_fc="dynamic \link api-tir-fc-array array field classes\endlink" +ALIASES += bt_p_opt_fc="\link api-tir-fc-opt option field classes\endlink" +ALIASES += bt_p_var_fc="\link api-tir-fc-var variant field classes\endlink" + +# Aliases: field class object types: plural, capitalized +ALIASES += bt_cp_fc="\link api-tir-fc Field classes\endlink" +ALIASES += bt_cp_ba_fc="\link api-tir-fc-ba Bit array field classes\endlink" +ALIASES += bt_cp_bool_fc="\link api-tir-fc-bool Boolean field classes\endlink" +ALIASES += bt_cp_int_fc="\link api-tir-fc-int Integer field classes\endlink" +ALIASES += bt_cp_sint_fc="Signed \link api-tir-fc-int integer field classes\endlink" +ALIASES += bt_cp_uint_fc="Unsigned \link api-tir-fc-int integer field classes\endlink" +ALIASES += bt_cp_real_fc="\link api-tir-fc-real Real field classes\endlink" +ALIASES += bt_cp_enum_fc="\link api-tir-fc-enum Enumeration field classes\endlink" +ALIASES += bt_cp_senum_fc="Signed \link api-tir-fc-enum enumeration field classes\endlink" +ALIASES += bt_cp_uenum_fc="Unsigned \link api-tir-fc-enum enumeration field classes\endlink" +ALIASES += bt_cp_string_fc="\link api-tir-fc-string String field classes\endlink" +ALIASES += bt_cp_struct_fc="\link api-tir-fc-struct Structure field classes\endlink" +ALIASES += bt_cp_array_fc="\link api-tir-fc-array Array field classes\endlink" +ALIASES += bt_cp_sarray_fc="Static \link api-tir-fc-array array field classes\endlink" +ALIASES += bt_cp_darray_fc="Dynamic \link api-tir-fc-array array field classes\endlink" +ALIASES += bt_cp_opt_fc="\link api-tir-fc-opt Option field classes\endlink" +ALIASES += bt_cp_var_fc="\link api-tir-fc-var Variant field classes\endlink" + +# Aliases: field object types: singular +ALIASES += bt_field="\link api-tir-field field\endlink" +ALIASES += bt_ba_field="\link api-tir-field-ba bit array field\endlink" +ALIASES += bt_bool_field="\link api-tir-field-bool boolean field\endlink" +ALIASES += bt_int_field="\link api-tir-field-int integer field\endlink" +ALIASES += bt_sint_field="signed \link api-tir-field-int integer field\endlink" +ALIASES += bt_uint_field="unsigned \link api-tir-field-int integer field\endlink" +ALIASES += bt_real_field="\link api-tir-field-real real field\endlink" +ALIASES += bt_sreal_field="single-precision \link api-tir-field-real real field\endlink" +ALIASES += bt_dreal_field="double-precision \link api-tir-field-real real field\endlink" +ALIASES += bt_enum_field="\link api-tir-field-enum enumeration field\endlink" +ALIASES += bt_senum_field="signed \link api-tir-field-enum enumeration field\endlink" +ALIASES += bt_uenum_field="unsigned \link api-tir-field-enum enumeration field\endlink" +ALIASES += bt_string_field="\link api-tir-field-string string field\endlink" +ALIASES += bt_struct_field="\link api-tir-field-struct structure field\endlink" +ALIASES += bt_array_field="\link api-tir-field-array array field\endlink" +ALIASES += bt_sarray_field="static \link api-tir-field-array array field\endlink" +ALIASES += bt_darray_field="dynamic \link api-tir-field-array array field\endlink" +ALIASES += bt_opt_field="\link api-tir-field-opt option field\endlink" +ALIASES += bt_var_field="\link api-tir-field-var variant field\endlink" + +# Aliases: field object types: singular, capitalized +ALIASES += bt_c_field="\link api-tir-field Field\endlink" +ALIASES += bt_c_ba_field="\link api-tir-field-ba Bit array field\endlink" +ALIASES += bt_c_bool_field="\link api-tir-field-bool Boolean field\endlink" +ALIASES += bt_c_int_field="\link api-tir-field-int Integer field\endlink" +ALIASES += bt_c_sint_field="Signed \link api-tir-field-int integer field\endlink" +ALIASES += bt_c_uint_field="Unsigned \link api-tir-field-int integer field\endlink" +ALIASES += bt_c_real_field="\link api-tir-field-real Real field\endlink" +ALIASES += bt_c_sreal_field="Single-precision \link api-tir-field-real real field\endlink" +ALIASES += bt_c_dreal_field="Double-precision \link api-tir-field-real real field\endlink" +ALIASES += bt_c_enum_field="\link api-tir-field-enum Enumeration field\endlink" +ALIASES += bt_c_senum_field="Signed \link api-tir-field-enum enumeration field\endlink" +ALIASES += bt_c_uenum_field="Unsigned \link api-tir-field-enum enumeration field\endlink" +ALIASES += bt_c_string_field="\link api-tir-field-string String field\endlink" +ALIASES += bt_c_struct_field="\link api-tir-field-struct Structure field\endlink" +ALIASES += bt_c_array_field="\link api-tir-field-array Array field\endlink" +ALIASES += bt_c_sarray_field="Static \link api-tir-field-array array field\endlink" +ALIASES += bt_c_darray_field="Dynamic \link api-tir-field-array array field\endlink" +ALIASES += bt_c_opt_field="\link api-tir-field-opt Option field\endlink" +ALIASES += bt_c_var_field="\link api-tir-field-var Variant field\endlink" + +# Aliases: field object types: plural +ALIASES += bt_p_field="\link api-tir-field fields\endlink" +ALIASES += bt_p_ba_field="\link api-tir-field-ba bit array fields\endlink" +ALIASES += bt_p_bool_field="\link api-tir-field-bool boolean fields\endlink" +ALIASES += bt_p_int_field="\link api-tir-field-int integer fields\endlink" +ALIASES += bt_p_sint_field="signed \link api-tir-field-int integer fields\endlink" +ALIASES += bt_p_uint_field="unsigned \link api-tir-field-int integer fields\endlink" +ALIASES += bt_p_real_field="\link api-tir-field-real real fields\endlink" +ALIASES += bt_p_sreal_field="single-precision \link api-tir-field-real real fields\endlink" +ALIASES += bt_p_dreal_field="double-precision \link api-tir-field-real real fields\endlink" +ALIASES += bt_p_enum_field="\link api-tir-field-enum enumeration fields\endlink" +ALIASES += bt_p_senum_field="signed \link api-tir-field-enum enumeration fields\endlink" +ALIASES += bt_p_uenum_field="unsigned \link api-tir-field-enum enumeration fields\endlink" +ALIASES += bt_p_string_field="\link api-tir-field-string string fields\endlink" +ALIASES += bt_p_struct_field="\link api-tir-field-struct structure fields\endlink" +ALIASES += bt_p_array_field="\link api-tir-field-array array fields\endlink" +ALIASES += bt_p_sarray_field="static \link api-tir-field-array array fields\endlink" +ALIASES += bt_p_darray_field="dynamic \link api-tir-field-array array fields\endlink" +ALIASES += bt_p_opt_field="\link api-tir-field-opt option fields\endlink" +ALIASES += bt_p_var_field="\link api-tir-field-var variant fields\endlink" + +# Aliases: field object types: plural, capitalized +ALIASES += bt_cp_field="\link api-tir-field Fields\endlink" +ALIASES += bt_cp_ba_field="\link api-tir-field-ba Bit array fields\endlink" +ALIASES += bt_cp_bool_field="\link api-tir-field-bool Boolean fields\endlink" +ALIASES += bt_cp_int_field="\link api-tir-field-int Integer fields\endlink" +ALIASES += bt_cp_sint_field="Signed \link api-tir-field-int integer fields\endlink" +ALIASES += bt_cp_uint_field="Unsigned \link api-tir-field-int integer fields\endlink" +ALIASES += bt_cp_real_field="\link api-tir-field-real Real fields\endlink" +ALIASES += bt_cp_sreal_field="Single-precision \link api-tir-field-real real fields\endlink" +ALIASES += bt_cp_dreal_field="Double-precision \link api-tir-field-real real fields\endlink" +ALIASES += bt_cp_enum_field="\link api-tir-field-enum Enumeration fields\endlink" +ALIASES += bt_cp_senum_field="Signed \link api-tir-field-enum enumeration fields\endlink" +ALIASES += bt_cp_uenum_field="Unsigned \link api-tir-field-enum enumeration fields\endlink" +ALIASES += bt_cp_string_field="\link api-tir-field-string String fields\endlink" +ALIASES += bt_cp_struct_field="\link api-tir-field-struct Structure fields\endlink" +ALIASES += bt_cp_array_field="\link api-tir-field-array Array fields\endlink" +ALIASES += bt_cp_sarray_field="Static \link api-tir-field-array array fields\endlink" +ALIASES += bt_cp_darray_field="Dynamic \link api-tir-field-array array fields\endlink" +ALIASES += bt_cp_opt_field="\link api-tir-field-opt Option fields\endlink" +ALIASES += bt_cp_var_field="\link api-tir-field-var Variant fields\endlink" + +# Aliases: trace IR objects: singular +ALIASES += bt_clock_cls="\link api-tir-clock-cls clock class\endlink" +ALIASES += bt_cs="\link api-tir-cs clock snapshot\endlink" +ALIASES += bt_ev_cls="\link api-tir-ev-cls event class\endlink" +ALIASES += bt_ev="\link api-tir-ev event\endlink" +ALIASES += bt_field_path="\link api-tir-field-path field path\endlink" +ALIASES += bt_pkt="\link api-tir-pkt packet\endlink" +ALIASES += bt_stream_cls="\link api-tir-stream-cls stream class\endlink" +ALIASES += bt_stream="\link api-tir-stream stream\endlink" +ALIASES += bt_trace="\link api-tir-trace trace\endlink" +ALIASES += bt_trace_cls="\link api-tir-trace-cls trace class\endlink" + +# Aliases: trace IR objects: singular, capitalized +ALIASES += bt_c_clock_cls="\link api-tir-clock-cls Clock class\endlink" +ALIASES += bt_c_cs="\link api-tir-cs Clock snapshot\endlink" +ALIASES += bt_c_ev_cls="\link api-tir-ev-cls Event class\endlink" +ALIASES += bt_c_ev="\link api-tir-ev Event\endlink" +ALIASES += bt_c_field_path="\link api-tir-field-path Field path\endlink" +ALIASES += bt_c_pkt="\link api-tir-pkt Packet\endlink" +ALIASES += bt_c_stream_cls="\link api-tir-stream-cls Stream class\endlink" +ALIASES += bt_c_stream="\link api-tir-stream Stream\endlink" +ALIASES += bt_c_trace="\link api-tir-trace Trace\endlink" +ALIASES += bt_c_trace_cls="\link api-tir-trace-cls Trace class\endlink" + +# Aliases: trace IR objects: plural +ALIASES += bt_p_clock_cls="\link api-tir-clock-cls clock classes\endlink" +ALIASES += bt_p_cs="\link api-tir-cs clock snapshots\endlink" +ALIASES += bt_p_ev_cls="\link api-tir-ev-cls event classes\endlink" +ALIASES += bt_p_ev="\link api-tir-ev events\endlink" +ALIASES += bt_p_field_path="\link api-tir-field-path field paths\endlink" +ALIASES += bt_p_pkt="\link api-tir-pkt packets\endlink" +ALIASES += bt_p_stream_cls="\link api-tir-stream-cls stream classes\endlink" +ALIASES += bt_p_stream="\link api-tir-stream streams\endlink" +ALIASES += bt_p_trace="\link api-tir-trace traces\endlink" +ALIASES += bt_p_trace_cls="\link api-tir-trace-cls trace classes\endlink" + +# Aliases: trace IR objects: plural, capitalized +ALIASES += bt_cp_clock_cls="\link api-tir-clock-cls Clock classes\endlink" +ALIASES += bt_cp_cs="\link api-tir-cs Clock snapshots\endlink" +ALIASES += bt_cp_ev_cls="\link api-tir-ev-cls event classes\endlink" +ALIASES += bt_cp_ev="\link api-tir-ev Events\endlink" +ALIASES += bt_cp_field_path="\link api-tir-field-path Field paths\endlink" +ALIASES += bt_cp_pkt="\link api-tir-pkt Packets\endlink" +ALIASES += bt_cp_stream_cls="\link api-tir-stream-cls Stream classes\endlink" +ALIASES += bt_cp_stream="\link api-tir-stream Streams\endlink" +ALIASES += bt_cp_trace="\link api-tir-trace Traces\endlink" +ALIASES += bt_cp_trace_cls="\link api-tir-trace-cls Trace classes\endlink" + +# Aliases: graph objects: singular +ALIASES += bt_comp="\link api-comp component\endlink" +ALIASES += bt_comp_cls="\link api-comp-cls component class\endlink" +ALIASES += bt_comp_descr_set="\link api-comp-descr-set component descriptor set\endlink" +ALIASES += bt_conn="\link api-conn connection\endlink" +ALIASES += bt_flt_comp="\link api-comp-flt filter component\endlink" +ALIASES += bt_flt_comp_cls="\link api-comp-cls-flt filter component class\endlink" +ALIASES += bt_graph="\link api-graph graph\endlink" +ALIASES += bt_intr="\link api-intr interrupter\endlink" +ALIASES += bt_ip_msg_iter="\link api-ip-msg-iter self component input port message iterator\endlink" +ALIASES += bt_iport="\link api-port-in input port\endlink" +ALIASES += bt_mip="\link api-msg-mip Message Interchange Protocol\endlink" +ALIASES += bt_msg_iter="\link api-msg-iter message iterator\endlink" +ALIASES += bt_msg_iter_cls="\link api-msg-iter-cls message iterator class\endlink" +ALIASES += bt_oport="\link api-port-out output port\endlink" +ALIASES += bt_port="\link api-port port\endlink" +ALIASES += bt_priv_qexec="\link api-priv-qexec private query executor\endlink" +ALIASES += bt_qexec="\link api-qexec query executor\endlink" +ALIASES += bt_self_comp="\link api-self-comp self component\endlink" +ALIASES += bt_self_comp_port="\link api-self-comp-port self component port\endlink" +ALIASES += bt_self_comp_iport="\link api-self-comp-port self component input port\endlink" +ALIASES += bt_self_comp_oport="\link api-self-comp-port self component output port\endlink" +ALIASES += bt_self_comp_cls="\link api-self-comp-cls self component class\endlink" +ALIASES += bt_self_flt_comp="\link api-self-comp self filter component\endlink" +ALIASES += bt_self_flt_comp_cls="\link api-self-comp-cls self filter component class\endlink" +ALIASES += bt_self_msg_iter="\link api-self-msg-iter self message iterator\endlink" +ALIASES += bt_self_sink_comp="\link api-self-comp self sink component\endlink" +ALIASES += bt_self_sink_comp_cls="\link api-self-comp-cls self sink component class\endlink" +ALIASES += bt_self_src_comp="\link api-self-comp self source component\endlink" +ALIASES += bt_self_src_comp_cls="\link api-self-comp-cls self source component class\endlink" +ALIASES += bt_sink_comp="\link api-comp-sink sink component\endlink" +ALIASES += bt_sink_comp_cls="\link api-comp-cls-sink sink component class\endlink" +ALIASES += bt_src_comp="\link api-comp-src source component\endlink" +ALIASES += bt_src_comp_cls="\link api-comp-cls-src source component class\endlink" + +# Aliases: graph objects: singular, capitalized +ALIASES += bt_c_comp="\link api-comp Component\endlink" +ALIASES += bt_c_comp_cls="\link api-comp-cls Component class\endlink" +ALIASES += bt_c_comp_descr="\link api-comp-descr-set Component descriptor set\endlink" +ALIASES += bt_c_conn="\link api-conn Connection\endlink" +ALIASES += bt_c_flt_comp="\link api-comp-flt Filter component\endlink" +ALIASES += bt_c_flt_comp_cls="\link api-comp-cls-flt Filter component class\endlink" +ALIASES += bt_c_graph="\link api-graph Graph\endlink" +ALIASES += bt_c_intr="\link api-intr Interrupter\endlink" +ALIASES += bt_c_ip_msg_iter="\link api-ip-msg-iter Self component input port message iterator\endlink" +ALIASES += bt_c_iport="\link api-port-in Input port\endlink" +ALIASES += bt_c_msg_iter="\link api-msg-iter Message iterator\endlink" +ALIASES += bt_c_msg_iter_cls="\link api-msg-iter-cls Message iterator class\endlink" +ALIASES += bt_c_oport="\link api-port-out Output port\endlink" +ALIASES += bt_c_port="\link api-port Port\endlink" +ALIASES += bt_c_priv_qexec="\link api-priv-qexec Private query executor\endlink" +ALIASES += bt_c_qexec="\link api-qexec Query executor\endlink" +ALIASES += bt_c_self_comp="\link api-self-comp Self component\endlink" +ALIASES += bt_c_self_comp_port="\link api-self-comp-port Self component port\endlink" +ALIASES += bt_c_self_comp_iport="\link api-self-comp-port Self component input port\endlink" +ALIASES += bt_c_self_comp_oport="\link api-self-comp-port Self component output port\endlink" +ALIASES += bt_c_self_comp_cls="\link api-self-comp-cls Self component class\endlink" +ALIASES += bt_c_self_flt_comp="\link api-self-comp Self filter component\endlink" +ALIASES += bt_c_self_flt_comp_cls="\link api-self-comp-cls Self filter component class\endlink" +ALIASES += bt_c_self_msg_iter="\link api-self-msg-iter Self message iterator\endlink" +ALIASES += bt_c_self_sink_comp="\link api-self-comp Self sink component\endlink" +ALIASES += bt_c_self_sink_comp_cls="\link api-self-comp-cls Self sink component class\endlink" +ALIASES += bt_c_self_src_comp="\link api-self-comp Self source component\endlink" +ALIASES += bt_c_self_src_comp_cls="\link api-self-comp-cls Self source component class\endlink" +ALIASES += bt_c_sink_comp="\link api-comp-sink Sink component\endlink" +ALIASES += bt_c_sink_comp_cls="\link api-comp-cls-sink Sink component class\endlink" +ALIASES += bt_c_src_comp="\link api-comp-src Source component\endlink" +ALIASES += bt_c_src_comp_cls="\link api-comp-cls-src Source component class\endlink" + +# Aliases: graph objects: plural +ALIASES += bt_p_comp="\link api-comp components\endlink" +ALIASES += bt_p_comp_cls="\link api-comp-cls component classes\endlink" +ALIASES += bt_p_comp_descr="\link api-comp-descr-set component descriptor sets\endlink" +ALIASES += bt_p_conn="\link api-conn connections\endlink" +ALIASES += bt_p_flt_comp="\link api-comp-flt filter components\endlink" +ALIASES += bt_p_flt_comp_cls="\link api-comp-cls-flt filter component classes\endlink" +ALIASES += bt_p_graph="\link api-graph graphs\endlink" +ALIASES += bt_p_intr="\link api-intr interrupters\endlink" +ALIASES += bt_p_ip_msg_iter="\link api-ip-msg-iter self component input port message iterators\endlink" +ALIASES += bt_p_iport="\link api-port-in input ports\endlink" +ALIASES += bt_p_msg_iter="\link api-msg-iter message iterators\endlink" +ALIASES += bt_p_msg_iter_cls="\link api-msg-iter-cls message iterator classes\endlink" +ALIASES += bt_p_oport="\link api-port-out output ports\endlink" +ALIASES += bt_p_port="\link api-port ports\endlink" +ALIASES += bt_p_priv_qexec="\link api-priv-qexec private query executors\endlink" +ALIASES += bt_p_qexec="\link api-qexec query executors\endlink" +ALIASES += bt_p_self_comp="\link api-self-comp self components\endlink" +ALIASES += bt_p_self_comp_port="\link api-self-comp-port self component ports\endlink" +ALIASES += bt_p_self_comp_iport="\link api-self-comp-port self component input ports\endlink" +ALIASES += bt_p_self_comp_oport="\link api-self-comp-port self component output ports\endlink" +ALIASES += bt_p_self_comp_cls="\link api-self-comp-cls self component classes\endlink" +ALIASES += bt_p_self_flt_comp="\link api-self-comp self filter components\endlink" +ALIASES += bt_p_self_flt_comp_cls="\link api-self-comp-cls self filter component classes\endlink" +ALIASES += bt_p_self_msg_iter="\link api-self-msg-iter self message iterators\endlink" +ALIASES += bt_p_self_sink_comp="\link api-self-comp self sink components\endlink" +ALIASES += bt_p_self_sink_comp_cls="\link api-self-comp-cls self sink component classes\endlink" +ALIASES += bt_p_self_src_comp="\link api-self-comp self source components\endlink" +ALIASES += bt_p_self_src_comp_cls="\link api-self-comp-cls self source component classes\endlink" +ALIASES += bt_p_sink_comp="\link api-comp-sink sink components\endlink" +ALIASES += bt_p_sink_comp_cls="\link api-comp-cls-sink sink component classes\endlink" +ALIASES += bt_p_src_comp="\link api-comp-src source components\endlink" +ALIASES += bt_p_src_comp_cls="\link api-comp-cls-src source component classes\endlink" + +# Aliases: graph objects: plural, capitalized +ALIASES += bt_cp_comp="\link api-comp Components\endlink" +ALIASES += bt_cp_comp_cls="\link api-comp-cls Component classes\endlink" +ALIASES += bt_cp_comp_descr="\link api-comp-descr-set Component descriptor sets\endlink" +ALIASES += bt_cp_conn="\link api-conn Connections\endlink" +ALIASES += bt_cp_flt_comp="\link api-comp-flt Filter components\endlink" +ALIASES += bt_cp_flt_comp_cls="\link api-comp-cls-flt Filter component classes\endlink" +ALIASES += bt_cp_graph="\link api-graph Graphs\endlink" +ALIASES += bt_cp_intr="\link api-intr Interrupters\endlink" +ALIASES += bt_cp_ip_msg_iter="\link api-ip-msg-iter Self component input port message iterators\endlink" +ALIASES += bt_cp_iport="\link api-port-in Input ports\endlink" +ALIASES += bt_cp_msg_iter="\link api-msg-iter Message iterators\endlink" +ALIASES += bt_cp_msg_iter_cls="\link api-msg-iter-cls Message iterator classes\endlink" +ALIASES += bt_cp_oport="\link api-port-out Output ports\endlink" +ALIASES += bt_cp_port="\link api-port Ports\endlink" +ALIASES += bt_cp_priv_qexec="\link api-priv-qexec Private query executors\endlink" +ALIASES += bt_cp_qexec="\link api-qexec Query executors\endlink" +ALIASES += bt_cp_self_comp="\link api-self-comp Self components\endlink" +ALIASES += bt_cp_self_comp_port="\link api-self-comp-port Self component ports\endlink" +ALIASES += bt_cp_self_comp_iport="\link api-self-comp-port Self component input ports\endlink" +ALIASES += bt_cp_self_comp_oport="\link api-self-comp-port Self component output ports\endlink" +ALIASES += bt_cp_self_comp_cls="\link api-self-comp-cls Self component classes\endlink" +ALIASES += bt_cp_self_flt_comp="\link api-self-comp Self filter components\endlink" +ALIASES += bt_cp_self_flt_comp_cls="\link api-self-comp-cls Self filter component classes\endlink" +ALIASES += bt_cp_self_msg_iter="\link api-self-msg-iter Self message iterators\endlink" +ALIASES += bt_cp_self_sink_comp="\link api-self-comp Self sink components\endlink" +ALIASES += bt_cp_self_sink_comp_cls="\link api-self-comp-cls Self sink component classes\endlink" +ALIASES += bt_cp_self_src_comp="\link api-self-comp Self source components\endlink" +ALIASES += bt_cp_self_src_comp_cls="\link api-self-comp-cls Self source component classes\endlink" +ALIASES += bt_cp_sink_comp="\link api-comp-sink Sink components\endlink" +ALIASES += bt_cp_sink_comp_cls="\link api-comp-cls-sink Sink component classes\endlink" +ALIASES += bt_cp_src_comp="\link api-comp-src Source components\endlink" +ALIASES += bt_cp_src_comp_cls="\link api-comp-cls-src Source component classes\endlink" + +# Aliases: message objects: singular +ALIASES += bt_disc_ev_msg="\link api-msg-disc-ev discarded events message\endlink" +ALIASES += bt_disc_pkt_msg="\link api-msg-disc-pkt discarded packets message\endlink" +ALIASES += bt_ev_msg="\link api-msg-ev event message\endlink" +ALIASES += bt_inac_msg="\link api-msg-inac message iterator inactivity message\endlink" +ALIASES += bt_msg="\link api-msg message\endlink" +ALIASES += bt_pb_msg="\link api-msg-pb packet beginning message\endlink" +ALIASES += bt_pe_msg="\link api-msg-pe packet end message\endlink" +ALIASES += bt_sb_msg="\link api-msg-sb stream beginning message\endlink" +ALIASES += bt_se_msg="\link api-msg-se stream end message\endlink" + +# Aliases: message objects: singular, capitalized +ALIASES += bt_c_disc_ev_msg="\link api-msg-disc-ev Discarded events message\endlink" +ALIASES += bt_c_disc_pkt_msg="\link api-msg-disc-pkt Discarded packets message\endlink" +ALIASES += bt_c_ev_msg="\link api-msg-ev Event message\endlink" +ALIASES += bt_c_inac_msg="\link api-msg-inac Message iterator inactivity message\endlink" +ALIASES += bt_c_msg="\link api-msg Message\endlink" +ALIASES += bt_c_pb_msg="\link api-msg-pb Packet beginning message\endlink" +ALIASES += bt_c_pe_msg="\link api-msg-pe Packet end message\endlink" +ALIASES += bt_c_sb_msg="\link api-msg-sb Stream beginning message\endlink" +ALIASES += bt_c_se_msg="\link api-msg-se Stream end message\endlink" + +# Aliases: message objects: plural +ALIASES += bt_p_disc_ev_msg="\link api-msg-disc-ev discarded events messages\endlink" +ALIASES += bt_p_disc_pkt_msg="\link api-msg-disc-pkt discarded packets messages\endlink" +ALIASES += bt_p_ev_msg="\link api-msg-ev event messages\endlink" +ALIASES += bt_p_inac_msg="\link api-msg-inac message iterator inactivity messages\endlink" +ALIASES += bt_p_msg="\link api-msg messages\endlink" +ALIASES += bt_p_pb_msg="\link api-msg-pb packet beginning messages\endlink" +ALIASES += bt_p_pe_msg="\link api-msg-pe packet end messages\endlink" +ALIASES += bt_p_sb_msg="\link api-msg-sb stream beginning messages\endlink" +ALIASES += bt_p_se_msg="\link api-msg-se stream end messages\endlink" + +# Aliases: message objects: plural, capitalized +ALIASES += bt_cp_disc_ev_msg="\link api-msg-disc-ev Discarded events messages\endlink" +ALIASES += bt_cp_disc_pkt_msg="\link api-msg-disc-pkt Discarded packets messages\endlink" +ALIASES += bt_cp_ev_msg="\link api-msg-ev Event messages\endlink" +ALIASES += bt_cp_inac_msg="\link api-msg-inac Message iterator inactivity messages\endlink" +ALIASES += bt_cp_msg="\link api-msg Messages\endlink" +ALIASES += bt_cp_pb_msg="\link api-msg-pb Packet beginning messages\endlink" +ALIASES += bt_cp_pe_msg="\link api-msg-pe Packet end messages\endlink" +ALIASES += bt_cp_sb_msg="\link api-msg-sb Stream beginning messages\endlink" +ALIASES += bt_cp_se_msg="\link api-msg-se Stream end messages\endlink" + +# Aliases: plugin objects: singular +ALIASES += bt_plugin="\link api-plugin plugin\endlink" +ALIASES += bt_plugin_set="\link api-plugin plugin set\endlink" + +# Aliases: plugin objects: singular, capitalized +ALIASES += bt_c_plugin="\link api-plugin Plugin\endlink" +ALIASES += bt_c_plugin_set="\link api-plugin Plugin set\endlink" + +# Aliases: plugin objects: plural +ALIASES += bt_p_plugin="\link api-plugin plugins\endlink" +ALIASES += bt_p_plugin_set="\link api-plugin plugin sets\endlink" + +# Aliases: plugin objects: plural, capitalized +ALIASES += bt_cp_plugin="\link api-plugin Plugins\endlink" +ALIASES += bt_cp_plugin_set="\link api-plugin Plugin sets\endlink" + +# Aliases: value objects: singular +ALIASES += bt_val="\link api-val value\endlink" +ALIASES += bt_null_val="null \link api-val value\endlink" +ALIASES += bt_bool_val="boolean \link api-val value\endlink" +ALIASES += bt_sint_val="signed integer \link api-val value\endlink" +ALIASES += bt_uint_val="unsigned integer \link api-val value\endlink" +ALIASES += bt_real_val="real \link api-val value\endlink" +ALIASES += bt_string_val="string \link api-val value\endlink" +ALIASES += bt_map_val="map \link api-val value\endlink" +ALIASES += bt_array_val="array \link api-val value\endlink" + +# Aliases: value objects: singular, capitalized +ALIASES += bt_c_val="\link api-val Value\endlink" +ALIASES += bt_c_null_val="Null \link api-val value\endlink" +ALIASES += bt_c_bool_val="Boolean \link api-val value\endlink" +ALIASES += bt_c_sint_val="Signed integer \link api-val value\endlink" +ALIASES += bt_c_uint_val="Unsigned integer \link api-val value\endlink" +ALIASES += bt_c_real_val="Real \link api-val value\endlink" +ALIASES += bt_c_string_val="String \link api-val value\endlink" +ALIASES += bt_c_map_val="Map \link api-val value\endlink" +ALIASES += bt_c_array_val="Array \link api-val value\endlink" + +# Aliases: value objects: plural +ALIASES += bt_p_val="\link api-val values\endlink" +ALIASES += bt_p_null_val="null \link api-val values\endlink" +ALIASES += bt_p_bool_val="boolean \link api-val values\endlink" +ALIASES += bt_p_sint_val="signed integer \link api-val values\endlink" +ALIASES += bt_p_uint_val="unsigned integer \link api-val values\endlink" +ALIASES += bt_p_real_val="real \link api-val values\endlink" +ALIASES += bt_p_string_val="string \link api-val values\endlink" +ALIASES += bt_p_map_val="map \link api-val values\endlink" +ALIASES += bt_p_array_val="array \link api-val values\endlink" + +# Aliases: value objects: plural, capitalized +ALIASES += bt_cp_val="\link api-val Values\endlink" +ALIASES += bt_cp_null_val="Null \link api-val values\endlink" +ALIASES += bt_cp_bool_val="Boolean \link api-val values\endlink" +ALIASES += bt_cp_sint_val="Signed integer \link api-val values\endlink" +ALIASES += bt_cp_uint_val="Unsigned integer \link api-val values\endlink" +ALIASES += bt_cp_real_val="Real \link api-val values\endlink" +ALIASES += bt_cp_string_val="String \link api-val values\endlink" +ALIASES += bt_cp_map_val="Map \link api-val values\endlink" +ALIASES += bt_cp_array_val="Array \link api-val values\endlink" + +# Aliases: integer range set objects: singular +ALIASES += bt_sint_rg="\link api-int-rs signed integer range\endlink" +ALIASES += bt_uint_rg="\link api-int-rs unsigned integer range\endlink" +ALIASES += bt_int_rs="\link api-int-rs integer range set\endlink" +ALIASES += bt_sint_rs="\link api-int-rs signed integer range set\endlink" +ALIASES += bt_uint_rs="\link api-int-rs unsigned integer range set\endlink" + +# Aliases: integer range set objects: singular, capitalized +ALIASES += bt_c_sint_rg="\link api-int-rs Signed integer range\endlink" +ALIASES += bt_c_uint_rg="\link api-int-rs Unsigned integer range\endlink" +ALIASES += bt_c_int_rs="\link api-int-rs Integer range set\endlink" +ALIASES += bt_c_sint_rs="\link api-int-rs Signed integer range set\endlink" +ALIASES += bt_c_uint_rs="\link api-int-rs Unsigned integer range set\endlink" + +# Aliases: integer range set objects: plural +ALIASES += bt_p_sint_rg="\link api-int-rs signed integer ranges\endlink" +ALIASES += bt_p_uint_rg="\link api-int-rs unsigned integer ranges\endlink" +ALIASES += bt_p_int_rs="\link api-int-rs integer range sets\endlink" +ALIASES += bt_p_sint_rs="\link api-int-rs signed integer range sets\endlink" +ALIASES += bt_p_uint_rs="\link api-int-rs unsigned integer range sets\endlink" + +# Aliases: integer range set objects: plural, capitalized +ALIASES += bt_cp_sint_rg="\link api-int-rs Signed integer ranges\endlink" +ALIASES += bt_cp_uint_rg="\link api-int-rs Unsigned integer ranges\endlink" +ALIASES += bt_cp_int_rs="\link api-int-rs Integer range sets\endlink" +ALIASES += bt_cp_sint_rs="\link api-int-rs Signed integer range sets\endlink" +ALIASES += bt_cp_uint_rs="\link api-int-rs Unsigned integer range sets\endlink" + +OPTIMIZE_OUTPUT_FOR_C = YES +MARKDOWN_SUPPORT = NO +TOC_INCLUDE_HEADINGS = 0 +AUTOLINK_SUPPORT = YES +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 + +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = YES +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE = NO +SHOW_INCLUDE_FILES = NO +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = NO +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST = YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 0 +SHOW_USED_FILES = NO +SHOW_FILES = NO +SHOW_NAMESPACES = NO +FILE_VERSION_FILTER = +LAYOUT_FILE = "@srcdir@/DoxygenLayout.xml" +CITE_BIB_FILES = + +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = + +INPUT = "@srcdir@/dox/main-page.dox" \ + "@srcdir@/dox/api-fund.dox" \ + "@srcdir@/dox/guides.dox" \ + "@srcdir@/dox/examples.dox" \ + "@top_srcdir@/include/babeltrace2/types.h" \ + "@top_srcdir@/include/babeltrace2/error-reporting.h" \ + "@top_srcdir@/include/babeltrace2/util.h" \ + "@top_srcdir@/include/babeltrace2/graph/graph.h" \ + "@top_srcdir@/include/babeltrace2/graph/component-class-dev.h" \ + "@top_srcdir@/include/babeltrace2/graph/message.h" \ + "@srcdir@/dox/group-trace-ir.dox" \ + "@top_srcdir@/include/babeltrace2/trace-ir/clock-class.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/clock-snapshot.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/event.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/event-class.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/field.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/field-class.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/field-path.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/packet.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/stream.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/stream-class.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/trace.h" \ + "@top_srcdir@/include/babeltrace2/trace-ir/trace-class.h" \ + "@top_srcdir@/include/babeltrace2/graph/message-iterator.h" \ + "@top_srcdir@/include/babeltrace2/graph/message-iterator-class.h" \ + "@top_srcdir@/include/babeltrace2/graph/self-message-iterator.h" \ + "@top_srcdir@/include/babeltrace2/graph/private-query-executor.h" \ + "@top_srcdir@/include/babeltrace2/graph/self-component.h" \ + "@top_srcdir@/include/babeltrace2/graph/self-component-port.h" \ + "@top_srcdir@/include/babeltrace2/graph/self-component-class.h" \ + "@top_srcdir@/include/babeltrace2/graph/component.h" \ + "@top_srcdir@/include/babeltrace2/graph/component-class.h" \ + "@top_srcdir@/include/babeltrace2/graph/component-descriptor-set.h" \ + "@top_srcdir@/include/babeltrace2/graph/connection.h" \ + "@top_srcdir@/include/babeltrace2/graph/port.h" \ + "@top_srcdir@/include/babeltrace2/graph/interrupter.h" \ + "@top_srcdir@/include/babeltrace2/graph/query-executor.h" \ + "@top_srcdir@/include/babeltrace2/integer-range-set.h" \ + "@top_srcdir@/include/babeltrace2/version.h" \ + "@top_srcdir@/include/babeltrace2/logging.h" \ + "@top_srcdir@/include/babeltrace2/plugin/plugin-dev.h" \ + "@top_srcdir@/include/babeltrace2/plugin/plugin-loading.h" \ + "@top_srcdir@/include/babeltrace2/value.h" +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.h *.hh *.hpp *.dox +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = "@srcdir@/examples" +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = "@srcdir@/images" +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = + +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES + +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = + +OUTPUT_DIRECTORY = @builddir@/output + +GENERATE_HTML = YES +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = @srcdir@/style.css +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 120 +HTML_TIMESTAMP = NO +HTML_DYNAMIC_SECTIONS = NO +HTML_DYNAMIC_MENUS = NO +HTML_INDEX_NUM_ENTRIES = 100 + +GENERATE_DOCSET = NO +GENERATE_HTMLHELP = NO +GENERATE_CHI = NO +GENERATE_QHP = NO +GENERATE_ECLIPSEHELP = NO + +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 1 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = + +GENERATE_LATEX = NO +GENERATE_RTF = NO +GENERATE_MAN = NO +GENERATE_XML = NO +GENERATE_PERLMOD = NO diff --git a/doc/api/libbabeltrace2/DoxygenLayout.xml b/doc/api/libbabeltrace2/DoxygenLayout.xml new file mode 100644 index 00000000..7e40db87 --- /dev/null +++ b/doc/api/libbabeltrace2/DoxygenLayout.xml @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/api/libbabeltrace2/Makefile.am b/doc/api/libbabeltrace2/Makefile.am new file mode 100644 index 00000000..87b565d5 --- /dev/null +++ b/doc/api/libbabeltrace2/Makefile.am @@ -0,0 +1,19 @@ +API_DOC_INSTALL_DIR = "$(DESTDIR)$(docdir)/api" + +all-local: doxygen-doc + +install-data-local: doxygen-doc + $(mkdir_p) "$(API_DOC_INSTALL_DIR)" + cp -rv output/html "$(API_DOC_INSTALL_DIR)" + +@DX_RULES@ + +MOSTLYCLEANFILES = $(DX_CLEANFILES) +EXTRA_DIST = \ + Doxyfile.in \ + DoxygenLayout.xml \ + README.adoc \ + style.css \ + dox \ + examples \ + images diff --git a/doc/api/libbabeltrace2/README.adoc b/doc/api/libbabeltrace2/README.adoc new file mode 100644 index 00000000..71675a63 --- /dev/null +++ b/doc/api/libbabeltrace2/README.adoc @@ -0,0 +1,386 @@ +// Render with Asciidoctor + += Babeltrace{nbsp}2 C API documentation guidelines +Philippe Proulx +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 `` and + ``: ++ +-- +---- +@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 + On success, \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 `` and ``. Likewise, you can use strong emphasis +when needed with the `\b` command (one word) or with `` and +``. In general, prefer light emphasis to strong emphasis, and +use it economically. + +Links to other parts of the documentation are very important. Consider +that the reader never knows that other functions exist other than the +one she's reading. Use as many internal links as possible. Use the +following forms of links: + +`__func__()`:: + Automatic link to the function or macro named `__func__`. + +`#__name__`:: + Automatic link to the type or enumerator named `__name__`. + +`\ref __ref__`:: + Link to `__ref__` (page name, group name, function or macro name, + type name, variable name, etc.) using its default text. + +`\ref __ref__ "__some text__"`:: + Link to `__ref__` (page name, group name, function or macro name, + type name, variable name, etc.) using the text `__some text__`. + +See Doxygen's http://www.doxygen.nl/manual/autolink.html[Automatic link +generation] for other ways to create automatic links. + +Follow, as much as possible, the +https://docs.microsoft.com/en-ca/style-guide/welcome/[Microsoft Style +Guide] when you document the API. This includes: + +* Use an active voice. +* Use a gender-neutral language. +* Use the present tense (you almost never need the future tense). +* Address your reader directly (use "`you`"). +* Use contractions ("`it's`", "`you're`", "`don't`", and the rest). +* Avoid anthropomorphism. +* Ensure parallelism in lists, procedures, and sentences. +* Terminate list items with a period. +* Do not use Latin abbreviations. +* Use "`and`" or "`or`" instead of a slash. +* Avoid using negatives. +* Avoid using "`should`": most of the time, you mean "`must`", and + that's very clear for the reader. diff --git a/doc/api/libbabeltrace2/dox/api-fund.dox b/doc/api/libbabeltrace2/dox/api-fund.dox new file mode 100644 index 00000000..f8026b29 --- /dev/null +++ b/doc/api/libbabeltrace2/dox/api-fund.dox @@ -0,0 +1,569 @@ +/*! +@page api-fund API fundamentals + +This page explains the basic principles of the \bt_api. + +You \em must understand what the API expects before you create a +\bt_name \bt_plugin or an application which uses the API. + +@section api-fund-header Header file + +To use the \bt_api, include %babeltrace2/babeltrace.h: + +@code +#include +@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 +preconditions. + +All the functions of libbabeltrace2 which call a user function which +returns something check that the returned value meets their +postconditions. + +The function descriptions in the +API reference modules +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 abort(). + +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 +object-oriented. + +With a few exceptions, API functions are actually +methods +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 API reference modules 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: + +

+
\anchor api-fund-shared-object Shared object
+
+ A \em shared object has a reference + count. + + 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 *_get_ref() and *_put_ref() functions, + and all *_PUT_REF_AND_RESET() 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 + borrowed reference: if you need your own reference, get + one with the appropriate *_get_ref() function. +
+ +
\anchor api-fund-unique-object Unique object
+
+ 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 + API reference modules 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. +
+
+ +In the API reference, 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 API reference modules +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 +opaque pointers, +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 API reference modules make +this clear in the precondition section. Such objects always have a +*_get_type() 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 bt_A_as_B() 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 bt_A_as_B() 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 const-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: + +
+
If it's a pointer
+
+ The function returns \c NULL if the property/object is missing. +
+ +
If it's not a pointer
+
+
+
If the property is available
+
+ The function returns the property by output parameter and returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE. +
+ +
If the property is not available
+
+ The function returns #BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE. +
+
+
+
+ +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 API reference modules +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 *ptr 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 +object-oriented programming +(OOP) language. + +Here's the mapping of typical OOP language features to the +\bt_name library domain: + + + + + + + + + + +
OOP concept + \bt_name equivalent +
User class. + + Class object with implemented user functions. + + For example: #bt_component_class_source. +
User class instance. + + Instance object, created from a class object. + + For example: #bt_component_source. +
+ Instance pointer (\c this keyword in C++/Java and \c self variable + in Python, for example). + + "Self" (private) object. + + A "self" object has a specific, dedicated C type which starts + with bt_self_. + + For example: #bt_self_component_source. +
Protected, final method. + + Library function accepting an instance pointer ("self" object) as + its first parameter. + + Those functions always start with bt_self_. + + For example: bt_self_component_source_add_output_port(). +
Protected, overridable method. + + User function with a specific signature, accepting an instance + pointer ("self" object) as its first parameter. + + For example: #bt_component_class_source_initialize_method. +
Private user method. + + Custom \c static user function having access to the instance + pointer ("self" object) somehow. +
Private user property or attribute. + + 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()). +
+ +@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 _get_ref() or _put_ref()). + +The +babeltrace2 +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 (05-11 00:58:03.691). + +-# The process and thread IDs (23402 23402). + +-# The logging level (\c D for \em DEBUG). + +-# The function logging (\c bt_value_destroy). + +-# The file and line number logging (values.c:498). + +-# The message, which typically ends with a list of fields adding + details. +*/ diff --git a/doc/api/libbabeltrace2/dox/examples.dox b/doc/api/libbabeltrace2/dox/examples.dox new file mode 100644 index 00000000..507b6e4b --- /dev/null +++ b/doc/api/libbabeltrace2/dox/examples.dox @@ -0,0 +1,233 @@ +/*! +@page examples Examples + +The examples of this section apply the different parts of the +libbabeltrace2 API to accomplish real tasks. + +The available examples are: + +- \subpage example-simple-plugin-def-file +- \subpage example-simple-src-cmp-cls +- \subpage example-simple-flt-cmp-cls +- \subpage example-simple-sink-cmp-cls + +@page example-simple-plugin-def-file Simple shared object plugin definition C file + +This example shows a basic \bt_name +\ref api-plugin-dev "shared object plugin" definition C file. + +The shared object plugin's name is vestige. 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 +sink.vestige.output. + +Assume that \c vestige.c contains the actual source and sink component +classes's code, and that \c vestige.h contains its declarations. + +vestige-plugin.c: + +@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 dust and the name of the source +component class is input. Therefore the +component class is identified in the \bt_cli +command-line tool as source.dust.input. + +A source.dust.input \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 + Unix timestamp + (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 source.dust.input component accepts a single +\ref api-comp-cls-dev-meth-init "initialization parameter", +path, which is the path of the file to open and read. + +A source.dust.input component creates a single +\bt_oport named out. + +For each line of the input file, a source.dust.input +component's \bt_msg_iter emits an \bt_ev_msg. + +To simplify this example, a source.dust.input 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, dust.c: + +@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 +dust, you can view the event messages that a +source.dust.input 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 distill and the name of the +filter component class is theone. Therefore the +component class is identified in the \bt_cli +command-line tool as filter.distill.theone. + +A filter.distill.theone \bt_comp removes specific +\bt_p_ev_msg from a \bt_stream based on their \bt_ev_cls's name. + +A filter.distill.theone component accepts a single +\ref api-comp-cls-dev-meth-init "initialization parameter", +names, which is an \bt_array_val of string values. The +array value contains the names of the classes of the events to discard. + +A filter.distill.theone component creates a single +\bt_iport named in and a single \bt_oport named +out. + +To simplify this example, a filter.distill.theone 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, distill.c: + +@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 +filter.distill.theone component, reading a +CTF 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 epitome and the name of the +sink component class is output. Therefore the component +class is identified in the \bt_cli +command-line tool as sink.epitome.output. + +A sink.epitome.output \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 sink.epitome.output component does not need any +\ref api-comp-cls-dev-meth-init "initialization parameter": it just +prints to the standard output. + +A sink.epitome.output component creates a single +\bt_iport named in. + +To simplify this example, a sink.epitome.output 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, epitome.c: + +@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 +sink.epitome.output component, reading a +CTF trace +(see \bt_man{babeltrace2-source.ctf.fs,7}) for example: + +@code{.unparsed} +$ babeltrace2 --plugin-path=. /path/to/ctf/trace --component=sink.epitome.output +@endcode +*/ diff --git a/doc/api/libbabeltrace2/dox/group-trace-ir.dox b/doc/api/libbabeltrace2/dox/group-trace-ir.dox new file mode 100644 index 00000000..db258057 --- /dev/null +++ b/doc/api/libbabeltrace2/dox/group-trace-ir.dox @@ -0,0 +1,108 @@ +/*! +@defgroup api-tir Trace IR +@ingroup api-msg + +@brief + Intermediate representation of + tracing + domain objects and concepts (contents of \bt_p_msg). + +The \bt_name +trace IR (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: + +
+
Metadata
+
+ 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 + Common Trace Format, 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 +
+ +
Data
+
+ 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 +
+
+ +The trace IR metadata to data object association is: + + + + + + + + +
Metadata object + Data object +
\bt_c_clock_cls + Stream clock (see \ref api-tir-cs) +
\bt_c_ev_cls + \bt_c_ev +
\bt_c_fc + \bt_c_field +
\bt_c_stream_cls + \bt_c_stream +
\bt_c_trace_cls + \bt_c_trace +
+ +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 user +attributes property (a \bt_map_val): you can use it to attach +custom attributes, without any semantics specified by the \bt_name +project, to those objects. +*/ diff --git a/doc/api/libbabeltrace2/dox/guides.dox b/doc/api/libbabeltrace2/dox/guides.dox new file mode 100644 index 00000000..ad2166f0 --- /dev/null +++ b/doc/api/libbabeltrace2/dox/guides.dox @@ -0,0 +1,211 @@ +/*! +@page guides Guides + +The guides in this section are step-by-step procedures to accomplish +common tasks with libbabeltrace2. + +Guides help you navigate through the most important features of +the library and its API. + +Make sure to eventually read \ref api-fund before you use the \bt_api +seriously. + +The available guides are: + +- \subpage guide-build-bt2-dev +- \subpage guide-comp-link-plugin-so +- \subpage guide-comp-link-app + +@if meow + +- \subpage guide-create-graph +- \subpage guide-write-min-src-comp-cls +- \subpage guide-write-min-flt-comp-cls +- \subpage guide-write-min-sink-comp-cls +- \subpage guide-write-simple-sink-comp-cls +- \subpage guide-create-plugin +- \subpage guide-write-full-src-comp-cls +- \subpage guide-write-full-flt-comp-cls +- \subpage guide-write-full-sink-comp-cls +- \subpage guide-query +- \subpage guide-seek-msg-iter +- \subpage guide-intr-graph +- \subpage guide-intr-query +- \subpage guide-graph-listeners + +@endif + +@page guide-build-bt2-dev Build Babeltrace 2 for development + +If you are developing a \bt_name \bt_plugin or an application which uses +libbabeltrace2, we recommend that: + +- You build \bt_name from source in developer mode. + + 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: + +
    +
  1. + Download the + \bt_name tarball and extract it. + + See the project's + README + for build-time requirements and detailed build instructions. +
  2. + 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 +
  3. + Build and install the project: + +@code{.unparsed} +$ make +# make install +@endcode +
+ +\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: + +
    +
  1. + Compile the plugin's C/C++ source files with the + \-fPIC + and + \-c + 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 +
    2. + +
  2. + Link the resulting object files with the + \-shared + 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 +
    3. +
+ +@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: + +
    +
  1. + Compile your C/C++ files as usual. +
    2. + +
  2. + 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 +
    3. +
+ +@if meow + +@page guide-create-graph Create a graph from existing component classes and run it + +TODO! + +@page guide-write-min-src-comp-cls Write a minimal source component class + +TODO! + +@page guide-write-min-flt-comp-cls Write a minimal filter component class + +TODO! + +@page guide-write-min-sink-comp-cls Write a minimal sink component class + +TODO! + +@page guide-write-simple-sink-comp-cls Write a simple sink component class + +TODO! + +@page guide-create-plugin Create a Babeltrace 2 plugin + +TODO! + +@page guide-write-full-src-comp-cls Write a complete source component class + +TODO! + +@page guide-write-full-flt-comp-cls Write a complete filter component class + +TODO! + +@page guide-write-full-sink-comp-cls Write a complete sink component class + +TODO! + +@page guide-query Query an object from a component class + +TODO! + +@page guide-seek-msg-iter Make a message iterator seek + +TODO! + +@page guide-intr-graph Interrupt a running graph + +TODO! + +@page guide-intr-query Interrupt a query operation + +TODO! + +@page guide-graph-listeners Use graph listeners to react to topology events + +TODO! + +@endif +*/ diff --git a/doc/api/libbabeltrace2/dox/main-page.dox b/doc/api/libbabeltrace2/dox/main-page.dox new file mode 100644 index 00000000..22c1e5d3 --- /dev/null +++ b/doc/api/libbabeltrace2/dox/main-page.dox @@ -0,0 +1,124 @@ +/*! +@mainpage Välkommen! + +@note +This documentation (text and illustrations) is licensed under a +Creative +Commons Attribution-ShareAlike 4.0 International license. + +Welcome to the +\bt_api (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 + +\bt_name +is an open-source software project by +EfficiOS; its purpose is to +process or convert +traces. + +The \bt_name project contains: + +- A library, libbabeltrace2, which all the other parts rely on. + + libbabeltrace2 offers a + C99 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. + + Common Trace Format (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 + convert + and + run + 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 LTTng relay daemon). +This is what the \bt_cli CLI tool's +query +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? + +
+
\ref api-fund
+
+ Explains the basic principles of the \bt_api. + + Make sure you understand this section as you need this knowledge to + use the API correctly. +
+ +
\ref guides
+
+ Shows how to achieve common tasks with libbabeltrace2. + + Guides help you navigate through the most important features of + the library and its API. +
+ +
\ref examples
+
+ Contains simple and more complex examples which apply the different + parts of the API to accomplish real tasks. +
+ +
API reference
+
+ 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. +
+
+*/ diff --git a/doc/api/libbabeltrace2/examples/distill.c b/doc/api/libbabeltrace2/examples/distill.c new file mode 100644 index 00000000..81fe2e82 --- /dev/null +++ b/doc/api/libbabeltrace2/examples/distill.c @@ -0,0 +1,284 @@ +#include +#include +#include +#include +#include +#include +#include + +/* Filter component's private data */ +struct distill { + /* Names of the classes of the events to discard (owned by this) */ + const bt_value *names_value; + + /* Component's input port (weak) */ + bt_self_component_port_input *in_port; +}; + +/* + * Initializes the filter component. + */ +static +bt_component_class_initialize_method_status distill_initialize( + bt_self_component_filter *self_component_filter, + bt_self_component_filter_configuration *configuration, + const bt_value *params, void *initialize_method_data) +{ + /* Allocate a private data structure */ + struct distill *distill = malloc(sizeof(*distill)); + + /* + * Keep a reference of the `names` array value parameter so that the + * "next" method of a message iterator can access it to decide + * whether or not to discard an event message. + */ + distill->names_value = + bt_value_map_borrow_entry_value_const(params, "names"); + bt_value_get_ref(distill->names_value); + + /* Set the component's user data to our private data structure */ + bt_self_component_set_data( + bt_self_component_filter_as_self_component(self_component_filter), + distill); + + /* + * Add an input port named `in` to the filter component. + * + * This is needed so that this filter component can be connected to + * a filter or a source component. With a connected upstream + * component, this filter component's message iterator can create a + * message iterator to consume messages. + * + * Add an output port named `out` to the filter component. + * + * This is needed so that this filter component can be connected to + * a filter or a sink component. Once a downstream component is + * connected, it can create our message iterator. + */ + bt_self_component_filter_add_input_port(self_component_filter, + "in", NULL, &distill->in_port); + bt_self_component_filter_add_output_port(self_component_filter, + "out", NULL, NULL); + + return BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK; +} + +/* + * Finalizes the filter component. + */ +static +void distill_finalize(bt_self_component_filter *self_component_filter) +{ + /* Retrieve our private data from the component's user data */ + struct distill *distill = bt_self_component_get_data( + bt_self_component_filter_as_self_component(self_component_filter)); + + /* Put all references */ + bt_value_put_ref(distill->names_value); + + /* Free the allocated structure */ + free(distill); +} + +/* Message iterator's private data */ +struct distill_message_iterator { + /* (Weak) link to the component's private data */ + struct distill *distill; + + /* Upstream message iterator (owned by this) */ + bt_message_iterator *message_iterator; +}; + +/* + * Initializes the message iterator. + */ +static +bt_message_iterator_class_initialize_method_status +distill_message_iterator_initialize( + bt_self_message_iterator *self_message_iterator, + bt_self_message_iterator_configuration *configuration, + bt_self_component_port_output *self_port) +{ + /* Allocate a private data structure */ + struct distill_message_iterator *distill_iter = + malloc(sizeof(*distill_iter)); + + /* Retrieve the component's private data from its user data */ + struct distill *distill = bt_self_component_get_data( + bt_self_message_iterator_borrow_component(self_message_iterator)); + + /* Keep a link to the component's private data */ + distill_iter->distill = distill; + + /* Create the uptream message iterator */ + bt_message_iterator_create_from_message_iterator(self_message_iterator, + distill->in_port, &distill_iter->message_iterator); + + /* Set the message iterator's user data to our private data structure */ + bt_self_message_iterator_set_data(self_message_iterator, distill_iter); + + return BT_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_STATUS_OK; +} + +/* + * Finalizes the message iterator. + */ +static +void distill_message_iterator_finalize( + bt_self_message_iterator *self_message_iterator) +{ + /* Retrieve our private data from the message iterator's user data */ + struct distill_message_iterator *distill_iter = + bt_self_message_iterator_get_data(self_message_iterator); + + /* Free the allocated structure */ + free(distill_iter); +} + +/* + * Returns `true` if `message` passes, that is, one of: + * + * * It's not an event message. + * * The event message does not need to be discarded based on its event + * class's name. + */ +static +bool message_passes(struct distill_message_iterator *distill_iter, + const bt_message *message) +{ + bool passes = true; + + /* Move as is if it's not an event message */ + if (bt_message_get_type(message) != BT_MESSAGE_TYPE_EVENT) { + passes = false; + goto end; + } + + /* Borrow the event message's event and its class */ + const bt_event *event = + bt_message_event_borrow_event_const(message); + const bt_event_class *event_class = bt_event_borrow_class_const(event); + + /* Get the event class's name */ + const char *name = bt_event_class_get_name(event_class); + + for (uint64_t i = 0; i < bt_value_array_get_length( + distill_iter->distill->names_value); i++) { + const char *discard_name = bt_value_string_get( + bt_value_array_borrow_element_by_index_const( + distill_iter->distill->names_value, i)); + + if (strcmp(name, discard_name) == 0) { + passes = false; + goto end; + } + } + +end: + return passes; +} + +/* + * Returns the next message to the message iterator's user. + * + * This method can fill the `messages` array with up to `capacity` + * messages. + * + * To keep this example simple, we put a single message into `messages` + * and set `*count` to 1 (if the message iterator is not ended). + */ +static +bt_message_iterator_class_next_method_status distill_message_iterator_next( + bt_self_message_iterator *self_message_iterator, + bt_message_array_const messages, uint64_t capacity, + uint64_t *count) +{ + /* Retrieve our private data from the message iterator's user data */ + struct distill_message_iterator *distill_iter = + bt_self_message_iterator_get_data(self_message_iterator); + + /* Consume a batch of messages from the upstream message iterator */ + bt_message_array_const upstream_messages; + uint64_t upstream_message_count; + bt_message_iterator_next_status next_status; + +consume_upstream_messages: + next_status = bt_message_iterator_next(distill_iter->message_iterator, + &upstream_messages, &upstream_message_count); + + /* Initialize the return status to a success */ + bt_message_iterator_class_next_method_status status = + BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK; + + switch (next_status) { + case BT_MESSAGE_ITERATOR_NEXT_STATUS_END: + /* End of iteration: put the message iterator's reference */ + bt_message_iterator_put_ref(distill_iter->message_iterator); + status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_END; + goto end; + case BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN: + status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_AGAIN; + goto end; + case BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR: + status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_MEMORY_ERROR; + goto end; + case BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR: + status = BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR; + goto end; + default: + break; + } + + /* Output message array index */ + uint64_t i = 0; + + /* For each consumed message */ + for (uint64_t upstream_i = 0; upstream_i < upstream_message_count; + upstream_i++) { + /* Current message */ + const bt_message *upstream_message = upstream_messages[upstream_i]; + + /* Check if the upstream message passes */ + if (message_passes(distill_iter, upstream_message)) { + /* Move upstream message to output message array */ + messages[i] = upstream_message; + i++; + continue; + } + + /* Discard upstream message: put its reference */ + bt_message_put_ref(upstream_message); + } + + if (i == 0) { + /* + * We discarded all the upstream messages: get a new batch of + * messages, because this method _cannot_ return + * `BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_OK` and put no + * messages into its output message array. + */ + goto consume_upstream_messages; + } + + *count = i; + +end: + return status; +} + +/* Mandatory */ +BT_PLUGIN_MODULE(); + +/* Define the `distill` plugin */ +BT_PLUGIN(distill); + +/* Define the `theone` filter component class */ +BT_PLUGIN_FILTER_COMPONENT_CLASS(theone, distill_message_iterator_next); + +/* Set some of the `theone` filter component class's optional methods */ +BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD(theone, distill_initialize); +BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD(theone, distill_finalize); +BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD( + theone, distill_message_iterator_initialize); +BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(theone, + distill_message_iterator_finalize); diff --git a/doc/api/libbabeltrace2/examples/dust b/doc/api/libbabeltrace2/examples/dust new file mode 100644 index 00000000..de238606 --- /dev/null +++ b/doc/api/libbabeltrace2/examples/dust @@ -0,0 +1,5 @@ +1578694237 154215 send-msg Jowl pig filet mignon, turducken capicola. +1578694237 200774 recv-msg Pork belly pig burgdoggen venison bacon. +1578694241 001831 send-msg Bacon ipsum dolor amet strip steak. +1578694241 944187 send-msg Spare ribs filet mignon boudin bresaola. +1578694245 115406 recv-msg Rump cow t-bone hamburger short tenderloin. diff --git a/doc/api/libbabeltrace2/examples/dust.c b/doc/api/libbabeltrace2/examples/dust.c new file mode 100644 index 00000000..fd1f1db9 --- /dev/null +++ b/doc/api/libbabeltrace2/examples/dust.c @@ -0,0 +1,436 @@ +#include +#include +#include +#include +#include +#include + +/* 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); diff --git a/doc/api/libbabeltrace2/examples/epitome.c b/doc/api/libbabeltrace2/examples/epitome.c new file mode 100644 index 00000000..852ca3f7 --- /dev/null +++ b/doc/api/libbabeltrace2/examples/epitome.c @@ -0,0 +1,196 @@ +#include +#include +#include +#include +#include +#include + +/* Sink component's private data */ +struct epitome_out { + /* Upstream message iterator (owned by this) */ + bt_message_iterator *message_iterator; + + /* Current event message index */ + uint64_t index; +}; + +/* + * Initializes the sink component. + */ +static +bt_component_class_initialize_method_status epitome_out_initialize( + bt_self_component_sink *self_component_sink, + bt_self_component_sink_configuration *configuration, + const bt_value *params, void *initialize_method_data) +{ + /* Allocate a private data structure */ + struct epitome_out *epitome_out = malloc(sizeof(*epitome_out)); + + /* Initialize the first event message's index */ + epitome_out->index = 1; + + /* Set the component's user data to our private data structure */ + bt_self_component_set_data( + bt_self_component_sink_as_self_component(self_component_sink), + epitome_out); + + /* + * Add an input port named `in` to the sink component. + * + * This is needed so that this sink component can be connected to a + * filter or a source component. With a connected upstream + * component, this sink component can create a message iterator + * to consume messages. + */ + bt_self_component_sink_add_input_port(self_component_sink, + "in", NULL, NULL); + + return BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK; +} + +/* + * Finalizes the sink component. + */ +static +void epitome_out_finalize(bt_self_component_sink *self_component_sink) +{ + /* Retrieve our private data from the component's user data */ + struct epitome_out *epitome_out = bt_self_component_get_data( + bt_self_component_sink_as_self_component(self_component_sink)); + + /* Free the allocated structure */ + free(epitome_out); +} + +/* + * Called when the trace processing graph containing the sink component + * is configured. + * + * This is where we can create our upstream message iterator. + */ +static +bt_component_class_sink_graph_is_configured_method_status +epitome_out_graph_is_configured(bt_self_component_sink *self_component_sink) +{ + /* Retrieve our private data from the component's user data */ + struct epitome_out *epitome_out = bt_self_component_get_data( + bt_self_component_sink_as_self_component(self_component_sink)); + + /* Borrow our unique port */ + bt_self_component_port_input *in_port = + bt_self_component_sink_borrow_input_port_by_index( + self_component_sink, 0); + + /* Create the uptream message iterator */ + bt_message_iterator_create_from_sink_component(self_component_sink, + in_port, &epitome_out->message_iterator); + + return BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK; +} + +/* + * Prints a line for `message`, if it's an event message, to the + * standard output. + */ +static +void print_message(struct epitome_out *epitome_out, const bt_message *message) +{ + /* Discard if it's not an event message */ + if (bt_message_get_type(message) != BT_MESSAGE_TYPE_EVENT) { + goto end; + } + + /* Borrow the event message's event and its class */ + const bt_event *event = + bt_message_event_borrow_event_const(message); + const bt_event_class *event_class = bt_event_borrow_class_const(event); + + /* Get the number of payload field members */ + const bt_field *payload_field = + bt_event_borrow_payload_field_const(event); + uint64_t member_count = bt_field_class_structure_get_member_count( + bt_field_borrow_class_const(payload_field)); + + /* Write a corresponding line to the standard output */ + printf("#%" PRIu64 ": %s (%" PRIu64 " payload member%s)\n", + epitome_out->index, bt_event_class_get_name(event_class), + member_count, member_count == 1 ? "" : "s"); + + /* Increment the current event message's index */ + epitome_out->index++; + +end: + return; +} + +/* + * Consumes a batch of messages and writes the corresponding lines to + * the standard output. + */ +bt_component_class_sink_consume_method_status epitome_out_consume( + bt_self_component_sink *self_component_sink) +{ + bt_component_class_sink_consume_method_status status = + BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK; + + /* Retrieve our private data from the component's user data */ + struct epitome_out *epitome_out = bt_self_component_get_data( + bt_self_component_sink_as_self_component(self_component_sink)); + + /* Consume a batch of messages from the upstream message iterator */ + bt_message_array_const messages; + uint64_t message_count; + bt_message_iterator_next_status next_status = + bt_message_iterator_next(epitome_out->message_iterator, &messages, + &message_count); + + switch (next_status) { + case BT_MESSAGE_ITERATOR_NEXT_STATUS_END: + /* End of iteration: put the message iterator's reference */ + bt_message_iterator_put_ref(epitome_out->message_iterator); + status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END; + goto end; + case BT_MESSAGE_ITERATOR_NEXT_STATUS_AGAIN: + status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN; + goto end; + case BT_MESSAGE_ITERATOR_NEXT_STATUS_MEMORY_ERROR: + status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR; + goto end; + case BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR: + status = BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR; + goto end; + default: + break; + } + + /* For each consumed message */ + for (uint64_t i = 0; i < message_count; i++) { + /* Current message */ + const bt_message *message = messages[i]; + + /* Print line for current message if it's an event message */ + print_message(epitome_out, message); + + /* Put this message's reference */ + bt_message_put_ref(message); + } + +end: + return status; +} + +/* Mandatory */ +BT_PLUGIN_MODULE(); + +/* Define the `epitome` plugin */ +BT_PLUGIN(epitome); + +/* Define the `output` sink component class */ +BT_PLUGIN_SINK_COMPONENT_CLASS(output, epitome_out_consume); + +/* Set some of the `output` sink component class's optional methods */ +BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD(output, + epitome_out_initialize); +BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD(output, epitome_out_finalize); +BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD(output, + epitome_out_graph_is_configured); diff --git a/doc/api/libbabeltrace2/examples/vestige-plugin.c b/doc/api/libbabeltrace2/examples/vestige-plugin.c new file mode 100644 index 00000000..5f607ffd --- /dev/null +++ b/doc/api/libbabeltrace2/examples/vestige-plugin.c @@ -0,0 +1,45 @@ +/* Component class method declarations */ +#include "vestige.h" + +/* Always start with this line */ +BT_PLUGIN_MODULE(); + +/* Declare the `vestige` plugin */ +BT_PLUGIN(vestige); + +/* Set some optional plugin properties */ +BT_PLUGIN_DESCRIPTION("Input and output for the Vestige format."); +BT_PLUGIN_AUTHOR("Denis Rondeau"); +BT_PLUGIN_LICENSE("MIT"); + +/* Add the `input` source component class */ +BT_PLUGIN_SOURCE_COMPONENT_CLASS(input, vestige_in_iter_next); + +/* Set the source component class's optional description */ +BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION(input, + "Read a Vestige trace file."); + +/* Set some optional methods of the source component class */ +BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD(input, + vestige_in_init); +BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD(input, + vestige_in_finalize); +BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD( + input, vestige_in_iter_init); +BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD( + input, vestige_in_iter_fini); + +/* Add the `output` sink component class */ +BT_PLUGIN_SINK_COMPONENT_CLASS(output, vestige_out_consume); + +/* Set the sink component class's optional description */ +BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION(output, + "Write a Vestige trace file."); + +/* Set some optional methods of the sink component class */ +BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD(output, + vestige_out_init); +BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD(output, + vestige_out_finalize); +BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD(output, + vestige_out_graph_is_configured); diff --git a/doc/api/libbabeltrace2/images/all-field-classes.png b/doc/api/libbabeltrace2/images/all-field-classes.png new file mode 100644 index 00000000..aa39252f Binary files /dev/null and b/doc/api/libbabeltrace2/images/all-field-classes.png differ diff --git a/doc/api/libbabeltrace2/images/all-fields.png b/doc/api/libbabeltrace2/images/all-fields.png new file mode 100644 index 00000000..7385064c Binary files /dev/null and b/doc/api/libbabeltrace2/images/all-fields.png differ diff --git a/doc/api/libbabeltrace2/images/basic-convert-graph.png b/doc/api/libbabeltrace2/images/basic-convert-graph.png new file mode 100644 index 00000000..a97dfcac Binary files /dev/null and b/doc/api/libbabeltrace2/images/basic-convert-graph.png differ diff --git a/doc/api/libbabeltrace2/images/clock-terminology.png b/doc/api/libbabeltrace2/images/clock-terminology.png new file mode 100644 index 00000000..5e26b5b8 Binary files /dev/null and b/doc/api/libbabeltrace2/images/clock-terminology.png differ diff --git a/doc/api/libbabeltrace2/images/clocks.png b/doc/api/libbabeltrace2/images/clocks.png new file mode 100644 index 00000000..0a3f375e Binary files /dev/null and b/doc/api/libbabeltrace2/images/clocks.png differ diff --git a/doc/api/libbabeltrace2/images/complex-graph.png b/doc/api/libbabeltrace2/images/complex-graph.png new file mode 100644 index 00000000..53d7bf6e Binary files /dev/null and b/doc/api/libbabeltrace2/images/complex-graph.png differ diff --git a/doc/api/libbabeltrace2/images/component-zoom.png b/doc/api/libbabeltrace2/images/component-zoom.png new file mode 100644 index 00000000..7d2b7aaf Binary files /dev/null and b/doc/api/libbabeltrace2/images/component-zoom.png differ diff --git a/doc/api/libbabeltrace2/images/component.png b/doc/api/libbabeltrace2/images/component.png new file mode 100644 index 00000000..eb9c621c Binary files /dev/null and b/doc/api/libbabeltrace2/images/component.png differ diff --git a/doc/api/libbabeltrace2/images/darray-link.png b/doc/api/libbabeltrace2/images/darray-link.png new file mode 100644 index 00000000..0c219c6f Binary files /dev/null and b/doc/api/libbabeltrace2/images/darray-link.png differ diff --git a/doc/api/libbabeltrace2/images/error-reporting-step-5.png b/doc/api/libbabeltrace2/images/error-reporting-step-5.png new file mode 100644 index 00000000..0f3fbc60 Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-step-5.png differ diff --git a/doc/api/libbabeltrace2/images/error-reporting-step-6.png b/doc/api/libbabeltrace2/images/error-reporting-step-6.png new file mode 100644 index 00000000..561d5c75 Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-step-6.png differ diff --git a/doc/api/libbabeltrace2/images/error-reporting-step-7.png b/doc/api/libbabeltrace2/images/error-reporting-step-7.png new file mode 100644 index 00000000..313ffcd9 Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-step-7.png differ diff --git a/doc/api/libbabeltrace2/images/error-reporting-steps-1234.png b/doc/api/libbabeltrace2/images/error-reporting-steps-1234.png new file mode 100644 index 00000000..fe6f7a8d Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-steps-1234.png differ diff --git a/doc/api/libbabeltrace2/images/error-reporting-steps-89.png b/doc/api/libbabeltrace2/images/error-reporting-steps-89.png new file mode 100644 index 00000000..5a95c87c Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting-steps-89.png differ diff --git a/doc/api/libbabeltrace2/images/error-reporting.png b/doc/api/libbabeltrace2/images/error-reporting.png new file mode 100644 index 00000000..690def66 Binary files /dev/null and b/doc/api/libbabeltrace2/images/error-reporting.png differ diff --git a/doc/api/libbabeltrace2/images/fc-array.png b/doc/api/libbabeltrace2/images/fc-array.png new file mode 100644 index 00000000..2764459c Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-array.png differ diff --git a/doc/api/libbabeltrace2/images/fc-ba.png b/doc/api/libbabeltrace2/images/fc-ba.png new file mode 100644 index 00000000..9d3af46c Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-ba.png differ diff --git a/doc/api/libbabeltrace2/images/fc-bool.png b/doc/api/libbabeltrace2/images/fc-bool.png new file mode 100644 index 00000000..34274eb5 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-bool.png differ diff --git a/doc/api/libbabeltrace2/images/fc-enum.png b/doc/api/libbabeltrace2/images/fc-enum.png new file mode 100644 index 00000000..56c74af2 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-enum.png differ diff --git a/doc/api/libbabeltrace2/images/fc-int.png b/doc/api/libbabeltrace2/images/fc-int.png new file mode 100644 index 00000000..4e7e8764 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-int.png differ diff --git a/doc/api/libbabeltrace2/images/fc-opt.png b/doc/api/libbabeltrace2/images/fc-opt.png new file mode 100644 index 00000000..60b3fcf5 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-opt.png differ diff --git a/doc/api/libbabeltrace2/images/fc-real.png b/doc/api/libbabeltrace2/images/fc-real.png new file mode 100644 index 00000000..21d7240e Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-real.png differ diff --git a/doc/api/libbabeltrace2/images/fc-string.png b/doc/api/libbabeltrace2/images/fc-string.png new file mode 100644 index 00000000..3232f019 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-string.png differ diff --git a/doc/api/libbabeltrace2/images/fc-struct.png b/doc/api/libbabeltrace2/images/fc-struct.png new file mode 100644 index 00000000..467e5700 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-struct.png differ diff --git a/doc/api/libbabeltrace2/images/fc-to-field.png b/doc/api/libbabeltrace2/images/fc-to-field.png new file mode 100644 index 00000000..47d45400 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-to-field.png differ diff --git a/doc/api/libbabeltrace2/images/fc-var.png b/doc/api/libbabeltrace2/images/fc-var.png new file mode 100644 index 00000000..b4a88c01 Binary files /dev/null and b/doc/api/libbabeltrace2/images/fc-var.png differ diff --git a/doc/api/libbabeltrace2/images/field-class-zoom.png b/doc/api/libbabeltrace2/images/field-class-zoom.png new file mode 100644 index 00000000..4a577e5b Binary files /dev/null and b/doc/api/libbabeltrace2/images/field-class-zoom.png differ diff --git a/doc/api/libbabeltrace2/images/graph-lifetime.png b/doc/api/libbabeltrace2/images/graph-lifetime.png new file mode 100644 index 00000000..3d1079a0 Binary files /dev/null and b/doc/api/libbabeltrace2/images/graph-lifetime.png differ diff --git a/doc/api/libbabeltrace2/images/linking.png b/doc/api/libbabeltrace2/images/linking.png new file mode 100644 index 00000000..c137fc2e Binary files /dev/null and b/doc/api/libbabeltrace2/images/linking.png differ diff --git a/doc/api/libbabeltrace2/images/msg-iter-cls.png b/doc/api/libbabeltrace2/images/msg-iter-cls.png new file mode 100644 index 00000000..03526ccd Binary files /dev/null and b/doc/api/libbabeltrace2/images/msg-iter-cls.png differ diff --git a/doc/api/libbabeltrace2/images/msg-iter-complex.png b/doc/api/libbabeltrace2/images/msg-iter-complex.png new file mode 100644 index 00000000..ba16db3d Binary files /dev/null and b/doc/api/libbabeltrace2/images/msg-iter-complex.png differ diff --git a/doc/api/libbabeltrace2/images/msg-iter.png b/doc/api/libbabeltrace2/images/msg-iter.png new file mode 100644 index 00000000..d2614042 Binary files /dev/null and b/doc/api/libbabeltrace2/images/msg-iter.png differ diff --git a/doc/api/libbabeltrace2/images/opt-link.png b/doc/api/libbabeltrace2/images/opt-link.png new file mode 100644 index 00000000..784fa476 Binary files /dev/null and b/doc/api/libbabeltrace2/images/opt-link.png differ diff --git a/doc/api/libbabeltrace2/images/plugin-comp-cls-full.png b/doc/api/libbabeltrace2/images/plugin-comp-cls-full.png new file mode 100644 index 00000000..95915e61 Binary files /dev/null and b/doc/api/libbabeltrace2/images/plugin-comp-cls-full.png differ diff --git a/doc/api/libbabeltrace2/images/plugin.png b/doc/api/libbabeltrace2/images/plugin.png new file mode 100644 index 00000000..3ca50581 Binary files /dev/null and b/doc/api/libbabeltrace2/images/plugin.png differ diff --git a/doc/api/libbabeltrace2/images/trace-structure-msg-seq.png b/doc/api/libbabeltrace2/images/trace-structure-msg-seq.png new file mode 100644 index 00000000..1529774c Binary files /dev/null and b/doc/api/libbabeltrace2/images/trace-structure-msg-seq.png differ diff --git a/doc/api/libbabeltrace2/images/trace-structure.png b/doc/api/libbabeltrace2/images/trace-structure.png new file mode 100644 index 00000000..6228eac2 Binary files /dev/null and b/doc/api/libbabeltrace2/images/trace-structure.png differ diff --git a/doc/api/libbabeltrace2/images/var-link.png b/doc/api/libbabeltrace2/images/var-link.png new file mode 100644 index 00000000..6ddfe071 Binary files /dev/null and b/doc/api/libbabeltrace2/images/var-link.png differ diff --git a/doc/api/libbabeltrace2/style.css b/doc/api/libbabeltrace2/style.css new file mode 100644 index 00000000..4a42678e --- /dev/null +++ b/doc/api/libbabeltrace2/style.css @@ -0,0 +1,79 @@ +.contents h1, +.contents h2, +.contents h3 { + color: #6A2F43; +} + +.contents h1, +.contents h2 { + border-bottom: 1px solid #ccc; + display: inline-block; +} + +.contents h1 { + font-size: 1.5em; + margin-top: 2em; +} + +.contents h2 { + font-size: 1.2em; + margin-top: 1.5em; +} + +.contents dl { + margin-left: 2em; +} + +.contents dl.params, +.contents dl.section, +.contents dl.retval, +.contents dl.exception, +.contents dl.tparams { + margin-left: 0; +} + +.contents .image { + background-color: rgba(0, 0, 0, .05); + padding-top: 1em; + padding-bottom: 1em; +} + +.contents .image img { + border: 1px solid #ccc; + background-color: white; + padding: 1em; +} + +.contents .image .caption { + font-size: 75%; +} + +.contents .fragment { + padding: 1em; +} + +#projectname { + font-size: 200%; +} + +#projectbrief { + display: none; +} + +span.bt-param, +table.params .paramname { + color: #602020; + font-weight: bold; + font-family: monospace; + font-size: 90%; +} + +.contents dl.attention { + background-color: #fbdfda; + padding-top: 1em; + padding-bottom: 1em; +} + +.contents table.doxtable th { + background-color: #5173b3; +} diff --git a/include/Makefile.am b/include/Makefile.am index dbb6efa5..159482c9 100644 --- a/include/Makefile.am +++ b/include/Makefile.am @@ -2,18 +2,13 @@ babeltrace2includedir = "$(includedir)/babeltrace2" babeltrace2include_HEADERS = \ babeltrace2/babeltrace.h \ - babeltrace2/current-thread.h \ - babeltrace2/error-cause-const.h \ - babeltrace2/error-const.h \ + babeltrace2/error-reporting.h \ babeltrace2/func-status.h \ - babeltrace2/integer-range-set-const.h \ babeltrace2/integer-range-set.h \ - babeltrace2/logging.h \ babeltrace2/logging-defs.h \ - babeltrace2/property.h \ + babeltrace2/logging.h \ babeltrace2/types.h \ babeltrace2/util.h \ - babeltrace2/value-const.h \ babeltrace2/value.h \ babeltrace2/version.h @@ -39,94 +34,42 @@ babeltrace2ctfwriterinclude_HEADERS = \ # Trace IR API babeltrace2traceirincludedir = "$(includedir)/babeltrace2/trace-ir" babeltrace2traceirinclude_HEADERS = \ - babeltrace2/trace-ir/clock-class-const.h \ babeltrace2/trace-ir/clock-class.h \ - babeltrace2/trace-ir/clock-snapshot-const.h \ - babeltrace2/trace-ir/event-class-const.h \ + babeltrace2/trace-ir/clock-snapshot.h \ babeltrace2/trace-ir/event-class.h \ - babeltrace2/trace-ir/event-const.h \ babeltrace2/trace-ir/event.h \ - babeltrace2/trace-ir/field-class-const.h \ babeltrace2/trace-ir/field-class.h \ - babeltrace2/trace-ir/field-path-const.h \ - babeltrace2/trace-ir/field-const.h \ + babeltrace2/trace-ir/field-path.h \ babeltrace2/trace-ir/field.h \ - babeltrace2/trace-ir/packet-const.h \ babeltrace2/trace-ir/packet.h \ - babeltrace2/trace-ir/stream-class-const.h \ babeltrace2/trace-ir/stream-class.h \ - babeltrace2/trace-ir/stream-const.h \ babeltrace2/trace-ir/stream.h \ - babeltrace2/trace-ir/trace-class-const.h \ babeltrace2/trace-ir/trace-class.h \ - babeltrace2/trace-ir/trace-const.h \ babeltrace2/trace-ir/trace.h # Plugin and plugin development API babeltrace2pluginincludedir = "$(includedir)/babeltrace2/plugin" babeltrace2plugininclude_HEADERS = \ babeltrace2/plugin/plugin-dev.h \ - babeltrace2/plugin/plugin-const.h \ - babeltrace2/plugin/plugin-set-const.h + babeltrace2/plugin/plugin-loading.h # Graph, component, and message API babeltrace2graphincludedir = "$(includedir)/babeltrace2/graph" babeltrace2graphinclude_HEADERS = \ - babeltrace2/graph/component-class-const.h \ - babeltrace2/graph/component-class-filter-const.h \ - babeltrace2/graph/component-class-filter.h \ - babeltrace2/graph/component-class-sink-const.h \ - babeltrace2/graph/component-class-sink.h \ - babeltrace2/graph/component-class-source-const.h \ - babeltrace2/graph/component-class-source.h \ + babeltrace2/graph/component-class-dev.h \ babeltrace2/graph/component-class.h \ - babeltrace2/graph/component-const.h \ - babeltrace2/graph/component-descriptor-set-const.h \ babeltrace2/graph/component-descriptor-set.h \ - babeltrace2/graph/component-filter-const.h \ - babeltrace2/graph/component-sink-const.h \ - babeltrace2/graph/component-source-const.h \ - babeltrace2/graph/connection-const.h \ - babeltrace2/graph/graph-const.h \ + babeltrace2/graph/component.h \ + babeltrace2/graph/connection.h \ babeltrace2/graph/graph.h \ - babeltrace2/graph/interrupter-const.h \ babeltrace2/graph/interrupter.h \ - babeltrace2/graph/message-const.h \ - babeltrace2/graph/message-discarded-events-const.h \ - babeltrace2/graph/message-discarded-events.h \ - babeltrace2/graph/message-discarded-packets-const.h \ - babeltrace2/graph/message-discarded-packets.h \ - babeltrace2/graph/message-event-const.h \ - babeltrace2/graph/message-event.h \ - babeltrace2/graph/message-message-iterator-inactivity-const.h \ - babeltrace2/graph/message-message-iterator-inactivity.h \ - babeltrace2/graph/message-iterator.h \ babeltrace2/graph/message-iterator-class.h \ - babeltrace2/graph/message-packet-beginning-const.h \ - babeltrace2/graph/message-packet-beginning.h \ - babeltrace2/graph/message-packet-end-const.h \ - babeltrace2/graph/message-packet-end.h \ - babeltrace2/graph/message-stream-beginning-const.h \ - babeltrace2/graph/message-stream-beginning.h \ - babeltrace2/graph/message-stream-const.h \ - babeltrace2/graph/message-stream-end-const.h \ - babeltrace2/graph/message-stream-end.h \ - babeltrace2/graph/mip.h \ - babeltrace2/graph/port-const.h \ - babeltrace2/graph/port-input-const.h \ - babeltrace2/graph/port-output-const.h \ + babeltrace2/graph/message-iterator.h \ + babeltrace2/graph/message.h \ + babeltrace2/graph/port.h \ babeltrace2/graph/private-query-executor.h \ - babeltrace2/graph/query-executor-const.h \ babeltrace2/graph/query-executor.h \ - babeltrace2/graph/self-component-class-filter.h \ - babeltrace2/graph/self-component-class-sink.h \ - babeltrace2/graph/self-component-class-source.h \ babeltrace2/graph/self-component-class.h \ - babeltrace2/graph/self-component-filter.h \ - babeltrace2/graph/self-component-port-input.h \ - babeltrace2/graph/self-component-port-output.h \ babeltrace2/graph/self-component-port.h \ - babeltrace2/graph/self-component-sink.h \ - babeltrace2/graph/self-component-source.h \ babeltrace2/graph/self-component.h \ babeltrace2/graph/self-message-iterator.h diff --git a/include/babeltrace2/babeltrace.h b/include/babeltrace2/babeltrace.h index ffb8109e..3f919cf3 100644 --- a/include/babeltrace2/babeltrace.h +++ b/include/babeltrace2/babeltrace.h @@ -44,119 +44,43 @@ # define __BT_UPCAST_CONST(_type, _p) ((const _type *) (_p)) #endif -/* Core API */ -#include -#include -#include -#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include #include #include -#include -#include -#include -#include -#include -#include - -/* Trace IR API */ -#include +#include +#include #include -#include -#include +#include #include -#include #include -#include #include -#include -#include +#include #include -#include #include -#include #include -#include #include -#include #include -#include #include - -/* Component class API */ -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -/* Component API */ -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -/* Message iterator API */ -#include -#include - -/* Message API */ -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -/* Graph API */ -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -/* Query executor API */ -#include -#include -#include - -/* Plugin API */ -#include -#include - -/* Plugin development */ -#include +#include +#include +#include +#include /* Cancel private definitions */ #undef __BT_FUNC_STATUS_AGAIN diff --git a/include/babeltrace2/current-thread.h b/include/babeltrace2/current-thread.h deleted file mode 100644 index 39c6ae22..00000000 --- a/include/babeltrace2/current-thread.h +++ /dev/null @@ -1,102 +0,0 @@ -#ifndef BABELTRACE2_CURRENT_THREAD_H -#define BABELTRACE2_CURRENT_THREAD_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -const bt_error *bt_current_thread_take_error(void); - -extern -void bt_current_thread_clear_error(void); - -extern -void bt_current_thread_move_error(const bt_error *error); - -typedef enum bt_current_thread_error_append_cause_status { - BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_current_thread_error_append_cause_status; - -extern -bt_current_thread_error_append_cause_status -bt_current_thread_error_append_cause_from_unknown( - const char *module_name, const char *file_name, - uint64_t line_no, const char *msg_fmt, ...); - -extern -bt_current_thread_error_append_cause_status -bt_current_thread_error_append_cause_from_component( - bt_self_component *self_comp, const char *file_name, - uint64_t line_no, const char *msg_fmt, ...); - -extern -bt_current_thread_error_append_cause_status -bt_current_thread_error_append_cause_from_component_class( - bt_self_component_class *self_comp_class, const char *file_name, - uint64_t line_no, const char *msg_fmt, ...); - -extern -bt_current_thread_error_append_cause_status -bt_current_thread_error_append_cause_from_message_iterator( - bt_self_message_iterator *self_iter, const char *file_name, - uint64_t line_no, const char *msg_fmt, ...); - -#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_UNKNOWN(_module_name, _msg_fmt, ...) \ - bt_current_thread_error_append_cause_from_unknown( \ - (_module_name), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__) - -#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT(_self_comp, _msg_fmt, ...) \ - bt_current_thread_error_append_cause_from_component( \ - (_self_comp), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__) - -#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_COMPONENT_CLASS(_self_cc, _msg_fmt, ...) \ - bt_current_thread_error_append_cause_from_component_class( \ - (_self_cc), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__) - -#define BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_MESSAGE_ITERATOR(_self_iter, _msg_fmt, ...) \ - bt_current_thread_error_append_cause_from_message_iterator( \ - (_self_iter), __FILE__, __LINE__, (_msg_fmt), ##__VA_ARGS__) - -#define BT_CURRENT_THREAD_MOVE_ERROR_AND_RESET(_var) \ - do { \ - bt_current_thread_move_error(_var); \ - (_var) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_CURRENT_THREAD_H */ diff --git a/include/babeltrace2/error-cause-const.h b/include/babeltrace2/error-cause-const.h deleted file mode 100644 index 004741fc..00000000 --- a/include/babeltrace2/error-cause-const.h +++ /dev/null @@ -1,117 +0,0 @@ -#ifndef BABELTRACE2_ERROR_CAUSE_CONST_H -#define BABELTRACE2_ERROR_CAUSE_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_error_cause_actor_type { - BT_ERROR_CAUSE_ACTOR_TYPE_UNKNOWN = 1 << 0, - BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT = 1 << 1, - BT_ERROR_CAUSE_ACTOR_TYPE_COMPONENT_CLASS = 1 << 2, - BT_ERROR_CAUSE_ACTOR_TYPE_MESSAGE_ITERATOR = 1 << 3, -} bt_error_cause_actor_type; - -extern -bt_error_cause_actor_type bt_error_cause_get_actor_type( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_get_message(const bt_error_cause *cause); - -extern -const char *bt_error_cause_get_module_name(const bt_error_cause *cause); - -extern -const char *bt_error_cause_get_file_name(const bt_error_cause *cause); - -extern -uint64_t bt_error_cause_get_line_number(const bt_error_cause *cause); - -extern -const char *bt_error_cause_component_actor_get_component_name( - const bt_error_cause *cause); - -extern -bt_component_class_type bt_error_cause_component_actor_get_component_class_type( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_component_actor_get_component_class_name( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_component_actor_get_plugin_name( - const bt_error_cause *cause); - -extern -bt_component_class_type -bt_error_cause_component_class_actor_get_component_class_type( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_component_class_actor_get_component_class_name( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_component_class_actor_get_plugin_name( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_message_iterator_actor_get_component_name( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_message_iterator_actor_get_component_output_port_name( - const bt_error_cause *cause); - -extern -bt_component_class_type -bt_error_cause_message_iterator_actor_get_component_class_type( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_message_iterator_actor_get_component_class_name( - const bt_error_cause *cause); - -extern -const char *bt_error_cause_message_iterator_actor_get_plugin_name( - const bt_error_cause *cause); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_ERROR_CAUSE_CONST_H */ diff --git a/include/babeltrace2/error-const.h b/include/babeltrace2/error-const.h deleted file mode 100644 index 8f09b4b7..00000000 --- a/include/babeltrace2/error-const.h +++ /dev/null @@ -1,53 +0,0 @@ -#ifndef BABELTRACE2_ERROR_CONST_H -#define BABELTRACE2_ERROR_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -uint64_t bt_error_get_cause_count(const bt_error *error); - -extern -const bt_error_cause *bt_error_borrow_cause_by_index( - const bt_error *error, uint64_t index); - -extern -void bt_error_release(const bt_error *error); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_ERROR_CONST_H */ diff --git a/include/babeltrace2/error-reporting.h b/include/babeltrace2/error-reporting.h new file mode 100644 index 00000000..8539ddf8 --- /dev/null +++ b/include/babeltrace2/error-reporting.h @@ -0,0 +1,1471 @@ +#ifndef BABELTRACE2_ERROR_REPORTING_H +#define BABELTRACE2_ERROR_REPORTING_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include + +#include +#include + +#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 + +
    +
  1. + An error occurs within the "next" method of the source message + iterator: the function cannot read a file because permission was + denied. +
+ +@image html error-reporting-step-6.png + +
    +
  1. + The source message iterator's "next" method appends the error + cause "Cannot read file /some/file: permission denied" + and returns + #BT_MESSAGE_ITERATOR_CLASS_NEXT_METHOD_STATUS_ERROR. +
+ +@image html error-reporting-step-7.png + +
    +
  1. + bt_message_iterator_next() appends + the error cause "Message iterator's 'next' method failed" + with details about the source component and + returns #BT_MESSAGE_ITERATOR_NEXT_STATUS_ERROR. +
+ +@image html error-reporting-steps-89.png + +
    +
  1. + The sink component's "consume" method appends the error + cause "Cannot consume upstream message iterator's messages" + and returns #BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR. + +
  2. + bt_graph_run() appends the error cause "Component's 'consume' + method failed" with details about the sink component and + returns #BT_GRAPH_RUN_STATUS_ERROR. +
+ +At this point, the current thread's error contains four causes: + +- "Cannot read file /some/file: permission denied" +- "Message iterator's 'next' method failed" +- "Cannot consume upstream message iterator's messages" +- "Component's 'consume' method failed" + +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. + +

\anchor api-error-append-cause Append an error cause

+ +When your function returns an error status code, use one of the +bt_current_thread_error_append_cause_from_*() +functions or BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*() +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: + +
+
Component
+
+ 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(). +
+ +
Message iterator
+
+ 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(). +
+ +
Component class
+
+ 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(). +
+ +
Unknown
+
+ 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(). +
+
+ +The BT_CURRENT_THREAD_ERROR_APPEND_CAUSE_FROM_*() macros +uses \c __FILE__ and \c __LINE__ as the file name and line number +parameters of their corresponding +bt_current_thread_error_append_cause_from_*() function. + +

\anchor api-error-handle Handle an error

+ +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 object-oriented programming + 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 + +

Error cause

+ +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: + +
+
Message
+
+ Description of the error cause. + + Use bt_error_cause_get_message(). +
+ +
Module name
+
+ 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(). +
+ +
File name
+
+ Name of the source file causing the error. + + Use bt_error_cause_get_file_name(). +
+ +
Line number
+
+ Line number of the statement causing the error. + + Use bt_error_cause_get_line_number(). +
+
+ +

Error cause with a component actor

+ +An error cause with a \bt_comp actor has the following specific +properties: + +
+
Component name
+
+ Name of the component. + + Use bt_error_cause_component_actor_get_component_name(). +
+ +
Component class name
+
+ Name of the component's \ref api-comp-cls "class". + + Use bt_error_cause_component_actor_get_component_class_type(). +
+ +
Component class type
+
+ Type of the component's class. + + Use bt_error_cause_component_actor_get_component_class_name(). +
+ +
\bt_dt_opt Plugin name
+
+ Name of the \bt_plugin which provides the component's class, if any. + + Use bt_error_cause_component_actor_get_plugin_name(). +
+
+ +

Error cause with a message iterator actor

+ +An error cause with a \bt_msg_iter actor has the following specific +properties: + +
+
Component output port name
+
+ Name of the \bt_comp \bt_oport from which the message iterator + was created. + + Use bt_error_cause_component_actor_get_component_name(). +
+ +
Component name
+
+ Name of the component. + + Use bt_error_cause_component_actor_get_component_name(). +
+ + bt_error_cause_message_iterator_actor_get_component_output_port_name + +
Component class name
+
+ Name of the component's \ref api-comp-cls "class". + + Use bt_error_cause_component_actor_get_component_class_type(). +
+ +
Component class type
+
+ Type of the component's class. + + Use bt_error_cause_component_actor_get_component_class_name(). +
+ +
\bt_dt_opt Plugin name
+
+ Name of the \bt_plugin which provides the component's class, if any. + + Use bt_error_cause_component_actor_get_plugin_name(). +
+
+ +

Error cause with a component class actor

+ +An error cause with a \bt_comp_cls actor has the following specific +properties: + +
+
Component class name
+
+ Name of the component class. + + Use bt_error_cause_component_class_actor_get_component_class_type(). +
+ +
Component class type
+
+ Type of the component class. + + Use bt_error_cause_component_class_actor_get_component_class_name(). +
+ +
\bt_dt_opt Plugin name
+
+ Name of the \bt_plugin which provides the component class, if any. + + Use bt_error_cause_component_class_actor_get_plugin_name(). +
+
+*/ + +/*! @{ */ + +/*! +@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 object-oriented programming + 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 + If this function does not return NULL, + 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 object-oriented programming +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 + bt_current_thread_error_append_cause_from_*() + 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 printf()-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: + +
+
\c NAME
+
Name of \bt_p{self_component}.
+ +
\c CC-TYPE
+
+ Type of the \ref api-comp-cls "class" of \bt_p{self_component} + (\c src, \c flt, or \c sink). +
+ +
\c PLUGIN-NAME
+
+ Name of the plugin which provides the class of + \bt_p{self_component}. +
+ +
\c CC-NAME
+
Name of the class of \bt_p{self_component}.
+
+ +@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 printf()). + +@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 + On success, 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 printf()-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: + +
+
\c COMP-NAME
+
Name of the \bt_comp of \bt_p{self_message_iterator}.
+ +
\c OUT-PORT-NAME
+
+ Name of the \bt_oport from which \bt_p{self_message_iterator}. + was created. +
+ +
\c CC-TYPE
+
+ Type of the \bt_comp_cls of \bt_p{self_message_iterator} + (\c src, \c flt, or \c sink). +
+ +
\c PLUGIN-NAME
+
+ Name of the plugin which provides the component class of + \bt_p{self_message_iterator}. +
+ +
\c CC-NAME
+
Name of the component class of \bt_p{self_message_iterator}.
+
+ +@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 printf()). + +@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 + On success, 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 printf()-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: + +
+
\c CC-TYPE
+
+ Type of \bt_p{self_component_class} (\c src, \c flt, or \c sink). +
+ +
\c PLUGIN-NAME
+
+ Name of the plugin which provides \bt_p{self_component_class}. +
+ +
\c CC-NAME
+
Name of \bt_p{self_component_class}.
+
+ +@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 printf()). + +@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 + On success, 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 printf()-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 printf()). + +@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 + On success, 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 object-oriented programming +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 */ diff --git a/include/babeltrace2/graph/component-class-const.h b/include/babeltrace2/graph/component-class-const.h deleted file mode 100644 index da46d290..00000000 --- a/include/babeltrace2/graph/component-class-const.h +++ /dev/null @@ -1,101 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_component_class_type { - BT_COMPONENT_CLASS_TYPE_SOURCE = 1 << 0, - BT_COMPONENT_CLASS_TYPE_FILTER = 1 << 1, - BT_COMPONENT_CLASS_TYPE_SINK = 1 << 2, -} bt_component_class_type; - -extern const char *bt_component_class_get_name( - const bt_component_class *component_class); - -extern const char *bt_component_class_get_description( - const bt_component_class *component_class); - -extern const char *bt_component_class_get_help( - const bt_component_class *component_class); - -extern bt_component_class_type bt_component_class_get_type( - const bt_component_class *component_class); - -static inline -bt_bool bt_component_class_is_source( - const bt_component_class *component_class) -{ - return bt_component_class_get_type(component_class) == - BT_COMPONENT_CLASS_TYPE_SOURCE; -} - -static inline -bt_bool bt_component_class_is_filter( - const bt_component_class *component_class) -{ - return bt_component_class_get_type(component_class) == - BT_COMPONENT_CLASS_TYPE_FILTER; -} - -static inline -bt_bool bt_component_class_is_sink( - const bt_component_class *component_class) -{ - return bt_component_class_get_type(component_class) == - BT_COMPONENT_CLASS_TYPE_SINK; -} - -extern void bt_component_class_get_ref( - const bt_component_class *component_class); - -extern void bt_component_class_put_ref( - const bt_component_class *component_class); - -#define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_class_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_CLASS_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_class_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_CONST_H */ diff --git a/include/babeltrace2/graph/component-class-dev.h b/include/babeltrace2/graph/component-class-dev.h new file mode 100644 index 00000000..1fa60162 --- /dev/null +++ b/include/babeltrace2/graph/component-class-dev.h @@ -0,0 +1,2225 @@ +#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H +#define BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*! +@defgroup api-comp-cls-dev Component class development +@ingroup api-graph + +@brief + Component class development (creation). + +A component class 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 methods. 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: + +
+
\anchor api-comp-cls-dev-instance-meth Instance method
+
+ 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 self) or a member function + in C++ (where the instance pointer is named this), + for example. +
+ +
\anchor api-comp-cls-dev-class-meth Class method
+
+ 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. +
+
+ +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(). + +

\anchor api-comp-cls-dev-methods Methods

+ +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: + + + + + + + + + + + +
Name + Method type + Component class types + Requirement + Graph is \ref api-graph-lc "configured"? + C types +
Consume + \ref api-comp-cls-dev-instance-meth "Instance" + Sink + Mandatory + Yes + #bt_component_class_sink_consume_method +
Finalize + Instance + All + Optional + Yes + + #bt_component_class_source_finalize_method
+ #bt_component_class_filter_finalize_method
+ #bt_component_class_sink_finalize_method +
Get supported \bt_mip (MIP) versions + \ref api-comp-cls-dev-class-meth "Class" + All + Optional + N/A + + #bt_component_class_source_get_supported_mip_versions_method
+ #bt_component_class_filter_get_supported_mip_versions_method
+ #bt_component_class_sink_get_supported_mip_versions_method +
Graph is \ref api-graph-lc "configured" + Instance + Sink + Mandatory + Yes + #bt_component_class_sink_graph_is_configured_method +
Initialize + Instance + All + Optional + No + + #bt_component_class_source_initialize_method
+ #bt_component_class_filter_initialize_method
+ #bt_component_class_sink_initialize_method +
\bt_c_iport connected + Instance + Filter and sink + Optional + No + + #bt_component_class_filter_input_port_connected_method
+ #bt_component_class_sink_input_port_connected_method +
\bt_c_oport connected + Instance + Source and filter + Optional + No + + #bt_component_class_source_output_port_connected_method
+ #bt_component_class_filter_output_port_connected_method +
Query + Class + All + Optional + N/A + + #bt_component_class_source_query_method
+ #bt_component_class_filter_query_method
+ #bt_component_class_sink_query_method +
+ +
+
+ \anchor api-comp-cls-dev-meth-consume + Consume +
+
+ 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(). +
+ +
+ \anchor api-comp-cls-dev-meth-fini + Finalize +
+
+ 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(). +
+ +
+ \anchor api-comp-cls-dev-meth-mip + Get supported \bt_mip (MIP) versions +
+
+ 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(). +
+ +
+ \anchor api-comp-cls-dev-meth-graph-configured + Graph is \ref api-graph-lc "configured" +
+
+ 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(). +
+ +
+ \anchor api-comp-cls-dev-meth-init + Initialize +
+
+ Called within a bt_graph_add_*_component*() 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 + bt_graph_add_*_component*() 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(). +
+ +
+ \anchor api-comp-cls-dev-meth-iport-connected + \bt_c_iport connected +
+
+ 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(). +
+ +
+ \anchor api-comp-cls-dev-meth-oport-connected + \bt_c_oport connected +
+
+ 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(). +
+ +
+ \anchor api-comp-cls-dev-meth-query + Query +
+
+ 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(). +
+
+ +@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 + On success, \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 + On success, \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 + On success, \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 + On success, \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 + On success, \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 + On success, \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: + + + + + + +
Property + Value +
\ref api-comp-cls-prop-name "Name" + \bt_p{name} +
\ref api-comp-cls-prop-descr "Description" + \em None +
\ref api-comp-cls-prop-help "Help text" + \em None +
+ +@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: + + + + + + +
Property + Value +
\ref api-comp-cls-prop-name "Name" + \bt_p{name} +
\ref api-comp-cls-prop-descr "Description" + \em None +
\ref api-comp-cls-prop-help "Help text" + \em None +
+ +@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: + + + + + + +
Property + Value +
\ref api-comp-cls-prop-name "Name" + \bt_p{name} +
\ref api-comp-cls-prop-descr "Description" + \em None +
\ref api-comp-cls-prop-help "Help text" + \em None +
+ +@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 + bt_component_class_*_set_*_method() functions. +*/ +typedef enum bt_component_class_set_method_status { + /*! + @brief + Success. + */ + BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, +} bt_component_class_set_method_status; + +/*! +@brief + Sets the optional finalization method of the \bt_src_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-fini "finalize" method. + +@param[in] component_class + Source component class of which to set the finalization method to + \bt_p{method}. +@param[in] method + New finalization method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_source_set_finalize_method( + bt_component_class_source *component_class, + bt_component_class_source_finalize_method method); + +/*! +@brief + Sets the optional finalization method of the \bt_flt_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-fini "finalize" method. + +@param[in] component_class + Filter component class of which to set the finalization method to + \bt_p{method}. +@param[in] method + New finalization method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_filter_set_finalize_method( + bt_component_class_filter *component_class, + bt_component_class_filter_finalize_method method); + +/*! +@brief + Sets the optional finalization method of the \bt_sink_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-fini "finalize" method. + +@param[in] component_class + Sink component class of which to set the finalization method to + \bt_p{method}. +@param[in] method + New finalization method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern +bt_component_class_set_method_status +bt_component_class_sink_set_finalize_method( + bt_component_class_sink *component_class, + bt_component_class_sink_finalize_method method); + +/*! +@brief + Sets the \"get supported \bt_mip versions\" method of the + \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions" +method. + +@param[in] component_class + Source component class of which to set the "get supported MIP + versions" method to \bt_p{method}. +@param[in] method + New "get supported MIP versions" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_source_set_get_supported_mip_versions_method( + bt_component_class_source *component_class, + bt_component_class_source_get_supported_mip_versions_method method); + +/*! +@brief + Sets the \"get supported \bt_mip versions\" method of the + \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions" +method. + +@param[in] component_class + Filter component class of which to set the "get supported MIP + versions" method to \bt_p{method}. +@param[in] method + New "get supported MIP versions" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_filter_set_get_supported_mip_versions_method( + bt_component_class_filter *component_class, + bt_component_class_filter_get_supported_mip_versions_method method); + +/*! +@brief + Sets the \"get supported \bt_mip versions\" method of the + \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-mip "get supported MIP versions" +method. + +@param[in] component_class + Sink component class of which to set the "get supported MIP + versions" method to \bt_p{method}. +@param[in] method + New "get supported MIP versions" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_sink_set_get_supported_mip_versions_method( + bt_component_class_sink *component_class, + bt_component_class_sink_get_supported_mip_versions_method method); + +/*! +@brief + Sets the "graph is configured" method of the + \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the +\ref api-comp-cls-dev-meth-graph-configured "graph is configured" +method. + +@param[in] component_class + Sink component class of which to set the "graph is configured" + method to \bt_p{method}. +@param[in] method + New "graph is configured" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern +bt_component_class_set_method_status +bt_component_class_sink_set_graph_is_configured_method( + bt_component_class_sink *component_class, + bt_component_class_sink_graph_is_configured_method method); + +/*! +@brief + Sets the optional initialization method of the \bt_src_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-init "initialize" method. + +@param[in] component_class + Source component class of which to set the initialization method to + \bt_p{method}. +@param[in] method + New initialization method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_source_set_initialize_method( + bt_component_class_source *component_class, + bt_component_class_source_initialize_method method); + +/*! +@brief + Sets the optional initialization method of the \bt_flt_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-init "initialize" method. + +@param[in] component_class + Filter component class of which to set the initialization method to + \bt_p{method}. +@param[in] method + New initialization method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_filter_set_initialize_method( + bt_component_class_filter *component_class, + bt_component_class_filter_initialize_method method); + +/*! +@brief + Sets the optional initialization method of the \bt_sink_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-init "initialize" method. + +@param[in] component_class + Sink component class of which to set the initialization method to + \bt_p{method}. +@param[in] method + New initialization method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern +bt_component_class_set_method_status +bt_component_class_sink_set_initialize_method( + bt_component_class_sink *component_class, + bt_component_class_sink_initialize_method method); + +/*! +@brief + Sets the optional "output port connected" method of the + \bt_src_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the +\ref api-comp-cls-dev-meth-oport-connected "output port connected" +method. + +@param[in] component_class + Source component class of which to set the "output port connected" + method to \bt_p{method}. +@param[in] method + New "output port connected" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_source_set_output_port_connected_method( + bt_component_class_source *component_class, + bt_component_class_source_output_port_connected_method method); + +/*! +@brief + Sets the optional "input port connected" method of the + \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the +\ref api-comp-cls-dev-meth-iport-connected "input port connected" +method. + +@param[in] component_class + Filter component class of which to set the "input port connected" + method to \bt_p{method}. +@param[in] method + New "input port connected" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_filter_set_input_port_connected_method( + bt_component_class_filter *component_class, + bt_component_class_filter_input_port_connected_method method); + +/*! +@brief + Sets the optional "output port connected" method of the + \bt_flt_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the +\ref api-comp-cls-dev-meth-oport-connected "output port connected" +method. + +@param[in] component_class + Filter component class of which to set the "output port connected" + method to \bt_p{method}. +@param[in] method + New "output port connected" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_filter_set_output_port_connected_method( + bt_component_class_filter *component_class, + bt_component_class_filter_output_port_connected_method method); + +/*! +@brief + Sets the optional "input port connected" method of the + \bt_sink_comp_cls \bt_p{component_class} to \bt_p{method}. + +See the +\ref api-comp-cls-dev-meth-iport-connected "input port connected" +method. + +@param[in] component_class + Sink component class of which to set the "input port connected" + method to \bt_p{method}. +@param[in] method + New "input port connected" method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern +bt_component_class_set_method_status +bt_component_class_sink_set_input_port_connected_method( + bt_component_class_sink *component_class, + bt_component_class_sink_input_port_connected_method method); + +/*! +@brief + Sets the optional query method of the \bt_src_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-query "query" method. + +@param[in] component_class + Source component class of which to set the query method to + \bt_p{method}. +@param[in] method + New query method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_source_set_query_method( + bt_component_class_source *component_class, + bt_component_class_source_query_method method); + +/*! +@brief + Sets the optional query method of the \bt_flt_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-query "query" method. + +@param[in] component_class + Filter component class of which to set the query method to + \bt_p{method}. +@param[in] method + New query method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern bt_component_class_set_method_status +bt_component_class_filter_set_query_method( + bt_component_class_filter *component_class, + bt_component_class_filter_query_method method); + +/*! +@brief + Sets the optional query method of the \bt_sink_comp_cls + \bt_p{component_class} to \bt_p{method}. + +See the \ref api-comp-cls-dev-meth-query "query" method. + +@param[in] component_class + Sink component class of which to set the query method to + \bt_p{method}. +@param[in] method + New query method of \bt_p{component_class}. + +@retval #BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK + Success. + +@bt_pre_not_null{component_class} +@bt_pre_hot{component_class} +@bt_pre_not_null{method} +*/ +extern +bt_component_class_set_method_status +bt_component_class_sink_set_query_method( + bt_component_class_sink *component_class, + bt_component_class_sink_query_method method); + +/*! @} */ + +/*! +@name Upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls + \bt_p{component_class} to the common #bt_component_class type. + +@param[in] component_class + @parblock + Source component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{component_class} as a common component class. +*/ +static inline +bt_component_class *bt_component_class_source_as_component_class( + bt_component_class_source *component_class) +{ + return __BT_UPCAST(bt_component_class, component_class); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls + \bt_p{component_class} to the common #bt_component_class type. + +@param[in] component_class + @parblock + Filter component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{component_class} as a common component class. +*/ +static inline +bt_component_class *bt_component_class_filter_as_component_class( + bt_component_class_filter *component_class) +{ + return __BT_UPCAST(bt_component_class, component_class); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls + \bt_p{component_class} to the common #bt_component_class type. + +@param[in] component_class + @parblock + Sink component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{component_class} as a common component class. +*/ +static inline +bt_component_class *bt_component_class_sink_as_component_class( + bt_component_class_sink *component_class) +{ + return __BT_UPCAST(bt_component_class, component_class); +} + +/*! @} */ + +/*! @} */ + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_DEV_H */ diff --git a/include/babeltrace2/graph/component-class-filter-const.h b/include/babeltrace2/graph/component-class-filter-const.h deleted file mode 100644 index f620e032..00000000 --- a/include/babeltrace2/graph/component-class-filter-const.h +++ /dev/null @@ -1,67 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component_class * -bt_component_class_filter_as_component_class_const( - const bt_component_class_filter *comp_cls_filter) -{ - return __BT_UPCAST_CONST(bt_component_class, comp_cls_filter); -} - -extern void bt_component_class_filter_get_ref( - const bt_component_class_filter *component_class_filter); - -extern void bt_component_class_filter_put_ref( - const bt_component_class_filter *component_class_filter); - -#define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_class_filter_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_class_filter_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_CONST_H */ diff --git a/include/babeltrace2/graph/component-class-filter.h b/include/babeltrace2/graph/component-class-filter.h deleted file mode 100644 index 9aa7a9c5..00000000 --- a/include/babeltrace2/graph/component-class-filter.h +++ /dev/null @@ -1,121 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef bt_component_class_get_supported_mip_versions_method_status -(*bt_component_class_filter_get_supported_mip_versions_method)( - bt_self_component_class_filter *comp_class, - const bt_value *params, void *init_method_data, - bt_logging_level log_level, - bt_integer_range_set_unsigned *supported_versions); - -typedef bt_component_class_initialize_method_status -(*bt_component_class_filter_initialize_method)( - bt_self_component_filter *self_component, - bt_self_component_filter_configuration *config, - const bt_value *params, void *init_method_data); - -typedef void (*bt_component_class_filter_finalize_method)( - bt_self_component_filter *self_component); - -typedef bt_component_class_query_method_status -(*bt_component_class_filter_query_method)( - bt_self_component_class_filter *comp_class, - bt_private_query_executor *query_executor, - const char *object, const bt_value *params, - void *method_data, const bt_value **result); - -typedef bt_component_class_port_connected_method_status -(*bt_component_class_filter_input_port_connected_method)( - bt_self_component_filter *self_component, - bt_self_component_port_input *self_port, - const bt_port_output *other_port); - -typedef bt_component_class_port_connected_method_status -(*bt_component_class_filter_output_port_connected_method)( - bt_self_component_filter *self_component, - bt_self_component_port_output *self_port, - const bt_port_input *other_port); - -static inline -bt_component_class *bt_component_class_filter_as_component_class( - bt_component_class_filter *comp_cls_filter) -{ - return __BT_UPCAST(bt_component_class, comp_cls_filter); -} - -extern -bt_component_class_filter *bt_component_class_filter_create( - const char *name, - bt_message_iterator_class *message_iterator_class); - -extern bt_component_class_set_method_status -bt_component_class_filter_set_get_supported_mip_versions_method( - bt_component_class_filter *comp_class, - bt_component_class_filter_get_supported_mip_versions_method method); - -extern bt_component_class_set_method_status -bt_component_class_filter_set_initialize_method( - bt_component_class_filter *comp_class, - bt_component_class_filter_initialize_method method); - -extern bt_component_class_set_method_status -bt_component_class_filter_set_finalize_method( - bt_component_class_filter *comp_class, - bt_component_class_filter_finalize_method method); - -extern bt_component_class_set_method_status -bt_component_class_filter_set_input_port_connected_method( - bt_component_class_filter *comp_class, - bt_component_class_filter_input_port_connected_method method); - -extern bt_component_class_set_method_status -bt_component_class_filter_set_output_port_connected_method( - bt_component_class_filter *comp_class, - bt_component_class_filter_output_port_connected_method method); - -extern bt_component_class_set_method_status -bt_component_class_filter_set_query_method( - bt_component_class_filter *comp_class, - bt_component_class_filter_query_method method); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_FILTER_H */ diff --git a/include/babeltrace2/graph/component-class-sink-const.h b/include/babeltrace2/graph/component-class-sink-const.h deleted file mode 100644 index c4879d07..00000000 --- a/include/babeltrace2/graph/component-class-sink-const.h +++ /dev/null @@ -1,67 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component_class * -bt_component_class_sink_as_component_class_const( - const bt_component_class_sink *comp_cls_sink) -{ - return __BT_UPCAST_CONST(bt_component_class, comp_cls_sink); -} - -extern void bt_component_class_sink_get_ref( - const bt_component_class_sink *component_class_sink); - -extern void bt_component_class_sink_put_ref( - const bt_component_class_sink *component_class_sink); - -#define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_class_sink_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_CLASS_SINK_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_class_sink_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_CONST_H */ diff --git a/include/babeltrace2/graph/component-class-sink.h b/include/babeltrace2/graph/component-class-sink.h deleted file mode 100644 index aa56d266..00000000 --- a/include/babeltrace2/graph/component-class-sink.h +++ /dev/null @@ -1,142 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef bt_component_class_get_supported_mip_versions_method_status -(*bt_component_class_sink_get_supported_mip_versions_method)( - bt_self_component_class_sink *comp_class, - const bt_value *params, void *init_method_data, - bt_logging_level log_level, - bt_integer_range_set_unsigned *supported_versions); - -typedef bt_component_class_initialize_method_status -(*bt_component_class_sink_initialize_method)( - bt_self_component_sink *self_component, - bt_self_component_sink_configuration *config, - const bt_value *params, void *init_method_data); - -typedef void (*bt_component_class_sink_finalize_method)( - bt_self_component_sink *self_component); - -typedef bt_component_class_query_method_status -(*bt_component_class_sink_query_method)( - bt_self_component_class_sink *comp_class, - bt_private_query_executor *query_executor, - const char *object, const bt_value *params, - void *method_data, const bt_value **result); - -typedef bt_component_class_port_connected_method_status -(*bt_component_class_sink_input_port_connected_method)( - bt_self_component_sink *self_component, - bt_self_component_port_input *self_port, - const bt_port_output *other_port); - -typedef enum bt_component_class_sink_graph_is_configured_method_status { - BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_SINK_GRAPH_IS_CONFIGURED_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_sink_graph_is_configured_method_status; - -typedef bt_component_class_sink_graph_is_configured_method_status -(*bt_component_class_sink_graph_is_configured_method)( - bt_self_component_sink *self_component); - -typedef enum bt_component_class_sink_consume_method_status { - BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, - BT_COMPONENT_CLASS_SINK_CONSUME_METHOD_STATUS_END = __BT_FUNC_STATUS_END, -} bt_component_class_sink_consume_method_status; - -typedef bt_component_class_sink_consume_method_status -(*bt_component_class_sink_consume_method)( - bt_self_component_sink *self_component); - -static inline -bt_component_class *bt_component_class_sink_as_component_class( - bt_component_class_sink *comp_cls_sink) -{ - return __BT_UPCAST(bt_component_class, comp_cls_sink); -} - -extern bt_component_class_set_method_status -bt_component_class_sink_set_get_supported_mip_versions_method( - bt_component_class_sink *comp_class, - bt_component_class_sink_get_supported_mip_versions_method method); - -extern -bt_component_class_sink *bt_component_class_sink_create( - const char *name, - bt_component_class_sink_consume_method method); - -extern -bt_component_class_set_method_status -bt_component_class_sink_set_initialize_method( - bt_component_class_sink *comp_class, - bt_component_class_sink_initialize_method method); - -extern -bt_component_class_set_method_status -bt_component_class_sink_set_finalize_method( - bt_component_class_sink *comp_class, - bt_component_class_sink_finalize_method method); - -extern -bt_component_class_set_method_status -bt_component_class_sink_set_input_port_connected_method( - bt_component_class_sink *comp_class, - bt_component_class_sink_input_port_connected_method method); - -extern -bt_component_class_set_method_status -bt_component_class_sink_set_graph_is_configured_method( - bt_component_class_sink *comp_class, - bt_component_class_sink_graph_is_configured_method method); - -extern -bt_component_class_set_method_status -bt_component_class_sink_set_query_method( - bt_component_class_sink *comp_class, - bt_component_class_sink_query_method method); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SINK_H */ diff --git a/include/babeltrace2/graph/component-class-source-const.h b/include/babeltrace2/graph/component-class-source-const.h deleted file mode 100644 index 163eb31c..00000000 --- a/include/babeltrace2/graph/component-class-source-const.h +++ /dev/null @@ -1,67 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component_class * -bt_component_class_source_as_component_class_const( - const bt_component_class_source *comp_cls_source) -{ - return __BT_UPCAST_CONST(bt_component_class, comp_cls_source); -} - -extern void bt_component_class_source_get_ref( - const bt_component_class_source *component_class_source); - -extern void bt_component_class_source_put_ref( - const bt_component_class_source *component_class_source); - -#define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_class_source_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_class_source_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_CONST_H */ diff --git a/include/babeltrace2/graph/component-class-source.h b/include/babeltrace2/graph/component-class-source.h deleted file mode 100644 index 10942f88..00000000 --- a/include/babeltrace2/graph/component-class-source.h +++ /dev/null @@ -1,110 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_H -#define BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef bt_component_class_get_supported_mip_versions_method_status -(*bt_component_class_source_get_supported_mip_versions_method)( - bt_self_component_class_source *comp_class, - const bt_value *params, void *init_method_data, - bt_logging_level log_level, - bt_integer_range_set_unsigned *supported_versions); - -typedef bt_component_class_initialize_method_status -(*bt_component_class_source_initialize_method)( - bt_self_component_source *self_component, - bt_self_component_source_configuration *config, - const bt_value *params, void *init_method_data); - -typedef void (*bt_component_class_source_finalize_method)( - bt_self_component_source *self_component); - -typedef bt_component_class_query_method_status -(*bt_component_class_source_query_method)( - bt_self_component_class_source *comp_class, - bt_private_query_executor *query_executor, - const char *object, const bt_value *params, - void *method_data, const bt_value **result); - -typedef bt_component_class_port_connected_method_status -(*bt_component_class_source_output_port_connected_method)( - bt_self_component_source *self_component, - bt_self_component_port_output *self_port, - const bt_port_input *other_port); - -static inline -bt_component_class *bt_component_class_source_as_component_class( - bt_component_class_source *comp_cls_source) -{ - return __BT_UPCAST(bt_component_class, comp_cls_source); -} - -extern -bt_component_class_source *bt_component_class_source_create( - const char *name, - bt_message_iterator_class *message_iterator_class); - -extern bt_component_class_set_method_status -bt_component_class_source_set_get_supported_mip_versions_method( - bt_component_class_source *comp_class, - bt_component_class_source_get_supported_mip_versions_method method); - -extern bt_component_class_set_method_status -bt_component_class_source_set_initialize_method( - bt_component_class_source *comp_class, - bt_component_class_source_initialize_method method); - -extern bt_component_class_set_method_status -bt_component_class_source_set_finalize_method( - bt_component_class_source *comp_class, - bt_component_class_source_finalize_method method); - -extern bt_component_class_set_method_status -bt_component_class_source_set_output_port_connected_method( - bt_component_class_source *comp_class, - bt_component_class_source_output_port_connected_method method); - -extern bt_component_class_set_method_status -bt_component_class_source_set_query_method( - bt_component_class_source *comp_class, - bt_component_class_source_query_method method); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_SOURCE_H */ diff --git a/include/babeltrace2/graph/component-class.h b/include/babeltrace2/graph/component-class.h index b8495d45..98f66fbb 100644 --- a/include/babeltrace2/graph/component-class.h +++ b/include/babeltrace2/graph/component-class.h @@ -33,53 +33,855 @@ extern "C" { #endif -typedef enum bt_component_class_get_supported_mip_versions_method_status { - BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_get_supported_mip_versions_method_status; - -typedef enum bt_component_class_initialize_method_status { - BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_INITIALIZE_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_initialize_method_status; - -typedef enum bt_component_class_port_connected_method_status { - BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_PORT_CONNECTED_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_port_connected_method_status; - -typedef enum bt_component_class_query_method_status { - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_COMPONENT_CLASS_QUERY_METHOD_STATUS_UNKNOWN_OBJECT = __BT_FUNC_STATUS_UNKNOWN_OBJECT, -} bt_component_class_query_method_status; - -typedef enum bt_component_class_set_method_status { - BT_COMPONENT_CLASS_SET_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_component_class_set_method_status; - -typedef enum bt_component_class_set_description_status { - BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_SET_DESCRIPTION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_set_description_status; - -extern bt_component_class_set_description_status -bt_component_class_set_description(bt_component_class *component_class, - const char *description); - -typedef enum bt_component_class_set_help_status { - BT_COMPONENT_CLASS_SET_HELP_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_COMPONENT_CLASS_SET_HELP_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_component_class_set_help_status; - -extern bt_component_class_set_help_status bt_component_class_set_help( - bt_component_class *component_class, - const char *help); +/*! +@defgroup api-comp-cls Component classes +@ingroup api-graph + +@brief + Source, filter, and sink component classes (non-development). + +A component class 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 +bt_graph_add_*_component*() 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: + +
+
\anchor api-comp-cls-src Source component class
+
+ 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(). +
+ +
\anchor api-comp-cls-flt Filter component class
+
+ 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(). +
+ +
\anchor api-comp-cls-sink Sink component class
+
+ 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(). +
+
+ +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. + +

Properties

+ +A component class has the following common properties: + +
+
+ \anchor api-comp-cls-prop-name + Name +
+
+ 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(). +
+ +
+ \anchor api-comp-cls-prop-descr + \bt_dt_opt Description +
+
+ Textual description of the component class. + + Get a component class's description with + bt_component_class_get_description(). +
+ +
+ \anchor api-comp-cls-prop-help + \bt_dt_opt Help text +
+
+ Help text of the component class. + + Get a component class's help text with + bt_component_class_get_help(). +
+
+*/ + +/*! @{ */ + +/*! +@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 } diff --git a/include/babeltrace2/graph/component-const.h b/include/babeltrace2/graph/component-const.h deleted file mode 100644 index 11554b5e..00000000 --- a/include/babeltrace2/graph/component-const.h +++ /dev/null @@ -1,103 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Get component's name. - * - * @param component Component instance of which to get the name - * @returns Returns a pointer to the component's name - */ -extern const char *bt_component_get_name(const bt_component *component); - -extern bt_logging_level bt_component_get_logging_level( - const bt_component *component); - -/** - * Get component's class. - * - * @param component Component instance of which to get the class - * @returns The component's class - */ -extern const bt_component_class *bt_component_borrow_class_const( - const bt_component *component); - -extern bt_component_class_type bt_component_get_class_type( - const bt_component *component); - -static inline -bt_bool bt_component_is_source(const bt_component *component) -{ - return bt_component_get_class_type(component) == - BT_COMPONENT_CLASS_TYPE_SOURCE; -} - -static inline -bt_bool bt_component_is_filter(const bt_component *component) -{ - return bt_component_get_class_type(component) == - BT_COMPONENT_CLASS_TYPE_FILTER; -} - -static inline -bt_bool bt_component_is_sink(const bt_component *component) -{ - return bt_component_get_class_type(component) == - BT_COMPONENT_CLASS_TYPE_SINK; -} - -extern void bt_component_get_ref(const bt_component *component); - -extern void bt_component_put_ref(const bt_component *component); - -#define BT_COMPONENT_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_CONST_H */ diff --git a/include/babeltrace2/graph/component-descriptor-set-const.h b/include/babeltrace2/graph/component-descriptor-set-const.h deleted file mode 100644 index 4fdf49a1..00000000 --- a/include/babeltrace2/graph/component-descriptor-set-const.h +++ /dev/null @@ -1,59 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern void bt_component_descriptor_set_get_ref( - const bt_component_descriptor_set *comp_descriptor_set); - -extern void bt_component_descriptor_set_put_ref( - const bt_component_descriptor_set *comp_descriptor_set); - -#define BT_COMPONENT_DESCRIPTOR_SET_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_descriptor_set_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_DESCRIPTOR_SET_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_descriptor_set_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_DESCRIPTOR_SET_CONST_H */ diff --git a/include/babeltrace2/graph/component-descriptor-set.h b/include/babeltrace2/graph/component-descriptor-set.h index e551a70b..b9057209 100644 --- a/include/babeltrace2/graph/component-descriptor-set.h +++ b/include/babeltrace2/graph/component-descriptor-set.h @@ -34,24 +34,269 @@ extern "C" { #endif +/*! +@defgroup api-comp-descr-set Component descriptor set +@ingroup api-graph + +@brief + Set of descriptors of prospective \bt_p_comp to use with + bt_get_greatest_operative_mip_version(). + +A component descriptor set +is an \em unordered set of component descriptors. + +A component descriptor 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 component class to instantiate, which you would + pass as the \bt_p{component_class} parameter of one of the + bt_graph_add_*_component*() functions. + +- The initialization parameters, which you + would pass as the \bt_p{params} parameter of one of the + bt_graph_add_*_component*() functions. + +- The initialization method data, which you would pass + as the \bt_p{initialize_method_data} parameter of one of the + bt_graph_add_*_component_with_initialize_method_data() + 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 } diff --git a/include/babeltrace2/graph/component-filter-const.h b/include/babeltrace2/graph/component-filter-const.h deleted file mode 100644 index 55ddbd75..00000000 --- a/include/babeltrace2/graph/component-filter-const.h +++ /dev/null @@ -1,94 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_FILTER_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_FILTER_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component *bt_component_filter_as_component_const( - const bt_component_filter *component) -{ - return __BT_UPCAST_CONST(bt_component, component); -} - -extern const bt_component_class_filter * -bt_component_filter_borrow_class_const( - const bt_component_filter *component); - -extern uint64_t bt_component_filter_get_input_port_count( - const bt_component_filter *component); - -extern const bt_port_input * -bt_component_filter_borrow_input_port_by_name_const( - const bt_component_filter *component, const char *name); - -extern const bt_port_input * -bt_component_filter_borrow_input_port_by_index_const( - const bt_component_filter *component, uint64_t index); - -extern uint64_t bt_component_filter_get_output_port_count( - const bt_component_filter *component); - -extern const bt_port_output * -bt_component_filter_borrow_output_port_by_name_const( - const bt_component_filter *component, const char *name); - -extern const bt_port_output * -bt_component_filter_borrow_output_port_by_index_const( - const bt_component_filter *component, uint64_t index); - -extern void bt_component_filter_get_ref( - const bt_component_filter *component_filter); - -extern void bt_component_filter_put_ref( - const bt_component_filter *component_filter); - -#define BT_COMPONENT_FILTER_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_filter_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_FILTER_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_filter_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_FILTER_CONST_H */ diff --git a/include/babeltrace2/graph/component-sink-const.h b/include/babeltrace2/graph/component-sink-const.h deleted file mode 100644 index 64e8b050..00000000 --- a/include/babeltrace2/graph/component-sink-const.h +++ /dev/null @@ -1,83 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_SINK_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_SINK_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component *bt_component_sink_as_component_const( - const bt_component_sink *component) -{ - return __BT_UPCAST_CONST(bt_component, component); -} - -extern const bt_component_class_sink * -bt_component_sink_borrow_class_const( - const bt_component_sink *component); - -extern uint64_t bt_component_sink_get_input_port_count( - const bt_component_sink *component); - -extern const bt_port_input * -bt_component_sink_borrow_input_port_by_name_const( - const bt_component_sink *component, const char *name); - -extern const bt_port_input * -bt_component_sink_borrow_input_port_by_index_const( - const bt_component_sink *component, uint64_t index); - -extern void bt_component_sink_get_ref( - const bt_component_sink *component_sink); - -extern void bt_component_sink_put_ref( - const bt_component_sink *component_sink); - -#define BT_COMPONENT_SINK_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_sink_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_SINK_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_sink_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_SINK_CONST_H */ diff --git a/include/babeltrace2/graph/component-source-const.h b/include/babeltrace2/graph/component-source-const.h deleted file mode 100644 index 85f89236..00000000 --- a/include/babeltrace2/graph/component-source-const.h +++ /dev/null @@ -1,83 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_COMPONENT_SOURCE_CONST_H -#define BABELTRACE2_GRAPH_COMPONENT_SOURCE_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component *bt_component_source_as_component_const( - const bt_component_source *component) -{ - return __BT_UPCAST_CONST(bt_component, component); -} - -extern const bt_component_class_source * -bt_component_source_borrow_class_const( - const bt_component_source *component); - -extern uint64_t bt_component_source_get_output_port_count( - const bt_component_source *component); - -extern const bt_port_output * -bt_component_source_borrow_output_port_by_name_const( - const bt_component_source *component, const char *name); - -extern const bt_port_output * -bt_component_source_borrow_output_port_by_index_const( - const bt_component_source *component, uint64_t index); - -extern void bt_component_source_get_ref( - const bt_component_source *component_source); - -extern void bt_component_source_put_ref( - const bt_component_source *component_source); - -#define BT_COMPONENT_SOURCE_PUT_REF_AND_RESET(_var) \ - do { \ - bt_component_source_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_COMPONENT_SOURCE_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_component_source_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_COMPONENT_SOURCE_CONST_H */ diff --git a/include/babeltrace2/graph/component.h b/include/babeltrace2/graph/component.h new file mode 100644 index 00000000..82aee896 --- /dev/null +++ b/include/babeltrace2/graph/component.h @@ -0,0 +1,1280 @@ +#ifndef BABELTRACE2_GRAPH_COMPONENT_H +#define BABELTRACE2_GRAPH_COMPONENT_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include +#include +#include + +#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 component 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: + +
+
\anchor api-comp-src Source component
+
+ 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(). +
+ +
\anchor api-comp-flt Filter component
+
+ 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(). +
+ +
\anchor api-comp-sink Sink component
+
+ 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(). +
+
+ +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 +bt_component_*_create() functions. A trace processing +\bt_graph creates a component from a \bt_comp_cls when you call one of +the bt_graph_add_*_component*() functions. Those functions +also return a borrowed reference of the created component through their +\bt_p{component} parameter. + +

Properties

+ +A component has the following common properties: + +
+
+ \anchor api-comp-prop-name + Name +
+
+ 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 + bt_graph_add_*_component*() functions (\bt_p{name} + parameter); you cannot change it afterwards. + + Get a component's name with bt_component_get_name(). +
+ +
+ \anchor api-comp-prop-log-lvl + Logging level +
+
+ 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 bt_graph_add_*_component*() 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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 */ diff --git a/include/babeltrace2/graph/connection-const.h b/include/babeltrace2/graph/connection-const.h deleted file mode 100644 index 9282c17d..00000000 --- a/include/babeltrace2/graph/connection-const.h +++ /dev/null @@ -1,63 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_CONNECTION_CONST_H -#define BABELTRACE2_GRAPH_CONNECTION_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_port_input *bt_connection_borrow_downstream_port_const( - const bt_connection *connection); - -extern const bt_port_output *bt_connection_borrow_upstream_port_const( - const bt_connection *connection); - -extern void bt_connection_get_ref(const bt_connection *connection); - -extern void bt_connection_put_ref(const bt_connection *connection); - -#define BT_CONNECTION_PUT_REF_AND_RESET(_var) \ - do { \ - bt_connection_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_CONNECTION_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_connection_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_CONNECTION_CONST_H */ diff --git a/include/babeltrace2/graph/connection.h b/include/babeltrace2/graph/connection.h new file mode 100644 index 00000000..68b56344 --- /dev/null +++ b/include/babeltrace2/graph/connection.h @@ -0,0 +1,210 @@ +#ifndef BABELTRACE2_GRAPH_CONNECTION_H +#define BABELTRACE2_GRAPH_CONNECTION_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*! +@defgroup api-conn Connection +@ingroup api-graph + +@brief + \bt_c_comp \bt_port connection. + +A connection 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 */ diff --git a/include/babeltrace2/graph/graph-const.h b/include/babeltrace2/graph/graph-const.h deleted file mode 100644 index 168ed2b2..00000000 --- a/include/babeltrace2/graph/graph-const.h +++ /dev/null @@ -1,57 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_GRAPH_CONST_H -#define BABELTRACE2_GRAPH_GRAPH_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern void bt_graph_get_ref(const bt_graph *graph); - -extern void bt_graph_put_ref(const bt_graph *graph); - -#define BT_GRAPH_PUT_REF_AND_RESET(_var) \ - do { \ - bt_graph_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_GRAPH_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_graph_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_GRAPH_CONST_H */ diff --git a/include/babeltrace2/graph/graph.h b/include/babeltrace2/graph/graph.h index d562e366..6c7b2d1b 100644 --- a/include/babeltrace2/graph/graph.h +++ b/include/babeltrace2/graph/graph.h @@ -34,213 +34,1981 @@ extern "C" { #endif -typedef enum bt_graph_listener_func_status { - BT_GRAPH_LISTENER_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_GRAPH_LISTENER_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_GRAPH_LISTENER_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_graph_listener_func_status; +/*! +@defgroup api-graph Graph -typedef bt_graph_listener_func_status -(*bt_graph_filter_component_input_port_added_listener_func)( - const bt_component_filter *component, - const bt_port_input *port, void *data); +@brief + Trace processing graph. -typedef bt_graph_listener_func_status -(*bt_graph_sink_component_input_port_added_listener_func)( - const bt_component_sink *component, - const bt_port_input *port, void *data); +A trace processing graph is a specialized +filter graph +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": source.ctf.fs. + +- All components are instances of \bt_plugin-provided classes: + babeltrace2-plugin-ctf.so, + user-plugin.so, + babeltrace2-plugin-utils.so, and + babeltrace2-plugin-text.so. + +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(). + +

\anchor api-graph-lc Trace processing graph life cycle

+ +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 +configured, 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 ERROR) during step 1 or 2, the trace processing +graph is considered faulty: 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(). + +

\anchor api-graph-lc-add Add components

+ +Adding a \bt_comp to a trace processing graph is also known as +instantiating a \bt_comp_cls 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: + +
+
Source component
+
+
+
Without initialization method data
+
bt_graph_add_source_component()
+ +
With initialization method data
+
bt_graph_add_source_component_with_initialize_method_data()
+
+
+ +
Filter component
+
+
+
Without initialization method data
+
bt_graph_add_filter_component()
+ +
With initialization method data
+
bt_graph_add_filter_component_with_initialize_method_data()
+
+
+ +
Sink component
+
+
+
Without initialization method data
+
bt_graph_add_sink_component()
+ +
With initialization method data
+
bt_graph_add_sink_component_with_initialize_method_data()
+
+
+
+ +The *_with_initialize_method_data() 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 + On success, \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. + +

\anchor api-graph-lc-add-ss Add a simple sink component

+ +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: + +
+
\bt_dt_opt Initialization
+
+ 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. +
+ +
Consume
+
+ 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. +
+ +
\bt_dt_opt Finalization
+
+ Called when the sink component is finalized. +
+
+ +The three functions above receive, as their last parameter, the user +data you passed to bt_graph_add_simple_sink_component() . + +

\anchor api-graph-lc-connect Connect component ports

+ +When you \ref api-graph-lc-add "add a component" to a trace processing +graph with one of the bt_graph_add_*_component*() +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. + +

\anchor api-graph-lc-run Run

+ +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(). + +

Standard \bt_name component classes

-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: + +
+
\c ctf plugin
+
+
+
\c fs source component class
+
+ Opens a + CTF trace on the file + system and emits the \bt_p_msg of their data stream files. + + See \bt_man{babeltrace2-source.ctf.fs,7}. +
+ +
\c lttng-live source component class
+
+ Connects to an LTTng relay + daemon and emits the messages of the received CTF data streams. + + See \bt_man{babeltrace2-source.ctf.lttng-live,7}. +
+ +
\c fs sink component class
+
+ Writes the consumed messages as one or more CTF traces on the + file system. + + See \bt_man{babeltrace2-sink.ctf.fs,7}. +
+
+
+ +
\c lttng-utils plugin
+
+
+
\c debug-info filter component class
+
+ Adds debugging information to compatible LTTng event messages. + + This component class is only available if the project was + built with the \-\-enable-debug-info + configuration option. + + See \bt_man{babeltrace2-filter.lttng-utils.debug-info,7}. +
+
+
+ +
\c text plugin
+
+
+
\c dmesg source component class
+
+ Reads the lines of a Linux kernel ring buffer, that is, the + output of the + dmesg + tool, and emits each line as an \bt_ev_msg. + + See \bt_man{babeltrace2-source.text.dmesg,7}. +
+ +
\c details sink component class
+
+ Deterministically prints the messages it consumes with details + to the standard output. + + See \bt_man{babeltrace2-sink.text.details,7}. +
+ +
\c pretty sink component class
+
+ 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 + Babeltrace 1 + command-line tool. + + See \bt_man{babeltrace2-sink.text.pretty,7}. +
+
+
+ +
\c utils plugin
+
+
+
\c muxer filter component class
+
+ Muxes messages by time. + + See \bt_man{babeltrace2-filter.utils.muxer,7}. +
+ +
\c trimmer filter component class
+
+ 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}. +
+ +
\c counter sink component class
+
+ 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}. +
+ +
\c dummy sink component class
+
+ 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}. +
+
+
+
+ +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 + +

\anchor api-graph-listeners Listeners

+ +A \bt_comp can add a \bt_port: + +- At initialization time, that is, when you call one of the + bt_graph_add_*_component*() 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 +bt_graph_add_*_component*() 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 + bt_graph_add_*_component*() 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 + On success, if not \c NULL, \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 + On success, if not \c NULL, \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 + On success, if not \c NULL, \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 + On success, if not \c NULL, \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 + On success, if not \c NULL, \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 configured. 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: + +
+
Succeeds
+
This function returns #BT_GRAPH_RUN_ONCE_STATUS_OK.
+ +
Returns "try again"
+
This function returns #BT_GRAPH_RUN_ONCE_STATUS_AGAIN.
+ +
Fails
+
+ This function returns #BT_GRAPH_RUN_ONCE_STATUS_MEMORY_ERROR + or #BT_GRAPH_RUN_ONCE_STATUS_ERROR. +
+
+ +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 configured. 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 default interrupter. + + 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 + bt_graph_add_*_component_*_port_added_listener() + 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 + bt_graph_*_component_*_port_added_listener_func() + 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 + On success and if not \c NULL, \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 + On success and if not \c NULL, \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 + On success and if not \c NULL, \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 + On success and if not \c NULL, \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 } diff --git a/include/babeltrace2/graph/interrupter-const.h b/include/babeltrace2/graph/interrupter-const.h deleted file mode 100644 index 8a85dcca..00000000 --- a/include/babeltrace2/graph/interrupter-const.h +++ /dev/null @@ -1,59 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_INTERRUPTER_CONST_H -#define BABELTRACE2_GRAPH_INTERRUPTER_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern bt_bool bt_interrupter_is_set(const bt_interrupter *interrupter); - -extern void bt_interrupter_get_ref(const bt_interrupter *interrupter); - -extern void bt_interrupter_put_ref(const bt_interrupter *interrupter); - -#define BT_INTERRUPTER_PUT_REF_AND_RESET(_var) \ - do { \ - bt_interrupter_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_INTERRUPTER_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_interrupter_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_INTERRUPTER_CONST_H */ diff --git a/include/babeltrace2/graph/interrupter.h b/include/babeltrace2/graph/interrupter.h index 95377532..56c022e2 100644 --- a/include/babeltrace2/graph/interrupter.h +++ b/include/babeltrace2/graph/interrupter.h @@ -33,12 +33,258 @@ extern "C" { #endif +/*! +@defgroup api-intr Interrupter +@ingroup api-graph + +@brief + Interrupter. + +An interrupter 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 diff --git a/include/babeltrace2/graph/message-const.h b/include/babeltrace2/graph/message-const.h deleted file mode 100644 index 0612b3c8..00000000 --- a/include/babeltrace2/graph/message-const.h +++ /dev/null @@ -1,79 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Message types. Unhandled message types should be ignored. - */ -typedef enum bt_message_type { - BT_MESSAGE_TYPE_EVENT = 1 << 0, - BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY = 1 << 1, - BT_MESSAGE_TYPE_STREAM_BEGINNING = 1 << 2, - BT_MESSAGE_TYPE_STREAM_END = 1 << 3, - BT_MESSAGE_TYPE_PACKET_BEGINNING = 1 << 4, - BT_MESSAGE_TYPE_PACKET_END = 1 << 5, - BT_MESSAGE_TYPE_DISCARDED_EVENTS = 1 << 6, - BT_MESSAGE_TYPE_DISCARDED_PACKETS = 1 << 7, -} bt_message_type; - -/** - * Get a message's type. - * - * @param message Message instance - * @returns One of #bt_message_type - */ -extern bt_message_type bt_message_get_type(const bt_message *message); - -extern void bt_message_get_ref(const bt_message *message); - -extern void bt_message_put_ref(const bt_message *message); - -#define BT_MESSAGE_PUT_REF_AND_RESET(_var) \ - do { \ - bt_message_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_MESSAGE_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_message_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_CONST_H */ diff --git a/include/babeltrace2/graph/message-discarded-events-const.h b/include/babeltrace2/graph/message-discarded-events-const.h deleted file mode 100644 index 87508e2c..00000000 --- a/include/babeltrace2/graph/message-discarded-events-const.h +++ /dev/null @@ -1,58 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_clock_snapshot * -bt_message_discarded_events_borrow_beginning_default_clock_snapshot_const( - const bt_message *msg); - -extern const bt_clock_snapshot * -bt_message_discarded_events_borrow_end_default_clock_snapshot_const( - const bt_message *msg); - -extern const bt_clock_class * -bt_message_discarded_events_borrow_stream_class_default_clock_class_const( - const bt_message *msg); - -extern const bt_stream * -bt_message_discarded_events_borrow_stream_const(const bt_message *message); - -extern bt_property_availability bt_message_discarded_events_get_count( - const bt_message *message, uint64_t *count); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_CONST_H */ diff --git a/include/babeltrace2/graph/message-discarded-events.h b/include/babeltrace2/graph/message-discarded-events.h deleted file mode 100644 index 0b102fa3..00000000 --- a/include/babeltrace2/graph/message-discarded-events.h +++ /dev/null @@ -1,57 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_H -#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern bt_message *bt_message_discarded_events_create( - bt_self_message_iterator *message_iterator, - const bt_stream *stream); - -extern bt_message *bt_message_discarded_events_create_with_default_clock_snapshots( - bt_self_message_iterator *message_iterator, - const bt_stream *stream, uint64_t beginning_raw_value, - uint64_t end_raw_value); - -extern bt_stream *bt_message_discarded_events_borrow_stream( - bt_message *message); - -extern void bt_message_discarded_events_set_count(bt_message *message, - uint64_t count); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_EVENTS_H */ diff --git a/include/babeltrace2/graph/message-discarded-packets-const.h b/include/babeltrace2/graph/message-discarded-packets-const.h deleted file mode 100644 index a528b760..00000000 --- a/include/babeltrace2/graph/message-discarded-packets-const.h +++ /dev/null @@ -1,58 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_clock_snapshot * -bt_message_discarded_packets_borrow_beginning_default_clock_snapshot_const( - const bt_message *msg); - -extern const bt_clock_snapshot * -bt_message_discarded_packets_borrow_end_default_clock_snapshot_const( - const bt_message *msg); - -extern const bt_clock_class * -bt_message_discarded_packets_borrow_stream_class_default_clock_class_const( - const bt_message *msg); - -extern const bt_stream * -bt_message_discarded_packets_borrow_stream_const(const bt_message *message); - -extern bt_property_availability bt_message_discarded_packets_get_count( - const bt_message *message, uint64_t *count); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_CONST_H */ diff --git a/include/babeltrace2/graph/message-discarded-packets.h b/include/babeltrace2/graph/message-discarded-packets.h deleted file mode 100644 index c268d54d..00000000 --- a/include/babeltrace2/graph/message-discarded-packets.h +++ /dev/null @@ -1,57 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_H -#define BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern bt_message *bt_message_discarded_packets_create( - bt_self_message_iterator *message_iterator, - const bt_stream *stream); - -extern bt_message *bt_message_discarded_packets_create_with_default_clock_snapshots( - bt_self_message_iterator *message_iterator, - const bt_stream *stream, uint64_t beginning_raw_value, - uint64_t end_raw_value); - -extern bt_stream *bt_message_discarded_packets_borrow_stream( - bt_message *message); - -extern void bt_message_discarded_packets_set_count(bt_message *message, - uint64_t count); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_DISCARDED_PACKETS_H */ diff --git a/include/babeltrace2/graph/message-event-const.h b/include/babeltrace2/graph/message-event-const.h deleted file mode 100644 index 3cb886c7..00000000 --- a/include/babeltrace2/graph/message-event-const.h +++ /dev/null @@ -1,50 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_EVENT_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_EVENT_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_event *bt_message_event_borrow_event_const( - const bt_message *message); - -extern const bt_clock_snapshot * -bt_message_event_borrow_default_clock_snapshot_const(const bt_message *msg); - -extern const bt_clock_class * -bt_message_event_borrow_stream_class_default_clock_class_const( - const bt_message *msg); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_EVENT_CONST_H */ diff --git a/include/babeltrace2/graph/message-event.h b/include/babeltrace2/graph/message-event.h deleted file mode 100644 index 739a6848..00000000 --- a/include/babeltrace2/graph/message-event.h +++ /dev/null @@ -1,69 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_EVENT_H -#define BABELTRACE2_GRAPH_MESSAGE_EVENT_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -bt_message *bt_message_event_create( - bt_self_message_iterator *message_iterator, - const bt_event_class *event_class, - const bt_stream *stream); - -extern -bt_message *bt_message_event_create_with_packet( - bt_self_message_iterator *message_iterator, - const bt_event_class *event_class, - const bt_packet *packet); - -extern -bt_message *bt_message_event_create_with_default_clock_snapshot( - bt_self_message_iterator *message_iterator, - const bt_event_class *event_class, - const bt_stream *stream, uint64_t raw_clock_value); - -extern -bt_message *bt_message_event_create_with_packet_and_default_clock_snapshot( - bt_self_message_iterator *message_iterator, - const bt_event_class *event_class, - const bt_packet *packet, uint64_t raw_clock_value); - -extern bt_event *bt_message_event_borrow_event( - bt_message *message); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_EVENT_H */ diff --git a/include/babeltrace2/graph/message-iterator-class.h b/include/babeltrace2/graph/message-iterator-class.h index 3ee9c0da..e668a515 100644 --- a/include/babeltrace2/graph/message-iterator-class.h +++ b/include/babeltrace2/graph/message-iterator-class.h @@ -31,131 +31,1216 @@ extern "C" { #endif -typedef enum bt_message_iterator_class_set_method_status { - BT_MESSAGE_ITERATOR_CLASS_SET_METHOD_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_message_iterator_class_set_method_status; +/*! +@defgroup api-msg-iter-cls Message iterator class +@ingroup api-comp-cls-dev + +@brief + \bt_c_msg_iter class. + +A message iterator class 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 methods. 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 self) or a member function in C++ (where the +instance pointer is named this), 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. + +

\anchor api-msg-iter-cls-methods Methods

+ +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: + + + + + + + + + + +
Name + Requirement + C type +
Can seek beginning? + Optional + #bt_message_iterator_class_can_seek_beginning_method +
Can seek ns from origin? + Optional + #bt_message_iterator_class_can_seek_ns_from_origin_method +
Finalize + Optional + #bt_message_iterator_class_finalize_method +
Initialize + Optional + #bt_message_iterator_class_initialize_method +
Next + Mandatory + #bt_message_iterator_class_next_method +
Seek beginning + Optional + #bt_message_iterator_class_seek_beginning_method +
Seek ns from origin + Optional + #bt_message_iterator_class_seek_ns_from_origin_method +
+ +
+
+ \anchor api-msg-iter-cls-meth-can-seek-beg + Can seek beginning? +
+
+ 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(). +
+ +
+ \anchor api-msg-iter-cls-meth-can-seek-ns + Can seek ns from origin? +
+
+ 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(). +
+ +
+ \anchor api-msg-iter-cls-meth-fini + Finalize +
+
+ 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(). +
+ +
+ \anchor api-msg-iter-cls-meth-init + Initialize +
+
+ 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 seek forward. + + 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(). +
+ +
+ \anchor api-msg-iter-cls-meth-next + "Next" (get next messages) +
+
+ 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: + +
+
For a \bt_src_comp's message iterator
+
+ Creates brand new \bt_p_msg to represent one or more input + traces. +
+ +
For a \bt_flt_comp's message iterator
+
+ Gets \em one message batch from one (or more) upstream + \bt_msg_iter and filters them. +
+
+ + 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(). +
+ +
+ \anchor api-msg-iter-cls-meth-seek-beg + Seek beginning +
+
+ 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(). +
+ +
+ \anchor api-msg-iter-cls-meth-seek-ns + Seek ns from origin +
+
+ 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(). +
+
+ +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 + On success, \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 + On success, \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 + On success, 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 + On success, \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 + On success, \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 + On success, \bt_p{messages} contains \bt_p{*count} + message references as its first \bt_p{*count} elements. +@post + On success, the \bt_p_msg in \bt_p{messages} honour + the \ref api-msg-seq "message sequence rules". +@post + On success, 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 + On success, \bt_p{*count} â‰¥ 1. +@post + On success, + \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 + If \bt_p{self_message_iterator} has a + \ref api-msg-iter-cls-meth-can-seek-beg "can seek beginning?" + method, 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 + If \bt_p{self_message_iterator} has a + \ref api-msg-iter-cls-meth-can-seek-ns "can seek ns from origin?" + method, 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 + bt_message_iterator_class_set_*_method() 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 diff --git a/include/babeltrace2/graph/message-iterator.h b/include/babeltrace2/graph/message-iterator.h index 228b40d1..cda5040a 100644 --- a/include/babeltrace2/graph/message-iterator.h +++ b/include/babeltrace2/graph/message-iterator.h @@ -31,125 +31,865 @@ extern "C" { #endif +/*! +@defgroup api-msg-iter Message iterator +@ingroup api-comp-cls-dev + +@brief + Iterator of a \bt_msg sequence. + +A message iterator 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: + +
+
From another message iterator
+
+ 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". +
+ +
From a \bt_sink_comp
+
+ 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. +
+
+ +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 +\ref api-port-prop-is-connected "connected" 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 + +

\anchor api-msg-iter-ops Operations

+ +Once you have created a message iterator, there are three possible +operations: + +
+
+ \anchor api-msg-iter-op-next + Get the message iterator's next messages +
+
+ 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(). +
+ +
+ \anchor api-msg-iter-op-seek-beg + Make the message iterator seek its beginning +
+
+ 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(). +
+ +
+ \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 +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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 + On success, \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 + bt_port_is_connected(port) 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 + On success, \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 + bt_port_is_connected(port) 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 + On success, \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 + On success, \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 + On success, \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 + On success, \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 + bt_message_iterator_can_seek_beginning(message_iterator) + 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 + On success, \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 + bt_message_iterator_can_seek_ns_from_origin(message_iterator, ns_from_origin) + 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 diff --git a/include/babeltrace2/graph/message-message-iterator-inactivity-const.h b/include/babeltrace2/graph/message-message-iterator-inactivity-const.h deleted file mode 100644 index ce5ed337..00000000 --- a/include/babeltrace2/graph/message-message-iterator-inactivity-const.h +++ /dev/null @@ -1,44 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_clock_snapshot * -bt_message_message_iterator_inactivity_borrow_clock_snapshot_const( - const bt_message *msg); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_CONST_H */ diff --git a/include/babeltrace2/graph/message-message-iterator-inactivity.h b/include/babeltrace2/graph/message-message-iterator-inactivity.h deleted file mode 100644 index dba7c4a4..00000000 --- a/include/babeltrace2/graph/message-message-iterator-inactivity.h +++ /dev/null @@ -1,47 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_H -#define BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -bt_message *bt_message_message_iterator_inactivity_create( - bt_self_message_iterator *message_iterator, - const bt_clock_class *clock_class, uint64_t raw_value); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_MESSAGE_ITERATOR_INACTIVITY_H */ diff --git a/include/babeltrace2/graph/message-packet-beginning-const.h b/include/babeltrace2/graph/message-packet-beginning-const.h deleted file mode 100644 index af2f747c..00000000 --- a/include/babeltrace2/graph/message-packet-beginning-const.h +++ /dev/null @@ -1,51 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_packet *bt_message_packet_beginning_borrow_packet_const( - const bt_message *message); - -extern const bt_clock_snapshot * -bt_message_packet_beginning_borrow_default_clock_snapshot_const( - const bt_message *msg); - -extern const bt_clock_class * -bt_message_packet_beginning_borrow_stream_class_default_clock_class_const( - const bt_message *msg); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_CONST_H */ diff --git a/include/babeltrace2/graph/message-packet-beginning.h b/include/babeltrace2/graph/message-packet-beginning.h deleted file mode 100644 index 93a9785e..00000000 --- a/include/babeltrace2/graph/message-packet-beginning.h +++ /dev/null @@ -1,55 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_H -#define BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -bt_message *bt_message_packet_beginning_create( - bt_self_message_iterator *message_iterator, - const bt_packet *packet); - -extern -bt_message *bt_message_packet_beginning_create_with_default_clock_snapshot( - bt_self_message_iterator *message_iterator, - const bt_packet *packet, uint64_t raw_value); - -extern bt_packet *bt_message_packet_beginning_borrow_packet( - bt_message *message); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_BEGINNING_H */ diff --git a/include/babeltrace2/graph/message-packet-end-const.h b/include/babeltrace2/graph/message-packet-end-const.h deleted file mode 100644 index 82e2bbd4..00000000 --- a/include/babeltrace2/graph/message-packet-end-const.h +++ /dev/null @@ -1,51 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_END_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_PACKET_END_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_packet *bt_message_packet_end_borrow_packet_const( - const bt_message *message); - -extern const bt_clock_snapshot * -bt_message_packet_end_borrow_default_clock_snapshot_const( - const bt_message *msg); - -extern const bt_clock_class * -bt_message_packet_end_borrow_stream_class_default_clock_class_const( - const bt_message *msg); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_END_CONST_H */ diff --git a/include/babeltrace2/graph/message-packet-end.h b/include/babeltrace2/graph/message-packet-end.h deleted file mode 100644 index a0201799..00000000 --- a/include/babeltrace2/graph/message-packet-end.h +++ /dev/null @@ -1,55 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_PACKET_END_H -#define BABELTRACE2_GRAPH_MESSAGE_PACKET_END_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -bt_message *bt_message_packet_end_create( - bt_self_message_iterator *message_iterator, - const bt_packet *packet); - -extern -bt_message *bt_message_packet_end_create_with_default_clock_snapshot( - bt_self_message_iterator *message_iterator, - const bt_packet *packet, uint64_t raw_value); - -extern bt_packet *bt_message_packet_end_borrow_packet( - bt_message *message); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_PACKET_END_H */ diff --git a/include/babeltrace2/graph/message-stream-beginning-const.h b/include/babeltrace2/graph/message-stream-beginning-const.h deleted file mode 100644 index 69fdaa48..00000000 --- a/include/babeltrace2/graph/message-stream-beginning-const.h +++ /dev/null @@ -1,52 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_stream *bt_message_stream_beginning_borrow_stream_const( - const bt_message *message); - -extern bt_message_stream_clock_snapshot_state -bt_message_stream_beginning_borrow_default_clock_snapshot_const( - const bt_message *message, const bt_clock_snapshot **snapshot); - -extern const bt_clock_class * -bt_message_stream_beginning_borrow_stream_class_default_clock_class_const( - const bt_message *msg); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_CONST_H */ diff --git a/include/babeltrace2/graph/message-stream-beginning.h b/include/babeltrace2/graph/message-stream-beginning.h deleted file mode 100644 index e7385c54..00000000 --- a/include/babeltrace2/graph/message-stream-beginning.h +++ /dev/null @@ -1,52 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_H -#define BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -bt_message *bt_message_stream_beginning_create( - bt_self_message_iterator *message_iterator, - const bt_stream *stream); - -extern bt_stream *bt_message_stream_beginning_borrow_stream( - bt_message *message); - -extern -void bt_message_stream_beginning_set_default_clock_snapshot( - bt_message *message, uint64_t raw_value); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_BEGINNING_H */ diff --git a/include/babeltrace2/graph/message-stream-const.h b/include/babeltrace2/graph/message-stream-const.h deleted file mode 100644 index 8ecdfe78..00000000 --- a/include/babeltrace2/graph/message-stream-const.h +++ /dev/null @@ -1,43 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_STREAM_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_message_stream_clock_snapshot_state { - BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_UNKNOWN = 0, - BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN = 1, -} bt_message_stream_clock_snapshot_state; - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_CONST_H */ diff --git a/include/babeltrace2/graph/message-stream-end-const.h b/include/babeltrace2/graph/message-stream-end-const.h deleted file mode 100644 index b822e3bb..00000000 --- a/include/babeltrace2/graph/message-stream-end-const.h +++ /dev/null @@ -1,52 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_END_CONST_H -#define BABELTRACE2_GRAPH_MESSAGE_STREAM_END_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_stream *bt_message_stream_end_borrow_stream_const( - const bt_message *message); - -extern bt_message_stream_clock_snapshot_state -bt_message_stream_end_borrow_default_clock_snapshot_const( - const bt_message *message, const bt_clock_snapshot **snapshot); - -extern const bt_clock_class * -bt_message_stream_end_borrow_stream_class_default_clock_class_const( - const bt_message *msg); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_END_CONST_H */ diff --git a/include/babeltrace2/graph/message-stream-end.h b/include/babeltrace2/graph/message-stream-end.h deleted file mode 100644 index 34b98b8f..00000000 --- a/include/babeltrace2/graph/message-stream-end.h +++ /dev/null @@ -1,52 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MESSAGE_STREAM_END_H -#define BABELTRACE2_GRAPH_MESSAGE_STREAM_END_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern -bt_message *bt_message_stream_end_create( - bt_self_message_iterator *message_iterator, - const bt_stream *stream); - -extern bt_stream *bt_message_stream_end_borrow_stream( - bt_message *message); - -extern -void bt_message_stream_end_set_default_clock_snapshot( - bt_message *message, uint64_t raw_value); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MESSAGE_STREAM_END_H */ diff --git a/include/babeltrace2/graph/message.h b/include/babeltrace2/graph/message.h new file mode 100644 index 00000000..34b98bc0 --- /dev/null +++ b/include/babeltrace2/graph/message.h @@ -0,0 +1,3223 @@ +#ifndef BABELTRACE2_GRAPH_MESSAGE_H +#define BABELTRACE2_GRAPH_MESSAGE_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*! +@defgroup api-msg Messages +@ingroup api-comp-cls-dev + +@brief + Elements exchanged between \bt_p_comp. + +Messages 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 \bt_stream, 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 +_with_default_clock_snapshot (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. + +

Message types

+ +This section details each type of message. + +The following table shows the creation functions and types for each type +of message: + + + + + + + + + + + +
Name + Type enumerator + Creation functions +
\ref api-msg-sb "Stream beginning" + #BT_MESSAGE_TYPE_STREAM_BEGINNING + bt_message_stream_beginning_create() +
\ref api-msg-se "Stream end" + #BT_MESSAGE_TYPE_STREAM_END + bt_message_stream_end_create() +
\ref api-msg-ev "Event" + #BT_MESSAGE_TYPE_EVENT + + bt_message_event_create()
+ bt_message_event_create_with_default_clock_snapshot()
+ bt_message_event_create_with_packet()
+ bt_message_event_create_with_packet_and_default_clock_snapshot() +
\ref api-msg-pb "Packet beginning" + #BT_MESSAGE_TYPE_PACKET_BEGINNING + + bt_message_packet_beginning_create()
+ bt_message_packet_beginning_create_with_default_clock_snapshot() +
\ref api-msg-pe "Packet end" + #BT_MESSAGE_TYPE_PACKET_END + + bt_message_packet_end_create()
+ bt_message_packet_end_create_with_default_clock_snapshot() +
\ref api-msg-disc-ev "Discarded events" + #BT_MESSAGE_TYPE_DISCARDED_EVENTS + + bt_message_discarded_events_create()
+ bt_message_discarded_events_create_with_default_clock_snapshots() +
\ref api-msg-disc-pkt "Discarded packets" + #BT_MESSAGE_TYPE_DISCARDED_PACKETS + + bt_message_discarded_packets_create()
+ bt_message_discarded_packets_create_with_default_clock_snapshots() +
\ref api-msg-inac "Message iterator inactivity" + #BT_MESSAGE_TYPE_MESSAGE_ITERATOR_INACTIVITY + bt_message_message_iterator_inactivity_create() +
+ +

\anchor api-msg-sb Stream beginning message

+ +A stream beginning message 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: + +
+
\anchor api-msg-sb-prop-stream Stream
+
+ \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(). +
+ +
+ \anchor api-msg-sb-prop-cs + \bt_dt_opt Default \bt_cs +
+
+ 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 unknown. + + 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(). +
+
+ +

\anchor api-msg-se Stream end message

+ +A stream end message 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: + +
+
\anchor api-msg-se-prop-stream Stream
+
+ \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(). +
+ +
+ \anchor api-msg-se-prop-cs + \bt_dt_opt Default \bt_cs +
+
+ 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 unknown. + + 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(). +
+
+ +

\anchor api-msg-ev Event message

+ +An event message 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: + +
+
+ If the stream's \ref api-tir-stream-cls "class" + \ref api-tir-stream-cls-prop-supports-pkt "supports packets" +
+
After a \bt_pb_msg and before a \bt_pe_msg.
+ +
+ If the stream's class does not support packets +
+
After the \bt_sb_msg and before the \bt_se_msg.
+
+ +To create an event message for a given stream, use: + +
+
+ If the stream's \ref api-tir-stream-cls "class" + \ref api-tir-stream-cls-prop-supports-pkt "supports packets" +
+
+
+
+ If the stream's class has a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class" +
+
bt_message_event_create_with_packet_and_default_clock_snapshot()
+ +
+ If the stream's class does not have a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class" +
+
bt_message_event_create_with_packet()
+
+ + 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. +
+ +
+ If the stream's class does not supports packets +
+
+
+
+ If the stream's class has a default clock class +
+
bt_message_event_create_with_default_clock_snapshot()
+ +
+ If the stream's class does not have a + \ref api-tir-stream-cls-prop-def-clock-cls "default clock class" +
+
bt_message_event_create()
+
+
+
+ +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 not set: 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: + +
+
\anchor api-msg-ev-prop-ev Event
+
+ \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(). +
+ +
+ \anchor api-msg-ev-prop-cs + \bt_dt_opt Default \bt_cs +
+
+ 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(). +
+
+ +

\anchor api-msg-pb Packet beginning message

+ +A packet beginning message 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: + +
+
+ If, for this stream's class, + \ref api-tir-stream-cls-prop-pkt-beg-cs "packets have a beginning default clock snapshot" +
+
bt_message_packet_beginning_create_with_default_clock_snapshot()
+ +
+ If, for this stream's class, packets do not have a beginning default + clock snapshot +
+
bt_message_packet_beginning_create()
+
+ +A packet beginning message has the following properties: + +
+
\anchor api-msg-pb-prop-pkt Packet
+
+ \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(). +
+ +
+ \anchor api-msg-pb-prop-cs + \bt_dt_opt Default \bt_cs +
+
+ 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(). +
+
+ +

\anchor api-msg-pe Packet end message

+ +A packet end message 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: + +
+
+ If, for this stream's class, + \ref api-tir-stream-cls-prop-pkt-end-cs "packets have an end default clock snapshot" +
+
bt_message_packet_end_create_with_default_clock_snapshot()
+ +
+ If, for this stream's class, packets do not have an end default + clock snapshot +
+
bt_message_packet_end_create()
+
+ +A packet end message has the following properties: + +
+
\anchor api-msg-pe-prop-pkt Packet
+
+ \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(). +
+ +
+ \anchor api-msg-pe-prop-cs + \bt_dt_opt Default \bt_cs +
+
+ 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(). +
+
+ +

\anchor api-msg-disc-ev Discarded events message

+ +A discarded events message indicates that +events were discarded at tracing time. 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: + +
+
+ If, for this stream's class, + \ref api-tir-stream-cls-prop-disc-ev-cs "discarded events have default clock snapshots" +
+
bt_message_discarded_events_create_with_default_clock_snapshots()
+ +
+ If, for this stream's class, discarded events do not have default + clock snapshots +
+
bt_message_discarded_events_create()
+
+ +A discarded events message has the following properties: + +
+
\anchor api-msg-disc-ev-prop-stream Stream
+
+ \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(). +
+ +
+ \anchor api-msg-disc-ev-prop-cs-beg + \bt_dt_opt Beginning default \bt_cs +
+
+ 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(). +
+ +
+ \anchor api-msg-disc-ev-prop-cs-end + \bt_dt_opt End default \bt_cs +
+
+ 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(). +
+ +
+ \anchor api-msg-disc-ev-prop-count + \bt_dt_opt Discarded event count +
+
+ 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(). +
+
+ +

\anchor api-msg-disc-pkt Discarded packets message

+ +A discarded packets message indicates that +packets were discarded at tracing time. 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: + +
+
+ If, for this stream's class, + \ref api-tir-stream-cls-prop-disc-pkt-cs "discarded packets have default clock snapshots" +
+
bt_message_discarded_packets_create_with_default_clock_snapshots()
+ +
+ If, for this stream's class, discarded packets do not have default + clock snapshots +
+
bt_message_discarded_packets_create()
+
+ +A discarded packets message has the following properties: + +
+
\anchor api-msg-disc-pkt-prop-stream Stream
+
+ \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(). +
+ +
+ \anchor api-msg-disc-pkt-prop-cs-beg + \bt_dt_opt Beginning default \bt_cs +
+
+ 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(). +
+ +
+ \anchor api-msg-disc-pkt-prop-cs-end + \bt_dt_opt End default \bt_cs +
+
+ 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(). +
+ +
+ \anchor api-msg-disc-pkt-prop-count + \bt_dt_opt Discarded packet count +
+
+ 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(). +
+
+ +

\anchor api-msg-inac Message iterator inactivity

+ +A message iterator inactivity message +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 progress. + +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: + +
+
+ \anchor api-msg-inac-prop-cs + \bt_dt_opt \bt_c_cs +
+
+ 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(). +
+
+ +

\anchor api-msg-mip Message Interchange Protocol

+ +The Message Interchange Protocol (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, 264 - 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 +bt_graph_add_*_component*() 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. + +

\anchor api-msg-seq Message sequence rules

+ +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: + +
    +
  • + For a given \bt_stream: + + - The sequence must begin with a \bt_sb_msg. + - The sequence must end with a \bt_se_msg. + - If the stream's \ref api-tir-stream-cls "class" + \ref api-tir-stream-cls-prop-supports-pkt "supports packets": + - 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: + +
    +
    Without packets
    +
    + @code{.unparsed} + SB (E | DE)* SE + @endcode +
    + +
    With packets
    +
    + @code{.unparsed} + SB ((PB (E | DE)* PE) | DE | DP)* SE + @endcode +
    +
    + + With this alphabet: + +
    +
    SB
    +
    \bt_c_sb_msg
    + +
    SE
    +
    \bt_c_se_msg
    + +
    E
    +
    \bt_c_ev_msg
    + +
    PB
    +
    \bt_c_pb_msg
    + +
    PE
    +
    \bt_c_pe_msg
    + +
    DE
    +
    \bt_c_disc_ev_msg
    + +
    DP
    +
    \bt_c_disc_pkt_msg
    +
    +
  • + 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. +
  • + 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"). +
+*/ + +/*! @{ */ + +/*! +@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: + + + + + +
Property + Value +
\ref api-msg-sb-prop-stream "Stream" + \bt_p{stream} +
\ref api-msg-sb-prop-cs "Default clock snapshot" + \em None +
+ +@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 + If this function returns + #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN, + \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: + + + + + +
Property + Value +
\ref api-msg-se-prop-stream "Stream" + \bt_p{stream} +
\ref api-msg-se-prop-cs "Default clock snapshot" + \em None +
+ +@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 + If this function returns + #BT_MESSAGE_STREAM_CLOCK_SNAPSHOT_STATE_KNOWN, + \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: + + + + + +
Property + Value +
\ref api-msg-ev-prop-ev "Event" + + An instance (with \bt_p_field that are not set) of + \bt_p{event_class}. +
\ref api-msg-se-prop-cs "Default clock snapshot" + \em None +
+ +@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, + bt_event_class_borrow_stream_class_const(event_class) + and + bt_stream_borrow_class_const(stream) have the + same value. +@bt_pre_not_null{stream} +@pre + bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream)) + returns #BT_FALSE. +@pre + bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream)) + 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: + + + + + +
Property + Value +
\ref api-msg-ev-prop-ev "Event" + + An instance (with \bt_p_field that are not set) of + \bt_p{event_class}. +
\ref api-msg-se-prop-cs "Default clock snapshot" + \bt_c_cs with the value \bt_p{clock_snapshot_value}. +
+ +@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, + bt_event_class_borrow_stream_class_const(event_class) + and + bt_stream_borrow_class_const(stream) have the + same value. +@bt_pre_not_null{stream} +@pre + bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream)) + returns #BT_FALSE. +@pre + bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(stream)) + 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: + + + + + +
Property + Value +
\ref api-msg-ev-prop-ev "Event" + + An instance (with \bt_p_field that are not set) of + \bt_p{event_class}. +
\ref api-msg-se-prop-cs "Default clock snapshot" + \em None +
+ +@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, + bt_event_class_borrow_stream_class_const(event_class) + and + bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)) + have the same value. +@bt_pre_not_null{packet} +@pre + bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) + returns #BT_TRUE. +@pre + bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) + 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: + + + + + +
Property + Value +
\ref api-msg-ev-prop-ev "Event" + + An instance (with \bt_p_field that are not set) of + \bt_p{event_class}. +
\ref api-msg-se-prop-cs "Default clock snapshot" + \bt_c_cs with the value \bt_p{clock_snapshot_value}. +
+ +@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, + bt_event_class_borrow_stream_class_const(event_class) + and + bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)) + have the same value. +@bt_pre_not_null{packet} +@pre + bt_stream_class_supports_packets(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) + returns #BT_TRUE. +@pre + bt_stream_class_borrow_default_clock_class_const(bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet))) + 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: + + + + + +
Property + Value +
\ref api-msg-pb-prop-pkt "Packet" + \bt_p{packet} +
\ref api-msg-pb-prop-cs "Default clock snapshot" + \em None +
+ +@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 + bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)). +@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: + + + + + +
Property + Value +
\ref api-msg-pb-prop-pkt "Packet" + \bt_p{packet} +
\ref api-msg-pb-prop-cs "Default clock snapshot" + \bt_c_cs with the value \bt_p{clock_snapshot_value}. +
+ +@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 + bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)). +@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: + + + + + +
Property + Value +
\ref api-msg-pe-prop-pkt "Packet" + \bt_p{packet} +
\ref api-msg-pe-prop-cs "Default clock snapshot" + \em None +
+ +@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 + bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)). +@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: + + + + + +
Property + Value +
\ref api-msg-pe-prop-pkt "Packet" + \bt_p{packet} +
\ref api-msg-pe-prop-cs "Default clock snapshot" + \bt_c_cs with the value \bt_p{clock_snapshot_value}. +
+ +@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 + bt_stream_borrow_class_const(bt_packet_borrow_stream_const(packet)). +@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: + + + + + + + +
Property + Value +
\ref api-msg-disc-ev-prop-stream "Stream" + \bt_p{stream} +
\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot" + \em None +
\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot" + \em None +
\ref api-msg-disc-ev-prop-count "Discarded event count" + \em None +
+ +@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 + bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) + 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: + + + + + + + +
Property + Value +
\ref api-msg-disc-ev-prop-stream "Stream" + \bt_p{stream} +
\ref api-msg-disc-ev-prop-cs-beg "Beginning default clock snapshot" + \bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}. +
\ref api-msg-disc-ev-prop-cs-end "End default clock snapshot" + \bt_c_cs with the value \bt_p{end_clock_snapshot_value}. +
\ref api-msg-disc-ev-prop-count "Discarded event count" + \em None +
+ +@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 + bt_stream_class_discarded_events_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) + 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 + If this function returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE, \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: + + + + + + + +
Property + Value +
\ref api-msg-disc-pkt-prop-stream "Stream" + \bt_p{stream} +
\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot" + \em None +
\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot" + \em None +
\ref api-msg-disc-pkt-prop-count "Discarded packet count" + \em None +
+ +@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 + bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) + 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: + + + + + + + +
Property + Value +
\ref api-msg-disc-pkt-prop-stream "Stream" + \bt_p{stream} +
\ref api-msg-disc-pkt-prop-cs-beg "Beginning default clock snapshot" + \bt_c_cs with the value \bt_p{beginning_clock_snapshot_value}. +
\ref api-msg-disc-pkt-prop-cs-end "End default clock snapshot" + \bt_c_cs with the value \bt_p{end_clock_snapshot_value}. +
\ref api-msg-disc-pkt-prop-count "Discarded packet count" + \em None +
+ +@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 + bt_stream_class_discarded_packets_have_default_clock_snapshots(bt_stream_borrow_class_const(stream)) + 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 + If this function returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE, \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: + + + + +
Property + Value +
\ref api-msg-inac-prop-cs "Clock snapshot" + + \bt_c_cs (snapshot of a fictitious instance of \bt_p{clock_class}) + with the value \bt_p{clock_snapshot_value}. +
+ +@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 + On success, \bt_p{*mip_version} is the greatest + operative MIP version of all the component descriptors in + \bt_p{component_descriptors}. + +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK + Success. +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH + No operative MIP version exists for the component descriptors of + \bt_p{component_descriptors}. +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR + Out of memory. +@retval #BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR + Other error. + +@bt_pre_not_null{component_descriptors} +@pre + \bt_p{component_descriptors} contains one or more component + descriptors. +@bt_pre_not_null{mip_version} +*/ +extern bt_get_greatest_operative_mip_version_status +bt_get_greatest_operative_mip_version( + const bt_component_descriptor_set *component_descriptors, + bt_logging_level logging_level, uint64_t *mip_version); + +/*! +@brief + Returns the maximal available \bt_mip version as of + \bt_name_version_min_maj. + +As of \bt_name_version_min_maj, this function returns +\bt_max_mip_version. + +@returns + Maximal available MIP version (\bt_max_mip_version). +*/ +extern uint64_t bt_get_maximal_mip_version(void); + +/*! @} */ + +/*! @} */ + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE2_GRAPH_MESSAGE_H */ diff --git a/include/babeltrace2/graph/mip.h b/include/babeltrace2/graph/mip.h deleted file mode 100644 index f5da87c5..00000000 --- a/include/babeltrace2/graph/mip.h +++ /dev/null @@ -1,56 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_MIP_H -#define BABELTRACE2_GRAPH_MIP_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_get_greatest_operative_mip_version_status { - BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_GET_GREATEST_OPERATIVE_MIP_VERSION_STATUS_NO_MATCH = __BT_FUNC_STATUS_NO_MATCH, -} bt_get_greatest_operative_mip_version_status; - -extern bt_get_greatest_operative_mip_version_status -bt_get_greatest_operative_mip_version( - const bt_component_descriptor_set *comp_descriptor_set, - bt_logging_level log_level, uint64_t *operative_mip_version); - -extern uint64_t bt_get_maximal_mip_version(void); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_MIP_H */ diff --git a/include/babeltrace2/graph/port-const.h b/include/babeltrace2/graph/port-const.h deleted file mode 100644 index eda9ccb9..00000000 --- a/include/babeltrace2/graph/port-const.h +++ /dev/null @@ -1,88 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_PORT_CONST_H -#define BABELTRACE2_GRAPH_PORT_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_port_type { - BT_PORT_TYPE_INPUT = 1 << 0, - BT_PORT_TYPE_OUTPUT = 1 << 1, -} bt_port_type; - -extern const char *bt_port_get_name(const bt_port *port); - -extern bt_port_type bt_port_get_type(const bt_port *port); - -extern const bt_connection *bt_port_borrow_connection_const( - const bt_port *port); - -extern const bt_component *bt_port_borrow_component_const( - const bt_port *port); - -extern bt_bool bt_port_is_connected(const bt_port *port); - -static inline -bt_bool bt_port_is_input(const bt_port *port) -{ - return bt_port_get_type(port) == BT_PORT_TYPE_INPUT; -} - -static inline -bt_bool bt_port_is_output(const bt_port *port) -{ - return bt_port_get_type(port) == BT_PORT_TYPE_OUTPUT; -} - -extern void bt_port_get_ref(const bt_port *port); - -extern void bt_port_put_ref(const bt_port *port); - -#define BT_PORT_PUT_REF_AND_RESET(_var) \ - do { \ - bt_port_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_PORT_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_port_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_PORT_CONST_H */ diff --git a/include/babeltrace2/graph/port-input-const.h b/include/babeltrace2/graph/port-input-const.h deleted file mode 100644 index c3eff668..00000000 --- a/include/babeltrace2/graph/port-input-const.h +++ /dev/null @@ -1,65 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_PORT_INPUT_CONST_H -#define BABELTRACE2_GRAPH_PORT_INPUT_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_port *bt_port_input_as_port_const(const bt_port_input *port_input) -{ - return __BT_UPCAST_CONST(bt_port, port_input); -} - -extern void bt_port_input_get_ref(const bt_port_input *port_input); - -extern void bt_port_input_put_ref(const bt_port_input *port_input); - -#define BT_PORT_INPUT_PUT_REF_AND_RESET(_var) \ - do { \ - bt_port_input_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_PORT_INPUT_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_port_input_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_PORT_INPUT_CONST_H */ diff --git a/include/babeltrace2/graph/port-output-const.h b/include/babeltrace2/graph/port-output-const.h deleted file mode 100644 index 6d88926d..00000000 --- a/include/babeltrace2/graph/port-output-const.h +++ /dev/null @@ -1,65 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_PORT_OUTPUT_CONST_H -#define BABELTRACE2_GRAPH_PORT_OUTPUT_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_port *bt_port_output_as_port_const(const bt_port_output *port_output) -{ - return __BT_UPCAST_CONST(bt_port, port_output); -} - -extern void bt_port_output_get_ref(const bt_port_output *port_output); - -extern void bt_port_output_put_ref(const bt_port_output *port_output); - -#define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_var) \ - do { \ - bt_port_output_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_PORT_OUTPUT_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_port_output_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_PORT_OUTPUT_CONST_H */ diff --git a/include/babeltrace2/graph/port.h b/include/babeltrace2/graph/port.h new file mode 100644 index 00000000..5567d04d --- /dev/null +++ b/include/babeltrace2/graph/port.h @@ -0,0 +1,673 @@ +#ifndef BABELTRACE2_GRAPH_PORT_H +#define BABELTRACE2_GRAPH_PORT_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*! +@defgroup api-port Ports +@ingroup api-comp + +@brief + \bt_c_comp input and output ports. + +A port 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: + +
+
\anchor api-port-in Input port
+
+ 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(). +
+ +
\anchor api-port-out Output port
+
+ 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(). +
+
+ +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(). + +

Properties

+ +A port has the following common properties: + +
+
+ \anchor api-port-prop-name + Name +
+
+ 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(). +
+ +
+ \anchor api-port-prop-is-connected + Is connected? +
+
+ 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. +
+
+*/ + +/*! @{ */ + +/*! +@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 */ diff --git a/include/babeltrace2/graph/private-query-executor.h b/include/babeltrace2/graph/private-query-executor.h index 348d30d4..79b1f5f8 100644 --- a/include/babeltrace2/graph/private-query-executor.h +++ b/include/babeltrace2/graph/private-query-executor.h @@ -33,6 +33,63 @@ extern "C" { #endif +/*! +@defgroup api-priv-qexec Private query executor +@ingroup api-comp-cls-dev + +@brief + Private view of a \bt_qexec for a \bt_comp_cls + \ref api-comp-cls-dev-meth-query "query method". + +A private query executor is a private view, +from within a \bt_comp_cls +\ref api-comp-cls-dev-meth-query "query method", of a +\bt_qexec. + +A query method receives a private query executor as its +\bt_p{query_executor} parameter. + +As of \bt_name_version_min_maj, this module only offers the +bt_private_query_executor_as_query_executor_const() function to +\ref api-fund-c-typing "upcast" a private query executor to a +\c const query executor. You need this to get the query executor's +\ref api-qexec-prop-log-lvl "logging level". +*/ + +/*! @{ */ + +/*! +@name Type +@{ + +@typedef struct bt_private_query_executor bt_private_query_executor; + +@brief + Private query executor. + +@} +*/ + +/*! +@name Upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the private query executor + \bt_p{query_executor} to the public #bt_query_executor type. + +@param[in] query_executor + @parblock + Private query executor to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{query_executor} as a public query executor. +*/ static inline const bt_query_executor * bt_private_query_executor_as_query_executor_const( @@ -41,6 +98,10 @@ bt_private_query_executor_as_query_executor_const( return __BT_UPCAST_CONST(bt_query_executor, query_executor); } +/*! @} */ + +/*! @} */ + #ifdef __cplusplus } #endif diff --git a/include/babeltrace2/graph/query-executor-const.h b/include/babeltrace2/graph/query-executor-const.h deleted file mode 100644 index a857ed70..00000000 --- a/include/babeltrace2/graph/query-executor-const.h +++ /dev/null @@ -1,63 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_CONST_H -#define BABELTRACE2_GRAPH_QUERY_EXECUTOR_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern bt_bool bt_query_executor_is_interrupted( - const bt_query_executor *query_executor); - -extern bt_logging_level bt_query_executor_get_logging_level( - const bt_query_executor *query_executor); - -extern void bt_query_executor_get_ref(const bt_query_executor *query_executor); - -extern void bt_query_executor_put_ref(const bt_query_executor *query_executor); - -#define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_var) \ - do { \ - bt_query_executor_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_QUERY_EXECUTOR_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_query_executor_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_CONST_H */ diff --git a/include/babeltrace2/graph/query-executor.h b/include/babeltrace2/graph/query-executor.h index c393e6ec..a3d1c637 100644 --- a/include/babeltrace2/graph/query-executor.h +++ b/include/babeltrace2/graph/query-executor.h @@ -34,47 +34,547 @@ extern "C" { #endif +/*! +@defgroup api-qexec Query executor +@ingroup api-graph + +@brief + Executor of \bt_comp_cls object queries. + +A query executor 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 +source.ctf.lttng-live component class (see +\bt_man{babeltrace2-source.ctf.lttng-live,7}) offers the \c sessions +object to list the available +LTTng live +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(). + +

Property

+ +A query executor has the following property: + +
+
+ \anchor api-qexec-prop-log-lvl + Logging level +
+
+ Logging level of the query executor's query operations. + + Use bt_query_executor_set_logging_level() and + bt_query_executor_get_logging_level(). +
+
+*/ + +/*! @{ */ + +/*! +@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 bt_graph_add_*_component_*_port_added_listener() + 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 + On success, \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 default interrupter. + + 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 } diff --git a/include/babeltrace2/graph/self-component-class-filter.h b/include/babeltrace2/graph/self-component-class-filter.h deleted file mode 100644 index f2f96ceb..00000000 --- a/include/babeltrace2/graph/self-component-class-filter.h +++ /dev/null @@ -1,57 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_FILTER_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_FILTER_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component_class_filter * -bt_self_component_class_filter_as_component_class_filter( - bt_self_component_class_filter *self_comp_cls_filter) -{ - return __BT_UPCAST_CONST(bt_component_class_filter, - self_comp_cls_filter); -} - -static inline -bt_self_component_class* -bt_self_component_class_filter_as_self_component_class( - bt_self_component_class_filter *self_comp_cls_filter) -{ - return __BT_UPCAST(bt_self_component_class, self_comp_cls_filter); -} - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_FILTER_H */ diff --git a/include/babeltrace2/graph/self-component-class-sink.h b/include/babeltrace2/graph/self-component-class-sink.h deleted file mode 100644 index 00f6841c..00000000 --- a/include/babeltrace2/graph/self-component-class-sink.h +++ /dev/null @@ -1,56 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SINK_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SINK_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component_class_sink * -bt_self_component_class_sink_as_component_class_sink( - bt_self_component_class_sink *self_comp_cls_sink) -{ - return __BT_UPCAST_CONST(bt_component_class_sink, self_comp_cls_sink); -} - -static inline -bt_self_component_class* -bt_self_component_class_sink_as_self_component_class( - bt_self_component_class_sink *self_comp_cls_sink) -{ - return __BT_UPCAST(bt_self_component_class, self_comp_cls_sink); -} - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SINK_H */ diff --git a/include/babeltrace2/graph/self-component-class-source.h b/include/babeltrace2/graph/self-component-class-source.h deleted file mode 100644 index fb025f0c..00000000 --- a/include/babeltrace2/graph/self-component-class-source.h +++ /dev/null @@ -1,57 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SOURCE_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SOURCE_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -const bt_component_class_source * -bt_self_component_class_source_as_component_class_source( - bt_self_component_class_source *self_comp_cls_source) -{ - return __BT_UPCAST_CONST(bt_component_class_source, - self_comp_cls_source); -} - -static inline -bt_self_component_class* -bt_self_component_class_source_as_self_component_class( - bt_self_component_class_source *self_comp_cls_source) -{ - return __BT_UPCAST(bt_self_component_class, self_comp_cls_source); -} - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_CLASS_SOURCE_H */ diff --git a/include/babeltrace2/graph/self-component-class.h b/include/babeltrace2/graph/self-component-class.h index 7cdd441e..33fda7b0 100644 --- a/include/babeltrace2/graph/self-component-class.h +++ b/include/babeltrace2/graph/self-component-class.h @@ -33,6 +33,73 @@ extern "C" { #endif +/*! +@defgroup api-self-comp-cls Self component classes +@ingroup api-comp-cls-dev + +@brief + Private views of \bt_p_comp_cls for class methods. + +The #bt_self_component_class, #bt_self_component_class_source, +#bt_self_component_class_filter, #bt_self_component_class_sink types are +private views of a \bt_comp_cls from within a component class +\ref api-comp-cls-dev-class-meth "class method". + +As of \bt_name_version_min_maj, this module only contains functions +to \ref api-fund-c-typing "upcast" the "self" (private) types to their +public #bt_component_class, #bt_component_class_source, +#bt_component_class_filter, and #bt_component_class_sink counterparts. +*/ + +/*! @{ */ + +/*! +@name Types +@{ + +@typedef struct bt_self_component_class bt_self_component_class; + +@brief + Self \bt_comp_cls. + +@typedef struct bt_self_component_class_source bt_self_component_class_source; + +@brief + Self \bt_src_comp_cls. + +@typedef struct bt_self_component_class_filter bt_self_component_class_filter; + +@brief + Self \bt_flt_comp_cls. + +@typedef struct bt_self_component_class_sink bt_self_component_class_sink; + +@brief + Self \bt_sink_comp_cls. + +@} +*/ + +/*! +@name Self to public upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_comp_cls + \bt_p{self_component_class} to the public #bt_component_class type. + +@param[in] self_component_class + @parblock + Component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_class} as a public component class. +*/ static inline const bt_component_class *bt_self_component_class_as_component_class( bt_self_component_class *self_component_class) @@ -40,6 +107,163 @@ const bt_component_class *bt_self_component_class_as_component_class( return __BT_UPCAST(bt_component_class, self_component_class); } +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_src_comp_cls + \bt_p{self_component_class} to the public #bt_component_class_source + type. + +@param[in] self_component_class + @parblock + Source component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_class} as a public source component class. +*/ +static inline +const bt_component_class_source * +bt_self_component_class_source_as_component_class_source( + bt_self_component_class_source *self_component_class) +{ + return __BT_UPCAST_CONST(bt_component_class_source, + self_component_class); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp_cls + \bt_p{self_component_class} to the public #bt_component_class_filter + type. + +@param[in] self_component_class + @parblock + Filter component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_class} as a public filter component class. +*/ +static inline +const bt_component_class_filter * +bt_self_component_class_filter_as_component_class_filter( + bt_self_component_class_filter *self_component_class) +{ + return __BT_UPCAST_CONST(bt_component_class_filter, + self_component_class); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp_cls + \bt_p{self_component_class} to the public #bt_component_class_sink + type. + +@param[in] self_component_class + @parblock + Sink component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_class} as a public sink component class. +*/ +static inline +const bt_component_class_sink * +bt_self_component_class_sink_as_component_class_sink( + bt_self_component_class_sink *self_component_class) +{ + return __BT_UPCAST_CONST(bt_component_class_sink, self_component_class); +} + +/*! @} */ + +/*! +@name Self to common self upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_src_comp_cls + \bt_p{self_component_class} to the common #bt_self_component_class + type. + +@param[in] self_component_class + @parblock + Source component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_class} as a common self component class. +*/ +static inline +bt_self_component_class* +bt_self_component_class_source_as_self_component_class( + bt_self_component_class_source *self_component_class) +{ + return __BT_UPCAST(bt_self_component_class, self_component_class); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp_cls + \bt_p{self_component_class} to the common #bt_self_component_class + type. + +@param[in] self_component_class + @parblock + Filter component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_class} as a common self component class. +*/ +static inline +bt_self_component_class* +bt_self_component_class_filter_as_self_component_class( + bt_self_component_class_filter *self_component_class) +{ + return __BT_UPCAST(bt_self_component_class, self_component_class); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp_cls + \bt_p{self_component_class} to the common #bt_self_component_class + type. + +@param[in] self_component_class + @parblock + Sink component class to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_class} as a common self component class. +*/ +static inline +bt_self_component_class* +bt_self_component_class_sink_as_self_component_class( + bt_self_component_class_sink *self_component_class) +{ + return __BT_UPCAST(bt_self_component_class, self_component_class); +} + +/*! @} */ + +/*! @} */ + #ifdef __cplusplus } #endif diff --git a/include/babeltrace2/graph/self-component-filter.h b/include/babeltrace2/graph/self-component-filter.h deleted file mode 100644 index ec49b6f9..00000000 --- a/include/babeltrace2/graph/self-component-filter.h +++ /dev/null @@ -1,90 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_FILTER_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_FILTER_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -bt_self_component *bt_self_component_filter_as_self_component( - bt_self_component_filter *self_comp_filter) -{ - return __BT_UPCAST(bt_self_component, self_comp_filter); -} - -static inline -const bt_component_filter * -bt_self_component_filter_as_component_filter( - bt_self_component_filter *self_comp_filter) -{ - return __BT_UPCAST_CONST(bt_component_filter, self_comp_filter); -} - -extern bt_self_component_port_output * -bt_self_component_filter_borrow_output_port_by_name( - bt_self_component_filter *self_component, - const char *name); - -extern bt_self_component_port_output * -bt_self_component_filter_borrow_output_port_by_index( - bt_self_component_filter *self_component, - uint64_t index); - -extern bt_self_component_add_port_status -bt_self_component_filter_add_output_port( - bt_self_component_filter *self_component, - const char *name, void *user_data, - bt_self_component_port_output **self_component_port); - -extern bt_self_component_port_input * -bt_self_component_filter_borrow_input_port_by_name( - bt_self_component_filter *self_component, - const char *name); - -extern bt_self_component_port_input * -bt_self_component_filter_borrow_input_port_by_index( - bt_self_component_filter *self_component, - uint64_t index); - -extern bt_self_component_add_port_status -bt_self_component_filter_add_input_port( - bt_self_component_filter *self_component, - const char *name, void *user_data, - bt_self_component_port_input **self_component_port); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_FILTER_H */ diff --git a/include/babeltrace2/graph/self-component-port-input.h b/include/babeltrace2/graph/self-component-port-input.h deleted file mode 100644 index 0c13c015..00000000 --- a/include/babeltrace2/graph/self-component-port-input.h +++ /dev/null @@ -1,55 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_INPUT_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_INPUT_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -bt_self_component_port * -bt_self_component_port_input_as_self_component_port( - bt_self_component_port_input *self_component_port) -{ - return __BT_UPCAST(bt_self_component_port, self_component_port); -} - -static inline -const bt_port_input *bt_self_component_port_input_as_port_input( - const bt_self_component_port_input *self_component_port) -{ - return __BT_UPCAST_CONST(bt_port_input, self_component_port); -} - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_INPUT_H */ diff --git a/include/babeltrace2/graph/self-component-port-output.h b/include/babeltrace2/graph/self-component-port-output.h deleted file mode 100644 index b3daa62a..00000000 --- a/include/babeltrace2/graph/self-component-port-output.h +++ /dev/null @@ -1,55 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_OUTPUT_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_OUTPUT_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -bt_self_component_port * -bt_self_component_port_output_as_self_component_port( - bt_self_component_port_output *self_component_port) -{ - return __BT_UPCAST(bt_self_component_port, self_component_port); -} - -static inline -const bt_port_output *bt_self_component_port_output_as_port_output( - bt_self_component_port_output *self_component_port) -{ - return __BT_UPCAST_CONST(bt_port_output, self_component_port); -} - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_PORT_OUTPUT_H */ diff --git a/include/babeltrace2/graph/self-component-port.h b/include/babeltrace2/graph/self-component-port.h index db08e2c7..0ab59ac3 100644 --- a/include/babeltrace2/graph/self-component-port.h +++ b/include/babeltrace2/graph/self-component-port.h @@ -33,18 +33,235 @@ extern "C" { #endif +/*! +@defgroup api-self-comp-port Self component ports +@ingroup api-self-comp + +@brief + Private views of \bt_p_port for \bt_comp_cls instance methods. + +The #bt_self_component_port, #bt_self_component_port_input, and +#bt_self_component_port_output types are private views of a \bt_port +from within a component class +\ref api-comp-cls-dev-instance-meth "instance method". + +Borrow the \bt_self_comp of a port with +bt_self_component_port_borrow_component(). + +Get the user data attached to a port with +bt_self_component_port_get_data(). + +\ref api-fund-c-typing "Upcast" the "self" (private) types to the +public and common self component port types with the +bt_self_component_port*_as_port*() and +bt_self_component_port_*_as_self_component_port() +functions. +*/ + +/*! @{ */ + +/*! +@name Types +@{ + +@typedef struct bt_self_component_port bt_self_component_port; + +@brief + Self component \bt_comp. + +@typedef struct bt_self_component_port_input bt_self_component_port_input; + +@brief + Self component \bt_iport. + +@typedef struct bt_self_component_port_output bt_self_component_port_output; + +@brief + Self component \bt_oport. + +@} +*/ + +/*! +@name Component access +@{ +*/ + +/*! +@brief + Borrows the \bt_comp of the \bt_port \bt_p{self_component_port}. + +@param[in] self_component_port + Port from which to borrow the component which owns it. + +@returns + Component which owns \bt_p{self_component_port}. + +@bt_pre_not_null{self_component_port} +*/ +extern bt_self_component *bt_self_component_port_borrow_component( + bt_self_component_port *self_component_port); + +/*! @} */ + +/*! +@name User data access +@{ +*/ + +/*! +@brief + Returns the user data of the \bt_port \bt_p{self_component_port}. + +You can attach user data to a port when you add it to a component with +bt_self_component_source_add_output_port(), +bt_self_component_filter_add_input_port(), +bt_self_component_filter_add_output_port(), and +bt_self_component_sink_add_input_port(). + +@param[in] self_component_port + Port of which to get the user data. + +@returns + User data of \bt_p{self_component_port}. + +@bt_pre_not_null{self_component_port} +*/ +extern void *bt_self_component_port_get_data( + const bt_self_component_port *self_component_port); + + +/*! @} */ + +/*! +@name Self to public upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self component port + \bt_p{self_component_port} to the public #bt_port type. + +@param[in] self_component_port + @parblock + Port to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_port} as a public port. +*/ static inline const bt_port *bt_self_component_port_as_port( - bt_self_component_port *self_port) + bt_self_component_port *self_component_port) { - return __BT_UPCAST_CONST(bt_port, self_port); + return __BT_UPCAST_CONST(bt_port, self_component_port); } -extern bt_self_component *bt_self_component_port_borrow_component( - bt_self_component_port *self_port); +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self component \bt_iport + \bt_p{self_component_port} to the public #bt_port_input type. -extern void *bt_self_component_port_get_data( - const bt_self_component_port *self_port); +@param[in] self_component_port + @parblock + Input port to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_port} as a public input port. +*/ +static inline +const bt_port_input *bt_self_component_port_input_as_port_input( + const bt_self_component_port_input *self_component_port) +{ + return __BT_UPCAST_CONST(bt_port_input, self_component_port); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self component \bt_oport + \bt_p{self_component_port} to the public #bt_port_output type. + +@param[in] self_component_port + @parblock + Output port to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_port} as a public output port. +*/ +static inline +const bt_port_output *bt_self_component_port_output_as_port_output( + bt_self_component_port_output *self_component_port) +{ + return __BT_UPCAST_CONST(bt_port_output, self_component_port); +} + +/*! @} */ + +/*! +@name Self to common self upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_iport + \bt_p{self_component_port} to the common #bt_self_component_port + type. + +@param[in] self_component_port + @parblock + Input port to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_port} as a common self component port. +*/ +static inline +bt_self_component_port * +bt_self_component_port_input_as_self_component_port( + bt_self_component_port_input *self_component_port) +{ + return __BT_UPCAST(bt_self_component_port, self_component_port); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_oport + \bt_p{self_component_port} to the common #bt_self_component_port + type. + +@param[in] self_component_port + @parblock + Output port to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component_port} as a common self component port. +*/ +static inline +bt_self_component_port * +bt_self_component_port_output_as_self_component_port( + bt_self_component_port_output *self_component_port) +{ + return __BT_UPCAST(bt_self_component_port, self_component_port); +} + +/*! @} */ + +/*! @} */ #ifdef __cplusplus } diff --git a/include/babeltrace2/graph/self-component-sink.h b/include/babeltrace2/graph/self-component-sink.h deleted file mode 100644 index 224c6781..00000000 --- a/include/babeltrace2/graph/self-component-sink.h +++ /dev/null @@ -1,76 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_SINK_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_SINK_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -bt_self_component *bt_self_component_sink_as_self_component( - bt_self_component_sink *self_comp_sink) -{ - return __BT_UPCAST(bt_self_component, self_comp_sink); -} - -static inline -const bt_component_sink * -bt_self_component_sink_as_component_sink( - bt_self_component_sink *self_comp_sink) -{ - return __BT_UPCAST_CONST(bt_component_sink, self_comp_sink); -} - -extern bt_self_component_port_input * -bt_self_component_sink_borrow_input_port_by_name( - bt_self_component_sink *self_component, - const char *name); - -extern bt_self_component_port_input * -bt_self_component_sink_borrow_input_port_by_index( - bt_self_component_sink *self_component, uint64_t index); - -extern bt_self_component_add_port_status -bt_self_component_sink_add_input_port( - bt_self_component_sink *self_component, - const char *name, void *user_data, - bt_self_component_port_input **self_component_port); - -extern bt_bool bt_self_component_sink_is_interrupted( - const bt_self_component_sink *self_component); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_SINK_H */ diff --git a/include/babeltrace2/graph/self-component-source.h b/include/babeltrace2/graph/self-component-source.h deleted file mode 100644 index ec022fd3..00000000 --- a/include/babeltrace2/graph/self-component-source.h +++ /dev/null @@ -1,74 +0,0 @@ -#ifndef BABELTRACE2_GRAPH_SELF_COMPONENT_SOURCE_H -#define BABELTRACE2_GRAPH_SELF_COMPONENT_SOURCE_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -static inline -bt_self_component *bt_self_component_source_as_self_component( - bt_self_component_source *self_comp_source) -{ - return __BT_UPCAST(bt_self_component, self_comp_source); -} - -static inline -const bt_component_source * -bt_self_component_source_as_component_source( - bt_self_component_source *self_comp_source) -{ - return __BT_UPCAST_CONST(bt_component_source, self_comp_source); -} - -extern bt_self_component_port_output * -bt_self_component_source_borrow_output_port_by_name( - bt_self_component_source *self_component, - const char *name); - -extern bt_self_component_port_output * -bt_self_component_source_borrow_output_port_by_index( - bt_self_component_source *self_component, - uint64_t index); - -extern bt_self_component_add_port_status -bt_self_component_source_add_output_port( - bt_self_component_source *self_component, - const char *name, void *user_data, - bt_self_component_port_output **self_component_port); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_GRAPH_SELF_COMPONENT_SOURCE_H */ diff --git a/include/babeltrace2/graph/self-component.h b/include/babeltrace2/graph/self-component.h index ba722d98..b995c088 100644 --- a/include/babeltrace2/graph/self-component.h +++ b/include/babeltrace2/graph/self-component.h @@ -33,12 +33,690 @@ extern "C" { #endif +/*! +@defgroup api-self-comp Self components +@ingroup api-comp-cls-dev + +@brief + Private views of \bt_p_comp for instance methods. + +The #bt_self_component, #bt_self_component_source, +#bt_self_component_filter, #bt_self_component_sink types are +private views of a \bt_comp from within a component class +\ref api-comp-cls-dev-instance-meth "instance method". + +Add a \bt_port to a component with +bt_self_component_source_add_output_port(), +bt_self_component_filter_add_input_port(), +bt_self_component_filter_add_output_port(), and +bt_self_component_sink_add_input_port(). + +When you add a port to a component, you can attach custom user data +to it (\bt_voidp). You can retrieve this user data +afterwards with bt_self_component_port_get_data(). + +Borrow a \bt_self_comp_port from a component by index with +bt_self_component_source_borrow_output_port_by_index(), +bt_self_component_filter_borrow_input_port_by_index(), +bt_self_component_filter_borrow_output_port_by_index(), and +bt_self_component_sink_borrow_input_port_by_index(). + +Borrow a \bt_self_comp_port from a component by name with +bt_self_component_source_borrow_output_port_by_name(), +bt_self_component_filter_borrow_input_port_by_name(), +bt_self_component_filter_borrow_output_port_by_name(), and +bt_self_component_sink_borrow_input_port_by_name(). + +Set and get user data attached to a component with +bt_self_component_set_data() and bt_self_component_get_data(). + +Get a component's owning trace processing \bt_graph's effective +\bt_mip version with bt_self_component_get_graph_mip_version(). + +Check whether or not a \bt_sink_comp is interrupted with +bt_self_component_sink_is_interrupted(). + +\ref api-fund-c-typing "Upcast" the "self" (private) types to the +public and common self component types with the +bt_self_component*_as_component*() and +bt_self_component_*_as_self_component() 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 + On success, if not \c NULL, + \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 + On success, if not \c NULL, + \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 + On success, if not \c NULL, + \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 + On success, if not \c NULL, + \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) @@ -46,14 +724,157 @@ const bt_component *bt_self_component_as_component( return __BT_UPCAST(bt_component, self_component); } -extern -uint64_t bt_self_component_get_graph_mip_version(bt_self_component *self_component); +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_src_comp + \bt_p{self_component} to the public #bt_component_source + type. -extern void *bt_self_component_get_data( - const bt_self_component *self_component); +@param[in] self_component + @parblock + Source component to upcast. -extern void bt_self_component_set_data( - bt_self_component *self_component, void *data); + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component} as a public source component. +*/ +static inline +const bt_component_source * +bt_self_component_source_as_component_source( + bt_self_component_source *self_component) +{ + return __BT_UPCAST_CONST(bt_component_source, self_component); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp + \bt_p{self_component} to the public #bt_component_filter + type. + +@param[in] self_component + @parblock + Filter component to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component} as a public filter component. +*/ +static inline +const bt_component_filter * +bt_self_component_filter_as_component_filter( + bt_self_component_filter *self_component) +{ + return __BT_UPCAST_CONST(bt_component_filter, self_component); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp + \bt_p{self_component} to the public #bt_component_sink + type. + +@param[in] self_component + @parblock + Sink component to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component} as a public sink component. +*/ +static inline +const bt_component_sink * +bt_self_component_sink_as_component_sink( + bt_self_component_sink *self_component) +{ + return __BT_UPCAST_CONST(bt_component_sink, self_component); +} + +/*! @} */ + +/*! +@name Self to common self upcast +@{ +*/ + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_src_comp + \bt_p{self_component} to the common #bt_self_component + type. + +@param[in] self_component + @parblock + Source component to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component} as a common self component. +*/ +static inline +bt_self_component *bt_self_component_source_as_self_component( + bt_self_component_source *self_component) +{ + return __BT_UPCAST(bt_self_component, self_component); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_flt_comp + \bt_p{self_component} to the common #bt_self_component + type. + +@param[in] self_component + @parblock + Filter component to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component} as a common self component. +*/ +static inline +bt_self_component *bt_self_component_filter_as_self_component( + bt_self_component_filter *self_component) +{ + return __BT_UPCAST(bt_self_component, self_component); +} + +/*! +@brief + \ref api-fund-c-typing "Upcasts" the self \bt_sink_comp + \bt_p{self_component} to the common #bt_self_component + type. + +@param[in] self_component + @parblock + Sink component to upcast. + + Can be \c NULL. + @endparblock + +@returns + \bt_p{self_component} as a common self component. +*/ +static inline +bt_self_component *bt_self_component_sink_as_self_component( + bt_self_component_sink *self_component) +{ + return __BT_UPCAST(bt_self_component, self_component); +} + +/*! @} */ + +/*! @} */ #ifdef __cplusplus } diff --git a/include/babeltrace2/graph/self-message-iterator.h b/include/babeltrace2/graph/self-message-iterator.h index 9aaa2767..0a6697d1 100644 --- a/include/babeltrace2/graph/self-message-iterator.h +++ b/include/babeltrace2/graph/self-message-iterator.h @@ -33,28 +33,214 @@ extern "C" { #endif -extern bt_bool bt_self_message_iterator_is_interrupted( - const bt_self_message_iterator *message_iterator); +/*! +@defgroup api-self-msg-iter Self message iterator +@ingroup api-msg-iter-cls + +@brief + Private view of a \bt_msg_iter for methods. + +The #bt_self_message_iterator type is a private view of a \bt_msg_iter +from within a \bt_msg_iter_cls method. + +Borrow the \bt_comp which provides a message iterator with +bt_self_message_iterator_borrow_component(). + +Borrow the \bt_oport on which a message iterator operates with +bt_self_message_iterator_borrow_port(). + +Set and get user data attached to a message iterator with +bt_self_message_iterator_set_data() and +bt_self_message_iterator_get_data(). + +Check whether or not a message iterator is interrupted with +bt_self_message_iterator_is_interrupted(). + +Set whether or not a message iterator can seek forward with +bt_self_message_iterator_configuration_set_can_seek_forward(). +*/ + +/*! @{ */ + +/*! +@name Types +@{ + +@typedef struct bt_self_message_iterator bt_self_message_iterator; + +@brief + Self \bt_msg_iter. + +@typedef struct bt_self_message_iterator_configuration bt_self_message_iterator_configuration; +@brief + Self \bt_msg_iter configuration. + +@} +*/ + +/*! +@name Component access +@{ +*/ + +/*! +@brief + Borrows the \bt_comp which provides the \bt_msg_iter + \bt_p{self_message_iterator}. + +@param[in] self_message_iterator + Message iterator instance. + +@returns + Component which provides \bt_p{self_message_iterator}. + +@bt_pre_not_null{self_message_iterator} +*/ extern bt_self_component * bt_self_message_iterator_borrow_component( - bt_self_message_iterator *message_iterator); + bt_self_message_iterator *self_message_iterator); +/*! @} */ + +/*! +@name Output port access +@{ +*/ + +/*! +@brief + Borrows the \bt_oport on which the \bt_msg_iter + \bt_p{self_message_iterator} operates. + +@param[in] self_message_iterator + Message iterator instance. + +@returns + Output port on which \bt_p{self_message_iterator} operates. + +@bt_pre_not_null{self_message_iterator} +*/ extern bt_self_component_port_output * bt_self_message_iterator_borrow_port( - bt_self_message_iterator *message_iterator); + bt_self_message_iterator *self_message_iterator); + +/*! @} */ +/*! +@name User data +@{ +*/ + +/*! +@brief + Sets the user data of the \bt_msg_iter \bt_p{self_message_iterator} + to \bt_p{data}. + +@param[in] self_message_iterator + Message iterator instance. +@param[in] user_data + New user data of \bt_p{self_message_iterator}. + +@bt_pre_not_null{self_message_iterator} + +@sa bt_self_message_iterator_get_data() — + Returns the user data of a message iterator. +*/ extern void bt_self_message_iterator_set_data( - bt_self_message_iterator *message_iterator, + bt_self_message_iterator *self_message_iterator, void *user_data); -extern void *bt_self_message_iterator_get_data( - const bt_self_message_iterator *message_iterator); +/*! +@brief + Returns the user data of the \bt_msg_iter + \bt_p{self_message_iterator}. + +@param[in] self_message_iterator + Message iterator instance. + +@returns + User data of \bt_p{self_message_iterator}. + +@bt_pre_not_null{self_message_iterator} + +@sa bt_self_message_iterator_set_data() — + Sets the user data of a message iterator. +*/ +extern +void *bt_self_message_iterator_get_data( + const bt_self_message_iterator *self_message_iterator); + +/*! @} */ + +/*! +@name Interruption query +@{ +*/ + +/*! +@brief + Returns whether or not the \bt_msg_iter \bt_p{self_message_iterator} + is interrupted, that is, whether or not any of its \bt_p_intr + is set. + +@param[in] self_message_iterator + Message iterator instance. + +@returns + #BT_TRUE if \bt_p{self_message_iterator} is interrupted (any of its + interrupters is set). +@bt_pre_not_null{self_message_iterator} + +@sa bt_graph_borrow_default_interrupter() — + Borrows a trace processing graph's default interrupter. +@sa bt_graph_add_interrupter() — + Adds an interrupter to a graph. +*/ +extern bt_bool bt_self_message_iterator_is_interrupted( + const bt_self_message_iterator *self_message_iterator); + +/*! @} */ + +/*! +@name Configuration +@{ +*/ + +/*! +@brief + Sets whether or not the \bt_msg_iter of which the configuration + is \bt_p{configuration} can seek forward. + +A message iterator can seek forward if all the \bt_p_msg of its +message sequence have some \bt_cs. + +@attention + You can only call this function during the execution of a + message iterator's + \ref api-msg-iter-cls-meth-init "initialization method". + +@param[in] configuration + Configuration of the message iterator of which to set whether or + not it can seek forward. +@param[in] can_seek_forward + #BT_TRUE to make the message iterator of which the configuration is + \bt_p{configuration} forward-seekable. + +@bt_pre_not_null{configuration} + +@sa bt_message_iterator_can_seek_forward() — + Returns whether or not a message iterator can seek forward. +*/ extern void bt_self_message_iterator_configuration_set_can_seek_forward( - bt_self_message_iterator_configuration *config, + bt_self_message_iterator_configuration *configuration, bt_bool can_seek_forward); +/*! @} */ + +/*! @} */ + #ifdef __cplusplus } #endif diff --git a/include/babeltrace2/integer-range-set-const.h b/include/babeltrace2/integer-range-set-const.h deleted file mode 100644 index cbf9f33a..00000000 --- a/include/babeltrace2/integer-range-set-const.h +++ /dev/null @@ -1,133 +0,0 @@ -#ifndef BABELTRACE2_INTEGER_RANGE_SET_CONST_H -#define BABELTRACE2_INTEGER_RANGE_SET_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern uint64_t bt_integer_range_unsigned_get_lower( - const bt_integer_range_unsigned *range); - -extern uint64_t bt_integer_range_unsigned_get_upper( - const bt_integer_range_unsigned *range); - -extern int64_t bt_integer_range_signed_get_lower( - const bt_integer_range_signed *range); - -extern int64_t bt_integer_range_signed_get_upper( - const bt_integer_range_signed *range); - -extern bt_bool bt_integer_range_unsigned_is_equal( - const bt_integer_range_unsigned *range_a, - const bt_integer_range_unsigned *range_b); - -extern bt_bool bt_integer_range_signed_is_equal( - const bt_integer_range_signed *range_a, - const bt_integer_range_signed *range_b); - -static inline -const bt_integer_range_set *bt_integer_range_set_unsigned_as_range_set_const( - const bt_integer_range_set_unsigned *range_set) -{ - return __BT_UPCAST_CONST(bt_integer_range_set, range_set); -} - -static inline -const bt_integer_range_set *bt_integer_range_set_signed_as_range_set_const( - const bt_integer_range_set_signed *range_set) -{ - return __BT_UPCAST_CONST(bt_integer_range_set, range_set); -} - -extern uint64_t bt_integer_range_set_get_range_count(const bt_integer_range_set *range_set); - -extern const bt_integer_range_unsigned * -bt_integer_range_set_unsigned_borrow_range_by_index_const( - const bt_integer_range_set_unsigned *range_set, uint64_t index); - -extern const bt_integer_range_signed * -bt_integer_range_set_signed_borrow_range_by_index_const( - const bt_integer_range_set_signed *range_set, uint64_t index); - -extern bt_bool bt_integer_range_set_unsigned_is_equal( - const bt_integer_range_set_unsigned *range_set_a, - const bt_integer_range_set_unsigned *range_set_b); - -extern bt_bool bt_integer_range_set_signed_is_equal( - const bt_integer_range_set_signed *range_set_a, - const bt_integer_range_set_signed *range_set_b); - -extern void bt_integer_range_set_unsigned_get_ref( - const bt_integer_range_set_unsigned *range_set); - -extern void bt_integer_range_set_unsigned_put_ref( - const bt_integer_range_set_unsigned *range_set); - -#define BT_INTEGER_RANGE_SET_UNSIGNED_PUT_REF_AND_RESET(_var) \ - do { \ - bt_integer_range_set_unsigned_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_INTEGER_RANGE_SET_UNSIGNED_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_integer_range_set_unsigned_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -extern void bt_integer_range_set_signed_get_ref( - const bt_integer_range_set_signed *range_set); - -extern void bt_integer_range_set_signed_put_ref( - const bt_integer_range_set_signed *range_set); - -#define BT_INTEGER_RANGE_SET_SIGNED_PUT_REF_AND_RESET(_var) \ - do { \ - bt_integer_range_set_signed_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_INTEGER_RANGE_SET_SIGNED_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_integer_range_set_signed_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_INTEGER_RANGE_SET_CONST_H */ diff --git a/include/babeltrace2/integer-range-set.h b/include/babeltrace2/integer-range-set.h index f1d9a56c..8eb13434 100644 --- a/include/babeltrace2/integer-range-set.h +++ b/include/babeltrace2/integer-range-set.h @@ -31,29 +31,757 @@ #include #include -#include #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 integer range set +is an \em unordered set of integer ranges. + +An integer range represents all the +integers \b 𝑥 which satisfy +(lower value â‰¤ ð‘¥ â‰¤ upper value). + +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 diff --git a/include/babeltrace2/logging.h b/include/babeltrace2/logging.h index 8091ec43..1c931743 100644 --- a/include/babeltrace2/logging.h +++ b/include/babeltrace2/logging.h @@ -33,116 +33,210 @@ extern "C" { #endif -/** -@defgroup logging Logging -@ingroup apiref -@brief Logging. +/*! +@defgroup api-logging Logging -@code -#include -@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 libbabeltrace2'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 } diff --git a/include/babeltrace2/plugin/plugin-const.h b/include/babeltrace2/plugin/plugin-const.h deleted file mode 100644 index 65b66def..00000000 --- a/include/babeltrace2/plugin/plugin-const.h +++ /dev/null @@ -1,164 +0,0 @@ -#ifndef BABELTRACE2_PLUGIN_PLUGIN_CONST_H -#define BABELTRACE2_PLUGIN_PLUGIN_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_plugin_find_status { - BT_PLUGIN_FIND_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_PLUGIN_FIND_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, - BT_PLUGIN_FIND_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_PLUGIN_FIND_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_plugin_find_status; - -extern bt_plugin_find_status bt_plugin_find(const char *plugin_name, - bt_bool find_in_std_env_var, bt_bool find_in_user_dir, - bt_bool find_in_sys_dir, bt_bool find_in_static, - bt_bool fail_on_load_error, const bt_plugin **plugin); - -typedef enum bt_plugin_find_all_status { - BT_PLUGIN_FIND_ALL_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_PLUGIN_FIND_ALL_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, - BT_PLUGIN_FIND_ALL_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_PLUGIN_FIND_ALL_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_plugin_find_all_status; - -bt_plugin_find_all_status bt_plugin_find_all(bt_bool find_in_std_env_var, - bt_bool find_in_user_dir, bt_bool find_in_sys_dir, - bt_bool find_in_static, bt_bool fail_on_load_error, - const bt_plugin_set **plugin_set); - -typedef enum bt_plugin_find_all_from_file_status { - BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, - BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_plugin_find_all_from_file_status; - -extern bt_plugin_find_all_from_file_status bt_plugin_find_all_from_file( - const char *path, bt_bool fail_on_load_error, - const bt_plugin_set **plugin_set); - -typedef enum bt_plugin_find_all_from_dir_status { - BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, - BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_plugin_find_all_from_dir_status; - -extern bt_plugin_find_all_from_dir_status bt_plugin_find_all_from_dir( - const char *path, bt_bool recurse, bt_bool fail_on_load_error, - const bt_plugin_set **plugin_set); - -typedef enum bt_plugin_find_all_from_static_status { - BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_NOT_FOUND = __BT_FUNC_STATUS_NOT_FOUND, - BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, -} bt_plugin_find_all_from_static_status; - -extern bt_plugin_find_all_from_static_status bt_plugin_find_all_from_static( - bt_bool fail_on_load_error, const bt_plugin_set **plugin_set); - -extern const char *bt_plugin_get_name(const bt_plugin *plugin); - -extern const char *bt_plugin_get_author(const bt_plugin *plugin); - -extern const char *bt_plugin_get_license(const bt_plugin *plugin); - -extern const char *bt_plugin_get_description(const bt_plugin *plugin); - -extern const char *bt_plugin_get_path(const bt_plugin *plugin); - -extern bt_property_availability bt_plugin_get_version( - const bt_plugin *plugin, unsigned int *major, - unsigned int *minor, unsigned int *patch, const char **extra); - -extern uint64_t bt_plugin_get_source_component_class_count( - const bt_plugin *plugin); - -extern uint64_t bt_plugin_get_filter_component_class_count( - const bt_plugin *plugin); - -extern uint64_t bt_plugin_get_sink_component_class_count( - const bt_plugin *plugin); - -extern const bt_component_class_source * -bt_plugin_borrow_source_component_class_by_index_const( - const bt_plugin *plugin, uint64_t index); - -extern const bt_component_class_filter * -bt_plugin_borrow_filter_component_class_by_index_const( - const bt_plugin *plugin, uint64_t index); - -extern const bt_component_class_sink * -bt_plugin_borrow_sink_component_class_by_index_const( - const bt_plugin *plugin, uint64_t index); - -extern const bt_component_class_source * -bt_plugin_borrow_source_component_class_by_name_const( - const bt_plugin *plugin, const char *name); - -extern const bt_component_class_filter * -bt_plugin_borrow_filter_component_class_by_name_const( - const bt_plugin *plugin, const char *name); - -extern const bt_component_class_sink * -bt_plugin_borrow_sink_component_class_by_name_const( - const bt_plugin *plugin, const char *name); - -extern void bt_plugin_get_ref(const bt_plugin *plugin); - -extern void bt_plugin_put_ref(const bt_plugin *plugin); - -#define BT_PLUGIN_PUT_REF_AND_RESET(_var) \ - do { \ - bt_plugin_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_PLUGIN_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_plugin_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_PLUGIN_PLUGIN_CONST_H */ diff --git a/include/babeltrace2/plugin/plugin-dev.h b/include/babeltrace2/plugin/plugin-dev.h index c78288b8..71372536 100644 --- a/include/babeltrace2/plugin/plugin-dev.h +++ b/include/babeltrace2/plugin/plugin-dev.h @@ -29,10 +29,7 @@ #include -#include -#include -#include -#include +#include #include #include @@ -51,19 +48,2386 @@ extern "C" { #endif -/* Plugin initialization function type */ +/*! +@defgroup api-plugin-dev Plugin development + +@brief + Shared object plugin development. + +This module offers macros to create a \bt_name shared object plugin. + +Behind the scenes, the BT_PLUGIN_*() 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. + +

Plugin definition C file structure

+ +The structure of a \bt_name plugin definition C file is as such: + +
    +
  1. + Start with + + @code + BT_PLUGIN_MODULE(); + @endcode +
    2. + +
  2. + 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 auto. +
    3. + +
  3. + \bt_dt_opt Use any of the following macros (or their + *_WITH_ID() counterpart) \em once to set the properties + of the plugin: + + - BT_PLUGIN_AUTHOR() + - BT_PLUGIN_DESCRIPTION() + - BT_PLUGIN_LICENSE() + - BT_PLUGIN_VERSION() +
    4. + +
  4. + \bt_dt_opt Use any of the following macros (or their + *_WITH_ID() 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. +
    5. + +
  5. + Use any of the following macros (or their *_WITH_ID() + counterpart) to add a component class to the plugin: + + - BT_PLUGIN_SOURCE_COMPONENT_CLASS() + - BT_PLUGIN_FILTER_COMPONENT_CLASS() + - BT_PLUGIN_SINK_COMPONENT_CLASS() +
    6. + +
  6. + \bt_dt_opt Depending on the type of the component class of step 5, + use any of the following macros (or their *_WITH_ID() + counterpart) + \em once to set its properties: + +
    +
    \bt_c_src_comp_cls
    +
    + - BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION() + - BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP() +
    + +
    \bt_c_flt_comp_cls
    +
    + - BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION() + - BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP() +
    + +
    \bt_c_sink_comp_cls
    +
    + - BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION() + - BT_PLUGIN_SINK_COMPONENT_CLASS_HELP() +
    +
    +
    7. + +
  7. + \bt_dt_opt Depending on the type of the component class of step 5, + use any of the following macros (or their *_WITH_ID() + counterpart) to set its optional methods: + +
    +
    Source component class
    +
    + - 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() +
    + +
    Filter component class
    +
    + - 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() +
    + +
    Sink component class
    +
    + - 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() +
    +
    +
    8. +
+ +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. + +

\anchor api-plugin-dev-custom-plugin-id Custom plugin ID

+ +The BT_PLUGIN() macro defines a plugin with a specific name and the +ID auto. + +All the BT_PLUGIN_*() macros which do not end with +_WITH_ID refer to the auto 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 BT_PLUGIN_*_WITH_ID() 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 auto 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 + +

Custom component class ID

+ +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 auto. + +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 auto +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 + auto, if you have more than one). + +- You want to give the component class a name which is not a valid C + identifier. + + The BT_PLUGIN_*_COMPONENT_CLASS_WITH_ID() 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 BT_PLUGIN_*_COMPONENT_CLASS_WITH_ID() 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 auto: + + @code + BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(auto, my_comp_class_id, + "my-source", my_source_iter_next); + @endcode + @endparblock + +Then, use the BT_PLUGIN_*_COMPONENT_CLASS_*_WITH_ID() +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 BT_PLUGIN*() 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 + const char * + + 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 + auto. +*/ +#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 + const char * + + 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 auto. +*/ +#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 + const char * + + 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 auto. +*/ +#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 + const char * + + 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 auto. +*/ +#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 + unsigned int + + Plugin's major version. + @endparblock +@param[in] _minor + @parblock + unsigned int + + Plugin's minor version. + @endparblock +@param[in] _patch + @parblock + unsigned int + + Plugin's patch version. + @endparblock +@param[in] _extra + @parblock + const char * + + 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 auto. +*/ +#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 auto. +*/ +#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 auto. +*/ +#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 + const char * + + 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 auto, 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 + const char * + + 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 auto, 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 + const char * + + 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 auto, 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 + const char * + + 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 auto 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 + const char * + + 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 auto 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 + const char * + + 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 auto 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 + const char * + + 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 auto 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 + const char * + + 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 auto 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 + const char * + + 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto 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 auto and + the \bt_p{_component_class_id} parameter set to \bt_p{_name}. +*/ +#define BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD(_name, _method) \ + BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _method) + +/*! @} */ + +/*! @} */ + /* Plugin descriptor: describes a single plugin (internal use) */ struct __bt_plugin_descriptor { /* Plugin's name */ @@ -255,6 +2619,47 @@ struct __bt_plugin_component_class_descriptor const * const *__bt_get_end_sectio struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_begin_section_component_class_descriptor_attributes(void); struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_end_section_component_class_descriptor_attributes(void); +/* + * Defines a plugin attribute (generic, internal use). + * + * _attr_name: Name of the attribute (C identifier). + * _attr_type: Type of the attribute (enum __bt_plugin_descriptor_attribute_type). + * _id: Plugin descriptor ID (C identifier). + * _x: Value. + */ +#define __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _x) \ + static struct __bt_plugin_descriptor_attribute __bt_plugin_descriptor_attribute_##_id##_##_attr_name = { \ + .plugin_descriptor = &__bt_plugin_descriptor_##_id, \ + .type_name = #_attr_name, \ + .type = _attr_type, \ + .value = { ._attr_name = _x }, \ + }; \ + static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_##_id##_##_attr_name##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_descriptor_attribute_##_id##_##_attr_name + +#define __BT_PLUGIN_VERSION_STRUCT_VALUE(_major, _minor, _patch, _extra) \ + {.major = _major, .minor = _minor, .patch = _patch, .extra = _extra,} + +/* + * Defines a component class descriptor attribute (generic, internal + * use). + * + * _id: Plugin descriptor ID (C identifier). + * _component_class_id: Component class ID (C identifier). + * _type: Component class type (`source`, `filter`, or `sink`). + * _attr_name: Name of the attribute (C identifier). + * _attr_type: Type of the attribute + * (enum __bt_plugin_descriptor_attribute_type). + * _x: Value. + */ +#define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _component_class_id, _type, _x) \ + static struct __bt_plugin_component_class_descriptor_attribute __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_component_class_id##_##_attr_name = { \ + .comp_class_descriptor = &__bt_plugin_##_type##_component_class_descriptor_##_id##_##_component_class_id, \ + .type_name = #_attr_name, \ + .type = _attr_type, \ + .value = { ._attr_name = _x }, \ + }; \ + static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_component_class_id##_##_attr_name##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_component_class_id##_##_attr_name + /* * Variable attributes for a plugin descriptor pointer to be added to * the plugin descriptor section (internal use). @@ -400,1042 +2805,6 @@ struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_ #define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_EXTRA #endif -/* - * Declares a plugin descriptor pointer variable with a custom ID. - * - * _id: ID (any valid C identifier except `auto`). - */ -#define BT_PLUGIN_DECLARE(_id) extern struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id - -/* - * Defines a plugin descriptor with a custom ID. - * - * _id: ID (any valid C identifier except `auto`). - * _name: Plugin's name (C string). - */ -#define BT_PLUGIN_WITH_ID(_id, _name) \ - struct __bt_plugin_descriptor __bt_plugin_descriptor_##_id = { \ - .name = _name, \ - }; \ - static struct __bt_plugin_descriptor const * const __bt_plugin_descriptor_##_id##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRS = &__bt_plugin_descriptor_##_id - -/* - * Defines a plugin attribute (generic, internal use). - * - * _attr_name: Name of the attribute (C identifier). - * _attr_type: Type of the attribute (enum __bt_plugin_descriptor_attribute_type). - * _id: Plugin descriptor ID (C identifier). - * _x: Value. - */ -#define __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _x) \ - static struct __bt_plugin_descriptor_attribute __bt_plugin_descriptor_attribute_##_id##_##_attr_name = { \ - .plugin_descriptor = &__bt_plugin_descriptor_##_id, \ - .type_name = #_attr_name, \ - .type = _attr_type, \ - .value = { ._attr_name = _x }, \ - }; \ - static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_##_id##_##_attr_name##_ptr __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_descriptor_attribute_##_id##_##_attr_name - -/* - * Defines a plugin initialization function attribute attached to a - * specific plugin descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _x: Initialization function (bt_plugin_initialize_func). - */ -#define BT_PLUGIN_INITIALIZE_FUNC_WITH_ID(_id, _x) \ - __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(init, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_INIT, _id, _x) - -/* - * Defines a plugin exit function attribute attached to a specific - * plugin descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _x: Exit function (bt_plugin_finalize_func). - */ -#define BT_PLUGIN_FINALIZE_FUNC_WITH_ID(_id, _x) \ - __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(exit, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_EXIT, _id, _x) - -/* - * Defines an author attribute attached to a specific plugin descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _x: Author (C string). - */ -#define BT_PLUGIN_AUTHOR_WITH_ID(_id, _x) \ - __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(author, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_AUTHOR, _id, _x) - -/* - * Defines a license attribute attached to a specific plugin descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _x: License (C string). - */ -#define BT_PLUGIN_LICENSE_WITH_ID(_id, _x) \ - __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(license, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_LICENSE, _id, _x) - -/* - * Defines a description attribute attached to a specific plugin - * descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _x: Description (C string). - */ -#define BT_PLUGIN_DESCRIPTION_WITH_ID(_id, _x) \ - __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _x) - -#define __BT_PLUGIN_VERSION_STRUCT_VALUE(_major, _minor, _patch, _extra) \ - {.major = _major, .minor = _minor, .patch = _patch, .extra = _extra,} - -/* - * Defines a version attribute attached to a specific plugin descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _major: Plugin's major version (uint32_t). - * _minor: Plugin's minor version (uint32_t). - * _patch: Plugin's patch version (uint32_t). - * _extra: Plugin's version extra information (C string). - */ -#define BT_PLUGIN_VERSION_WITH_ID(_id, _major, _minor, _patch, _extra) \ - __BT_PLUGIN_DESCRIPTOR_ATTRIBUTE(version, BT_PLUGIN_DESCRIPTOR_ATTRIBUTE_TYPE_VERSION, _id, __BT_PLUGIN_VERSION_STRUCT_VALUE(_major, _minor, _patch, _extra)) - -/* - * Defines a source component class descriptor with a custom ID. - * - * _id: ID (any valid C identifier except `auto`). - * _comp_class_id: Component class ID (C identifier). - * _name: Component class name (C string). - * _msg_iter_next_method: Component class's iterator next method - * (bt_component_class_source_message_iterator_next_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(_id, _comp_class_id, _name, _msg_iter_next_method) \ - static struct __bt_plugin_component_class_descriptor __bt_plugin_source_component_class_descriptor_##_id##_##_comp_class_id = { \ - .plugin_descriptor = &__bt_plugin_descriptor_##_id, \ - .name = _name, \ - .type = BT_COMPONENT_CLASS_TYPE_SOURCE, \ - .methods = { .source = { .msg_iter_next = _msg_iter_next_method } }, \ - }; \ - static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_source_component_class_descriptor_##_id##_##_comp_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_source_component_class_descriptor_##_id##_##_comp_class_id - -/* - * Defines a filter component class descriptor with a custom ID. - * - * _id: ID (any valid C identifier except `auto`). - * _comp_class_id: Component class ID (C identifier). - * _name: Component class name (C string). - * _msg_iter_next_method: Component class's iterator next method - * (bt_component_class_filter_message_iterator_next_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID(_id, _comp_class_id, _name, _msg_iter_next_method) \ - static struct __bt_plugin_component_class_descriptor __bt_plugin_filter_component_class_descriptor_##_id##_##_comp_class_id = { \ - .plugin_descriptor = &__bt_plugin_descriptor_##_id, \ - .name = _name, \ - .type = BT_COMPONENT_CLASS_TYPE_FILTER, \ - .methods = { .filter = { .msg_iter_next = _msg_iter_next_method } }, \ - }; \ - static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_filter_component_class_descriptor_##_id##_##_comp_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_filter_component_class_descriptor_##_id##_##_comp_class_id - -/* - * Defines a sink component class descriptor with a custom ID. - * - * _id: ID (any valid C identifier except `auto`). - * _comp_class_id: Component class ID (C identifier). - * _name: Component class name (C string). - * _consume_method: Component class's iterator consume method - * (bt_component_class_sink_consume_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID(_id, _comp_class_id, _name, _consume_method) \ - static struct __bt_plugin_component_class_descriptor __bt_plugin_sink_component_class_descriptor_##_id##_##_comp_class_id = { \ - .plugin_descriptor = &__bt_plugin_descriptor_##_id, \ - .name = _name, \ - .type = BT_COMPONENT_CLASS_TYPE_SINK, \ - .methods = { .sink = { .consume = _consume_method } }, \ - }; \ - static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_sink_component_class_descriptor_##_id##_##_comp_class_id##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = &__bt_plugin_sink_component_class_descriptor_##_id##_##_comp_class_id - -/* - * Defines a component class descriptor attribute (generic, internal - * use). - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class ID (C identifier). - * _type: Component class type (`source`, `filter`, or `sink`). - * _attr_name: Name of the attribute (C identifier). - * _attr_type: Type of the attribute - * (enum __bt_plugin_descriptor_attribute_type). - * _x: Value. - */ -#define __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(_attr_name, _attr_type, _id, _comp_class_id, _type, _x) \ - static struct __bt_plugin_component_class_descriptor_attribute __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_attr_name = { \ - .comp_class_descriptor = &__bt_plugin_##_type##_component_class_descriptor_##_id##_##_comp_class_id, \ - .type_name = #_attr_name, \ - .type = _attr_type, \ - .value = { ._attr_name = _x }, \ - }; \ - static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_attr_name##_ptr __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = &__bt_plugin_##_type##_component_class_descriptor_attribute_##_id##_##_comp_class_id##_##_attr_name - -/* - * Defines a description attribute attached to a specific source - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Description (C string). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _comp_class_id, source, _x) - -/* - * Defines a description attribute attached to a specific filter - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Description (C string). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _comp_class_id, filter, _x) - -/* - * Defines a description attribute attached to a specific sink - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Description (C string). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(description, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_DESCRIPTION, _id, _comp_class_id, sink, _x) - -/* - * Defines a help attribute attached to a specific source component - * class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Help (C string). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _id, _comp_class_id, source, _x) - -/* - * Defines a help attribute attached to a specific filter component - * class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Help (C string). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _id, _comp_class_id, filter, _x) - -/* - * Defines a help attribute attached to a specific sink component class - * descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Help (C string). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_HELP_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(help, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_HELP, _id, _comp_class_id, sink, _x) - -/* - * Defines an initialization method attribute attached to a specific - * source component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Initialization method (bt_component_class_source_initialize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _id, _comp_class_id, source, _x) - -/* - * Defines an initialization method attribute attached to a specific - * filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Initialization method (bt_component_class_filter_initialize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _id, _comp_class_id, filter, _x) - -/* - * Defines an initialization method attribute attached to a specific - * sink component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Initialization method (bt_component_class_sink_initialize_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INITIALIZE_METHOD, _id, _comp_class_id, sink, _x) - -/* - * Defines a "get supported MIP versions" attribute attached to a - * specific source component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: "Get supported MIP versions" method (bt_component_class_source_get_supported_mip_versions_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _id, _comp_class_id, source, _x) - -/* - * Defines a "get supported MIP versions" attribute attached to a - * specific filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: "Get supported MIP versions" method (bt_component_class_filter_get_supported_mip_versions_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _id, _comp_class_id, filter, _x) - -/* - * Defines a "get supported MIP versions" attribute attached to a - * specific sink component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: "Get supported MIP versions" method (bt_component_class_sink_get_supported_mip_versions_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_get_supported_mip_versions_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GET_SUPPORTED_MIP_VERSIONS, _id, _comp_class_id, sink, _x) - -/* - * Defines a finalization method attribute attached to a specific source - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Finalize method (bt_component_class_source_finalize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _id, _comp_class_id, source, _x) - -/* - * Defines a finalization method attribute attached to a specific filter - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Finalize method (bt_component_class_filter_finalize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _id, _comp_class_id, filter, _x) - -/* - * Defines a finalization method attribute attached to a specific sink - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Finalize method (bt_component_class_sink_finalize_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_FINALIZE_METHOD, _id, _comp_class_id, sink, _x) - -/* - * Defines a query method attribute attached to a specific source - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Finalize method (bt_component_class_source_query_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _id, _comp_class_id, source, _x) - -/* - * Defines a query method attribute attached to a specific filter - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Finalize method (bt_component_class_filter_query_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _id, _comp_class_id, filter, _x) - -/* - * Defines a query method attribute attached to a specific sink - * component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Finalize method (bt_component_class_sink_query_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_query_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_QUERY_METHOD, _id, _comp_class_id, sink, _x) - -/* - * Defines an input port connected method attribute attached to a - * specific filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Port connected method - * (bt_component_class_filter_input_port_connected_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_input_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, filter, _x) - -/* - * Defines an input port connected method attribute attached to a - * specific sink component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Port connected method - * (bt_component_class_sink_input_port_connected_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_input_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_INPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, sink, _x) - -/* - * Defines an output port connected method attribute attached to a - * specific source component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Port connected method - * (bt_component_class_source_output_port_connected_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(source_output_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_OUTPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, source, _x) - -/* - * Defines an output port connected method attribute attached to a - * specific filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Port connected method - * (bt_component_class_filter_output_port_connected_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(filter_output_port_connected_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_OUTPUT_PORT_CONNECTED_METHOD, _id, _comp_class_id, filter, _x) - -/* - * Defines a "graph is configured" method attribute attached to a - * specific sink component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: "Graph is configured" method - * (bt_component_class_sink_graph_is_configured_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(sink_graph_is_configured_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_GRAPH_IS_CONFIGURED_METHOD, _id, _comp_class_id, sink, _x) - -/* - * Defines an iterator initialization method attribute attached to a - * specific source component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Iterator initialization method - * (bt_component_class_source_message_iterator_initialize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_INITIALIZE_METHOD, _id, _comp_class_id, source, _x) - -/* - * Defines an iterator finalize method attribute attached to a specific - * source component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Iterator finalize method - * (bt_component_class_source_message_iterator_finalize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_FINALIZE_METHOD, _id, _comp_class_id, source, _x) - -/* - * Defines an iterator "seek nanoseconds from origin" and "can seek nanoseconds - * from origin" method attributes attached to a specific source component class - * descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _seek_method: Iterator "seek nanoseconds from origin" method - * (bt_component_class_source_message_iterator_seek_ns_from_origin_method). - * _can_seek_method: Iterator "can seek nanoseconds from origin" method - * (bt_component_class_source_message_iterator_can_seek_ns_from_origin_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, source, _seek_method); \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, source, _can_seek_method) - -/* - * Defines an iterator "seek beginning" and "can seek beginning" method - * attributes attached to a specific source component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _seek_method: Iterator "seek beginning" method - * (bt_component_class_source_message_iterator_seek_beginning_method). - * _can_seek_method: Iterator "can seek beginning" method - * (bt_component_class_source_message_iterator_can_seek_beginning_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_BEGINNING_METHOD, _id, _comp_class_id, source, _seek_method); \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_BEGINNING_METHOD, _id, _comp_class_id, source, _can_seek_method) - -/* - * Defines an iterator initialization method attribute attached to a - * specific filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Iterator initialization method - * (bt_component_class_filter_message_iterator_initialize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_initialize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_INITIALIZE_METHOD, _id, _comp_class_id, filter, _x) - -/* - * Defines an iterator finalize method attribute attached to a specific - * filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _x: Iterator finalize method - * (bt_component_class_filter_message_iterator_finalize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(_id, _comp_class_id, _x) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_finalize_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_FINALIZE_METHOD, _id, _comp_class_id, filter, _x) - -/* - * Defines an iterator "seek nanoseconds" and "can seek nanoseconds from origin" - * method attributes attached to a specific filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _seek_method: Iterator "seek nanoseconds from origin" method - * (bt_component_class_filter_message_iterator_seek_ns_from_origin_method). - * _can_seek_method: Iterator "can seek nanoseconds from origin" method - * (bt_component_class_filter_message_iterator_can_seek_ns_from_origin_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, filter, _seek_method); \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_ns_from_origin_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_NS_FROM_ORIGIN_METHOD, _id, _comp_class_id, filter, _can_seek_method) - -/* - * Defines an iterator "seek beginning" and "can seek beginning" method - * attributes attached to a specific filter component class descriptor. - * - * _id: Plugin descriptor ID (C identifier). - * _comp_class_id: Component class descriptor ID (C identifier). - * _seek_method: Iterator "seek beginning" method - * (bt_component_class_filter_message_iterator_seek_beginning_method). - * _can_seek_method: Iterator "can seek beginning" method - * (bt_component_class_filter_message_iterator_can_seek_beginning_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(_id, _comp_class_id, _seek_method, _can_seek_method) \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_SEEK_BEGINNING_METHOD, _id, _comp_class_id, filter, _seek_method); \ - __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE(msg_iter_can_seek_beginning_method, BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTE_TYPE_MSG_ITER_CAN_SEEK_BEGINNING_METHOD, _id, _comp_class_id, filter, _can_seek_method); - -/* - * Defines a plugin descriptor with an automatic ID. - * - * _name: Plugin's name (C string). - */ -#define BT_PLUGIN(_name) static BT_PLUGIN_WITH_ID(auto, #_name) - -/* - * Defines a plugin initialization function attribute attached to the - * automatic plugin descriptor. - * - * _x: Initialization function (bt_plugin_initialize_func). - */ -#define BT_PLUGIN_INITIALIZE_FUNC(_x) BT_PLUGIN_INITIALIZE_FUNC_WITH_ID(auto, _x) - - /* - * Defines a plugin exit function attribute attached to the automatic - * plugin descriptor. - * - * _x: Exit function (bt_plugin_finalize_func). - */ -#define BT_PLUGIN_FINALIZE_FUNC(_x) BT_PLUGIN_FINALIZE_FUNC_WITH_ID(auto, _x) - -/* - * Defines an author attribute attached to the automatic plugin - * descriptor. - * - * _x: Author (C string). - */ -#define BT_PLUGIN_AUTHOR(_x) BT_PLUGIN_AUTHOR_WITH_ID(auto, _x) - -/* - * Defines a license attribute attached to the automatic plugin - * descriptor. - * - * _x: License (C string). - */ -#define BT_PLUGIN_LICENSE(_x) BT_PLUGIN_LICENSE_WITH_ID(auto, _x) - -/* - * Defines a description attribute attached to the automatic plugin - * descriptor. - * - * _x: Description (C string). - */ -#define BT_PLUGIN_DESCRIPTION(_x) BT_PLUGIN_DESCRIPTION_WITH_ID(auto, _x) - -/* - * Defines a version attribute attached to the automatic plugin - * descriptor. - * - * _major: Plugin's major version (uint32_t). - * _minor: Plugin's minor version (uint32_t). - * _patch: Plugin's patch version (uint32_t). - * _extra: Plugin's version extra information (C string). - */ -#define BT_PLUGIN_VERSION(_major, _minor, _patch, _extra) BT_PLUGIN_VERSION_WITH_ID(auto, _major, _minor, _patch, _extra) - -/* - * Defines a source component class attached to the automatic plugin - * descriptor. Its ID is the same as its name, hence its name must be a - * C identifier in this version. - * - * _name: Component class name (C identifier). - * _msg_iter_next_method: Component class's iterator next method - * (bt_component_class_source_message_iterator_next_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS(_name, _msg_iter_next_method) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _msg_iter_next_method) - -/* - * Defines a filter component class attached to the automatic plugin - * descriptor. Its ID is the same as its name, hence its name must be a - * C identifier in this version. - * - * _name: Component class name (C identifier). - * _msg_iter_next_method: Component class's iterator next method - * (bt_component_class_filter_message_iterator_next_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS(_name, _msg_iter_next_method) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _msg_iter_next_method) - -/* - * Defines a sink component class attached to the automatic plugin - * descriptor. Its ID is the same as its name, hence its name must be a - * C identifier in this version. - * - * _name: Component class name (C identifier). - * _consume_method: Component class's consume method - * (bt_component_class_sink_consume_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS(_name, _consume_method) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_WITH_ID(auto, _name, #_name, _consume_method) - -/* - * Defines a description attribute attached to a source component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Description (C string). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _x) - -/* - * Defines a description attribute attached to a filter component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Description (C string). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _x) - -/* - * Defines a description attribute attached to a sink component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Description (C string). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_DESCRIPTION_WITH_ID(auto, _name, _x) - -/* - * Defines a help attribute attached to a source component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Help (C string). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _x) - -/* - * Defines a help attribute attached to a filter component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Help (C string). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _x) - -/* - * Defines a help attribute attached to a sink component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Help (C string). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_HELP(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_HELP_WITH_ID(auto, _name, _x) - -/* - * Defines an initialization method attribute attached to a source - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_source_initialize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an initialization method attribute attached to a filter - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_filter_initialize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an initialization method attribute attached to a sink - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_sink_initialize_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a "get supported MIP versions" method attribute attached to a - * source component class descriptor which is attached to the automatic - * plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_source_get_supported_mip_versions_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a "get supported MIP versions" method attribute attached to a - * filter component class descriptor which is attached to the automatic - * plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_filter_get_supported_mip_versions_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a "get supported MIP versions" method attribute attached to a - * sink component class descriptor which is attached to the automatic - * plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_sink_get_supported_mip_versions_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_GET_SUPPORTED_MIP_VERSIONS_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a finalization method attribute attached to a source component - * class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_source_finalize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a finalization method attribute attached to a filter component - * class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_filter_finalize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a finalization method attribute attached to a sink component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_sink_finalize_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a query method attribute attached to a source component - * class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_source_query_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a query method attribute attached to a filter component - * class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_filter_query_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a query method attribute attached to a sink component - * class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Initialization method (bt_component_class_sink_query_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_QUERY_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an input port connected method attribute attached to a filter - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Port connected (bt_component_class_filter_input_port_connected_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an input port connected method attribute attached to a sink - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Port connected (bt_component_class_sink_input_port_connected_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_INPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an output port connected method attribute attached to a source - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Port connected (bt_component_class_source_output_port_connected_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an output port connected method attribute attached to a filter - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Port connected (bt_component_class_filter_output_port_connected_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_OUTPUT_PORT_CONNECTED_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines a "graph is configured" method attribute attached to - * a sink component class descriptor which is attached to the automatic - * plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: "Graph is configured" method - * (bt_component_class_sink_graph_is_configured_method). - */ -#define BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD(_name, _x) \ - BT_PLUGIN_SINK_COMPONENT_CLASS_GRAPH_IS_CONFIGURED_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an iterator initialization method attribute attached to a - * source component class descriptor which is attached to the automatic - * plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Iterator initialization method - * (bt_component_class_source_message_iterator_initialize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an iterator finalize method attribute attached to a source - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Iterator finalize method - * (bt_component_class_source_message_iterator_finalize_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(_name, _x) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an iterator "seek nanoseconds from origin" and "can seek nanoseconds - * from origin" method attributes attached to a source component class - * descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _seek_method: Iterator "seek nanoseconds from origin" method - * (bt_component_class_source_message_iterator_seek_ns_from_origin_method). - * _can_seek_method: Iterator "can seek nanoseconds from origin" method - * (bt_component_class_source_message_iterator_can_seek_ns_from_origin_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS(_name, _seek_method, _can_seek_method) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method) - -/* - * Defines an iterator "seek beginning" and "can seek beginning" method - * attributes attached to a source component class descriptor which is attached - * to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _seek_method: Iterator "can seek beginning" method - * (bt_component_class_source_message_iterator_can_seek_beginning_method). - * _can_seek_method: Iterator "can seek beginning" method - * (bt_component_class_source_message_iterator_seek_beginning_method). - */ -#define BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS(_name, _seek_method, _can_seek_method) \ - BT_PLUGIN_SOURCE_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method) - -/* - * Defines an iterator initialization method attribute attached to a - * filter component class descriptor which is attached to the automatic - * plugin descriptor. - * - * _name: Component class name (C identifier). - * _x: Iterator initialization method - * (bt_component_class_filter_message_iterator_initialize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_INITIALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an iterator finalize method attribute attached to a filter - * component class descriptor which is attached to the automatic plugin - * descriptor. - * - * _name: Component class name (C identifier). - * _x: Iterator finalize method - * (bt_component_class_filter_message_iterator_finalize_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD(_name, _x) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_FINALIZE_METHOD_WITH_ID(auto, _name, _x) - -/* - * Defines an iterator "seek nanosecconds from origin" and "can seek - * nanoseconds from origin" method attributes attached to a filter component - * class descriptor which is attached to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _seek_method: Iterator "seek nanoseconds from origin" method - * (bt_component_class_filter_message_iterator_seek_ns_from_origin_method). - * _can_seek_method: Iterator "can seek nanoseconds from origin" method - * (bt_component_class_filter_message_iterator_can_seek_ns_from_origin_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS(_name, _seek_method, _can_seek_method) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_NS_FROM_ORIGIN_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method) - -/* - * Defines an iterator "seek beginning" and "can seek beginning" method - * attributes attached to a filter component class descriptor which is attached - * to the automatic plugin descriptor. - * - * _name: Component class name (C identifier). - * _seek_method: Iterator "seek beginning" method - * (bt_component_class_filter_message_iterator_seek_beginning_method). - * _can_seek_method: Iterator "can seek beginning" method - * (bt_component_class_filter_message_iterator_can_seek_beginning_method). - */ -#define BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS(_name, _seek_method, _can_seek_method) \ - BT_PLUGIN_FILTER_COMPONENT_CLASS_MESSAGE_ITERATOR_CLASS_SEEK_BEGINNING_METHODS_WITH_ID(auto, _name, _seek_method, _can_seek_method) - -#define BT_PLUGIN_MODULE() \ - static struct __bt_plugin_descriptor const * const __bt_plugin_descriptor_dummy __BT_PLUGIN_DESCRIPTOR_ATTRS = NULL; \ - _BT_HIDDEN extern struct __bt_plugin_descriptor const *__BT_PLUGIN_DESCRIPTOR_BEGIN_SYMBOL __BT_PLUGIN_DESCRIPTOR_BEGIN_EXTRA; \ - _BT_HIDDEN extern struct __bt_plugin_descriptor const *__BT_PLUGIN_DESCRIPTOR_END_SYMBOL __BT_PLUGIN_DESCRIPTOR_END_EXTRA; \ - \ - static struct __bt_plugin_descriptor_attribute const * const __bt_plugin_descriptor_attribute_dummy __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_ATTRS = NULL; \ - _BT_HIDDEN extern struct __bt_plugin_descriptor_attribute const *__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_EXTRA; \ - _BT_HIDDEN extern struct __bt_plugin_descriptor_attribute const *__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_SYMBOL __BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_EXTRA; \ - \ - static struct __bt_plugin_component_class_descriptor const * const __bt_plugin_component_class_descriptor_dummy __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRS = NULL; \ - _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_EXTRA; \ - _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_EXTRA; \ - \ - static struct __bt_plugin_component_class_descriptor_attribute const * const __bt_plugin_component_class_descriptor_attribute_dummy __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_ATTRS = NULL; \ - _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor_attribute const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_EXTRA; \ - _BT_HIDDEN extern struct __bt_plugin_component_class_descriptor_attribute const *__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_SYMBOL __BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_EXTRA; \ - \ - struct __bt_plugin_descriptor const * const *__bt_get_begin_section_plugin_descriptors(void) \ - { \ - return &__BT_PLUGIN_DESCRIPTOR_BEGIN_SYMBOL; \ - } \ - struct __bt_plugin_descriptor const * const *__bt_get_end_section_plugin_descriptors(void) \ - { \ - return &__BT_PLUGIN_DESCRIPTOR_END_SYMBOL; \ - } \ - struct __bt_plugin_descriptor_attribute const * const *__bt_get_begin_section_plugin_descriptor_attributes(void) \ - { \ - return &__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL; \ - } \ - struct __bt_plugin_descriptor_attribute const * const *__bt_get_end_section_plugin_descriptor_attributes(void) \ - { \ - return &__BT_PLUGIN_DESCRIPTOR_ATTRIBUTES_END_SYMBOL; \ - } \ - struct __bt_plugin_component_class_descriptor const * const *__bt_get_begin_section_component_class_descriptors(void) \ - { \ - return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_BEGIN_SYMBOL; \ - } \ - struct __bt_plugin_component_class_descriptor const * const *__bt_get_end_section_component_class_descriptors(void) \ - { \ - return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_END_SYMBOL; \ - } \ - struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_begin_section_component_class_descriptor_attributes(void) \ - { \ - return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_BEGIN_SYMBOL; \ - } \ - struct __bt_plugin_component_class_descriptor_attribute const * const *__bt_get_end_section_component_class_descriptor_attributes(void) \ - { \ - return &__BT_PLUGIN_COMPONENT_CLASS_DESCRIPTOR_ATTRIBUTES_END_SYMBOL; \ - } - #ifdef __cplusplus } #endif diff --git a/include/babeltrace2/plugin/plugin-loading.h b/include/babeltrace2/plugin/plugin-loading.h new file mode 100644 index 00000000..c95b53c5 --- /dev/null +++ b/include/babeltrace2/plugin/plugin-loading.h @@ -0,0 +1,1432 @@ +#ifndef BABELTRACE2_PLUGIN_PLUGIN_LOADING_H +#define BABELTRACE2_PLUGIN_PLUGIN_LOADING_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include +#include + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*! +@defgroup api-plugin Plugin loading + +@brief + Plugin loading functions. + +A plugin 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 find and load + 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: + +
+
Shared object plugin
+
+ .so file on Unix systems; + .dll file on Windows systems. +
+ +
Python 3 plugin
+
+ .py file which starts with the + bt_plugin_ prefix. +
+ +
Static plugin
+
+ A plugin built directly into libbabeltrace2 or into the + user application. +
+
+ +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 plugin set, that is, a shared object +containing one or more plugins. + +

Find and load plugins

+ +\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. + +-# $HOME/.local/lib/babeltrace2/plugins, + without recursing. + +-# The system \bt_name plugin directory, typically + /usr/lib/babeltrace2/plugins or + /usr/local/lib/babeltrace2/plugins 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. + +

Find and load a plugin by name

+ +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. + +

Find and load all the plugins from the default directories

+ +Load all the plugins found in the +\ref api-plugin-def-dirs "default plugin search directories" +and static plugins with bt_plugin_find_all(). + +

Find and load plugins from a specific file or directory

+ +Find and load plugins from a specific file (.so, +.dll, or .py) 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. + +

Find and load static plugins

+ +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. + +

Plugin properties

+ +A plugin has the following properties: + +
+
+ \anchor api-plugin-prop-name + Name +
+
+ 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 + Dan. + + Use bt_plugin_get_name(). +
+ +
+ \anchor api-plugin-prop-descr + \bt_dt_opt Description +
+
+ Description of the plugin. + + Use bt_plugin_get_description(). +
+ +
+ \anchor api-plugin-prop-author + \bt_dt_opt Author name(s) +
+
+ Name(s) of the plugin's author(s). + + Use bt_plugin_get_author(). +
+ +
+ \anchor api-plugin-prop-license + \bt_dt_opt License +
+
+ License or license name of the plugin. + + Use bt_plugin_get_license(). +
+ +
+ \anchor api-plugin-prop-path + \bt_dt_opt Path +
+
+ Path of the file which contains the plugin. + + A static plugin has no path property. + + Get bt_plugin_get_path(). +
+ +
+ \anchor api-plugin-prop-version + \bt_dt_opt Version +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + +-# If the \bt_p{find_in_std_env_var} parameter is + #BT_TRUE, + 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. + +-# If the \bt_p{find_in_user_dir} parameter is + #BT_TRUE, $HOME/.local/lib/babeltrace2/plugins, + without recursing. + +-# If the \bt_p{find_in_sys_dir} is #BT_TRUE, the + system \bt_name plugin directory, typically + /usr/lib/babeltrace2/plugins or + /usr/local/lib/babeltrace2/plugins on Linux, without + recursing. + +-# If the \bt_p{find_in_static} is #BT_TRUE, + 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 Dan. + +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: + +
+
If \bt_p{fail_on_load_error} is #BT_TRUE
+
Returns #BT_PLUGIN_FIND_STATUS_ERROR.
+ +
If \bt_p{fail_on_load_error} is #BT_FALSE
+
Ignores the loading error and continues searching.
+
+ +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 $HOME/.local/lib/babeltrace2/plugins 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 + On success, \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: + +-# If the \bt_p{find_in_std_env_var} parameter is + #BT_TRUE, + 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. + +-# If the \bt_p{find_in_user_dir} parameter is + #BT_TRUE, $HOME/.local/lib/babeltrace2/plugins, + without recursing. + +-# If the \bt_p{find_in_sys_dir} is #BT_TRUE, the + system \bt_name plugin directory, typically + /usr/lib/babeltrace2/plugins or + /usr/local/lib/babeltrace2/plugins on Linux, without + recursing. + +-# If the \bt_p{find_in_static} is #BT_TRUE, + 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: + +
+
If \bt_p{fail_on_load_error} is #BT_TRUE
+
Returns #BT_PLUGIN_FIND_ALL_STATUS_ERROR.
+ +
If \bt_p{fail_on_load_error} is #BT_FALSE
+
Ignores the loading error and continues searching.
+
+ +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 $HOME/.local/lib/babeltrace2/plugins 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 + On success, \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 Dan. + +If any plugin loading error occurs during this function's execution, the +function: + +
+
If \bt_p{fail_on_load_error} is #BT_TRUE
+
Returns #BT_PLUGIN_FIND_ALL_FROM_FILE_STATUS_ERROR.
+ +
If \bt_p{fail_on_load_error} is #BT_FALSE
+
Ignores the loading error and continues.
+
+ +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 + On success, \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: + +
+
If \bt_p{fail_on_load_error} is #BT_TRUE
+
Returns #BT_PLUGIN_FIND_ALL_FROM_DIR_STATUS_ERROR.
+ +
If \bt_p{fail_on_load_error} is #BT_FALSE
+
Ignores the loading error and continues.
+
+ +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 + On success, \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: + +
+
If \bt_p{fail_on_load_error} is #BT_TRUE
+
Returns #BT_PLUGIN_FIND_ALL_FROM_STATIC_STATUS_ERROR.
+ +
If \bt_p{fail_on_load_error} is #BT_FALSE
+
Ignores the loading error and continues.
+
+ +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 + On success, \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 + If not \c NULL and this function returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE, \bt_p{*major} is the + major version of \bt_p{plugin}. +@param[out] minor + If not \c NULL and this function returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE, \bt_p{*minor} is the + minor version of \bt_p{plugin}. +@param[out] patch + If not \c NULL and this function returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE, \bt_p{*patch} is the + patch version of \bt_p{plugin}. +@param[out] extra + @parblock + If not \c NULL and this function returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE, \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 */ diff --git a/include/babeltrace2/plugin/plugin-set-const.h b/include/babeltrace2/plugin/plugin-set-const.h deleted file mode 100644 index 209e1d33..00000000 --- a/include/babeltrace2/plugin/plugin-set-const.h +++ /dev/null @@ -1,65 +0,0 @@ -#ifndef BABELTRACE2_PLUGIN_PLUGIN_SET_CONST_H -#define BABELTRACE2_PLUGIN_PLUGIN_SET_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern uint64_t bt_plugin_set_get_plugin_count( - const bt_plugin_set *plugin_set); - -extern const bt_plugin *bt_plugin_set_borrow_plugin_by_index_const( - const bt_plugin_set *plugin_set, uint64_t index); - -extern void bt_plugin_set_get_ref(const bt_plugin_set *plugin_set); - -extern void bt_plugin_set_put_ref(const bt_plugin_set *plugin_set); - -#define BT_PLUGIN_SET_PUT_REF_AND_RESET(_var) \ - do { \ - bt_plugin_set_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_PLUGIN_SET_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_plugin_set_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_PLUGIN_PLUGIN_SET_CONST_H */ diff --git a/include/babeltrace2/property.h b/include/babeltrace2/property.h deleted file mode 100644 index 1ede1425..00000000 --- a/include/babeltrace2/property.h +++ /dev/null @@ -1,43 +0,0 @@ -#ifndef BABELTRACE2_PROPERTY_H -#define BABELTRACE2_PROPERTY_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_property_availability { - BT_PROPERTY_AVAILABILITY_NOT_AVAILABLE = 0, - BT_PROPERTY_AVAILABILITY_AVAILABLE = 1, -} bt_property_availability; - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_PROPERTY_H */ diff --git a/include/babeltrace2/trace-ir/clock-class-const.h b/include/babeltrace2/trace-ir/clock-class-const.h deleted file mode 100644 index 6316f83f..00000000 --- a/include/babeltrace2/trace-ir/clock-class-const.h +++ /dev/null @@ -1,93 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_CLOCK_CLASS_CONST_H -#define BABELTRACE2_TRACE_IR_CLOCK_CLASS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_value *bt_clock_class_borrow_user_attributes_const( - const bt_clock_class *clock_class); - -extern const char *bt_clock_class_get_name( - const bt_clock_class *clock_class); - -extern const char *bt_clock_class_get_description( - const bt_clock_class *clock_class); - -extern uint64_t bt_clock_class_get_frequency( - const bt_clock_class *clock_class); - -extern uint64_t bt_clock_class_get_precision( - const bt_clock_class *clock_class); - -extern void bt_clock_class_get_offset(const bt_clock_class *clock_class, - int64_t *seconds, uint64_t *cycles); - -extern bt_bool bt_clock_class_origin_is_unix_epoch( - const bt_clock_class *clock_class); - -extern bt_uuid bt_clock_class_get_uuid( - const bt_clock_class *clock_class); - -typedef enum bt_clock_class_cycles_to_ns_from_origin_status { - BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR = __BT_FUNC_STATUS_OVERFLOW_ERROR, - BT_CLOCK_CLASS_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_clock_class_cycles_to_ns_from_origin_status; - -extern bt_clock_class_cycles_to_ns_from_origin_status -bt_clock_class_cycles_to_ns_from_origin( - const bt_clock_class *clock_class, - uint64_t cycles, int64_t *ns_from_origin); - -extern void bt_clock_class_get_ref(const bt_clock_class *clock_class); - -extern void bt_clock_class_put_ref(const bt_clock_class *clock_class); - -#define BT_CLOCK_CLASS_PUT_REF_AND_RESET(_var) \ - do { \ - bt_clock_class_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_CLOCK_CLASS_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_clock_class_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_CLOCK_CLASS_CONST_H */ diff --git a/include/babeltrace2/trace-ir/clock-class.h b/include/babeltrace2/trace-ir/clock-class.h index 5d0c5987..4fbbf533 100644 --- a/include/babeltrace2/trace-ir/clock-class.h +++ b/include/babeltrace2/trace-ir/clock-class.h @@ -35,45 +35,954 @@ extern "C" { #endif -extern bt_clock_class *bt_clock_class_create(bt_self_component *self_comp); +/*! +@defgroup api-tir-clock-cls Clock class +@ingroup api-tir -extern bt_value *bt_clock_class_borrow_user_attributes( - bt_clock_class *clock_class); +@brief + Class of \bt_stream clocks. -extern void bt_clock_class_set_user_attributes( - bt_clock_class *clock_class, const bt_value *user_attributes); +A clock class is the class of \bt_stream +clocks. + +A clock class is a \ref api-tir "trace IR" metadata object. + +Stream clocks 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(). + +

\anchor api-tir-clock-cls-origin Clock value vs. clock class origin

+ +The value of a \bt_stream clock (a conceptual instance of a clock class) +is in cycles. 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: + +
+
If bt_clock_class_origin_is_unix_epoch() returns #BT_TRUE
+
+ The + Unix epoch. + + The stream clocks of all the clock classes which have a Unix + epoch origin, whatever the clock class + UUIDs, + are correlatable. +
+ +
If bt_clock_class_origin_is_unix_epoch() returns #BT_FALSE
+
+ 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. +
+
+ +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 nanoseconds from origin 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. + +

Properties

+ +A clock class has the following properties: + +
+
\anchor api-tir-clock-cls-prop-freq Frequency
+
+ Frequency of the clock class's instances (stream clocks) + (cycles/second). + + Use bt_clock_class_set_frequency() and + bt_clock_class_get_frequency(). +
+ +
+ \anchor api-tir-clock-cls-prop-offset + Offset (in seconds and in cycles) +
+
+ 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(). +
+ +
\anchor api-tir-clock-cls-prop-precision Precision
+
+ 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(). +
+ +
+ \anchor api-tir-clock-cls-prop-origin-unix-epoch + Origin is Unix epoch? +
+
+ Whether or not the clock class's + \ref api-tir-clock-cls-origin "origin" + is the + Unix epoch. + + Use bt_clock_class_set_origin_is_unix_epoch() and + bt_clock_class_origin_is_unix_epoch(). +
+ +
\anchor api-tir-clock-cls-prop-name \bt_dt_opt Name
+
+ Name of the clock class. + + Use bt_clock_class_set_name() and bt_clock_class_get_name(). +
+ +
\anchor api-tir-clock-cls-prop-descr \bt_dt_opt Description
+
+ Description of the clock class. + + Use bt_clock_class_set_description() and + bt_clock_class_get_description(). +
+ +
\anchor api-tir-clock-cls-prop-uuid \bt_dt_opt UUID
+
+ UUID + of the clock class. + + The clock class's UUID uniquely identifies the clock class. + + When the clock class's origin is \em not the + Unix epoch, + 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(). +
+ +
+ \anchor api-tir-clock-cls-prop-user-attrs + \bt_dt_opt User attributes +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + + + + + + + + + + + + +
Property + Value +
\ref api-tir-clock-cls-prop-freq "Frequency" + 1 GHz +
\ref api-tir-clock-cls-prop-offset "Offset" in seconds + 0 seconds +
\ref api-tir-clock-cls-prop-offset "Offset" in cycles + 0 cycles +
\ref api-tir-clock-cls-prop-precision "Precision" + 0 cycles +
\ref api-tir-clock-cls-prop-origin-unix-epoch "Origin is Unix epoch?" + Yes +
\ref api-tir-clock-cls-prop-name "Name" + \em None +
\ref api-tir-clock-cls-prop-descr "Description" + \em None +
\ref api-tir-clock-cls-prop-uuid "UUID" + \em None +
\ref api-tir-clock-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 UINT64_C(-1). +@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 + Unix epoch. + +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 + Unix epoch. + +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 + UUID + 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 + On success, \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 diff --git a/include/babeltrace2/trace-ir/clock-snapshot-const.h b/include/babeltrace2/trace-ir/clock-snapshot-const.h deleted file mode 100644 index 3363b9df..00000000 --- a/include/babeltrace2/trace-ir/clock-snapshot-const.h +++ /dev/null @@ -1,58 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_CONST_H -#define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_clock_class *bt_clock_snapshot_borrow_clock_class_const( - const bt_clock_snapshot *clock_snapshot); - -extern uint64_t bt_clock_snapshot_get_value( - const bt_clock_snapshot *clock_snapshot); - -typedef enum bt_clock_snapshot_get_ns_from_origin_status { - BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR = __BT_FUNC_STATUS_OVERFLOW_ERROR, -} bt_clock_snapshot_get_ns_from_origin_status; - -extern bt_clock_snapshot_get_ns_from_origin_status -bt_clock_snapshot_get_ns_from_origin( - const bt_clock_snapshot *clock_snapshot, - int64_t *ns_from_origin); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_CONST_H */ diff --git a/include/babeltrace2/trace-ir/clock-snapshot.h b/include/babeltrace2/trace-ir/clock-snapshot.h new file mode 100644 index 00000000..23d86781 --- /dev/null +++ b/include/babeltrace2/trace-ir/clock-snapshot.h @@ -0,0 +1,228 @@ +#ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H +#define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*! +@defgroup api-tir-cs Clock snapshot +@ingroup api-tir + +@brief + Snapshot of a \bt_stream clock. + +A clock snapshot 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. + +Stream clocks 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 + On success, \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 */ diff --git a/include/babeltrace2/trace-ir/event-class-const.h b/include/babeltrace2/trace-ir/event-class-const.h deleted file mode 100644 index fa1ff786..00000000 --- a/include/babeltrace2/trace-ir/event-class-const.h +++ /dev/null @@ -1,103 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_EVENT_CLASS_CONST_H -#define BABELTRACE2_TRACE_IR_EVENT_CLASS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_event_class_log_level { - BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY = 0, - BT_EVENT_CLASS_LOG_LEVEL_ALERT = 1, - BT_EVENT_CLASS_LOG_LEVEL_CRITICAL = 2, - BT_EVENT_CLASS_LOG_LEVEL_ERROR = 3, - BT_EVENT_CLASS_LOG_LEVEL_WARNING = 4, - BT_EVENT_CLASS_LOG_LEVEL_NOTICE = 5, - BT_EVENT_CLASS_LOG_LEVEL_INFO = 6, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM = 7, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM = 8, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS = 9, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE = 10, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT = 11, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION = 12, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE = 13, - BT_EVENT_CLASS_LOG_LEVEL_DEBUG = 14, -} bt_event_class_log_level; - -extern const bt_value *bt_event_class_borrow_user_attributes_const( - const bt_event_class *event_class); - -extern const bt_stream_class *bt_event_class_borrow_stream_class_const( - const bt_event_class *event_class); - -extern const char *bt_event_class_get_name(const bt_event_class *event_class); - -extern uint64_t bt_event_class_get_id(const bt_event_class *event_class); - -extern bt_property_availability bt_event_class_get_log_level( - const bt_event_class *event_class, - bt_event_class_log_level *log_level); - -extern const char *bt_event_class_get_emf_uri( - const bt_event_class *event_class); - -extern const bt_field_class * -bt_event_class_borrow_specific_context_field_class_const( - const bt_event_class *event_class); - -extern const bt_field_class *bt_event_class_borrow_payload_field_class_const( - const bt_event_class *event_class); - -extern void bt_event_class_get_ref(const bt_event_class *event_class); - -extern void bt_event_class_put_ref(const bt_event_class *event_class); - -#define BT_EVENT_CLASS_PUT_REF_AND_RESET(_var) \ - do { \ - bt_event_class_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_EVENT_CLASS_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_event_class_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_EVENT_CLASS_CONST_H */ diff --git a/include/babeltrace2/trace-ir/event-class.h b/include/babeltrace2/trace-ir/event-class.h index e435d387..c82e6263 100644 --- a/include/babeltrace2/trace-ir/event-class.h +++ b/include/babeltrace2/trace-ir/event-class.h @@ -29,67 +29,1028 @@ #include -#include #include #ifdef __cplusplus extern "C" { #endif +/*! +@defgroup api-tir-ev-cls Event class +@ingroup api-tir + +@brief + Class of \bt_p_ev. + +An event class 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: + +
+
+ If bt_stream_class_assigns_automatic_event_class_id() returns + #BT_TRUE (the default) for the stream class to use +
+
Use bt_event_class_create().
+ +
+ If bt_stream_class_assigns_automatic_event_class_id() returns + #BT_FALSE for the stream class to use +
+
Use bt_event_class_create_with_id().
+
+ +

Properties

+ +An event class has the following properties: + +
+
\anchor api-tir-ev-cls-prop-id Numeric ID
+
+ 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(). +
+ +
\anchor api-tir-ev-cls-prop-name \bt_dt_opt Name
+
+ Name of the event class. + + Use bt_event_class_set_name() and bt_event_class_get_name(). +
+ +
\anchor api-tir-ev-cls-prop-log-lvl \bt_dt_opt Log level
+
+ 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(). +
+ +
+ \anchor api-tir-ev-cls-prop-emf-uri + \bt_dt_opt Eclipse Modeling Framework (EMF) URI +
+
+ EMF URI of the event class. + + Use bt_event_class_set_emf_uri() and + bt_event_class_get_emf_uri(). +
+ +
+ \anchor api-tir-ev-cls-prop-p-fc + \bt_dt_opt Payload field class +
+
+ 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(). +
+ +
+ \anchor api-tir-ev-cls-prop-sc-fc + \bt_dt_opt Specific context field class +
+
+ 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(). +
+ +
+ \anchor api-tir-ev-cls-prop-user-attrs + \bt_dt_opt User attributes +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + + + + + + + + + + +
Property + Value +
\ref api-tir-ev-cls-prop-id "Numeric ID" + Automatically assigned by \bt_p{stream_class} +
\ref api-tir-ev-cls-prop-name "Name" + \em None +
\ref api-tir-ev-cls-prop-log-lvl "Log level" + \em None +
\ref api-tir-ev-cls-prop-emf-uri "EMF URI" + \em None +
\ref api-tir-ev-cls-prop-p-fc "Payload field class" + \em None +
\ref api-tir-ev-cls-prop-sc-fc "Specific context field class" + \em None +
\ref api-tir-ev-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + bt_stream_class_assigns_automatic_event_class_id(stream_class) + 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: + + + + + + + + + + +
Property + Value +
\ref api-tir-ev-cls-prop-id "Numeric ID" + \bt_p{id} +
\ref api-tir-ev-cls-prop-name "Name" + \em None +
\ref api-tir-ev-cls-prop-log-lvl "Log level" + \em None +
\ref api-tir-ev-cls-prop-emf-uri "EMF URI" + \em None +
\ref api-tir-ev-cls-prop-p-fc "Payload field class" + \em None +
\ref api-tir-ev-cls-prop-sc-fc "Specific context field class" + \em None +
\ref api-tir-ev-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + bt_stream_class_assigns_automatic_event_class_id(stream_class) + 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 + If this function returns + #BT_PROPERTY_AVAILABILITY_AVAILABLE, \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 diff --git a/include/babeltrace2/trace-ir/event-const.h b/include/babeltrace2/trace-ir/event-const.h deleted file mode 100644 index fec42ea0..00000000 --- a/include/babeltrace2/trace-ir/event-const.h +++ /dev/null @@ -1,58 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_EVENT_CONST_H -#define BABELTRACE2_TRACE_IR_EVENT_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_event_class *bt_event_borrow_class_const( - const bt_event *event); - -extern const bt_packet *bt_event_borrow_packet_const( - const bt_event *event); - -extern const bt_stream *bt_event_borrow_stream_const( - const bt_event *event); - -extern const bt_field *bt_event_borrow_common_context_field_const( - const bt_event *event); - -extern const bt_field *bt_event_borrow_specific_context_field_const( - const bt_event *event); - -extern const bt_field *bt_event_borrow_payload_field_const( - const bt_event *event); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_EVENT_CONST_H */ diff --git a/include/babeltrace2/trace-ir/event.h b/include/babeltrace2/trace-ir/event.h index 12a27563..f1431844 100644 --- a/include/babeltrace2/trace-ir/event.h +++ b/include/babeltrace2/trace-ir/event.h @@ -33,19 +33,346 @@ extern "C" { #endif +/*! +@defgroup api-tir-ev Event +@ingroup api-tir + +@brief + Trace event. + +An event 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 +bt_event_create() 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. + +

Properties

+ +An event has the following properties: + +
+
\anchor api-tir-ev-prop-payload Payload field
+
+ 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(). +
+ +
\anchor api-tir-ev-prop-spec-ctx Specific context field
+
+ 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(). +
+ +
\anchor api-tir-ev-prop-common-ctx Common context field
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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 } diff --git a/include/babeltrace2/trace-ir/field-class-const.h b/include/babeltrace2/trace-ir/field-class-const.h deleted file mode 100644 index 2a5c88d6..00000000 --- a/include/babeltrace2/trace-ir/field-class-const.h +++ /dev/null @@ -1,313 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_FIELD_CLASS_CONST_H -#define BABELTRACE2_TRACE_IR_FIELD_CLASS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_field_class_type { - BT_FIELD_CLASS_TYPE_BOOL = 1ULL << 0, - BT_FIELD_CLASS_TYPE_BIT_ARRAY = 1ULL << 1, - BT_FIELD_CLASS_TYPE_INTEGER = 1ULL << 2, - BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER = (1ULL << 3) | BT_FIELD_CLASS_TYPE_INTEGER, - BT_FIELD_CLASS_TYPE_SIGNED_INTEGER = (1ULL << 4) | BT_FIELD_CLASS_TYPE_INTEGER, - BT_FIELD_CLASS_TYPE_ENUMERATION = 1ULL << 5, - BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER, - BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION = BT_FIELD_CLASS_TYPE_ENUMERATION | BT_FIELD_CLASS_TYPE_SIGNED_INTEGER, - BT_FIELD_CLASS_TYPE_REAL = 1ULL << 6, - BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL = (1ULL << 7) | BT_FIELD_CLASS_TYPE_REAL, - BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL = (1ULL << 8) | BT_FIELD_CLASS_TYPE_REAL, - BT_FIELD_CLASS_TYPE_STRING = 1ULL << 9, - BT_FIELD_CLASS_TYPE_STRUCTURE = 1ULL << 10, - BT_FIELD_CLASS_TYPE_ARRAY = 1ULL << 11, - BT_FIELD_CLASS_TYPE_STATIC_ARRAY = (1ULL << 12) | BT_FIELD_CLASS_TYPE_ARRAY, - BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY = (1ULL << 13) | BT_FIELD_CLASS_TYPE_ARRAY, - BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD = (1ULL << 14) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY, - BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD = (1ULL << 15) | BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY, - BT_FIELD_CLASS_TYPE_OPTION = 1ULL << 16, - BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD = (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION, - BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD = (1ULL << 18) | BT_FIELD_CLASS_TYPE_OPTION, - BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD = (1ULL << 19) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD, - BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD = (1ULL << 20) | BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD, - BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 21) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD, - BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 22) | BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD, - BT_FIELD_CLASS_TYPE_VARIANT = 1ULL << 23, - BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD = (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT, - BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD = (1ULL << 25) | BT_FIELD_CLASS_TYPE_VARIANT, - BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD = (1ULL << 26) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD, - BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 27) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD, - BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD = (1ULL << 28) | BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD, - - /* - * Make sure the enumeration type is a 64-bit integer in case - * the project needs field class types in the future. - * - * This is not part of the API. - */ - __BT_FIELD_CLASS_TYPE_BIG_VALUE = 1ULL << 62, -} bt_field_class_type; - -typedef enum bt_field_class_integer_preferred_display_base { - BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_BINARY = 2, - BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_OCTAL = 8, - BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL = 10, - BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_HEXADECIMAL = 16, -} bt_field_class_integer_preferred_display_base; - -extern bt_field_class_type bt_field_class_get_type( - const bt_field_class *field_class); - -static inline -bt_bool bt_field_class_type_is(const bt_field_class_type type, - const bt_field_class_type type_to_check) -{ - return (type & type_to_check) == type_to_check; -} - -extern const bt_value *bt_field_class_borrow_user_attributes_const( - const bt_field_class *field_class); - -extern uint64_t bt_field_class_bit_array_get_length( - const bt_field_class *field_class); - -extern uint64_t bt_field_class_integer_get_field_value_range( - const bt_field_class *field_class); - -extern bt_field_class_integer_preferred_display_base -bt_field_class_integer_get_preferred_display_base( - const bt_field_class *field_class); - -extern uint64_t bt_field_class_enumeration_get_mapping_count( - const bt_field_class *field_class); - -extern const bt_field_class_enumeration_unsigned_mapping * -bt_field_class_enumeration_unsigned_borrow_mapping_by_index_const( - const bt_field_class *field_class, uint64_t index); - -extern const bt_field_class_enumeration_unsigned_mapping * -bt_field_class_enumeration_unsigned_borrow_mapping_by_label_const( - const bt_field_class *field_class, const char *label); - -extern const bt_field_class_enumeration_signed_mapping * -bt_field_class_enumeration_signed_borrow_mapping_by_index_const( - const bt_field_class *field_class, uint64_t index); - -extern const bt_field_class_enumeration_signed_mapping * -bt_field_class_enumeration_signed_borrow_mapping_by_label_const( - const bt_field_class *field_class, const char *label); - -static inline -const bt_field_class_enumeration_mapping * -bt_field_class_enumeration_unsigned_mapping_as_mapping_const( - const bt_field_class_enumeration_unsigned_mapping *mapping) -{ - return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping); -} - -static inline -const bt_field_class_enumeration_mapping * -bt_field_class_enumeration_signed_mapping_as_mapping_const( - const bt_field_class_enumeration_signed_mapping *mapping) -{ - return __BT_UPCAST_CONST(bt_field_class_enumeration_mapping, mapping); -} - -extern const char *bt_field_class_enumeration_mapping_get_label( - const bt_field_class_enumeration_mapping *mapping); - -extern const bt_integer_range_set_unsigned * -bt_field_class_enumeration_unsigned_mapping_borrow_ranges_const( - const bt_field_class_enumeration_unsigned_mapping *mapping); - -extern const bt_integer_range_set_signed * -bt_field_class_enumeration_signed_mapping_borrow_ranges_const( - const bt_field_class_enumeration_signed_mapping *mapping); - -typedef enum bt_field_class_enumeration_get_mapping_labels_for_value_status { - BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_FIELD_CLASS_ENUMERATION_GET_MAPPING_LABELS_BY_VALUE_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_field_class_enumeration_get_mapping_labels_for_value_status; - -extern bt_field_class_enumeration_get_mapping_labels_for_value_status -bt_field_class_enumeration_unsigned_get_mapping_labels_for_value( - const bt_field_class *field_class, uint64_t value, - bt_field_class_enumeration_mapping_label_array *label_array, - uint64_t *count); - -extern bt_field_class_enumeration_get_mapping_labels_for_value_status -bt_field_class_enumeration_signed_get_mapping_labels_for_value( - const bt_field_class *field_class, int64_t value, - bt_field_class_enumeration_mapping_label_array *label_array, - uint64_t *count); - -extern uint64_t bt_field_class_structure_get_member_count( - const bt_field_class *field_class); - -extern const bt_field_class_structure_member * -bt_field_class_structure_borrow_member_by_index_const( - const bt_field_class *field_class, uint64_t index); - -extern const bt_field_class_structure_member * -bt_field_class_structure_borrow_member_by_name_const( - const bt_field_class *field_class, const char *name); - -extern const char *bt_field_class_structure_member_get_name( - const bt_field_class_structure_member *member); - -extern const bt_field_class * -bt_field_class_structure_member_borrow_field_class_const( - const bt_field_class_structure_member *member); - -extern const bt_value *bt_field_class_structure_member_borrow_user_attributes_const( - const bt_field_class_structure_member *member); - -extern const bt_field_class * -bt_field_class_array_borrow_element_field_class_const( - const bt_field_class *field_class); - -extern uint64_t bt_field_class_array_static_get_length( - const bt_field_class *field_class); - -extern const bt_field_path * -bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const( - const bt_field_class *field_class); - -extern const bt_field_class * -bt_field_class_option_borrow_field_class_const( - const bt_field_class *field_class); - -extern const bt_field_path * -bt_field_class_option_with_selector_field_borrow_selector_field_path_const( - const bt_field_class *field_class); - -extern bt_bool -bt_field_class_option_with_selector_field_bool_selector_is_reversed( - const bt_field_class *field_class); - -extern const bt_integer_range_set_unsigned * -bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const( - const bt_field_class *field_class); - -extern const bt_integer_range_set_signed * -bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const( - const bt_field_class *field_class); - -extern uint64_t bt_field_class_variant_get_option_count( - const bt_field_class *field_class); - -extern const bt_field_class_variant_option * -bt_field_class_variant_borrow_option_by_index_const( - const bt_field_class *field_class, uint64_t index); - -extern const bt_field_class_variant_option * -bt_field_class_variant_borrow_option_by_name_const( - const bt_field_class *field_class, const char *name); - -extern const bt_field_class_variant_with_selector_field_integer_unsigned_option * -bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const( - const bt_field_class *field_class, uint64_t index); - -extern const bt_field_class_variant_with_selector_field_integer_unsigned_option * -bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const( - const bt_field_class *field_class, const char *name); - -extern const bt_field_class_variant_with_selector_field_integer_signed_option * -bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const( - const bt_field_class *field_class, uint64_t index); - -extern const bt_field_class_variant_with_selector_field_integer_signed_option * -bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_name_const( - const bt_field_class *field_class, const char *name); - -extern const char *bt_field_class_variant_option_get_name( - const bt_field_class_variant_option *option); - -extern const bt_field_class * -bt_field_class_variant_option_borrow_field_class_const( - const bt_field_class_variant_option *option); - -extern const bt_value *bt_field_class_variant_option_borrow_user_attributes_const( - const bt_field_class_variant_option *option); - -extern const bt_field_path * -bt_field_class_variant_with_selector_field_borrow_selector_field_path_const( - const bt_field_class *field_class); - -extern const bt_integer_range_set_unsigned * -bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const( - const bt_field_class_variant_with_selector_field_integer_unsigned_option *option); - -static inline -const bt_field_class_variant_option * -bt_field_class_variant_with_selector_field_integer_unsigned_option_as_option_const( - const bt_field_class_variant_with_selector_field_integer_unsigned_option *option) -{ - return __BT_UPCAST_CONST(bt_field_class_variant_option, option); -} - -extern const bt_integer_range_set_signed * -bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const( - const bt_field_class_variant_with_selector_field_integer_signed_option *option); - -static inline -const bt_field_class_variant_option * -bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const( - const bt_field_class_variant_with_selector_field_integer_signed_option *option) -{ - return __BT_UPCAST_CONST(bt_field_class_variant_option, option); -} - -extern void bt_field_class_get_ref(const bt_field_class *field_class); - -extern void bt_field_class_put_ref(const bt_field_class *field_class); - -#define BT_FIELD_CLASS_PUT_REF_AND_RESET(_var) \ - do { \ - bt_field_class_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_FIELD_CLASS_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_field_class_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_FIELD_CLASS_CONST_H */ diff --git a/include/babeltrace2/trace-ir/field-class.h b/include/babeltrace2/trace-ir/field-class.h index e8be1c51..0aab9682 100644 --- a/include/babeltrace2/trace-ir/field-class.h +++ b/include/babeltrace2/trace-ir/field-class.h @@ -31,188 +31,4590 @@ #include #include -#include #ifdef __cplusplus extern "C" { #endif +/*! +@defgroup api-tir-fc Field classes +@ingroup api-tir + +@brief + Classes of \bt_p_field. + +Field classes 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: + +
+
Scalar
+
+ 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" +
+ +
Container
+
+ 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" +
+
+ +@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 bt_field_class_*_create() 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: + + + + + + + + + + + + + + + + + + + + + + + +
Name + Type enumerator + Creation function +
\ref api-tir-fc-bool "Boolean" + #BT_FIELD_CLASS_TYPE_BOOL + bt_field_class_bool_create() +
\ref api-tir-fc-ba "Bit array" + #BT_FIELD_CLASS_TYPE_BIT_ARRAY + bt_field_class_bit_array_create() +
Unsigned \ref api-tir-fc-int "integer" + #BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER + bt_field_class_integer_unsigned_create() +
Signed \ref api-tir-fc-int "integer" + #BT_FIELD_CLASS_TYPE_SIGNED_INTEGER + bt_field_class_integer_signed_create() +
Unsigned \ref api-tir-fc-enum "enumeration" + #BT_FIELD_CLASS_TYPE_UNSIGNED_ENUMERATION + bt_field_class_enumeration_unsigned_create() +
Signed \ref api-tir-fc-enum "enumeration" + #BT_FIELD_CLASS_TYPE_SIGNED_ENUMERATION + bt_field_class_enumeration_signed_create() +
Single-precision \ref api-tir-fc-real "real" + #BT_FIELD_CLASS_TYPE_SINGLE_PRECISION_REAL + bt_field_class_real_single_precision_create() +
Double-precision \ref api-tir-fc-real "real" + #BT_FIELD_CLASS_TYPE_DOUBLE_PRECISION_REAL + bt_field_class_real_double_precision_create() +
\ref api-tir-fc-string "String" + #BT_FIELD_CLASS_TYPE_STRING + bt_field_class_string_create() +
Static \ref api-tir-fc-array "array" + #BT_FIELD_CLASS_TYPE_STATIC_ARRAY + bt_field_class_array_static_create() +
Dynamic \ref api-tir-fc-array "array" (no length field) + #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD + bt_field_class_array_dynamic_create() +
Dynamic \ref api-tir-fc-array "array" (with length field) + #BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD + bt_field_class_array_dynamic_create() +
\ref api-tir-fc-struct "Structure" + #BT_FIELD_CLASS_TYPE_STRUCTURE + bt_field_class_structure_create() +
\ref api-tir-fc-opt "Option" (no selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD + bt_field_class_option_without_selector_create() +
\ref api-tir-fc-opt "Option" (boolean selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD + bt_field_class_option_with_selector_field_bool_create() +
\ref api-tir-fc-opt "Option" (unsigned integer selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_option_with_selector_field_integer_unsigned_create() +
\ref api-tir-fc-opt "Option" (signed integer selector field) + #BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_option_with_selector_field_integer_signed_create() +
\ref api-tir-fc-var "Variant" (no selector field) + #BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD + bt_field_class_variant_create() +
\ref api-tir-fc-var "Variant" (unsigned integer selector field) + #BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_variant_create() +
\ref api-tir-fc-var "Variant" (signed integer selector field) + #BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD + bt_field_class_variant_create() +
+ +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 scopes, 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". + +

Common field class property

+ +A field class has the following common property: + +
+
+ \anchor api-tir-fc-prop-user-attrs + \bt_dt_opt User attributes +
+
+ 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(). +
+
+ +

\anchor api-tir-fc-bool Boolean field class

+ +@image html fc-bool.png + +A boolean field class 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. + +

\anchor api-tir-fc-ba Bit array field class

+ +@image html fc-ba.png + +A bit array field class 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: + +
+
+ \anchor api-tir-fc-ba-prop-len + Length +
+
+ 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(). +
+
+ +

\anchor api-tir-fc-int Integer field classes

+ +@image html fc-int.png + +Integer field classes 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: + +
+
Unsigned integer field class
+
+ Its instances (unsigned integer fields) contain an unsigned integral + value (\c uint64_t). + + Create with bt_field_class_integer_unsigned_create(). +
+ +
Signed integer field class
+
+ Its instances (signed integer fields) contain a signed integral + value (\c int64_t). + + Create with bt_field_class_integer_signed_create(). +
+
+ +Integer field classes have the following common properties: + +
+
+ \anchor api-tir-fc-int-prop-size + Field value range +
+
+ 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(). +
+ +
+ \anchor api-tir-fc-int-prop-base + Preferred display base +
+
+ 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(). +
+
+ +

\anchor api-tir-fc-enum Enumeration field classes

+ +@image html fc-enum.png + +Enumeration field classes 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 mapping. + +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 SUGAR. + +An enumeration field class is an \em abstract field class: you cannot +create one. The concrete enumeration field classes are: + +
+
Unsigned enumeration field class
+
+ Its instances (unsigned enumeration fields) contain an unsigned + value (\c uint64_t). + + Create with bt_field_class_enumeration_unsigned_create(). +
+ +
Signed enumeration field class
+
+ Its instances (signed enumeration fields) contain a signed value + (\c int64_t). + + Create with bt_field_class_enumeration_signed_create(). +
+
+ +Enumeration field classes have the following common property: + +
+
+ \anchor api-tir-fc-enum-prop-mappings + Mappings +
+
+ 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: + + - CALORIES: [1, 11], [15, 37] + - SODIUM: [7, 13] + + In that case, the values 2 and 30 correpond to the label + CALORIES, the value 12 to the label + SODIUM, and the value 10 to the labels + \c CALORIES \em and SODIUM. + + 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(). +
+
+ +

\anchor api-tir-fc-real Real field classes

+ +@image html fc-real.png + +Real field classes are classes +of \bt_p_real_field. + +Real fields contain +real +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: + +
+
Single-precision real field class
+
+ Its instances (single-precision real fields) contain a \c float + value. + + Create with bt_field_class_real_single_precision_create(). +
+ +
Double-precision real field class
+
+ Its instances (double-precision real fields) contain a \c double + value. + + Create with bt_field_class_real_double_precision_create(). +
+
+ +Real field classes have no specific properties. + +

\anchor api-tir-fc-string String field class

+ +@image html fc-string.png + +A string field class 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. + +

\anchor api-tir-fc-array Array field classes

+ +@image html fc-array.png + +Array field classes 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: + +
+
Static array field class
+
+ 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: + +
+
+ \anchor api-tir-fc-sarray-prop-len + Length +
+
+ 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(). +
+
+
+ +
Dynamic array field class
+
+ 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: + +
+
+ \anchor api-tir-fc-darray-prop-len-fp + Length field path +
+
+ 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(). +
+
+
+
+ +Array field classes have the following common property: + +
+
+ \anchor api-tir-fc-array-prop-elem-fc + Element field class +
+
+ 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(). +
+
+ +

\anchor api-tir-fc-struct Structure field class

+ +@image html fc-struct.png + +A structure field class 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: + +
+
+ \anchor api-tir-fc-struct-prop-members + Members +
+
+ 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(). +
+
+ +

\anchor api-tir-fc-opt Option field classes

+ +@image html fc-opt.png + +Option field classes 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: + +
+
Option field class without a selector field
+
+ Create with bt_field_class_option_without_selector_create(). + + An option field class without a selector field has no specific + properties. +
+ +
Option field class with a boolean selector field
+
+ 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: + +
+
+ \anchor api-tir-fc-opt-prop-sel-rev + Selector is reversed? +
+
+ 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(). +
+
+
+ +
Option field class with an unsigned selector field
+
+ 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: + +
+
+ \anchor api-tir-fc-opt-prop-uint-rs + Selector's unsigned integer ranges +
+
+ 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(). +
+
+
+ +
Option field class with a signed selector field
+
+ 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: + +
+
+ \anchor api-tir-fc-opt-prop-sint-rs + Selector's signed integer ranges +
+
+ 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(). +
+
+
+
+ +Option field classes with a selector have the following common +property: + +
+
+ \anchor api-tir-fc-opt-prop-sel-fp + Selector field path +
+
+ 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(). +
+
+ +Option field classes have the following common property: + +
+
+ \anchor api-tir-fc-opt-prop-fc + Optional field class +
+
+ 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(). +
+
+ +

\anchor api-tir-fc-var Variant field classes

+ +@image html fc-var.png + +Variant field classes 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: + +
+
Variant field class without a selector field
+
+ 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. +
+ +
Variant field class with an unsigned selector field
+
+ 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(). +
+ +
Variant field class with a signed selector field
+
+ 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(). +
+
+ +Variant field classes with a selector have the following common +property: + +
+
+ \anchor api-tir-fc-var-prop-sel-fp + Selector field path +
+
+ 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(). +
+
+ +Variant field classes have the following common property: + +
+
+ \anchor api-tir-fc-var-prop-opts + Options +
+
+ 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(). +
+
+ +

\anchor api-tir-fc-link Field classes with links to other field classes

+ +\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: + +
+
\bt_c_darray_field
+
+ The linked field, a \bt_uint_field, contains the \b length of the + dynamic array field. +
+ +
\bt_c_opt_field
+
+ The linked field, either a \bt_bool_field or an \bt_int_field, + indicates whether or not the option field has a field. +
+ +
\bt_c_var_field
+
+ The linked field, an \bt_int_field, indicates the variant field's + current selected field. +
+
+ +Having a linked field class is optional: 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 +Common Trace Format, 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 scope. The available scopes are: + +
+
#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT
+
+ Packet context field. + + See bt_packet_borrow_context_field_const(). +
+ +
#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT
+
+ Event common context field. + + See bt_event_borrow_common_context_field_const(). +
+ +
#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT
+
+ Event specific context field. + + See bt_event_borrow_specific_context_field_const(). +
+ +
#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD
+
+ Event payload field. + + See bt_event_borrow_payload_field_const(). +
+
+ +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 + bt_field_class_*_create() 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 + bt_field_class_*_create() 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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + +
Property + Value +
\ref api-tir-fc-ba-prop-len "Length" + \bt_p{length} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + +
+
Unsigned integer field class
+
[0, 2N - 1]
+ +
Signed integer field class
+
[-2N, 2N - 1]
+
+ @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: + +
+
Unsigned integer field class
+
[0, 2N - 1]
+ +
Signed integer field class
+
[-2N, 2N - 1]
+
+ @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: + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [0, 264 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [-263, 263 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [0, 264 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-enum-prop-mappings "Mappings" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + On success, \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 + On success, \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: + + + + + + + +
Property + Value +
\ref api-tir-fc-int-prop-size "Field value range" + [-263, 263 - 1] +
\ref api-tir-fc-int-prop-base "Preferred display base" + #BT_FIELD_CLASS_INTEGER_PREFERRED_DISPLAY_BASE_DECIMAL +
\ref api-tir-fc-enum-prop-mappings "Mappings" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + On success, \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 + On success, \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: + + + + +
Property + Value +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + +
Property + Value +
\ref api-tir-fc-array-prop-elem-fc "Element field class" + \bt_p{element_field_class} +
\ref api-tir-fc-sarray-prop-len "Length" + \bt_p{length} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + +
Property + Value +
\ref api-tir-fc-array-prop-elem-fc "Element field class" + \bt_p{element_field_class} +
\ref api-tir-fc-darray-prop-len-fp "Length field path" + + \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) +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + If \bt_p{length_field_class} is not \c NULL, + \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: + + + + + +
Property + Value +
\ref api-tir-fc-struct-prop-members "Members" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-opt-prop-sel-fp "Selector field path" + + \em None (this property becomes available when the returned field + class becomes part of an \bt_ev_cls or of a \bt_stream_cls) +
\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?" + #BT_FALSE +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-opt-prop-sel-fp "Selector field path" + + \em None (this property becomes available when the returned field + class becomes part of an \bt_ev_cls or of a \bt_stream_cls) +
\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges" + \bt_p{ranges} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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: + + + + + + + +
Property + Value +
\ref api-tir-fc-opt-prop-fc "Optional field class" + \bt_p{optional_field_class} +
\ref api-tir-fc-opt-prop-sel-fp "Selector field path" + + \em None (this property becomes available when the returned field + class becomes part of an \bt_ev_cls or of a \bt_stream_cls) +
\ref api-tir-fc-opt-prop-sint-rs "Selector's signed integer ranges" + \bt_p{ranges} +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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); + + + + + +
Property + Value +
\ref api-tir-fc-var-prop-sel-fp "Selector field path" + + \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) +
\ref api-tir-fc-var-prop-opts "Options" + \em None +
\ref api-tir-fc-prop-user-attrs "User attributes" + Empty \bt_map_val +
-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 + If \bt_p{selector_field_class} is not \c NULL, + \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 } diff --git a/include/babeltrace2/trace-ir/field-const.h b/include/babeltrace2/trace-ir/field-const.h deleted file mode 100644 index c6529df2..00000000 --- a/include/babeltrace2/trace-ir/field-const.h +++ /dev/null @@ -1,118 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_FIELD_CONST_H -#define BABELTRACE2_TRACE_IR_FIELD_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_field_class *bt_field_borrow_class_const( - const bt_field *field); - -extern bt_field_class_type bt_field_get_class_type( - const bt_field *field); - -extern bt_bool bt_field_bool_get_value(const bt_field *field); - -extern uint64_t bt_field_bit_array_get_value_as_integer( - const bt_field *field); - -extern int64_t bt_field_integer_signed_get_value(const bt_field *field); - -extern uint64_t bt_field_integer_unsigned_get_value( - const bt_field *field); - -extern float bt_field_real_single_precision_get_value(const bt_field *field); - -extern double bt_field_real_double_precision_get_value(const bt_field *field); - -typedef enum bt_field_enumeration_get_mapping_labels_status { - BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_FIELD_ENUMERATION_GET_MAPPING_LABELS_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_field_enumeration_get_mapping_labels_status; - -extern bt_field_enumeration_get_mapping_labels_status -bt_field_enumeration_unsigned_get_mapping_labels(const bt_field *field, - bt_field_class_enumeration_mapping_label_array *label_array, - uint64_t *count); - -extern bt_field_enumeration_get_mapping_labels_status -bt_field_enumeration_signed_get_mapping_labels(const bt_field *field, - bt_field_class_enumeration_mapping_label_array *label_array, - uint64_t *count); - -extern const char *bt_field_string_get_value(const bt_field *field); - -extern uint64_t bt_field_string_get_length(const bt_field *field); - -extern const bt_field * -bt_field_structure_borrow_member_field_by_index_const( - const bt_field *field, uint64_t index); - -extern const bt_field * -bt_field_structure_borrow_member_field_by_name_const( - const bt_field *field, const char *name); - -extern uint64_t bt_field_array_get_length(const bt_field *field); - -extern const bt_field * -bt_field_array_borrow_element_field_by_index_const( - const bt_field *field, uint64_t index); - -extern const bt_field * -bt_field_option_borrow_field_const(const bt_field *field); - -extern uint64_t bt_field_variant_get_selected_option_index( - const bt_field *field); - -extern const bt_field * -bt_field_variant_borrow_selected_option_field_const( - const bt_field *field); - -extern const bt_field_class_variant_option * -bt_field_variant_borrow_selected_option_class_const( - const bt_field *field); - -extern const bt_field_class_variant_with_selector_field_integer_unsigned_option * -bt_field_variant_with_selector_field_integer_unsigned_borrow_selected_option_class_const( - const bt_field *field); - -extern const bt_field_class_variant_with_selector_field_integer_signed_option * -bt_field_variant_with_selector_field_integer_signed_borrow_selected_option_class_const( - const bt_field *field); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_FIELD_CONST_H */ diff --git a/include/babeltrace2/trace-ir/field-path-const.h b/include/babeltrace2/trace-ir/field-path-const.h deleted file mode 100644 index 06dfe052..00000000 --- a/include/babeltrace2/trace-ir/field-path-const.h +++ /dev/null @@ -1,87 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_CONST_H -#define BABELTRACE2_TRACE_IR_FIELD_PATH_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_field_path_item_type { - BT_FIELD_PATH_ITEM_TYPE_INDEX = 1 << 0, - BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT = 1 << 1, - BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT = 1 << 2, -} bt_field_path_item_type; - -typedef enum bt_field_path_scope { - BT_FIELD_PATH_SCOPE_PACKET_CONTEXT = 0, - BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT = 1, - BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT = 2, - BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD = 3, -} bt_field_path_scope; - -extern bt_field_path_scope bt_field_path_get_root_scope( - const bt_field_path *field_path); - -extern uint64_t bt_field_path_get_item_count( - const bt_field_path *field_path); - -extern const bt_field_path_item *bt_field_path_borrow_item_by_index_const( - const bt_field_path *field_path, uint64_t index); - -extern bt_field_path_item_type bt_field_path_item_get_type( - const bt_field_path_item *field_path_item); - -extern uint64_t bt_field_path_item_index_get_index( - const bt_field_path_item *field_path_item); - -extern void bt_field_path_get_ref(const bt_field_path *field_path); - -extern void bt_field_path_put_ref(const bt_field_path *field_path); - -#define BT_FIELD_PATH_PUT_REF_AND_RESET(_var) \ - do { \ - bt_field_path_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_FIELD_PATH_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_field_path_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_FIELD_PATH_CONST_H */ diff --git a/include/babeltrace2/trace-ir/field-path.h b/include/babeltrace2/trace-ir/field-path.h new file mode 100644 index 00000000..fdb17e75 --- /dev/null +++ b/include/babeltrace2/trace-ir/field-path.h @@ -0,0 +1,471 @@ +#ifndef BABELTRACE2_TRACE_IR_FIELD_PATH_H +#define BABELTRACE2_TRACE_IR_FIELD_PATH_H + +/* + * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#ifndef __BT_IN_BABELTRACE_H +# error "Please include instead." +#endif + +#include + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/*! +@defgroup api-tir-field-path Field path +@ingroup api-tir + +@brief + Path to a \bt_field. + +A field path indicates how to reach a given +\bt_field from a given root scope. + +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. + +

Properties

+ +A field path has the following properties: + +
+
+ \anchor api-tir-field-path-prop-root + Root scope +
+
+ 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(). +
+ +
+ \anchor api-tir-field-path-prop-items + Items +
+
+ 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. +
+
+ +

\anchor api-tir-field-path-lookup-algo Lookup algorithm

+ +The field resolution algorithm using a field path is: + +-# Use the appropriate function to set a current field variable + from the root scope (as returned by bt_field_path_get_root_scope()): + +
+
#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT
+
+ bt_packet_borrow_context_field_const(). +
+
#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT
+
+ bt_event_borrow_common_context_field_const(). +
+
#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT
+
+ bt_event_borrow_specific_context_field_const(). +
+
#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD
+
+ bt_event_borrow_payload_field_const(). +
+
+ +-# 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()): + +
+
#BT_FIELD_PATH_ITEM_TYPE_INDEX
+
+ 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()): + +
+
\bt_c_struct_fc
+
+ 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. +
+ +
\bt_c_var_fc
+
+ Call bt_field_variant_borrow_selected_option_field_const() + with the current field to set the new current field. +
+
+
+ +
#BT_FIELD_PATH_ITEM_TYPE_CURRENT_ARRAY_ELEMENT
+
+ 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. +
+ +
#BT_FIELD_PATH_ITEM_TYPE_CURRENT_OPTION_CONTENT
+
+ Call bt_field_option_borrow_field_const() with the current + field to set the new current field. +
+
+ +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 */ diff --git a/include/babeltrace2/trace-ir/field.h b/include/babeltrace2/trace-ir/field.h index f95298de..572118ee 100644 --- a/include/babeltrace2/trace-ir/field.h +++ b/include/babeltrace2/trace-ir/field.h @@ -35,79 +35,1502 @@ extern "C" { #endif +/*! +@defgroup api-tir-field Fields +@ingroup api-tir + +@brief + Containers of trace data. + +Fields 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: + +
+
Scalar
+
+ 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" +
+ +
Container
+
+ 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" +
+
+ +@image html fc-to-field.png "Fields (green) are instances of field classes (orange)." + +You cannot directly create a field: there are no +bt_field_*_create() 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 + bt_field_class_*_create() 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. + +

\anchor api-tir-field-bool Boolean field

+ +A boolean field 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(). + +

\anchor api-tir-field-ba Bit array field

+ +A bit array field 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(). + +

\anchor api-tir-field-int Integer fields

+ +Integer fields are \bt_int_fc instances. + +Integer fields contain integral values. + +An integer field is an \em abstract field. The concrete integer fields +are: + +
+
Unsigned integer field
+
+ 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(). +
+ +
Signed integer field
+
+ 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(). +
+
+ +

\anchor api-tir-field-enum Enumeration fields

+ +Enumeration fields 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: + +
+
Unsigned enumeration field
+
+ 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(). +
+ +
Signed enumeration field
+
+ 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(). +
+
+ +

\anchor api-tir-field-real Real fields

+ +Real fields are \bt_real_fc instances. + +Real fields contain +real +values (\c float or \c double types). + +A real field is an \em abstract field. The concrete real fields are: + +
+
Single-precision real field
+
+ 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(). +
+ +
Double-precision real field
+
+ 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(). +
+
+ +

\anchor api-tir-field-string String field

+ +A string field 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(). + +

\anchor api-tir-field-array Array fields

+ +Array fields 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: + +
+
Static array field
+
+ 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". +
+ +
Dynamic array field class
+
+ 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. +
+
+ +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(). + +

\anchor api-tir-field-struct Structure field

+ +A structure field 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(). + +

\anchor api-tir-field-opt Option field

+ +An option field 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(). + +

\anchor api-tir-field-var Variant field

+ +A variant field 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 diff --git a/include/babeltrace2/trace-ir/packet-const.h b/include/babeltrace2/trace-ir/packet-const.h deleted file mode 100644 index f3fdd2d6..00000000 --- a/include/babeltrace2/trace-ir/packet-const.h +++ /dev/null @@ -1,67 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_PACKET_CONST_H -#define BABELTRACE2_TRACE_IR_PACKET_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_stream *bt_packet_borrow_stream_const( - const bt_packet *packet); - -extern -const bt_field *bt_packet_borrow_context_field_const( - const bt_packet *packet); - -extern void bt_packet_get_ref(const bt_packet *packet); - -extern void bt_packet_put_ref(const bt_packet *packet); - -#define BT_PACKET_PUT_REF_AND_RESET(_var) \ - do { \ - bt_packet_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_PACKET_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_packet_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_PACKET_CONST_H */ diff --git a/include/babeltrace2/trace-ir/packet.h b/include/babeltrace2/trace-ir/packet.h index 6a310854..52d110ee 100644 --- a/include/babeltrace2/trace-ir/packet.h +++ b/include/babeltrace2/trace-ir/packet.h @@ -35,13 +35,306 @@ extern "C" { #endif +/*! +@defgroup api-tir-pkt Packet +@ingroup api-tir + +@brief + Trace packet. + +A packet 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 +Common Trace Format. + +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. + +

Property

+ +A packet has the following property: + +
+
\anchor api-tir-pkt-prop-ctx Context field
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + + + + +
Property + Value +
\ref api-tir-pkt-prop-ctx "Context field" + + 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}. +
+ +@param[in] stream + Stream for which to create the packet. + +@returns + New packet reference, or \c NULL on memory error. + +@pre + bt_stream_class_supports_packets(bt_stream_borrow_class_const(stream)) + 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 diff --git a/include/babeltrace2/trace-ir/stream-class-const.h b/include/babeltrace2/trace-ir/stream-class-const.h deleted file mode 100644 index 7a7077b9..00000000 --- a/include/babeltrace2/trace-ir/stream-class-const.h +++ /dev/null @@ -1,121 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_STREAM_CLASS_CONST_H -#define BABELTRACE2_TRACE_IR_STREAM_CLASS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_value *bt_stream_class_borrow_user_attributes_const( - const bt_stream_class *stream_class); - -extern const bt_trace_class *bt_stream_class_borrow_trace_class_const( - const bt_stream_class *stream_class); - -extern const char *bt_stream_class_get_name( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_assigns_automatic_event_class_id( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_assigns_automatic_stream_id( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_supports_packets( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_packets_have_beginning_default_clock_snapshot( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_packets_have_end_default_clock_snapshot( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_supports_discarded_events( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_supports_discarded_packets( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_discarded_events_have_default_clock_snapshots( - const bt_stream_class *stream_class); - -extern bt_bool bt_stream_class_discarded_packets_have_default_clock_snapshots( - const bt_stream_class *stream_class); - -extern uint64_t bt_stream_class_get_id( - const bt_stream_class *stream_class); - -extern const bt_field_class * -bt_stream_class_borrow_packet_context_field_class_const( - const bt_stream_class *stream_class); - -extern const bt_field_class * -bt_stream_class_borrow_event_common_context_field_class_const( - const bt_stream_class *stream_class); - -extern uint64_t bt_stream_class_get_event_class_count( - const bt_stream_class *stream_class); - -extern const bt_event_class * -bt_stream_class_borrow_event_class_by_index_const( - const bt_stream_class *stream_class, uint64_t index); - -extern const bt_event_class * -bt_stream_class_borrow_event_class_by_id_const( - const bt_stream_class *stream_class, uint64_t id); - -extern const bt_clock_class * -bt_stream_class_borrow_default_clock_class_const( - const bt_stream_class *stream_class); - -extern void bt_stream_class_get_ref(const bt_stream_class *stream_class); - -extern void bt_stream_class_put_ref(const bt_stream_class *stream_class); - -#define BT_STREAM_CLASS_PUT_REF_AND_RESET(_var) \ - do { \ - bt_stream_class_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_STREAM_CLASS_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_stream_class_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_STREAM_CLASS_CONST_H */ diff --git a/include/babeltrace2/trace-ir/stream-class.h b/include/babeltrace2/trace-ir/stream-class.h index 58bdbdc4..d05d4735 100644 --- a/include/babeltrace2/trace-ir/stream-class.h +++ b/include/babeltrace2/trace-ir/stream-class.h @@ -35,92 +35,1789 @@ extern "C" { #endif +/*! +@defgroup api-tir-stream-cls Stream class +@ingroup api-tir + +@brief + Class of \bt_p_stream. + +A stream class 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: + +
+
Default clock
+
+ 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. +
+ +
\anchor api-tir-stream-cls-pkt-support Packets
+
+ 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. +
+ +
Discarded events
+
+ 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. +
+ +
Discarded packets
+
+ 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. +
+
+ +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: + +
+
+ If bt_trace_class_assigns_automatic_stream_class_id() returns + #BT_TRUE (the default) for the trace class to use +
+
Use bt_stream_class_create().
+ +
+ If bt_trace_class_assigns_automatic_stream_class_id() returns + #BT_FALSE for the trace class to use +
+
Use bt_stream_class_create_with_id().
+
+ +

Properties

+ +A stream class has the following properties: + +
+
\anchor api-tir-stream-cls-prop-id Numeric ID
+
+ 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(). +
+ +
\anchor api-tir-stream-cls-prop-name \bt_dt_opt Name
+
+ Name of the stream class. + + Use bt_stream_class_set_name() and bt_stream_class_get_name(). +
+ +
+ \anchor api-tir-stream-cls-prop-def-clock-cls + \bt_dt_opt Default clock class +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-pc-fc + \bt_dt_opt Packet context field class +
+
+ \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(). +
+ +
+ \anchor api-tir-stream-cls-prop-ecc-fc + \bt_dt_opt Event common context field class +
+
+ \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(). +
+ +
+ \anchor api-tir-stream-cls-prop-auto-ec-id + Assigns automatic event class IDs? +
+
+ 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: + +
+
#BT_TRUE
+
+ Use bt_event_class_create(). +
+ +
#BT_FALSE
+
+ Use bt_event_class_create_with_id(). +
+
+ + Use bt_stream_class_set_assigns_automatic_event_class_id() + and bt_stream_class_assigns_automatic_event_class_id(). +
+ +
+ \anchor api-tir-stream-cls-prop-auto-stream-id + Assigns automatic stream IDs? +
+
+ 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: + +
+
#BT_TRUE
+
+ Use bt_stream_create(). +
+ +
#BT_FALSE
+
+ Use bt_stream_create_with_id(). +
+
+ + Use bt_stream_class_set_assigns_automatic_stream_id() + and bt_stream_class_assigns_automatic_stream_id(). +
+ +
+ \anchor api-tir-stream-cls-prop-supports-pkt + Supports packets? +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-pkt-beg-cs + Packets have a beginning default clock snapshot? +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-pkt-end-cs + Packets have an end default clock snapshot? +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-supports-disc-ev + Supports discarded events? +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-disc-ev-cs + Discarded events have default clock snapshots? +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-supports-disc-pkt + Supports discarded packets? +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-disc-pkt-cs + Discarded packets have default clock snapshots? +
+
+ 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(). +
+ +
+ \anchor api-tir-stream-cls-prop-user-attrs + \bt_dt_opt User attributes +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + + + + + + + + + + + + + + + + + + +
Property + Value +
\ref api-tir-stream-cls-prop-id "Numeric ID" + Automatically assigned by \bt_p{trace_class} +
\ref api-tir-stream-cls-prop-name "Name" + \em None +
\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class" + \em None +
\ref api-tir-stream-cls-prop-pc-fc "Packet context field class" + \em None +
\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class" + \em None +
\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?" + Yes +
\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?" + Yes +
\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?" + No +
\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?" + No +
\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?" + No +
\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + bt_trace_class_assigns_automatic_stream_class_id(trace_class) + 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: + + + + + + + + + + + + + + + + + + +
Property + Value +
\ref api-tir-stream-cls-prop-id "Numeric ID" + \bt_p{id} +
\ref api-tir-stream-cls-prop-name "Name" + \em None +
\ref api-tir-stream-cls-prop-def-clock-cls "Default clock class" + \em None +
\ref api-tir-stream-cls-prop-pc-fc "Packet context field class" + \em None +
\ref api-tir-stream-cls-prop-ecc-fc "Event common context field class" + \em None +
\ref api-tir-stream-cls-prop-auto-ec-id "Assigns automatic event class IDs?" + Yes +
\ref api-tir-stream-cls-prop-auto-stream-id "Assigns automatic stream IDs?" + Yes +
\ref api-tir-stream-cls-prop-supports-pkt "Supports packets?" + No +
\ref api-tir-stream-cls-prop-pkt-beg-cs "Packets have a beginning default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-pkt-end-cs "Packets have an end default clock snapshot?" + No +
\ref api-tir-stream-cls-prop-supports-disc-ev "Supports discarded events?" + No +
\ref api-tir-stream-cls-prop-disc-ev-cs "Discarded events have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-supports-disc-pkt "Supports discarded packets?" + No +
\ref api-tir-stream-cls-prop-disc-pkt-cs "Discarded packets have default clock snapshots?" + No +
\ref api-tir-stream-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + bt_trace_class_assigns_automatic_stream_class_id(trace_class) + 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 + bt_stream_class_supports_packets(stream_class) + 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 + If \bt_p{with_beginning_default_clock_snapshot} is + #BT_TRUE, + \bt_p{supports_packets} is also #BT_TRUE. +@pre + If \bt_p{with_beginning_default_clock_snapshot} is + #BT_TRUE, + \bt_p{supports_packets} is also #BT_TRUE. +@pre + If \bt_p{with_beginning_default_clock_snapshot} or + \bt_p{with_end_default_clock_snapshot} is #BT_TRUE, + \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 + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \bt_p{supports_discarded_events} is also #BT_TRUE. +@pre + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \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 + bt_stream_class_supports_packets(stream_class) + returns #BT_TRUE. +@pre + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \bt_p{supports_discarded_packets} is also #BT_TRUE. +@pre + If \bt_p{with_default_clock_snapshots} is #BT_TRUE, + \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 } diff --git a/include/babeltrace2/trace-ir/stream-const.h b/include/babeltrace2/trace-ir/stream-const.h deleted file mode 100644 index bf809830..00000000 --- a/include/babeltrace2/trace-ir/stream-const.h +++ /dev/null @@ -1,72 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_STREAM_CONST_H -#define BABELTRACE2_TRACE_IR_STREAM_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -extern const bt_value *bt_stream_borrow_user_attributes_const( - const bt_stream *stream); - -extern const bt_stream_class *bt_stream_borrow_class_const( - const bt_stream *stream); - -extern const bt_trace *bt_stream_borrow_trace_const( - const bt_stream *stream); - -extern const char *bt_stream_get_name(const bt_stream *stream); - -extern uint64_t bt_stream_get_id(const bt_stream *stream); - -extern void bt_stream_get_ref(const bt_stream *stream); - -extern void bt_stream_put_ref(const bt_stream *stream); - -#define BT_STREAM_PUT_REF_AND_RESET(_var) \ - do { \ - bt_stream_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_STREAM_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_stream_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_STREAM_CONST_H */ diff --git a/include/babeltrace2/trace-ir/stream.h b/include/babeltrace2/trace-ir/stream.h index 416e42ce..32bc98e1 100644 --- a/include/babeltrace2/trace-ir/stream.h +++ b/include/babeltrace2/trace-ir/stream.h @@ -35,30 +35,631 @@ extern "C" { #endif +/*! +@defgroup api-tir-stream Stream +@ingroup api-tir + +@brief + Trace stream. + +A stream 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: + +
+
+ If bt_stream_class_assigns_automatic_stream_id() returns + #BT_TRUE (the default) for the stream class to use +
+
Use bt_stream_create().
+ +
+ If bt_stream_class_assigns_automatic_stream_id() returns + #BT_FALSE for the stream class to use +
+
Use bt_stream_create_with_id().
+
+ +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. + +

Properties

+ +A stream has the following property: + +
+
\anchor api-tir-stream-prop-id Numeric ID
+
+ 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(). +
+ +
\anchor api-tir-stream-prop-name \bt_dt_opt Name
+
+ Name of the stream. + + Use bt_stream_set_name() and bt_stream_get_name(). +
+ +
+ \anchor api-tir-stream-prop-user-attrs + \bt_dt_opt User attributes +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + + + + + + +
Property + Value +
\ref api-tir-stream-prop-id "Numeric ID" + Automatically assigned by \bt_p{stream_class} and \bt_p{trace} +
\ref api-tir-stream-prop-name "Name" + \em None +
\ref api-tir-stream-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + bt_stream_class_assigns_automatic_stream_id(stream_class) + 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: + + + + + + +
Property + Value +
\ref api-tir-stream-prop-id "Numeric ID" + \bt_p{id} +
\ref api-tir-stream-prop-name "Name" + \em None +
\ref api-tir-stream-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + bt_stream_class_assigns_automatic_stream_id(stream_class) + 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 diff --git a/include/babeltrace2/trace-ir/trace-class-const.h b/include/babeltrace2/trace-ir/trace-class-const.h deleted file mode 100644 index 6ad9a9d7..00000000 --- a/include/babeltrace2/trace-ir/trace-class-const.h +++ /dev/null @@ -1,98 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_CONST_H -#define BABELTRACE2_TRACE_IR_TRACE_CLASS_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef void (* bt_trace_class_destruction_listener_func)( - const bt_trace_class *trace_class, void *data); - -extern const bt_value *bt_trace_class_borrow_user_attributes_const( - const bt_trace_class *trace_class); - -extern bt_bool bt_trace_class_assigns_automatic_stream_class_id( - const bt_trace_class *trace_class); - -extern uint64_t bt_trace_class_get_stream_class_count( - const bt_trace_class *trace_class); - -extern const bt_stream_class * -bt_trace_class_borrow_stream_class_by_index_const( - const bt_trace_class *trace_class, uint64_t index); - -extern const bt_stream_class *bt_trace_class_borrow_stream_class_by_id_const( - const bt_trace_class *trace_class, uint64_t id); - -typedef enum bt_trace_class_add_listener_status { - BT_TRACE_CLASS_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_TRACE_CLASS_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_trace_class_add_listener_status; - -extern bt_trace_class_add_listener_status -bt_trace_class_add_destruction_listener( - const bt_trace_class *trace_class, - bt_trace_class_destruction_listener_func listener, - void *data, bt_listener_id *listener_id); - -typedef enum bt_trace_class_remove_listener_status { - BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_TRACE_CLASS_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_trace_class_remove_listener_status; - -extern bt_trace_class_remove_listener_status -bt_trace_class_remove_destruction_listener( - const bt_trace_class *trace_class, bt_listener_id listener_id); - -extern void bt_trace_class_get_ref(const bt_trace_class *trace_class); - -extern void bt_trace_class_put_ref(const bt_trace_class *trace_class); - -#define BT_TRACE_CLASS_PUT_REF_AND_RESET(_var) \ - do { \ - bt_trace_class_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_TRACE_CLASS_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_trace_class_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_TRACE_CLASS_CONST_H */ diff --git a/include/babeltrace2/trace-ir/trace-class.h b/include/babeltrace2/trace-ir/trace-class.h index d90ba2c9..3bfbe347 100644 --- a/include/babeltrace2/trace-ir/trace-class.h +++ b/include/babeltrace2/trace-ir/trace-class.h @@ -1,4 +1,4 @@ -#ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H + #ifndef BABELTRACE2_TRACE_IR_TRACE_CLASS_H #define BABELTRACE2_TRACE_IR_TRACE_CLASS_H /* @@ -35,23 +35,634 @@ extern "C" { #endif -extern bt_trace_class *bt_trace_class_create(bt_self_component *self_comp); +/*! +@defgroup api-tir-trace-cls Trace class +@ingroup api-tir -extern bt_value *bt_trace_class_borrow_user_attributes( - bt_trace_class *trace_class); +@brief + Class of \bt_p_trace. -extern void bt_trace_class_set_user_attributes( - bt_trace_class *trace_class, const bt_value *user_attributes); +A trace class 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(). + +

Properties

+ +A trace class has the following properties: + +
+
+ \anchor api-tir-trace-cls-prop-auto-sc-id + Assigns automatic stream class IDs? +
+
+ 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: + +
+
#BT_TRUE
+
+ Use bt_stream_class_create(). +
+ +
#BT_FALSE
+
+ Use bt_stream_class_create_with_id(). +
+
+ + Use bt_trace_class_set_assigns_automatic_stream_class_id() + and bt_trace_class_assigns_automatic_stream_class_id(). +
+ +
+ \anchor api-tir-trace-cls-prop-user-attrs + \bt_dt_opt User attributes +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + + + + + +
Property + Value +
\ref api-tir-trace-cls-prop-auto-sc-id "Assigns automatic stream class IDs?" + Yes +
\ref api-tir-trace-cls-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + On success and if not \c NULL, \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 diff --git a/include/babeltrace2/trace-ir/trace-const.h b/include/babeltrace2/trace-ir/trace-const.h deleted file mode 100644 index d4410a2d..00000000 --- a/include/babeltrace2/trace-ir/trace-const.h +++ /dev/null @@ -1,107 +0,0 @@ -#ifndef BABELTRACE2_TRACE_IR_TRACE_CONST_H -#define BABELTRACE2_TRACE_IR_TRACE_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef void (* bt_trace_destruction_listener_func)( - const bt_trace *trace, void *data); - -extern const bt_value *bt_trace_borrow_user_attributes_const( - const bt_trace *trace); - -extern const bt_trace_class *bt_trace_borrow_class_const( - const bt_trace *trace); - -extern const char *bt_trace_get_name(const bt_trace *trace); - -extern bt_uuid bt_trace_get_uuid(const bt_trace *trace); - -extern uint64_t bt_trace_get_environment_entry_count(const bt_trace *trace); - -extern void bt_trace_borrow_environment_entry_by_index_const( - const bt_trace *trace, uint64_t index, - const char **name, const bt_value **value); - -extern const bt_value *bt_trace_borrow_environment_entry_value_by_name_const( - const bt_trace *trace, const char *name); - -extern uint64_t bt_trace_get_stream_count(const bt_trace *trace); - -extern const bt_stream *bt_trace_borrow_stream_by_index_const( - const bt_trace *trace, uint64_t index); - -extern const bt_stream *bt_trace_borrow_stream_by_id_const( - const bt_trace *trace, uint64_t id); - -typedef enum bt_trace_add_listener_status { - BT_TRACE_ADD_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_TRACE_ADD_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_trace_add_listener_status; - -extern bt_trace_add_listener_status bt_trace_add_destruction_listener( - const bt_trace *trace, - bt_trace_destruction_listener_func listener, - void *data, bt_listener_id *listener_id); - -typedef enum bt_trace_remove_listener_status { - BT_TRACE_REMOVE_LISTENER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_TRACE_REMOVE_LISTENER_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_trace_remove_listener_status; - -extern bt_trace_remove_listener_status bt_trace_remove_destruction_listener( - const bt_trace *trace, bt_listener_id listener_id); - -extern void bt_trace_get_ref(const bt_trace *trace); - -extern void bt_trace_put_ref(const bt_trace *trace); - -#define BT_TRACE_PUT_REF_AND_RESET(_var) \ - do { \ - bt_trace_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_TRACE_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_trace_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_TRACE_IR_TRACE_CONST_H */ diff --git a/include/babeltrace2/trace-ir/trace.h b/include/babeltrace2/trace-ir/trace.h index 4d17c484..a3f73dba 100644 --- a/include/babeltrace2/trace-ir/trace.h +++ b/include/babeltrace2/trace-ir/trace.h @@ -35,43 +35,938 @@ extern "C" { #endif -extern bt_trace_class *bt_trace_borrow_class(bt_trace *trace); +/*! +@defgroup api-tir-trace Trace +@ingroup api-tir + +@brief + Trace (set of \bt_p_stream). + +A trace 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(). + +

Properties

+ +A trace has the following properties: + +
+
+ \anchor api-tir-trace-prop-name + \bt_dt_opt Name +
+
+ Name of the trace. + + Use bt_trace_set_name() and bt_trace_get_name(). +
+ +
+ \anchor api-tir-trace-prop-uuid + \bt_dt_opt UUID +
+
+ UUID + of the trace. + + The trace's UUID uniquely identifies the trace. + + Use bt_trace_set_uuid() and bt_trace_get_uuid(). +
+ +
+ \anchor api-tir-trace-prop-env + \bt_dt_opt Environment +
+
+ 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(). +
+ +
+ \anchor api-tir-trace-prop-user-attrs + \bt_dt_opt User attributes +
+
+ 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(). +
+
+*/ + +/*! @{ */ + +/*! +@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: + + + + + + + +
Property + Value +
\ref api-tir-trace-prop-name "Name" + \em None +
\ref api-tir-trace-prop-uuid "UUID" + \em None +
\ref api-tir-trace-prop-env "Environment" + Empty +
\ref api-tir-trace-prop-user-attrs "User attributes" + Empty \bt_map_val +
+ +@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 + UUID + 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 + On success, \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 + On success, \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 + On success and if not \c NULL, \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 } diff --git a/include/babeltrace2/types.h b/include/babeltrace2/types.h index 11c6e824..521c603d 100644 --- a/include/babeltrace2/types.h +++ b/include/babeltrace2/types.h @@ -33,55 +33,6 @@ extern "C" { #endif -/** -@defgroup ctypes Babeltrace C types -@ingroup apiref -@brief Babeltrace C types. - -@code -#include -@endcode - -This header contains custom type definitions used across the library. - -@file -@brief Babeltrace C types. -@sa ctypes - -@addtogroup ctypes -@{ -*/ - -/// False boolean value for the #bt_bool type. -#define BT_FALSE 0 - -/// True boolean value for the #bt_bool type. -#define BT_TRUE 1 - -/** -@brief Babeltrace's boolean type. - -Use only the #BT_FALSE and #BT_TRUE definitions for #bt_bool parameters. -It is guaranteed that the library functions which return a #bt_bool -value return either #BT_FALSE or #BT_TRUE. - -You can always test the truthness of a #bt_bool value directly, without -comparing it to #BT_TRUE directly: - -@code -bt_bool ret = bt_some_function(...); - -if (ret) { - // ret is true -} -@endcode -*/ -typedef int bt_bool; - -typedef uint64_t bt_listener_id; - -typedef const uint8_t *bt_uuid; - typedef struct bt_clock_class bt_clock_class; typedef struct bt_clock_snapshot bt_clock_snapshot; typedef struct bt_component bt_component; @@ -155,10 +106,96 @@ typedef struct bt_trace bt_trace; typedef struct bt_trace_class bt_trace_class; typedef struct bt_value bt_value; -typedef const char * const *bt_field_class_enumeration_mapping_label_array; -typedef const struct bt_message **bt_message_array_const; +/*! +@defgroup api-common-types Common C types + +@brief + C types common to many parts of the API. +*/ + +/*! @{ */ + +/*! +@brief + \em True value for #bt_bool. +*/ +#define BT_TRUE 1 + +/*! +@brief + \em False value for #bt_bool. +*/ +#define BT_FALSE 0 + +/*! +@brief + \bt_name boolean type. + +The API uses #bt_bool instead of the C99 \c bool type for +application binary interface +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 + UUID, + 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 } diff --git a/include/babeltrace2/util.h b/include/babeltrace2/util.h index d4826541..6a76372d 100644 --- a/include/babeltrace2/util.h +++ b/include/babeltrace2/util.h @@ -33,15 +33,113 @@ extern "C" { #endif +/*! +@defgroup api-util General purpose utilities + +@brief + General purpose utilities. + +This module contains general purpose utilities. +*/ + +/*! @{ */ + +/*! +@brief + Status codes for bt_util_clock_cycles_to_ns_from_origin(). +*/ typedef enum bt_util_clock_cycles_to_ns_from_origin_status { + /*! + @brief + Success. + */ BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Integer overflow while computing the result. + */ BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR = __BT_FUNC_STATUS_OVERFLOW_ERROR, } bt_util_clock_cycles_to_ns_from_origin_status; +/*! +@brief + Converts the clock value \bt_p{cycles} from cycles to nanoseconds + from the clock's origin and sets \bt_p{*ns_from_origin} to the + result. + +This function considers the clock's frequency in Hz (\bt_p{frequency}), +an offset from its origin in seconds (\bt_p{offset_seconds}) which +can be negative, and an additional offset in cycles +(\bt_p{offset_cycles}). + +This function: + +-# Converts the \bt_p{offset_cycles} value to seconds using + \bt_p{frequency}. +-# Converts the \bt_p{cycles} value to seconds using \bt_p{frequency}. +-# Adds the values of 1., 2., and \bt_p{offset_seconds}. +-# Converts the value of 3. to nanoseconds and sets + \bt_p{*ns_from_origin} to this result. + +The following illustration shows the possible scenarios: + +@image html clock-terminology.png + +\bt_p{offset_seconds} can be negative. For example, considering: + +- A 1000 Hz clock. +- \bt_p{offset_seconds} set to -10 seconds. +- \bt_p{offset_cycles} set to 500 cycles + (that is, 0.5 seconds). +- \bt_p{cycles} set to 2000 cycles (that is, 2 seconds). + +The computed value is -7.5 seconds, so this function sets +\bt_p{*ns_from_origin} to -7,500,000,000. + +This function can fail and return the +#BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status +code if any step of the computation process causes an integer overflow. + +@param[in] cycles + Clock's value (cycles). +@param[in] frequency + Clock's frequency (Hz, or cycles/second). +@param[in] offset_seconds + Offset, in seconds, from the clock's origin to add to + \bt_p{cycles} (once converted to seconds). +@param[in] offset_cycles + Offset, in cycles, to add to \bt_p{cycles}. +@param[out] ns_from_origin + On success, \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 UINT64_C(-1). +@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 } diff --git a/include/babeltrace2/value-const.h b/include/babeltrace2/value-const.h deleted file mode 100644 index f42f60d8..00000000 --- a/include/babeltrace2/value-const.h +++ /dev/null @@ -1,214 +0,0 @@ -#ifndef BABELTRACE2_VALUE_CONST_H -#define BABELTRACE2_VALUE_CONST_H - -/* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - */ - -#ifndef __BT_IN_BABELTRACE_H -# error "Please include instead." -#endif - -#include -#include - -#include - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum bt_value_type { - /// Null value object. - BT_VALUE_TYPE_NULL = 1 << 0, - - /// Boolean value object (holds #BT_TRUE or #BT_FALSE). - BT_VALUE_TYPE_BOOL = 1 << 1, - - BT_VALUE_TYPE_INTEGER = 1 << 2, - - /// Unsigned integer value object (holds an unsigned 64-bit integer raw value). - BT_VALUE_TYPE_UNSIGNED_INTEGER = (1 << 3) | BT_VALUE_TYPE_INTEGER, - - /// Signed integer value object (holds a signed 64-bit integer raw value). - BT_VALUE_TYPE_SIGNED_INTEGER = (1 << 4) | BT_VALUE_TYPE_INTEGER, - - /// Floating point number value object (holds a \c double raw value). - BT_VALUE_TYPE_REAL = 1 << 5, - - /// String value object. - BT_VALUE_TYPE_STRING = 1 << 6, - - /// Array value object. - BT_VALUE_TYPE_ARRAY = 1 << 7, - - /// Map value object. - BT_VALUE_TYPE_MAP = 1 << 8, -} bt_value_type; - -extern bt_value_type bt_value_get_type(const bt_value *object); - -static inline -bt_bool bt_value_type_is(const bt_value_type type, - const bt_value_type type_to_check) -{ - return (type & type_to_check) == type_to_check; -} - -static inline -bt_bool bt_value_is_null(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_NULL; -} - -static inline -bt_bool bt_value_is_bool(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_BOOL; -} - -static inline -bt_bool bt_value_is_unsigned_integer(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_UNSIGNED_INTEGER; -} - -static inline -bt_bool bt_value_is_signed_integer(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_SIGNED_INTEGER; -} - -static inline -bt_bool bt_value_is_real(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_REAL; -} - -static inline -bt_bool bt_value_is_string(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_STRING; -} - -static inline -bt_bool bt_value_is_array(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_ARRAY; -} - -static inline -bt_bool bt_value_is_map(const bt_value *object) -{ - return bt_value_get_type(object) == BT_VALUE_TYPE_MAP; -} - -typedef enum bt_value_copy_status { - BT_VALUE_COPY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_VALUE_COPY_STATUS_OK = __BT_FUNC_STATUS_OK, -} bt_value_copy_status; - -extern bt_value_copy_status bt_value_copy(const bt_value *object, - bt_value **copy); - -extern bt_bool bt_value_is_equal(const bt_value *object_a, - const bt_value *object_b); - -extern bt_bool bt_value_bool_get(const bt_value *bool_obj); - -extern uint64_t bt_value_integer_unsigned_get(const bt_value *integer_obj); - -extern int64_t bt_value_integer_signed_get(const bt_value *integer_obj); - -extern double bt_value_real_get(const bt_value *real_obj); - -extern const char *bt_value_string_get(const bt_value *string_obj); - -extern uint64_t bt_value_array_get_length(const bt_value *array_obj); - -static inline -bt_bool bt_value_array_is_empty(const bt_value *array_obj) -{ - return bt_value_array_get_length(array_obj) == 0; -} - -extern const bt_value *bt_value_array_borrow_element_by_index_const( - const bt_value *array_obj, uint64_t index); - -extern uint64_t bt_value_map_get_size(const bt_value *map_obj); - -static inline -bt_bool bt_value_map_is_empty(const bt_value *map_obj) -{ - return bt_value_map_get_size(map_obj) == 0; -} - -extern const bt_value *bt_value_map_borrow_entry_value_const( - const bt_value *map_obj, const char *key); - -typedef enum bt_value_map_foreach_entry_const_func_status { - BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_CONST_FUNC_STATUS_INTERRUPT = __BT_FUNC_STATUS_INTERRUPTED, -} bt_value_map_foreach_entry_const_func_status; - -typedef bt_value_map_foreach_entry_const_func_status - (* bt_value_map_foreach_entry_const_func)(const char *key, - const bt_value *object, void *data); - -typedef enum bt_value_map_foreach_entry_const_status { - BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_OK = __BT_FUNC_STATUS_OK, - BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_USER_ERROR = __BT_FUNC_STATUS_USER_ERROR, - BT_VALUE_MAP_FOREACH_ENTRY_CONST_STATUS_INTERRUPTED = __BT_FUNC_STATUS_INTERRUPTED, -} bt_value_map_foreach_entry_const_status; - -extern bt_value_map_foreach_entry_const_status bt_value_map_foreach_entry_const( - const bt_value *map_obj, - bt_value_map_foreach_entry_const_func func, void *data); - -extern bt_bool bt_value_map_has_entry(const bt_value *map_obj, - const char *key); - -extern void bt_value_get_ref(const bt_value *value); - -extern void bt_value_put_ref(const bt_value *value); - -#define BT_VALUE_PUT_REF_AND_RESET(_var) \ - do { \ - bt_value_put_ref(_var); \ - (_var) = NULL; \ - } while (0) - -#define BT_VALUE_MOVE_REF(_var_dst, _var_src) \ - do { \ - bt_value_put_ref(_var_dst); \ - (_var_dst) = (_var_src); \ - (_var_src) = NULL; \ - } while (0) - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE2_VALUE_CONST_H */ diff --git a/include/babeltrace2/value.h b/include/babeltrace2/value.h index 42e3cf96..1bf683b5 100644 --- a/include/babeltrace2/value.h +++ b/include/babeltrace2/value.h @@ -31,166 +31,2435 @@ #include #include -#include #ifdef __cplusplus extern "C" { #endif +/*! +@defgroup api-val Values + +@brief + Generic, JSON-like basic data containers. + +Values 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 JSON +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: + +
+
Scalar values
+
+ - Null + - Boolean + - Unsigned integer (64-bit range) + - Signed integer (64-bit range) + - Real (\c double range) + - String +
+ +
Container values
+
+ - Array + - Map (string to value) +
+
+ +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 bt_value_is_*() 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 bt_value_*_create() or +bt_value_*_create_init() functions. + +This documentation names the actual data that a scalar value wraps the +raw value. + +Set and get the raw values of scalar values with functions that are +named bt_value_*_set() and bt_value_*_get(). + +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: + + + + + + + + + + + +
Name + Type enumerator + Type query function + Creation functions + Writing functions + Reading functions +
\em Null + #BT_VALUE_TYPE_NULL + bt_value_is_null() + \em N/A (use the #bt_value_null variable directly) + \em N/A + \em N/A +
\em Boolean + #BT_VALUE_TYPE_BOOL + bt_value_is_bool() + + bt_value_bool_create()
+ bt_value_bool_create_init() + 		bt_value_bool_set() + bt_value_bool_get() +
Unsigned integer + #BT_VALUE_TYPE_UNSIGNED_INTEGER + bt_value_is_unsigned_integer() + + bt_value_integer_unsigned_create()
+ bt_value_integer_unsigned_create_init() + 		bt_value_integer_unsigned_set() + bt_value_integer_unsigned_get() +
Signed integer + #BT_VALUE_TYPE_SIGNED_INTEGER + bt_value_is_signed_integer() + + bt_value_integer_signed_create()
+ bt_value_integer_signed_create_init() + 		bt_value_integer_signed_set() + bt_value_integer_signed_get() +
\em Real + #BT_VALUE_TYPE_REAL + bt_value_is_real() + + bt_value_real_create()
+ bt_value_real_create_init() + 		bt_value_real_set() + bt_value_real_get() +
\em String + #BT_VALUE_TYPE_STRING + bt_value_is_string() + + bt_value_string_create()
+ bt_value_string_create_init() + 		bt_value_string_set() + bt_value_string_get() +
\em Array + #BT_VALUE_TYPE_ARRAY + bt_value_is_array() + + bt_value_array_create() + + bt_value_array_append_element()
+ bt_value_array_append_bool_element()
+ bt_value_array_append_unsigned_integer_element()
+ bt_value_array_append_signed_integer_element()
+ bt_value_array_append_real_element()
+ bt_value_array_append_string_element()
+ bt_value_array_append_empty_array_element()
+ bt_value_array_append_empty_map_element()
+ bt_value_array_set_element_by_index() + 		+ bt_value_array_get_length()
+ bt_value_array_is_empty()
+ bt_value_array_borrow_element_by_index()
+ bt_value_array_borrow_element_by_index_const() +
\em Map + #BT_VALUE_TYPE_MAP + bt_value_is_map() + + bt_value_map_create() + + bt_value_map_insert_entry()
+ bt_value_map_insert_bool_entry()
+ bt_value_map_insert_unsigned_integer_entry()
+ bt_value_map_insert_signed_integer_entry()
+ bt_value_map_insert_real_entry()
+ bt_value_map_insert_string_entry()
+ bt_value_map_insert_empty_array_entry()
+ bt_value_map_insert_empty_map_entry()
+ bt_value_map_extend() + 		+ bt_value_map_get_size()
+ bt_value_map_is_empty()
+ bt_value_map_has_entry()
+ bt_value_map_borrow_entry_value()
+ bt_value_map_borrow_entry_value_const()
+ bt_value_map_foreach_entry()
+ bt_value_map_foreach_entry_const() +
+*/ + +/*! @{ */ + +/*! +@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 bt_value_array_append_*() + 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 + On success, 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 + On success, 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 + On success, 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 + On success, 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 + On success, 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 + On success, 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 + On success, if not \c NULL, \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 + On success, 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 + On success, if not \c NULL, \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 + On success, 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 + On success, 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 bt_value_map_insert_*() 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 + On success, if not \c NULL, \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 + On success, if not \c NULL, \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 bt_value_map_foreach_entry() + 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: + +
+
+ \bt_p{value} +
+
+ @code{.json} + { + "man": "giant", + "strange": 23 + } + @endcode +
+ +
+ \bt_p{extension_value} +
+
+ @code{.json} + { + "balance": -17 + "strange": false + } + @endcode +
+
+ +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 + On success, \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 } diff --git a/include/babeltrace2/version.h b/include/babeltrace2/version.h index 1a15af43..7cd0213f 100644 --- a/include/babeltrace2/version.h +++ b/include/babeltrace2/version.h @@ -31,11 +31,79 @@ extern "C" { #endif +/*! +@defgroup api-version Library version + +@brief + Library version getters. + +This module contains four functions to get the four parts of the +library's version: + +
+
Major version
+
bt_version_get_major()
+ +
Minor version
+
bt_version_get_minor()
+ +
Patch version
+
bt_version_get_patch()
+ +
Extra information
+
bt_version_get_extra()
+
+*/ + +/*! @{ */ + +/*! +@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 +-pre5 or -rc1. + +@returns + @parblock + Extra information about the library's version. + + Cannot be \c NULL. + + Can be an empty string if there's no extra information. + @endparblock +*/ extern const char *bt_version_get_extra(void); +/*! @} */ + #ifdef __cplusplus } #endif diff --git a/src/bindings/python/bt2/bt2/native_bt.i b/src/bindings/python/bt2/bt2/native_bt.i index 919fc1dc..2300cee4 100644 --- a/src/bindings/python/bt2/bt2/native_bt.i +++ b/src/bindings/python/bt2/bt2/native_bt.i @@ -207,8 +207,8 @@ void bt_bt2_exit_handler(void); */ #define __BT_IN_BABELTRACE_H -/* Property enumeration */ -%include +/* Common types */ +%include /* Common function status codes */ %include diff --git a/src/bindings/python/bt2/bt2/native_bt_clock_class.i b/src/bindings/python/bt2/bt2/native_bt_clock_class.i index 4e7bfb22..251722ff 100644 --- a/src/bindings/python/bt2/bt2/native_bt_clock_class.i +++ b/src/bindings/python/bt2/bt2/native_bt_clock_class.i @@ -22,5 +22,4 @@ * THE SOFTWARE. */ -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i b/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i index 5423bafe..93408d3e 100644 --- a/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i +++ b/src/bindings/python/bt2/bt2/native_bt_clock_snapshot.i @@ -22,4 +22,4 @@ * THE SOFTWARE. */ -%include +%include diff --git a/src/bindings/python/bt2/bt2/native_bt_component.i b/src/bindings/python/bt2/bt2/native_bt_component.i index ae44579b..aa3f7252 100644 --- a/src/bindings/python/bt2/bt2/native_bt_component.i +++ b/src/bindings/python/bt2/bt2/native_bt_component.i @@ -82,14 +82,8 @@ } } -%include -%include -%include -%include +%include %include -%include -%include -%include /* * This type map relies on the rather common "user_data" name, so don't pollute diff --git a/src/bindings/python/bt2/bt2/native_bt_component_class.i b/src/bindings/python/bt2/bt2/native_bt_component_class.i index 4c26660f..06710faa 100644 --- a/src/bindings/python/bt2/bt2/native_bt_component_class.i +++ b/src/bindings/python/bt2/bt2/native_bt_component_class.i @@ -23,16 +23,8 @@ */ %include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include +%include +%include %{ #include "native_bt_component_class.i.h" diff --git a/src/bindings/python/bt2/bt2/native_bt_connection.i b/src/bindings/python/bt2/bt2/native_bt_connection.i index bb228583..042c71ab 100644 --- a/src/bindings/python/bt2/bt2/native_bt_connection.i +++ b/src/bindings/python/bt2/bt2/native_bt_connection.i @@ -22,4 +22,4 @@ * THE SOFTWARE. */ -%include +%include diff --git a/src/bindings/python/bt2/bt2/native_bt_error.i b/src/bindings/python/bt2/bt2/native_bt_error.i index 1ccf6c4a..ad73753e 100644 --- a/src/bindings/python/bt2/bt2/native_bt_error.i +++ b/src/bindings/python/bt2/bt2/native_bt_error.i @@ -25,9 +25,7 @@ * We include current-thread.h here, because for now, it only contains * error-related things. */ -%include -%include -%include +%include %{ #include "native_bt_error.i.h" diff --git a/src/bindings/python/bt2/bt2/native_bt_event.i b/src/bindings/python/bt2/bt2/native_bt_event.i index 7812b0cd..ea3d8150 100644 --- a/src/bindings/python/bt2/bt2/native_bt_event.i +++ b/src/bindings/python/bt2/bt2/native_bt_event.i @@ -22,5 +22,4 @@ * THE SOFTWARE. */ -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_event_class.i b/src/bindings/python/bt2/bt2/native_bt_event_class.i index 5bf6ebd2..14f51625 100644 --- a/src/bindings/python/bt2/bt2/native_bt_event_class.i +++ b/src/bindings/python/bt2/bt2/native_bt_event_class.i @@ -36,5 +36,4 @@ $result = SWIG_Python_AppendOutput($result, SWIG_From_int(*$1)); } -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_field.i b/src/bindings/python/bt2/bt2/native_bt_field.i index 8b944c63..d1429d55 100644 --- a/src/bindings/python/bt2/bt2/native_bt_field.i +++ b/src/bindings/python/bt2/bt2/native_bt_field.i @@ -25,5 +25,4 @@ /* For label type mappings. */ %include "native_bt_field_class.i" -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_field_class.i b/src/bindings/python/bt2/bt2/native_bt_field_class.i index 5a84b869..48f48c08 100644 --- a/src/bindings/python/bt2/bt2/native_bt_field_class.i +++ b/src/bindings/python/bt2/bt2/native_bt_field_class.i @@ -24,14 +24,14 @@ /* Parameter names seem to be required for multi-argument typemaps to match. */ %typemap(in, numinputs=0) - (bt_field_class_enumeration_mapping_label_array *label_array, uint64_t *count) + (bt_field_class_enumeration_mapping_label_array *labels, uint64_t *count) (bt_field_class_enumeration_mapping_label_array temp_array, uint64_t temp_label_count = 0) { $1 = &temp_array; $2 = &temp_label_count; } %typemap(argout) - (bt_field_class_enumeration_mapping_label_array *label_array, uint64_t *count) { + (bt_field_class_enumeration_mapping_label_array *labels, uint64_t *count) { if (*$1) { PyObject *py_label_list = PyList_New(*$2); uint64_t i; @@ -47,5 +47,4 @@ } } -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_field_path.i b/src/bindings/python/bt2/bt2/native_bt_field_path.i index 562e9d52..05313df2 100644 --- a/src/bindings/python/bt2/bt2/native_bt_field_path.i +++ b/src/bindings/python/bt2/bt2/native_bt_field_path.i @@ -22,4 +22,4 @@ * THE SOFTWARE. */ -%include +%include diff --git a/src/bindings/python/bt2/bt2/native_bt_graph.i b/src/bindings/python/bt2/bt2/native_bt_graph.i index 4a7b9f6d..0bda11f7 100644 --- a/src/bindings/python/bt2/bt2/native_bt_graph.i +++ b/src/bindings/python/bt2/bt2/native_bt_graph.i @@ -101,7 +101,6 @@ } } -%include %include /* Helper functions for Python */ diff --git a/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i b/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i index 7cd26f00..2f13cc0d 100644 --- a/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i +++ b/src/bindings/python/bt2/bt2/native_bt_integer_range_set.i @@ -23,4 +23,3 @@ */ %include -%include diff --git a/src/bindings/python/bt2/bt2/native_bt_interrupter.i b/src/bindings/python/bt2/bt2/native_bt_interrupter.i index 43991446..c3383416 100644 --- a/src/bindings/python/bt2/bt2/native_bt_interrupter.i +++ b/src/bindings/python/bt2/bt2/native_bt_interrupter.i @@ -23,4 +23,3 @@ */ %include -%include diff --git a/src/bindings/python/bt2/bt2/native_bt_message.i b/src/bindings/python/bt2/bt2/native_bt_message.i index 06726f42..8cc90553 100644 --- a/src/bindings/python/bt2/bt2/native_bt_message.i +++ b/src/bindings/python/bt2/bt2/native_bt_message.i @@ -44,21 +44,4 @@ } } -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include -%include +%include diff --git a/src/bindings/python/bt2/bt2/native_bt_mip.i b/src/bindings/python/bt2/bt2/native_bt_mip.i index 77cd251c..41da5fd6 100644 --- a/src/bindings/python/bt2/bt2/native_bt_mip.i +++ b/src/bindings/python/bt2/bt2/native_bt_mip.i @@ -23,8 +23,7 @@ */ %include -%include -%include +%include %{ #include "native_bt_mip.i.h" diff --git a/src/bindings/python/bt2/bt2/native_bt_packet.i b/src/bindings/python/bt2/bt2/native_bt_packet.i index 10357937..4b68d3c5 100644 --- a/src/bindings/python/bt2/bt2/native_bt_packet.i +++ b/src/bindings/python/bt2/bt2/native_bt_packet.i @@ -22,5 +22,4 @@ * THE SOFTWARE. */ -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_plugin.i b/src/bindings/python/bt2/bt2/native_bt_plugin.i index e96ea6ed..edd91e79 100644 --- a/src/bindings/python/bt2/bt2/native_bt_plugin.i +++ b/src/bindings/python/bt2/bt2/native_bt_plugin.i @@ -64,8 +64,7 @@ } } -%include -%include +%include /* Helpers */ diff --git a/src/bindings/python/bt2/bt2/native_bt_port.i b/src/bindings/python/bt2/bt2/native_bt_port.i index 590ded69..c8c0832e 100644 --- a/src/bindings/python/bt2/bt2/native_bt_port.i +++ b/src/bindings/python/bt2/bt2/native_bt_port.i @@ -35,12 +35,8 @@ $result = $1; } -%include -%include -%include +%include %include -%include -%include /* * Clear this typemap, since it is a bit broad and could apply to something we diff --git a/src/bindings/python/bt2/bt2/native_bt_query_exec.i b/src/bindings/python/bt2/bt2/native_bt_query_exec.i index a422ecbb..857c3363 100644 --- a/src/bindings/python/bt2/bt2/native_bt_query_exec.i +++ b/src/bindings/python/bt2/bt2/native_bt_query_exec.i @@ -23,7 +23,6 @@ */ %include -%include %include %{ diff --git a/src/bindings/python/bt2/bt2/native_bt_stream.i b/src/bindings/python/bt2/bt2/native_bt_stream.i index 95a9d366..28f2a39a 100644 --- a/src/bindings/python/bt2/bt2/native_bt_stream.i +++ b/src/bindings/python/bt2/bt2/native_bt_stream.i @@ -22,5 +22,4 @@ * THE SOFTWARE. */ -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_stream_class.i b/src/bindings/python/bt2/bt2/native_bt_stream_class.i index 69937bab..1c93cbd5 100644 --- a/src/bindings/python/bt2/bt2/native_bt_stream_class.i +++ b/src/bindings/python/bt2/bt2/native_bt_stream_class.i @@ -22,5 +22,4 @@ * THE SOFTWARE. */ -%include %include diff --git a/src/bindings/python/bt2/bt2/native_bt_trace.i b/src/bindings/python/bt2/bt2/native_bt_trace.i index 5ecccf0c..0868055c 100644 --- a/src/bindings/python/bt2/bt2/native_bt_trace.i +++ b/src/bindings/python/bt2/bt2/native_bt_trace.i @@ -22,7 +22,6 @@ * THE SOFTWARE. */ -%include %include %{ diff --git a/src/bindings/python/bt2/bt2/native_bt_trace_class.i b/src/bindings/python/bt2/bt2/native_bt_trace_class.i index cc079379..3e491693 100644 --- a/src/bindings/python/bt2/bt2/native_bt_trace_class.i +++ b/src/bindings/python/bt2/bt2/native_bt_trace_class.i @@ -22,7 +22,6 @@ * THE SOFTWARE. */ -%include %include /* Helper functions for Python */ diff --git a/src/bindings/python/bt2/bt2/native_bt_value.i b/src/bindings/python/bt2/bt2/native_bt_value.i index f31a6d44..c04bb7f5 100644 --- a/src/bindings/python/bt2/bt2/native_bt_value.i +++ b/src/bindings/python/bt2/bt2/native_bt_value.i @@ -22,7 +22,6 @@ * THE SOFTWARE. */ -%include %include %{ diff --git a/src/cli/babeltrace2-cfg-cli-args.h b/src/cli/babeltrace2-cfg-cli-args.h index 27ab45d1..d962145b 100644 --- a/src/cli/babeltrace2-cfg-cli-args.h +++ b/src/cli/babeltrace2-cfg-cli-args.h @@ -29,7 +29,7 @@ #include #include "lib/object.h" #include "compat/compiler.h" -#include +#include #include #include "babeltrace2-cfg.h" diff --git a/src/lib/graph/component-class-sink-simple.c b/src/lib/graph/component-class-sink-simple.c index e7ca81b9..f8ac7ad1 100644 --- a/src/lib/graph/component-class-sink-simple.c +++ b/src/lib/graph/component-class-sink-simple.c @@ -27,10 +27,10 @@ #include "common/common.h" #include "lib/assert-pre.h" #include "lib/object.h" -#include -#include +#include #include #include +#include #include #include "component-class-sink-simple.h" diff --git a/src/lib/graph/component-class-sink-simple.h b/src/lib/graph/component-class-sink-simple.h index a6c527de..91c03ed5 100644 --- a/src/lib/graph/component-class-sink-simple.h +++ b/src/lib/graph/component-class-sink-simple.h @@ -25,7 +25,7 @@ #include #include -#include +#include struct simple_sink_init_method_data { bt_graph_simple_sink_component_initialize_func init_func; diff --git a/src/lib/graph/component-class.c b/src/lib/graph/component-class.c index 1c1497db..be0fdf70 100644 --- a/src/lib/graph/component-class.c +++ b/src/lib/graph/component-class.c @@ -28,13 +28,6 @@ #include "lib/assert-pre.h" #include "compat/compiler.h" #include -#include -#include -#include -#include -#include -#include -#include #include #include diff --git a/src/lib/graph/component-class.h b/src/lib/graph/component-class.h index 5974d832..b829672a 100644 --- a/src/lib/graph/component-class.h +++ b/src/lib/graph/component-class.h @@ -26,11 +26,8 @@ * SOFTWARE. */ -#include #include -#include -#include -#include +#include #include "common/macros.h" #include "lib/object.h" #include "common/list.h" diff --git a/src/lib/graph/component-descriptor-set.c b/src/lib/graph/component-descriptor-set.c index e6b0894d..14b6e70d 100644 --- a/src/lib/graph/component-descriptor-set.c +++ b/src/lib/graph/component-descriptor-set.c @@ -30,7 +30,6 @@ #include "common/common.h" #include #include -#include #include #include diff --git a/src/lib/graph/component-filter.c b/src/lib/graph/component-filter.c index e805f8da..5d8e5cab 100644 --- a/src/lib/graph/component-filter.c +++ b/src/lib/graph/component-filter.c @@ -28,8 +28,8 @@ #include "lib/assert-pre.h" #include "compat/compiler.h" #include -#include -#include +#include +#include #include #include "component-filter.h" diff --git a/src/lib/graph/component-filter.h b/src/lib/graph/component-filter.h index 194bab0f..87e5a01a 100644 --- a/src/lib/graph/component-filter.h +++ b/src/lib/graph/component-filter.h @@ -25,7 +25,7 @@ */ #include "common/macros.h" -#include +#include #include "component-class.h" #include "component.h" diff --git a/src/lib/graph/component-sink.c b/src/lib/graph/component-sink.c index 12ea8c27..7a24fed9 100644 --- a/src/lib/graph/component-sink.c +++ b/src/lib/graph/component-sink.c @@ -29,8 +29,8 @@ #include "lib/assert-post.h" #include "compat/compiler.h" #include -#include -#include +#include +#include #include #include "component-sink.h" diff --git a/src/lib/graph/component-sink.h b/src/lib/graph/component-sink.h index c523c770..7aaafc21 100644 --- a/src/lib/graph/component-sink.h +++ b/src/lib/graph/component-sink.h @@ -28,7 +28,7 @@ #include "common/macros.h" #include "compat/compiler.h" -#include +#include #include "component-class.h" #include "component.h" diff --git a/src/lib/graph/component-source.c b/src/lib/graph/component-source.c index 0e3eedc2..1bbb0e73 100644 --- a/src/lib/graph/component-source.c +++ b/src/lib/graph/component-source.c @@ -27,8 +27,8 @@ #include "common/assert.h" #include "lib/assert-pre.h" #include "compat/compiler.h" -#include -#include +#include +#include #include #include "component-source.h" diff --git a/src/lib/graph/component.c b/src/lib/graph/component.c index c771e278..65978e94 100644 --- a/src/lib/graph/component.c +++ b/src/lib/graph/component.c @@ -29,11 +29,8 @@ #include "lib/assert-pre.h" #include "lib/assert-post.h" #include -#include -#include -#include -#include -#include +#include +#include #include "common/macros.h" #include "compat/compiler.h" #include diff --git a/src/lib/graph/component.h b/src/lib/graph/component.h index 531bd63a..0925d5f2 100644 --- a/src/lib/graph/component.h +++ b/src/lib/graph/component.h @@ -25,7 +25,7 @@ */ #include "common/macros.h" -#include +#include #include #include "lib/object.h" #include diff --git a/src/lib/graph/connection.c b/src/lib/graph/connection.c index 743553b9..6552b5f2 100644 --- a/src/lib/graph/connection.c +++ b/src/lib/graph/connection.c @@ -27,7 +27,7 @@ #include "common/assert.h" #include "lib/assert-pre.h" #include "lib/assert-post.h" -#include +#include #include "lib/object.h" #include "compat/compiler.h" #include diff --git a/src/lib/graph/connection.h b/src/lib/graph/connection.h index 2024244d..1d89c993 100644 --- a/src/lib/graph/connection.h +++ b/src/lib/graph/connection.h @@ -24,7 +24,7 @@ * SOFTWARE. */ -#include +#include #include "lib/object.h" #include "common/assert.h" #include "common/macros.h" diff --git a/src/lib/graph/graph.c b/src/lib/graph/graph.c index 9e7e8ffc..b545a8ef 100644 --- a/src/lib/graph/graph.c +++ b/src/lib/graph/graph.c @@ -28,16 +28,13 @@ #include "lib/assert-pre.h" #include "lib/assert-post.h" #include -#include -#include -#include -#include +#include +#include #include "lib/graph/message/message.h" #include "compat/compiler.h" #include "common/common.h" #include #include -#include #include "lib/value.h" #include #include diff --git a/src/lib/graph/graph.h b/src/lib/graph/graph.h index 7e927e7a..7fffd0ca 100644 --- a/src/lib/graph/graph.h +++ b/src/lib/graph/graph.h @@ -30,7 +30,7 @@ #endif #include -#include +#include #include "common/macros.h" #include "lib/object.h" #include "lib/object-pool.h" diff --git a/src/lib/graph/iterator.c b/src/lib/graph/iterator.c index 5b2ebfbd..0beb6949 100644 --- a/src/lib/graph/iterator.c +++ b/src/lib/graph/iterator.c @@ -29,30 +29,21 @@ #include "lib/trace-ir/clock-class.h" #include "lib/trace-ir/clock-snapshot.h" #include -#include +#include #include "lib/trace-ir/event.h" -#include +#include #include "lib/trace-ir/packet.h" #include "lib/trace-ir/stream.h" -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include +#include +#include +#include +#include +#include +#include +#include +#include #include -#include +#include #include #include "common/assert.h" #include "lib/assert-pre.h" diff --git a/src/lib/graph/message/discarded-items.c b/src/lib/graph/message/discarded-items.c index 0b19abc3..e7646377 100644 --- a/src/lib/graph/message/discarded-items.c +++ b/src/lib/graph/message/discarded-items.c @@ -34,10 +34,6 @@ #include "lib/trace-ir/stream.h" #include "lib/property.h" #include "lib/graph/message/message.h" -#include -#include -#include -#include #include "discarded-items.h" diff --git a/src/lib/graph/message/discarded-items.h b/src/lib/graph/message/discarded-items.h index d9f3fb60..915cac16 100644 --- a/src/lib/graph/message/discarded-items.h +++ b/src/lib/graph/message/discarded-items.h @@ -27,7 +27,7 @@ #include "lib/trace-ir/clock-snapshot.h" #include "lib/trace-ir/stream.h" #include "lib/property.h" -#include +#include #include "message.h" diff --git a/src/lib/graph/message/event.c b/src/lib/graph/message/event.c index 8b211e10..0f7a8a0a 100644 --- a/src/lib/graph/message/event.c +++ b/src/lib/graph/message/event.c @@ -36,8 +36,7 @@ #include #include "lib/trace-ir/clock-snapshot.h" #include "lib/graph/graph.h" -#include -#include +#include #include #include #include diff --git a/src/lib/graph/message/iterator.h b/src/lib/graph/message/iterator.h index 68bdc833..f6e642b4 100644 --- a/src/lib/graph/message/iterator.h +++ b/src/lib/graph/message/iterator.h @@ -26,8 +26,8 @@ #include "common/macros.h" #include "lib/object.h" -#include -#include +#include +#include #include #include "common/assert.h" #include diff --git a/src/lib/graph/message/message-iterator-inactivity.c b/src/lib/graph/message/message-iterator-inactivity.c index d0c27e3d..1754f385 100644 --- a/src/lib/graph/message/message-iterator-inactivity.c +++ b/src/lib/graph/message/message-iterator-inactivity.c @@ -29,8 +29,7 @@ #include #include "lib/trace-ir/clock-snapshot.h" #include "lib/graph/message/message.h" -#include -#include +#include #include "message-iterator-inactivity.h" diff --git a/src/lib/graph/message/message-iterator-inactivity.h b/src/lib/graph/message/message-iterator-inactivity.h index 6e8c1fdd..942a7980 100644 --- a/src/lib/graph/message/message-iterator-inactivity.h +++ b/src/lib/graph/message/message-iterator-inactivity.h @@ -25,7 +25,7 @@ #include #include "lib/trace-ir/clock-snapshot.h" -#include +#include struct bt_message_message_iterator_inactivity { struct bt_message parent; diff --git a/src/lib/graph/message/message.c b/src/lib/graph/message/message.c index 5d1d8139..98d2eab2 100644 --- a/src/lib/graph/message/message.c +++ b/src/lib/graph/message/message.c @@ -27,7 +27,7 @@ #include "common/assert.h" #include "lib/assert-pre.h" #include "lib/assert-post.h" -#include +#include #include "lib/graph/message/message.h" #include "lib/graph/graph.h" @@ -37,7 +37,6 @@ void bt_message_init(struct bt_message *message, bt_object_release_func release, struct bt_graph *graph) { - BT_ASSERT(type >= 0 && type <= BT_MESSAGE_TYPE_DISCARDED_PACKETS); message->type = type; bt_object_init_shared(&message->base, release); message->graph = graph; diff --git a/src/lib/graph/message/message.h b/src/lib/graph/message/message.h index f290e3fd..ec7d2a6c 100644 --- a/src/lib/graph/message/message.h +++ b/src/lib/graph/message/message.h @@ -33,7 +33,7 @@ #include "lib/object.h" #include "common/assert.h" #include -#include +#include #include #include "lib/object-pool.h" #include diff --git a/src/lib/graph/message/packet.c b/src/lib/graph/message/packet.c index 125e49f6..6798fe51 100644 --- a/src/lib/graph/message/packet.c +++ b/src/lib/graph/message/packet.c @@ -36,10 +36,7 @@ #include "lib/trace-ir/stream.h" #include "lib/trace-ir/stream-class.h" #include "lib/graph/graph.h" -#include -#include -#include -#include +#include #include "common/assert.h" #include "lib/object.h" #include diff --git a/src/lib/graph/message/stream.c b/src/lib/graph/message/stream.c index 40903d00..1ecb452f 100644 --- a/src/lib/graph/message/stream.c +++ b/src/lib/graph/message/stream.c @@ -26,14 +26,11 @@ #include "lib/assert-pre.h" #include "compat/compiler.h" -#include +#include #include "lib/trace-ir/stream.h" #include #include "lib/trace-ir/stream-class.h" -#include -#include -#include -#include +#include #include "common/assert.h" #include diff --git a/src/lib/graph/message/stream.h b/src/lib/graph/message/stream.h index ed5d2816..6f261b05 100644 --- a/src/lib/graph/message/stream.h +++ b/src/lib/graph/message/stream.h @@ -24,7 +24,7 @@ * SOFTWARE. */ -#include +#include #include "compat/compiler.h" #include "lib/trace-ir/stream.h" diff --git a/src/lib/graph/mip.c b/src/lib/graph/mip.c index a4704c5d..27da722f 100644 --- a/src/lib/graph/mip.c +++ b/src/lib/graph/mip.c @@ -28,7 +28,7 @@ #include #include #include -#include +#include #include "common/assert.h" #include "compat/compiler.h" diff --git a/src/lib/graph/port.c b/src/lib/graph/port.c index 7ca86abe..46735e22 100644 --- a/src/lib/graph/port.c +++ b/src/lib/graph/port.c @@ -26,12 +26,8 @@ #include "common/assert.h" #include "lib/assert-pre.h" -#include -#include -#include +#include #include -#include -#include #include "lib/object.h" #include "compat/compiler.h" diff --git a/src/lib/graph/port.h b/src/lib/graph/port.h index 5ab27774..2592705e 100644 --- a/src/lib/graph/port.h +++ b/src/lib/graph/port.h @@ -24,7 +24,7 @@ * SOFTWARE. */ -#include +#include #include "common/macros.h" struct bt_port { diff --git a/src/lib/graph/query-executor.c b/src/lib/graph/query-executor.c index bc6f542a..e922d3ea 100644 --- a/src/lib/graph/query-executor.c +++ b/src/lib/graph/query-executor.c @@ -27,11 +27,10 @@ #include "common/common.h" #include "lib/assert-pre.h" #include "lib/assert-post.h" -#include #include #include +#include #include -#include #include "lib/object.h" #include "compat/compiler.h" diff --git a/src/lib/plugin/plugin-so.c b/src/lib/plugin/plugin-so.c index ebdbf823..3684acae 100644 --- a/src/lib/plugin/plugin-so.c +++ b/src/lib/plugin/plugin-so.c @@ -32,9 +32,6 @@ #include #include "lib/graph/component-class.h" #include -#include -#include -#include #include #include "common/list.h" #include diff --git a/src/lib/plugin/plugin.c b/src/lib/plugin/plugin.c index 16850d80..838ceeff 100644 --- a/src/lib/plugin/plugin.c +++ b/src/lib/plugin/plugin.c @@ -31,9 +31,9 @@ #include "common/macros.h" #include "compat/compiler.h" #include "common/common.h" -#include -#include -#include +#include +#include +#include #include "lib/graph/component-class.h" #include #include diff --git a/src/lib/plugin/plugin.h b/src/lib/plugin/plugin.h index b91adf4b..5f8e6b11 100644 --- a/src/lib/plugin/plugin.h +++ b/src/lib/plugin/plugin.h @@ -27,7 +27,7 @@ #include "common/macros.h" #include "common/common.h" #include "lib/graph/component-class.h" -#include +#include #include #include "lib/object.h" #include diff --git a/src/lib/trace-ir/attributes.c b/src/lib/trace-ir/attributes.c index 986ee383..fffedc3b 100644 --- a/src/lib/trace-ir/attributes.c +++ b/src/lib/trace-ir/attributes.c @@ -28,7 +28,7 @@ #include #include "lib/assert-pre.h" #include "lib/object.h" -#include +#include #include "lib/value.h" #include "attributes.h" #include diff --git a/src/lib/trace-ir/clock-class.c b/src/lib/trace-ir/clock-class.c index 736e0b8e..8a3640bc 100644 --- a/src/lib/trace-ir/clock-class.c +++ b/src/lib/trace-ir/clock-class.c @@ -26,7 +26,6 @@ #include "lib/assert-pre.h" #include "common/uuid.h" -#include #include #include "clock-class.h" #include "clock-snapshot.h" diff --git a/src/lib/trace-ir/clock-snapshot.c b/src/lib/trace-ir/clock-snapshot.c index 19aab80a..9d20c9c1 100644 --- a/src/lib/trace-ir/clock-snapshot.c +++ b/src/lib/trace-ir/clock-snapshot.c @@ -27,7 +27,7 @@ #include "common/uuid.h" #include "clock-class.h" #include "clock-snapshot.h" -#include +#include #include "compat/compiler.h" #include #include "compat/string.h" diff --git a/src/lib/trace-ir/event-class.c b/src/lib/trace-ir/event-class.c index 22211cd1..20b8850d 100644 --- a/src/lib/trace-ir/event-class.c +++ b/src/lib/trace-ir/event-class.c @@ -27,7 +27,6 @@ #include "lib/assert-pre.h" #include #include -#include #include #include "compat/compiler.h" #include "compat/endian.h" diff --git a/src/lib/trace-ir/event.c b/src/lib/trace-ir/event.c index ed2e2f84..d110aed8 100644 --- a/src/lib/trace-ir/event.c +++ b/src/lib/trace-ir/event.c @@ -25,10 +25,9 @@ #include "lib/logging.h" #include "lib/assert-pre.h" -#include +#include #include #include -#include #include #include #include "common/assert.h" diff --git a/src/lib/trace-ir/field-class.c b/src/lib/trace-ir/field-class.c index e036cfae..b4a54266 100644 --- a/src/lib/trace-ir/field-class.c +++ b/src/lib/trace-ir/field-class.c @@ -26,8 +26,6 @@ #include "lib/assert-pre.h" #include -#include -#include #include #include #include "lib/object.h" diff --git a/src/lib/trace-ir/field-path.c b/src/lib/trace-ir/field-path.c index 4e5b16f7..d91db38b 100644 --- a/src/lib/trace-ir/field-path.c +++ b/src/lib/trace-ir/field-path.c @@ -26,7 +26,7 @@ #include "lib/assert-pre.h" #include -#include +#include #include #include #include diff --git a/src/lib/trace-ir/field-path.h b/src/lib/trace-ir/field-path.h index 99c8f958..cda0ba2d 100644 --- a/src/lib/trace-ir/field-path.h +++ b/src/lib/trace-ir/field-path.h @@ -27,7 +27,7 @@ */ #include "lib/object.h" -#include +#include #include "common/assert.h" #include "common/macros.h" #include diff --git a/src/lib/trace-ir/field.c b/src/lib/trace-ir/field.c index 9ab11aac..c53d7faf 100644 --- a/src/lib/trace-ir/field.c +++ b/src/lib/trace-ir/field.c @@ -26,7 +26,6 @@ #include "lib/assert-pre.h" #include -#include #include "lib/object.h" #include "compat/compiler.h" #include "compat/fcntl.h" diff --git a/src/lib/trace-ir/packet.c b/src/lib/trace-ir/packet.c index 50304868..388e196f 100644 --- a/src/lib/trace-ir/packet.c +++ b/src/lib/trace-ir/packet.c @@ -24,7 +24,6 @@ #include "lib/logging.h" #include "lib/assert-pre.h" -#include #include #include #include diff --git a/src/lib/trace-ir/packet.h b/src/lib/trace-ir/packet.h index e2d825c6..cf3d80c7 100644 --- a/src/lib/trace-ir/packet.h +++ b/src/lib/trace-ir/packet.h @@ -25,7 +25,7 @@ #include #include "common/assert.h" -#include +#include #include #include #include diff --git a/src/lib/trace-ir/resolve-field-path.c b/src/lib/trace-ir/resolve-field-path.c index 9e8e4729..d92a7f3d 100644 --- a/src/lib/trace-ir/resolve-field-path.c +++ b/src/lib/trace-ir/resolve-field-path.c @@ -25,7 +25,7 @@ #include "lib/assert-pre.h" #include "common/assert.h" -#include +#include #include #include #include diff --git a/src/lib/trace-ir/resolve-field-path.h b/src/lib/trace-ir/resolve-field-path.h index 92e277b8..f44ef858 100644 --- a/src/lib/trace-ir/resolve-field-path.h +++ b/src/lib/trace-ir/resolve-field-path.h @@ -28,8 +28,8 @@ #include "common/macros.h" #include "lib/object.h" -#include -#include +#include +#include #include struct bt_resolve_field_path_context { diff --git a/src/lib/trace-ir/stream-class.c b/src/lib/trace-ir/stream-class.c index e580b2a9..e402f415 100644 --- a/src/lib/trace-ir/stream-class.c +++ b/src/lib/trace-ir/stream-class.c @@ -25,7 +25,7 @@ #include "lib/logging.h" #include "lib/assert-pre.h" -#include +#include #include "compat/compiler.h" #include "common/align.h" #include "compat/endian.h" diff --git a/src/lib/trace-ir/stream.c b/src/lib/trace-ir/stream.c index c35b9da9..18e8d093 100644 --- a/src/lib/trace-ir/stream.c +++ b/src/lib/trace-ir/stream.c @@ -25,7 +25,6 @@ #include "lib/logging.h" #include "lib/assert-pre.h" -#include #include #include #include diff --git a/src/lib/trace-ir/trace-class.c b/src/lib/trace-ir/trace-class.c index 15330099..593f390e 100644 --- a/src/lib/trace-ir/trace-class.c +++ b/src/lib/trace-ir/trace-class.c @@ -27,13 +27,11 @@ #include "lib/assert-pre.h" #include "lib/assert-post.h" #include -#include #include #include "ctf-writer/functor.h" #include "ctf-writer/clock.h" #include "compat/compiler.h" #include -#include #include "lib/value.h" #include #include "compat/endian.h" diff --git a/src/lib/trace-ir/trace.c b/src/lib/trace-ir/trace.c index 57ebf67b..688a113e 100644 --- a/src/lib/trace-ir/trace.c +++ b/src/lib/trace-ir/trace.c @@ -27,13 +27,11 @@ #include "lib/assert-pre.h" #include "lib/assert-post.h" #include -#include #include #include "ctf-writer/functor.h" #include "ctf-writer/clock.h" #include "compat/compiler.h" #include -#include #include "lib/value.h" #include #include "compat/endian.h" diff --git a/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c b/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c index 1b88e0f1..8faff7bc 100644 --- a/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c +++ b/src/plugins/lttng-utils/debug-info/trace-ir-mapping.c @@ -32,8 +32,6 @@ #include "common/assert.h" #include -/* For bt_property_availability */ -#include #include "debug-info.h" #include "trace-ir-data-copy.h" diff --git a/src/python-plugin-provider/python-plugin-provider.c b/src/python-plugin-provider/python-plugin-provider.c index 71bedfc3..5d8d8b65 100644 --- a/src/python-plugin-provider/python-plugin-provider.c +++ b/src/python-plugin-provider/python-plugin-provider.c @@ -31,10 +31,10 @@ #include "common/macros.h" #include "compat/compiler.h" -#include +#include #include "lib/plugin/plugin.h" #include -#include +#include #include "lib/graph/component-class.h" #include "py-common/py-common.h" #include