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

/*
 * SPDX-License-Identifier: MIT
 *
 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
 */

#ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
#define BABELTRACE2_GRAPH_QUERY_EXECUTOR_H

/* IWYU pragma: private, include <babeltrace2/babeltrace.h> */

#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 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)
		__BT_NOEXCEPT;

/*!
@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*()</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) __BT_NOEXCEPT;

/*! @} */

/*!
@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)
		__BT_NOEXCEPT;

/*! @} */

/*!
@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) __BT_NOEXCEPT;

/*!
@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) __BT_NOEXCEPT;

/*! @} */

/*!
@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) __BT_NOEXCEPT;

/*!
@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) __BT_NOEXCEPT;

/*!
@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) __BT_NOEXCEPT;

/*! @} */

/*!
@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)
		__BT_NOEXCEPT;

/*!
@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)
		__BT_NOEXCEPT;

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