2 * SPDX-License-Identifier: MIT
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
7 #ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
8 #define BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
16 #include <babeltrace2/types.h>
17 #include <babeltrace2/logging.h>
24 @defgroup api-qexec Query executor
28 Executor of \bt_comp_cls object queries.
30 A <strong><em>query executor</em></strong> is an executor of
31 \bt_comp_cls object queries.
33 A component class can implement a query method to offer one or more
34 \em objects depending on the query parameters.
36 Both the query parameters and the returned objects are \bt_p_val.
38 The query operation feature exists so that you can benefit from a
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.
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.
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().
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
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().
70 The type of a query executor is #bt_query_executor.
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
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.
87 To interrupt a running query operation, either:
89 - Borrow the query executor's default \bt_intr with
90 bt_query_executor_borrow_default_interrupter() and set it with
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.
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().
101 Then, set the interrupter with bt_interrupter_set().
105 A query executor has the following property:
109 \anchor api-qexec-prop-log-lvl
113 Logging level of the query executor's query operations.
115 Use bt_query_executor_set_logging_level() and
116 bt_query_executor_get_logging_level().
127 @typedef struct bt_query_executor bt_query_executor;
142 Alias of bt_query_executor_create_with_method_data()
143 with the \bt_p{method_data} parameter set to \c NULL.
146 bt_query_executor
*bt_query_executor_create(
147 const bt_component_class
*component_class
,
148 const char *object_name
, const bt_value
*params
)
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
158 When you call bt_query_executor_query() with the returned query
159 executor, the query method of \bt_p{component_class} receives:
161 - \bt_p{object_name} as its own \bt_p{object_name} parameter.
163 - \bt_p{params} as its own \bt_p{params} parameter
164 (or #bt_value_null if \bt_p{params} is \c NULL).
166 - \bt_p{method_data} as its own \bt_p{method_data} parameter.
168 @param[in] component_class
169 Component class from which to query the object named
171 @param[in] object_name
172 Name of the object to query from \bt_p{component_class}.
175 Parameters for the query operation performed by the query executor
178 Unlike the \bt_p{params} parameter of
179 the <code>bt_graph_add_*_component*()</code>
180 functions (see \ref api-graph), this parameter does not need to
183 Can be \c NULL (equivalent to passing #bt_value_null).
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().
190 New query executor reference, or \c NULL on memory error.
192 @bt_pre_not_null{component_class}
193 @bt_pre_not_null{object}
195 @bt_post_success_frozen{component_class}
196 @bt_post_success_frozen{params}
199 bt_query_executor
*bt_query_executor_create_with_method_data(
200 const bt_component_class
*component_class
,
201 const char *object_name
, const bt_value
*params
,
202 void *method_data
) __BT_NOEXCEPT
;
207 @name Query operation
213 Status codes for bt_query_executor_query().
215 typedef enum bt_query_executor_query_status
{
220 BT_QUERY_EXECUTOR_QUERY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
224 Unknown object to query.
226 BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
= __BT_FUNC_STATUS_UNKNOWN_OBJECT
,
232 BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
238 BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
244 BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
245 } bt_query_executor_query_status
;
249 Performs a query operation using the query executor
250 \bt_p{query_executor}, setting \bt_p{*result} to the operation's
253 This function calls the query executor's target \bt_comp_cls's
254 query method, passing:
256 - The object name of \bt_p{query_executor} as the
257 \bt_p{object_name} parameter.
259 - The query parameters of \bt_p{query_executor} as the
260 \bt_p{params} parameter.
262 - The query user data of \bt_p{query_executor} as the \bt_p{method_data}
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().
269 @param[in] query_executor
270 Query executor to use to execute the query operation.
272 <strong>On success</strong>, \bt_p{*result} is a \em strong
273 reference of the query operation's result.
275 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
277 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
278 Unknown object to query.
279 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
281 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
283 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
286 @bt_pre_not_null{query_executor}
287 @bt_pre_not_null{result}
290 bt_query_executor_query_status
bt_query_executor_query(
291 bt_query_executor
*query_executor
, const bt_value
**result
)
303 Status codes for bt_query_executor_set_logging_level().
305 typedef enum bt_query_executor_set_logging_level_status
{
310 BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
311 } bt_query_executor_set_logging_level_status
;
315 Sets the logging level of the query executor \bt_p{query_executor}
316 to \bt_p{logging_level}.
318 See the \ref api-qexec-prop-log-lvl "logging level" property.
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}.
326 @retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
329 @bt_pre_not_null{query_executor}
331 @sa bt_stream_class_get_logging_level() —
332 Returns the logging level of a query executor.
334 extern bt_query_executor_set_logging_level_status
335 bt_query_executor_set_logging_level(bt_query_executor
*query_executor
,
336 bt_logging_level logging_level
) __BT_NOEXCEPT
;
340 Returns the logging level of the query executor
341 \bt_p{query_executor}.
343 See the \ref api-qexec-prop-log-lvl "logging level" property.
345 @param[in] query_executor
346 Query executor of which to get the logging level.
349 Logging level of \bt_p{query_executor}.
351 @bt_pre_not_null{query_executor}
353 @sa bt_query_executor_set_logging_level() —
354 Sets the logging level of a query executor.
356 extern bt_logging_level
bt_query_executor_get_logging_level(
357 const bt_query_executor
*query_executor
) __BT_NOEXCEPT
;
368 Status codes for bt_query_executor_add_interrupter().
370 typedef enum bt_query_executor_add_interrupter_status
{
375 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
381 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
382 } bt_query_executor_add_interrupter_status
;
386 Adds the \bt_intr \bt_p{interrupter} to the query executor
387 \bt_p{query_executor}.
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().
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>.
399 Instead of adding your own interrupter to \bt_p{query_executor}, you
400 can set its default interrupter with
403 bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
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}.
412 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
414 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
417 @bt_pre_not_null{query_executor}
418 @bt_pre_not_null{interrupter}
420 @sa bt_query_executor_borrow_default_interrupter() —
421 Borrows the default interrupter from a query executor.
423 extern bt_query_executor_add_interrupter_status
424 bt_query_executor_add_interrupter(bt_query_executor
*query_executor
,
425 const bt_interrupter
*interrupter
) __BT_NOEXCEPT
;
429 Borrows the default \bt_intr from the query executor
430 \bt_p{query_executor}.
432 @param[in] query_executor
433 Query executor from which to borrow the default interrupter.
437 \em Borrowed reference of the default interrupter of
438 \bt_p{query_executor}.
440 The returned pointer remains valid as long as \bt_p{query_executor}
444 @bt_pre_not_null{query_executor}
446 @sa bt_query_executor_add_interrupter() —
447 Adds an interrupter to a query executor.
449 extern bt_interrupter
*bt_query_executor_borrow_default_interrupter(
450 bt_query_executor
*query_executor
) __BT_NOEXCEPT
;
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.
458 @param[in] query_executor
459 Query executor to check.
462 #BT_TRUE if \bt_p{query_executor} is interrupted (any of its
463 interrupters is set).
465 @bt_pre_not_null{query_executor}
467 extern bt_bool
bt_query_executor_is_interrupted(
468 const bt_query_executor
*query_executor
) __BT_NOEXCEPT
;
473 @name Reference count
479 Increments the \ref api-fund-shared-object "reference count" of
480 the query executor \bt_p{query_executor}.
482 @param[in] query_executor
484 Query executor of which to increment the reference count.
489 @sa bt_query_executor_put_ref() —
490 Decrements the reference count of a query executor.
492 extern void bt_query_executor_get_ref(const bt_query_executor
*query_executor
)
497 Decrements the \ref api-fund-shared-object "reference count" of
498 the query executor \bt_p{query_executor}.
500 @param[in] query_executor
502 Query executor of which to decrement the reference count.
507 @sa bt_query_executor_get_ref() —
508 Increments the reference count of a query executor.
510 extern void bt_query_executor_put_ref(const bt_query_executor
*query_executor
)
515 Decrements the reference count of the query executor
516 \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.
518 @param _query_executor
520 Query executor of which to decrement the reference count.
525 @bt_pre_assign_expr{_query_executor}
527 #define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor) \
529 bt_query_executor_put_ref(_query_executor); \
530 (_query_executor) = NULL; \
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.
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.
544 Destination expression.
555 @bt_pre_assign_expr{_dst}
556 @bt_pre_assign_expr{_src}
558 #define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src) \
560 bt_query_executor_put_ref(_dst); \
573 #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */