+/*!
+@defgroup api-qexec Query executor
+@ingroup api-graph
+
+@brief
+ Executor of \bt_comp_cls object queries.
+
+A <strong><em>query executor</em></strong> is an executor of
+\bt_comp_cls object queries.
+
+A component class can implement a query method to offer one or more
+\em objects depending on the query parameters.
+
+Both the query parameters and the returned objects are \bt_p_val.
+
+The query operation feature exists so that you can get benefit from a
+component class's implementation to get information about a trace, a
+stream, a distant server, and so on. For example, the
+<code>source.ctf.lttng-live</code> component class (see
+\bt_man{babeltrace2-source.ctf.lttng-live,7}) offers the \c sessions
+object to list the available
+<a href="https://lttng.org/docs/#doc-lttng-live">LTTng live</a>
+tracing session names and other properties.
+
+The semantics of the query parameters and the returned object are
+completely defined by the component class implementation: the library
+does not enforce or suggest any layout. The best way to know which
+objects you can query from a component class, what are the expected and
+optional parameters, and what the returned object contains is to read
+this component class's documentation.
+
+The purpose of the query executor itself is to keep some state for a
+specific query operation. For example, you can set a query executor's
+logging level with bt_query_executor_set_logging_level(); then a
+component class's query method can get the executor's current logging
+level with bt_query_executor_get_logging_level().
+
+Also, the query executor is an interruptible object: a long or blocking
+query operation can run, checking whether the executor is interrupted
+periodically, while another thread or a signal handler can interrupt the
+executor.
+
+A query executor is a
+\ref api-fund-shared-object "shared object": get a new reference with
+bt_query_executor_get_ref() and put an existing reference with
+bt_query_executor_put_ref().
+
+The type of a query executor is #bt_query_executor.
+
+Create a query executor with bt_query_executor_create() or
+bt_query_executor_create_with_method_data(). When you do so, you set the
+name of the object to query, from which component class to query the
+object, and what are the query parameters. You cannot change those
+properties once the query executor is created. With
+bt_query_executor_create_with_method_data(), you can also pass
+a custom, \bt_voidp pointer to the component class's
+query method.
+
+Perform a query operation with bt_query_executor_query(). This function
+can return #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN, in which case you can
+try to perform a query operation again later. It can also return
+#BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT, which means the
+component class does not offer the requested object.
+
+To interrupt a running query operation, either:
+
+- Borrow the query executor's default \bt_intr with
+ bt_query_executor_borrow_default_interrupter() and set it with
+ bt_interrupter_set().
+
+ When you call bt_query_executor_create() or
+ bt_query_executor_create_with_method_data(), the returned query
+ executor has a default interrupter.
+
+- Add your own interrupter with bt_query_executor_add_interrupter()
+ \em before you perform the query operation with
+ bt_query_executor_query().
+
+ Then, set the interrupter with bt_interrupter_set().
+
+<h1>Property</h1>
+
+A query executor has the following property:
+
+<dl>
+ <dt>
+ \anchor api-qexec-prop-log-lvl
+ Logging level
+ </dt>
+ <dd>
+ Logging level of the query executor's query operations.
+
+ Use bt_query_executor_set_logging_level() and
+ bt_query_executor_get_logging_level().
+ </dd>
+</dl>
+*/
+
+/*! @{ */
+
+/*!
+@name Type
+@{
+
+@typedef struct bt_query_executor bt_query_executor;
+
+@brief
+ Query executor.
+
+@}
+*/
+
+/*!
+@name Creation
+@{
+*/
+
+/*!
+@brief
+ Alias of bt_query_executor_create_with_method_data()
+ with the \bt_p{method_data} parameter set to \c NULL.
+*/
+extern
+bt_query_executor *bt_query_executor_create(
+ const bt_component_class *component_class,
+ const char *object_name, const bt_value *params);
+
+/*!
+@brief
+ Creates a query executor to query the object named
+ \bt_p{object_name} from the \bt_comp_cls \bt_p{component_class} with
+ the parameters \bt_p{params} and the query user data
+ \bt_p{method_data}.
+
+When you call bt_query_executor_query() with the returned query
+executor, the query method of \bt_p{component_class} receives:
+
+- \bt_p{object_name} as its own \bt_p{object_name} parameter.
+
+- \bt_p{params} as its own \bt_p{params} parameter
+ (or #bt_value_null if \bt_p{params} is \c NULL).
+
+- \bt_p{method_data} as its own \bt_p{method_data} parameter.
+
+@param[in] component_class
+ Component class from which to query the object named
+ \bt_p{object_name}.
+@param[in] object_name
+ Name of the object to query from \bt_p{component_class}.
+@param[in] params
+ @parblock
+ Parameters for the query operation performed by the query executor
+ to create.
+
+ Unlike the \bt_p{params} parameter of
+ the <code>bt_graph_add_*_component_*_port_added_listener()</code>
+ functions (see \ref api-graph), this parameter does not need to
+ be a \bt_map_val.
+
+ Can be \c NULL (equivalent to passing #bt_value_null).
+ @endparblock
+@param[in] method_data
+ User data passed as is to the query method of \bt_p{component_class}
+ when you call bt_query_executor_query().
+
+@returns
+ New query executor reference, or \c NULL on memory error.
+
+@bt_pre_not_null{component_class}
+@bt_pre_not_null{object}
+
+@bt_post_success_frozen{component_class}
+@bt_post_success_frozen{params}
+*/