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 #ifndef __BT_IN_BABELTRACE_H
11 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #include <babeltrace2/types.h>
15 #include <babeltrace2/logging.h>
22 @defgroup api-qexec Query executor
26 Executor of \bt_comp_cls object queries.
28 A <strong><em>query executor</em></strong> is an executor of
29 \bt_comp_cls object queries.
31 A component class can implement a query method to offer one or more
32 \em objects depending on the query parameters.
34 Both the query parameters and the returned objects are \bt_p_val.
36 The query operation feature exists so that you can benefit from a
37 component class's implementation to get information about a trace, a
38 stream, a distant server, and so on. For example, the
39 <code>source.ctf.lttng-live</code> component class (see
40 \bt_man{babeltrace2-source.ctf.lttng-live,7}) offers the \c sessions
41 object to list the available
42 <a href="https://lttng.org/docs/#doc-lttng-live">LTTng live</a>
43 tracing session names and other properties.
45 The semantics of the query parameters and the returned object are
46 completely defined by the component class implementation: the library
47 does not enforce or suggest any layout. The best way to know which
48 objects you can query from a component class, what are the expected and
49 optional parameters, and what the returned object contains is to read
50 this component class's documentation.
52 The purpose of the query executor itself is to keep some state for a
53 specific query operation. For example, you can set a query executor's
54 logging level with bt_query_executor_set_logging_level(); then a
55 component class's query method can get the executor's current logging
56 level with bt_query_executor_get_logging_level().
58 Also, the query executor is an interruptible object: a long or blocking
59 query operation can run, checking whether the executor is interrupted
60 periodically, while another thread or a signal handler can interrupt the
64 \ref api-fund-shared-object "shared object": get a new reference with
65 bt_query_executor_get_ref() and put an existing reference with
66 bt_query_executor_put_ref().
68 The type of a query executor is #bt_query_executor.
70 Create a query executor with bt_query_executor_create() or
71 bt_query_executor_create_with_method_data(). When you do so, you set the
72 name of the object to query, from which component class to query the
73 object, and what are the query parameters. You cannot change those
74 properties once the query executor is created. With
75 bt_query_executor_create_with_method_data(), you can also pass
76 a custom, \bt_voidp pointer to the component class's
79 Perform a query operation with bt_query_executor_query(). This function
80 can return #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN, in which case you can
81 try to perform a query operation again later. It can also return
82 #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT, which means the
83 component class does not offer the requested object.
85 To interrupt a running query operation, either:
87 - Borrow the query executor's default \bt_intr with
88 bt_query_executor_borrow_default_interrupter() and set it with
91 When you call bt_query_executor_create() or
92 bt_query_executor_create_with_method_data(), the returned query
93 executor has a default interrupter.
95 - Add your own interrupter with bt_query_executor_add_interrupter()
96 \em before you perform the query operation with
97 bt_query_executor_query().
99 Then, set the interrupter with bt_interrupter_set().
103 A query executor has the following property:
107 \anchor api-qexec-prop-log-lvl
111 Logging level of the query executor's query operations.
113 Use bt_query_executor_set_logging_level() and
114 bt_query_executor_get_logging_level().
125 @typedef struct bt_query_executor bt_query_executor;
140 Alias of bt_query_executor_create_with_method_data()
141 with the \bt_p{method_data} parameter set to \c NULL.
144 bt_query_executor
*bt_query_executor_create(
145 const bt_component_class
*component_class
,
146 const char *object_name
, const bt_value
*params
);
150 Creates a query executor to query the object named
151 \bt_p{object_name} from the \bt_comp_cls \bt_p{component_class} with
152 the parameters \bt_p{params} and the query user data
155 When you call bt_query_executor_query() with the returned query
156 executor, the query method of \bt_p{component_class} receives:
158 - \bt_p{object_name} as its own \bt_p{object_name} parameter.
160 - \bt_p{params} as its own \bt_p{params} parameter
161 (or #bt_value_null if \bt_p{params} is \c NULL).
163 - \bt_p{method_data} as its own \bt_p{method_data} parameter.
165 @param[in] component_class
166 Component class from which to query the object named
168 @param[in] object_name
169 Name of the object to query from \bt_p{component_class}.
172 Parameters for the query operation performed by the query executor
175 Unlike the \bt_p{params} parameter of
176 the <code>bt_graph_add_*_component_*_port_added_listener()</code>
177 functions (see \ref api-graph), this parameter does not need to
180 Can be \c NULL (equivalent to passing #bt_value_null).
182 @param[in] method_data
183 User data passed as is to the query method of \bt_p{component_class}
184 when you call bt_query_executor_query().
187 New query executor reference, or \c NULL on memory error.
189 @bt_pre_not_null{component_class}
190 @bt_pre_not_null{object}
192 @bt_post_success_frozen{component_class}
193 @bt_post_success_frozen{params}
196 bt_query_executor
*bt_query_executor_create_with_method_data(
197 const bt_component_class
*component_class
,
198 const char *object_name
, const bt_value
*params
,
204 @name Query operation
210 Status codes for bt_query_executor_query().
212 typedef enum bt_query_executor_query_status
{
217 BT_QUERY_EXECUTOR_QUERY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
221 Unknown object to query.
223 BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
= __BT_FUNC_STATUS_UNKNOWN_OBJECT
,
229 BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
235 BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
241 BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
242 } bt_query_executor_query_status
;
246 Performs a query operation using the query executor
247 \bt_p{query_executor}, setting \bt_p{*result} to the operation's
250 This function calls the query executor's target \bt_comp_cls's
251 query method, passing:
253 - The object name of \bt_p{query_executor} as the
254 \bt_p{object_name} parameter.
256 - The query parameters of \bt_p{query_executor} as the
257 \bt_p{params} parameter.
259 - The query user data of \bt_p{query_executor} as the \bt_p{method_data}
262 The three items above were set when you created \bt_p{query_executor}
263 with bt_query_executor_create() or
264 bt_query_executor_create_with_method_data().
266 @param[in] query_executor
267 Query executor to use to execute the query operation.
269 <strong>On success</strong>, \bt_p{*result} is a \em strong
270 reference of the query operation's result.
272 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
274 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
275 Unknown object to query.
276 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
278 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
280 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
283 @bt_pre_not_null{query_executor}
284 @bt_pre_not_null{result}
287 bt_query_executor_query_status
bt_query_executor_query(
288 bt_query_executor
*query_executor
, const bt_value
**result
);
299 Status codes for bt_query_executor_set_logging_level().
301 typedef enum bt_query_executor_set_logging_level_status
{
306 BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
307 } bt_query_executor_set_logging_level_status
;
311 Sets the logging level of the query executor \bt_p{query_executor}
312 to \bt_p{logging_level}.
314 See the \ref api-qexec-prop-log-lvl "logging level" property.
316 @param[in] query_executor
317 Query executor of which to set the logging level to
318 \bt_p{logging_level}.
319 @param[in] logging_level
320 New logging level of \bt_p{query_executor}.
322 @retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
325 @bt_pre_not_null{query_executor}
327 @sa bt_stream_class_get_logging_level() —
328 Returns the logging level of a query executor.
330 extern bt_query_executor_set_logging_level_status
331 bt_query_executor_set_logging_level(bt_query_executor
*query_executor
,
332 bt_logging_level logging_level
);
336 Returns the logging level of the query executor
337 \bt_p{query_executor}.
339 See the \ref api-qexec-prop-log-lvl "logging level" property.
341 @param[in] query_executor
342 Query executor of which to get the logging level.
345 Logging level of \bt_p{query_executor}.
347 @bt_pre_not_null{query_executor}
349 @sa bt_query_executor_set_logging_level() —
350 Sets the logging level of a query executor.
352 extern bt_logging_level
bt_query_executor_get_logging_level(
353 const bt_query_executor
*query_executor
);
364 Status codes for bt_query_executor_add_interrupter().
366 typedef enum bt_query_executor_add_interrupter_status
{
371 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
377 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
378 } bt_query_executor_add_interrupter_status
;
382 Adds the \bt_intr \bt_p{interrupter} to the query executor
383 \bt_p{query_executor}.
385 A \bt_comp_cls query method can check whether or not its executor is
386 interrupted (any of its interrupters, including its default interrupter,
387 is set) with bt_query_executor_is_interrupted().
391 bt_query_executor_create() and
392 bt_query_executor_create_with_method_data() return a query executor
393 which comes with its own <em>default interrupter</em>.
395 Instead of adding your own interrupter to \bt_p{query_executor}, you
396 can set its default interrupter with
399 bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
403 @param[in] query_executor
404 Query executor to which to add \bt_p{interrupter}.
405 @param[in] interrupter
406 Interrupter to add to \bt_p{query_executor}.
408 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
410 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
413 @bt_pre_not_null{query_executor}
414 @bt_pre_not_null{interrupter}
416 @sa bt_query_executor_borrow_default_interrupter() —
417 Borrows the default interrupter from a query executor.
419 extern bt_query_executor_add_interrupter_status
420 bt_query_executor_add_interrupter(bt_query_executor
*query_executor
,
421 const bt_interrupter
*interrupter
);
425 Borrows the default \bt_intr from the query executor
426 \bt_p{query_executor}.
428 @param[in] query_executor
429 Query executor from which to borrow the default interrupter.
433 \em Borrowed reference of the default interrupter of
434 \bt_p{query_executor}.
436 The returned pointer remains valid as long as \bt_p{query_executor}
440 @bt_pre_not_null{query_executor}
442 @sa bt_query_executor_add_interrupter() —
443 Adds an interrupter to a query executor.
445 extern bt_interrupter
*bt_query_executor_borrow_default_interrupter(
446 bt_query_executor
*query_executor
);
450 Returns whether or not the query executor \bt_p{query_executor}
451 is interrupted, that is, whether or not any of its \bt_p_intr,
452 including its default interrupter, is set.
454 @param[in] query_executor
455 Query executor to check.
458 #BT_TRUE if \bt_p{query_executor} is interrupted (any of its
459 interrupters is set).
461 @bt_pre_not_null{query_executor}
463 extern bt_bool
bt_query_executor_is_interrupted(
464 const bt_query_executor
*query_executor
);
469 @name Reference count
475 Increments the \ref api-fund-shared-object "reference count" of
476 the query executor \bt_p{query_executor}.
478 @param[in] query_executor
480 Query executor of which to increment the reference count.
485 @sa bt_query_executor_put_ref() —
486 Decrements the reference count of a query executor.
488 extern void bt_query_executor_get_ref(const bt_query_executor
*query_executor
);
492 Decrements the \ref api-fund-shared-object "reference count" of
493 the query executor \bt_p{query_executor}.
495 @param[in] query_executor
497 Query executor of which to decrement the reference count.
502 @sa bt_query_executor_get_ref() —
503 Increments the reference count of a query executor.
505 extern void bt_query_executor_put_ref(const bt_query_executor
*query_executor
);
509 Decrements the reference count of the query executor
510 \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.
512 @param _query_executor
514 Query executor of which to decrement the reference count.
519 @bt_pre_assign_expr{_query_executor}
521 #define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor) \
523 bt_query_executor_put_ref(_query_executor); \
524 (_query_executor) = NULL; \
529 Decrements the reference count of the query executor \bt_p{_dst}, sets
530 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
532 This macro effectively moves a query executor reference from the expression
533 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
534 \bt_p{_dst} reference.
538 Destination expression.
549 @bt_pre_assign_expr{_dst}
550 @bt_pre_assign_expr{_src}
552 #define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src) \
554 bt_query_executor_put_ref(_dst); \
567 #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */