[babeltrace.git] / include / babeltrace2 / graph / query-executor.h

#ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
#define BABELTRACE2_GRAPH_QUERY_EXECUTOR_H

/*
 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#ifndef __BT_IN_BABELTRACE_H
# error "Please include <babeltrace2/babeltrace.h> instead."
#endif

#include <babeltrace2/types.h>
#include <babeltrace2/logging.h>

#ifdef __cplusplus
extern "C" {
#endif

/*!
@defgroup api-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}
*/
extern
bt_query_executor *bt_query_executor_create_with_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,

	/*!
	@brief
	    Out of memory.
	*/
	BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,

	/*!
	@brief
	    Other error.
	*/
	BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR		= __BT_FUNC_STATUS_ERROR,
} bt_query_executor_query_status;

/*!
@brief
    Performs a query operation using the query executor
    \bt_p{query_executor}, setting \bt_p{*result} to the operation's
    result on success.

This function calls the query executor's target \bt_comp_cls's
query method, passing:

- The object name of \bt_p{query_executor} as the
  \bt_p{object_name} parameter.

- The query parameters of \bt_p{query_executor} as the
  \bt_p{params} parameter.

- The query user data of \bt_p{query_executor} as the \bt_p{method_data}
  parameter.

The three items above were set when you created \bt_p{query_executor}
with bt_query_executor_create() or
bt_query_executor_create_with_method_data().

@param[in] query_executor
    Query executor to use to execute the query operation.
@param[out] result
    <strong>On success</strong>, \bt_p{*result} is a \em strong
    reference of the query operation's result.

@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
    Success.
@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
    Unknown object to query.
@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
    Try again.
@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
    Out of memory.
@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
    Other error.

@bt_pre_not_null{query_executor}
@bt_pre_not_null{result}
*/
extern
bt_query_executor_query_status bt_query_executor_query(
		bt_query_executor *query_executor, const bt_value **result);

/*! @} */

/*!
@name Property
@{
*/

/*!
@brief
    Status codes for bt_query_executor_set_logging_level().
*/
typedef enum bt_query_executor_set_logging_level_status {
	/*!
	@brief
	    Success.
	*/
	BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK	= __BT_FUNC_STATUS_OK,
} bt_query_executor_set_logging_level_status;

/*!
@brief
    Sets the logging level of the query executor \bt_p{query_executor}
    to \bt_p{logging_level}.

See the \ref api-qexec-prop-log-lvl "logging level" property.

@param[in] query_executor
    Query executor of which to set the logging level to
    \bt_p{logging_level}.
@param[in] logging_level
    New logging level of \bt_p{query_executor}.

@retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
    Success.

@bt_pre_not_null{query_executor}

@sa bt_stream_class_get_logging_level() &mdash;
    Returns the logging level of a query executor.
*/
extern bt_query_executor_set_logging_level_status
bt_query_executor_set_logging_level(bt_query_executor *query_executor,
		bt_logging_level logging_level);

/*!
@brief
    Returns the logging level of the query executor
    \bt_p{query_executor}.

See the \ref api-qexec-prop-log-lvl "logging level" property.

@param[in] query_executor
    Query executor of which to get the logging level.

@returns
    Logging level of \bt_p{query_executor}.

@bt_pre_not_null{query_executor}

@sa bt_query_executor_set_logging_level() &mdash;
    Sets the logging level of a query executor.
*/
extern bt_logging_level bt_query_executor_get_logging_level(
		const bt_query_executor *query_executor);

/*! @} */

/*!
@name Interruption
@{
*/

/*!
@brief
    Status codes for bt_query_executor_add_interrupter().
*/
typedef enum bt_query_executor_add_interrupter_status {
	/*!
	@brief
	    Success.
	*/
	BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK		= __BT_FUNC_STATUS_OK,

	/*!
	@brief
	    Out of memory.
	*/
	BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR	= __BT_FUNC_STATUS_MEMORY_ERROR,
} bt_query_executor_add_interrupter_status;

/*!
@brief
    Adds the \bt_intr \bt_p{interrupter} to the query executor
    \bt_p{query_executor}.

A \bt_comp_cls query method can check whether or not its executor is
interrupted (any of its interrupters, including its default interrupter,
is set) with bt_query_executor_is_interrupted().

@note
    @parblock
    bt_query_executor_create() and
    bt_query_executor_create_with_method_data() return a query executor
    which comes with its own <em>default interrupter</em>.

    Instead of adding your own interrupter to \bt_p{query_executor}, you
    can set its default interrupter with

    @code
    bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
    @endcode
    @endparblock

@param[in] query_executor
    Query executor to which to add \bt_p{interrupter}.
@param[in] interrupter
    Interrupter to add to \bt_p{query_executor}.

@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
    Success.
@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
    Out of memory.

@bt_pre_not_null{query_executor}
@bt_pre_not_null{interrupter}

@sa bt_query_executor_borrow_default_interrupter() &mdash;
    Borrows the default interrupter from a query executor.
*/
extern bt_query_executor_add_interrupter_status
bt_query_executor_add_interrupter(bt_query_executor *query_executor,
		const bt_interrupter *interrupter);

/*!
@brief
    Borrows the default \bt_intr from the query executor
    \bt_p{query_executor}.

@param[in] query_executor
    Query executor from which to borrow the default interrupter.

@returns
    @parblock
    \em Borrowed reference of the default interrupter of
    \bt_p{query_executor}.

    The returned pointer remains valid as long as \bt_p{query_executor}
    exists.
    @endparblock

@bt_pre_not_null{query_executor}

@sa bt_query_executor_add_interrupter() &mdash;
    Adds an interrupter to a query executor.
*/
extern bt_interrupter *bt_query_executor_borrow_default_interrupter(
		bt_query_executor *query_executor);

/*!
@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.

@param[in] query_executor
    Query executor to check.

@returns
    #BT_TRUE if \bt_p{query_executor} is interrupted (any of its
    interrupters is set).

@bt_pre_not_null{query_executor}
*/
extern bt_bool bt_query_executor_is_interrupted(
		const bt_query_executor *query_executor);

/*! @} */

/*!
@name Reference count
@{
*/

/*!
@brief
    Increments the \ref api-fund-shared-object "reference count" of
    the query executor \bt_p{query_executor}.

@param[in] query_executor
    @parblock
    Query executor of which to increment the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_query_executor_put_ref() &mdash;
    Decrements the reference count of a query executor.
*/
extern void bt_query_executor_get_ref(const bt_query_executor *query_executor);

/*!
@brief
    Decrements the \ref api-fund-shared-object "reference count" of
    the query executor \bt_p{query_executor}.

@param[in] query_executor
    @parblock
    Query executor of which to decrement the reference count.

    Can be \c NULL.
    @endparblock

@sa bt_query_executor_get_ref() &mdash;
    Increments the reference count of a query executor.
*/
extern void bt_query_executor_put_ref(const bt_query_executor *query_executor);

/*!
@brief
    Decrements the reference count of the query executor
    \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.

@param _query_executor
    @parblock
    Query executor of which to decrement the reference count.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_query_executor}
*/
#define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor)	\
	do {							\
		bt_query_executor_put_ref(_query_executor);	\
		(_query_executor) = NULL;			\
	} while (0)

/*!
@brief
    Decrements the reference count of the query executor \bt_p{_dst}, sets
    \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.

This macro effectively moves a query executor reference from the expression
\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
\bt_p{_dst} reference.

@param _dst
    @parblock
    Destination expression.

    Can contain \c NULL.
    @endparblock
@param _src
    @parblock
    Source expression.

    Can contain \c NULL.
    @endparblock

@bt_pre_assign_expr{_dst}
@bt_pre_assign_expr{_src}
*/
#define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src)		\
	do {						\
		bt_query_executor_put_ref(_dst);	\
		(_dst) = (_src);			\
		(_src) = NULL;				\
	} while (0)

/*! @} */

/*! @} */

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */
Commit	Line	Data
924dc299 PP	1	#ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
924dc299 PP	2	#define BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
c7eee084 PP	3
c7eee084 PP	4	/*
bbb7b5f0	5	* Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
c7eee084 PP	6	*
	7	* Permission is hereby granted, free of charge, to any person obtaining a copy
	8	* of this software and associated documentation files (the "Software"), to deal
	9	* in the Software without restriction, including without limitation the rights
	10	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	11	* copies of the Software, and to permit persons to whom the Software is
	12	* furnished to do so, subject to the following conditions:
	13	*
	14	* The above copyright notice and this permission notice shall be included in
	15	* all copies or substantial portions of the Software.
	16	*
	17	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	18	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	19	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	20	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	21	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	22	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	23	* SOFTWARE.
	24	*/
	25
4fa90f32 PP	26	#ifndef __BT_IN_BABELTRACE_H
	27	# error "Please include <babeltrace2/babeltrace.h> instead."
	28	#endif
	29
3fadfbc0	30	#include <babeltrace2/types.h>
f4e38e70 PP	31	#include <babeltrace2/logging.h>
f4e38e70 PP	32
c7eee084 PP	33	#ifdef __cplusplus
	34	extern "C" {
	35	#endif
	36
43c59509 PP	37	/*!
	38	@defgroup api-qexec Query executor
	39	@ingroup api-graph
	40
	41	@brief
	42	Executor of \bt_comp_cls object queries.
	43
	44	A <strong><em>query executor</em></strong> is an executor of
	45	\bt_comp_cls object queries.
	46
	47	A component class can implement a query method to offer one or more
	48	\em objects depending on the query parameters.
	49
	50	Both the query parameters and the returned objects are \bt_p_val.
	51
	52	The query operation feature exists so that you can get benefit from a
	53	component class's implementation to get information about a trace, a
	54	stream, a distant server, and so on. For example, the
	55	<code>source.ctf.lttng-live</code> component class (see
	56	\bt_man{babeltrace2-source.ctf.lttng-live,7}) offers the \c sessions
	57	object to list the available
	58	<a href="https://lttng.org/docs/#doc-lttng-live">LTTng live</a>
	59	tracing session names and other properties.
	60
	61	The semantics of the query parameters and the returned object are
	62	completely defined by the component class implementation: the library
	63	does not enforce or suggest any layout. The best way to know which
	64	objects you can query from a component class, what are the expected and
	65	optional parameters, and what the returned object contains is to read
	66	this component class's documentation.
	67
	68	The purpose of the query executor itself is to keep some state for a
	69	specific query operation. For example, you can set a query executor's
	70	logging level with bt_query_executor_set_logging_level(); then a
	71	component class's query method can get the executor's current logging
	72	level with bt_query_executor_get_logging_level().
	73
	74	Also, the query executor is an interruptible object: a long or blocking
	75	query operation can run, checking whether the executor is interrupted
	76	periodically, while another thread or a signal handler can interrupt the
	77	executor.
	78
	79	A query executor is a
	80	\ref api-fund-shared-object "shared object": get a new reference with
	81	bt_query_executor_get_ref() and put an existing reference with
	82	bt_query_executor_put_ref().
	83
	84	The type of a query executor is #bt_query_executor.
	85
	86	Create a query executor with bt_query_executor_create() or
	87	bt_query_executor_create_with_method_data(). When you do so, you set the
	88	name of the object to query, from which component class to query the
	89	object, and what are the query parameters. You cannot change those
	90	properties once the query executor is created. With
	91	bt_query_executor_create_with_method_data(), you can also pass
	92	a custom, \bt_voidp pointer to the component class's
	93	query method.
	94
	95	Perform a query operation with bt_query_executor_query(). This function
	96	can return #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN, in which case you can
	97	try to perform a query operation again later. It can also return
	98	#BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT, which means the
	99	component class does not offer the requested object.
	100
101	To interrupt a running query operation, either:
102
103	- Borrow the query executor's default \bt_intr with
104	bt_query_executor_borrow_default_interrupter() and set it with
105	bt_interrupter_set().
106
107	When you call bt_query_executor_create() or
108	bt_query_executor_create_with_method_data(), the returned query
109	executor has a default interrupter.
110
111	- Add your own interrupter with bt_query_executor_add_interrupter()
112	\em before you perform the query operation with
113	bt_query_executor_query().
114
115	Then, set the interrupter with bt_interrupter_set().
116
117	<h1>Property</h1>
118
119	A query executor has the following property:
120
121	<dl>
122	<dt>
123	\anchor api-qexec-prop-log-lvl
124	Logging level
125	</dt>
126	<dd>
127	Logging level of the query executor's query operations.
128
129	Use bt_query_executor_set_logging_level() and
130	bt_query_executor_get_logging_level().
131	</dd>
132	</dl>
133	*/
134
135	/! @{ /
136
137	/*!
138	@name Type
139	@{
140
141	@typedef struct bt_query_executor bt_query_executor;
142
143	@brief
144	Query executor.
145
146	@}
147	*/
148
149	/*!
150	@name Creation
151	@{
152	*/
153
154	/*!
155	@brief
156	Alias of bt_query_executor_create_with_method_data()
157	with the \bt_p{method_data} parameter set to \c NULL.
158	*/
0d72b8c3	159	extern
3c729b9a	160	bt_query_executor *bt_query_executor_create(
43c59509 PP	161	const bt_component_class *component_class,
	162	const char object_name, const bt_value params);
	163
	164	/*!
	165	@brief
	166	Creates a query executor to query the object named
	167	\bt_p{object_name} from the \bt_comp_cls \bt_p{component_class} with
	168	the parameters \bt_p{params} and the query user data
	169	\bt_p{method_data}.
	170
	171	When you call bt_query_executor_query() with the returned query
	172	executor, the query method of \bt_p{component_class} receives:
	173
	174	- \bt_p{object_name} as its own \bt_p{object_name} parameter.
0d72b8c3	175
43c59509 PP	176	- \bt_p{params} as its own \bt_p{params} parameter
	177	(or #bt_value_null if \bt_p{params} is \c NULL).
	178
	179	- \bt_p{method_data} as its own \bt_p{method_data} parameter.
	180
	181	@param[in] component_class
	182	Component class from which to query the object named
	183	\bt_p{object_name}.
	184	@param[in] object_name
	185	Name of the object to query from \bt_p{component_class}.
	186	@param[in] params
	187	@parblock
	188	Parameters for the query operation performed by the query executor
	189	to create.
	190
	191	Unlike the \bt_p{params} parameter of
	192	the <code>bt_graph_add__component__port_added_listener()</code>
	193	functions (see \ref api-graph), this parameter does not need to
	194	be a \bt_map_val.
	195
	196	Can be \c NULL (equivalent to passing #bt_value_null).
	197	@endparblock
	198	@param[in] method_data
	199	User data passed as is to the query method of \bt_p{component_class}
	200	when you call bt_query_executor_query().
	201
	202	@returns
	203	New query executor reference, or \c NULL on memory error.
	204
	205	@bt_pre_not_null{component_class}
	206	@bt_pre_not_null{object}
	207
	208	@bt_post_success_frozen{component_class}
	209	@bt_post_success_frozen{params}
	210	*/
7c14d641 PP	211	extern
7c14d641 PP	212	bt_query_executor *bt_query_executor_create_with_method_data(
43c59509 PP	213	const bt_component_class *component_class,
	214	const char object_name, const bt_value params,
	215	void *method_data);
	216
	217	/! @} /
7c14d641	218
43c59509 PP	219	/*!
	220	@name Query operation
	221	@{
	222	*/
	223
	224	/*!
	225	@brief
	226	Status codes for bt_query_executor_query().
	227	*/
d24d5663	228	typedef enum bt_query_executor_query_status {
43c59509 PP	229	/*!
	230	@brief
	231	Success.
	232	*/
d24d5663	233	BT_QUERY_EXECUTOR_QUERY_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509 PP	234
	235	/*!
	236	@brief
	237	Unknown object to query.
	238	*/
	239	BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT = __BT_FUNC_STATUS_UNKNOWN_OBJECT,
	240
	241	/*!
	242	@brief
	243	Try again.
	244	*/
d24d5663	245	BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN,
43c59509 PP	246
	247	/*!
	248	@brief
	249	Out of memory.
	250	*/
d24d5663	251	BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
43c59509 PP	252
	253	/*!
	254	@brief
	255	Other error.
	256	*/
	257	BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR = __BT_FUNC_STATUS_ERROR,
d24d5663 PP	258	} bt_query_executor_query_status;
d24d5663 PP	259
43c59509 PP	260	/*!
	261	@brief
	262	Performs a query operation using the query executor
	263	\bt_p{query_executor}, setting \bt_p{*result} to the operation's
	264	result on success.
	265
	266	This function calls the query executor's target \bt_comp_cls's
	267	query method, passing:
	268
	269	- The object name of \bt_p{query_executor} as the
	270	\bt_p{object_name} parameter.
	271
	272	- The query parameters of \bt_p{query_executor} as the
	273	\bt_p{params} parameter.
	274
	275	- The query user data of \bt_p{query_executor} as the \bt_p{method_data}
	276	parameter.
	277
	278	The three items above were set when you created \bt_p{query_executor}
	279	with bt_query_executor_create() or
	280	bt_query_executor_create_with_method_data().
	281
	282	@param[in] query_executor
	283	Query executor to use to execute the query operation.
	284	@param[out] result
	285	<strong>On success</strong>, \bt_p{*result} is a \em strong
	286	reference of the query operation's result.
	287
	288	@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
	289	Success.
	290	@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
	291	Unknown object to query.
	292	@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
	293	Try again.
	294	@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
	295	Out of memory.
	296	@retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
	297	Other error.
	298
	299	@bt_pre_not_null{query_executor}
	300	@bt_pre_not_null{result}
	301	*/
0d72b8c3	302	extern
d24d5663	303	bt_query_executor_query_status bt_query_executor_query(
3c729b9a	304	bt_query_executor query_executor, const bt_value *result);
c7eee084	305
43c59509 PP	306	/! @} /
	307
	308	/*!
	309	@name Property
	310	@{
	311	*/
	312
	313	/*!
	314	@brief
	315	Status codes for bt_query_executor_set_logging_level().
	316	*/
	317	typedef enum bt_query_executor_set_logging_level_status {
	318	/*!
	319	@brief
	320	Success.
	321	*/
	322	BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK = __BT_FUNC_STATUS_OK,
	323	} bt_query_executor_set_logging_level_status;
	324
	325	/*!
	326	@brief
	327	Sets the logging level of the query executor \bt_p{query_executor}
	328	to \bt_p{logging_level}.
	329
	330	See the \ref api-qexec-prop-log-lvl "logging level" property.
	331
	332	@param[in] query_executor
	333	Query executor of which to set the logging level to
	334	\bt_p{logging_level}.
	335	@param[in] logging_level
	336	New logging level of \bt_p{query_executor}.
	337
	338	@retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
	339	Success.
	340
	341	@bt_pre_not_null{query_executor}
	342
	343	@sa bt_stream_class_get_logging_level() —
	344	Returns the logging level of a query executor.
	345	*/
	346	extern bt_query_executor_set_logging_level_status
	347	bt_query_executor_set_logging_level(bt_query_executor *query_executor,
	348	bt_logging_level logging_level);
	349
	350	/*!
	351	@brief
	352	Returns the logging level of the query executor
	353	\bt_p{query_executor}.
	354
	355	See the \ref api-qexec-prop-log-lvl "logging level" property.
	356
	357	@param[in] query_executor
	358	Query executor of which to get the logging level.
	359
	360	@returns
	361	Logging level of \bt_p{query_executor}.
	362
	363	@bt_pre_not_null{query_executor}
	364
	365	@sa bt_query_executor_set_logging_level() —
	366	Sets the logging level of a query executor.
	367	*/
	368	extern bt_logging_level bt_query_executor_get_logging_level(
	369	const bt_query_executor *query_executor);
370
371	/! @} /
372
373	/*!
374	@name Interruption
375	@{
376	*/
377
378	/*!
379	@brief
380	Status codes for bt_query_executor_add_interrupter().
381	*/
9b4f9b42	382	typedef enum bt_query_executor_add_interrupter_status {
43c59509 PP	383	/*!
	384	@brief
	385	Success.
	386	*/
2c938e2f	387	BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK = __BT_FUNC_STATUS_OK,
43c59509 PP	388
	389	/*!
	390	@brief
	391	Out of memory.
	392	*/
2c938e2f	393	BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR,
9b4f9b42	394	} bt_query_executor_add_interrupter_status;
d24d5663	395
43c59509 PP	396	/*!
	397	@brief
	398	Adds the \bt_intr \bt_p{interrupter} to the query executor
	399	\bt_p{query_executor}.
	400
	401	A \bt_comp_cls query method can check whether or not its executor is
	402	interrupted (any of its interrupters, including its default interrupter,
	403	is set) with bt_query_executor_is_interrupted().
	404
	405	@note
	406	@parblock
	407	bt_query_executor_create() and
	408	bt_query_executor_create_with_method_data() return a query executor
	409	which comes with its own <em>default interrupter</em>.
	410
	411	Instead of adding your own interrupter to \bt_p{query_executor}, you
	412	can set its default interrupter with
	413
	414	@code
	415	bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
	416	@endcode
	417	@endparblock
	418
	419	@param[in] query_executor
	420	Query executor to which to add \bt_p{interrupter}.
	421	@param[in] interrupter
	422	Interrupter to add to \bt_p{query_executor}.
	423
	424	@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
	425	Success.
	426	@retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
	427	Out of memory.
	428
	429	@bt_pre_not_null{query_executor}
	430	@bt_pre_not_null{interrupter}
	431
	432	@sa bt_query_executor_borrow_default_interrupter() —
	433	Borrows the default interrupter from a query executor.
	434	*/
9b4f9b42 PP	435	extern bt_query_executor_add_interrupter_status
	436	bt_query_executor_add_interrupter(bt_query_executor *query_executor,
	437	const bt_interrupter *interrupter);
	438
43c59509 PP	439	/*!
	440	@brief
	441	Borrows the default \bt_intr from the query executor
	442	\bt_p{query_executor}.
	443
	444	@param[in] query_executor
	445	Query executor from which to borrow the default interrupter.
	446
	447	@returns
	448	@parblock
	449	\em Borrowed reference of the default interrupter of
	450	\bt_p{query_executor}.
	451
	452	The returned pointer remains valid as long as \bt_p{query_executor}
	453	exists.
	454	@endparblock
	455
	456	@bt_pre_not_null{query_executor}
	457
	458	@sa bt_query_executor_add_interrupter() —
	459	Adds an interrupter to a query executor.
	460	*/
88d1a0b7 SM	461	extern bt_interrupter *bt_query_executor_borrow_default_interrupter(
88d1a0b7 SM	462	bt_query_executor *query_executor);
c7eee084	463
43c59509 PP	464	/*!
	465	@brief
	466	Returns whether or not the query executor \bt_p{query_executor}
	467	is interrupted, that is, whether or not any of its \bt_p_intr,
	468	including its default interrupter, is set.
3c729b9a	469
43c59509 PP	470	@param[in] query_executor
	471	Query executor to check.
	472
	473	@returns
	474	#BT_TRUE if \bt_p{query_executor} is interrupted (any of its
	475	interrupters is set).
	476
	477	@bt_pre_not_null{query_executor}
	478	*/
	479	extern bt_bool bt_query_executor_is_interrupted(
	480	const bt_query_executor *query_executor);
	481
	482	/! @} /
	483
	484	/*!
	485	@name Reference count
	486	@{
	487	*/
	488
	489	/*!
	490	@brief
	491	Increments the \ref api-fund-shared-object "reference count" of
	492	the query executor \bt_p{query_executor}.
	493
	494	@param[in] query_executor
	495	@parblock
	496	Query executor of which to increment the reference count.
	497
	498	Can be \c NULL.
	499	@endparblock
	500
	501	@sa bt_query_executor_put_ref() —
	502	Decrements the reference count of a query executor.
	503	*/
	504	extern void bt_query_executor_get_ref(const bt_query_executor *query_executor);
	505
	506	/*!
	507	@brief
	508	Decrements the \ref api-fund-shared-object "reference count" of
	509	the query executor \bt_p{query_executor}.
	510
	511	@param[in] query_executor
	512	@parblock
	513	Query executor of which to decrement the reference count.
	514
	515	Can be \c NULL.
	516	@endparblock
	517
	518	@sa bt_query_executor_get_ref() —
	519	Increments the reference count of a query executor.
	520	*/
	521	extern void bt_query_executor_put_ref(const bt_query_executor *query_executor);
	522
	523	/*!
	524	@brief
	525	Decrements the reference count of the query executor
	526	\bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.
	527
	528	@param _query_executor
	529	@parblock
	530	Query executor of which to decrement the reference count.
	531
	532	Can contain \c NULL.
	533	@endparblock
534
535	@bt_pre_assign_expr{_query_executor}
536	*/
537	#define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor) \
538	do { \
539	bt_query_executor_put_ref(_query_executor); \
540	(_query_executor) = NULL; \
541	} while (0)
542
543	/*!
544	@brief
545	Decrements the reference count of the query executor \bt_p{_dst}, sets
546	\bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
547
548	This macro effectively moves a query executor reference from the expression
549	\bt_p{_src} to the expression \bt_p{_dst}, putting the existing
550	\bt_p{_dst} reference.
551
552	@param _dst
553	@parblock
554	Destination expression.
555
556	Can contain \c NULL.
557	@endparblock
558	@param _src
559	@parblock
560	Source expression.
561
562	Can contain \c NULL.
563	@endparblock
564
565	@bt_pre_assign_expr{_dst}
566	@bt_pre_assign_expr{_src}
567	*/
568	#define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src) \
569	do { \
570	bt_query_executor_put_ref(_dst); \
571	(_dst) = (_src); \
572	(_src) = NULL; \
573	} while (0)
574
575	/! @} /
576
577	/! @} /
3c729b9a	578
c7eee084 PP	579	#ifdef __cplusplus
	580	}
	581	#endif
	582
924dc299	583	#endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */