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
);
152 Creates a query executor to query the object named
153 \bt_p{object_name} from the \bt_comp_cls \bt_p{component_class} with
154 the parameters \bt_p{params} and the query user data
157 When you call bt_query_executor_query() with the returned query
158 executor, the query method of \bt_p{component_class} receives:
160 - \bt_p{object_name} as its own \bt_p{object_name} parameter.
162 - \bt_p{params} as its own \bt_p{params} parameter
163 (or #bt_value_null if \bt_p{params} is \c NULL).
165 - \bt_p{method_data} as its own \bt_p{method_data} parameter.
167 @param[in] component_class
168 Component class from which to query the object named
170 @param[in] object_name
171 Name of the object to query from \bt_p{component_class}.
174 Parameters for the query operation performed by the query executor
177 Unlike the \bt_p{params} parameter of
178 the <code>bt_graph_add_*_component*()</code>
179 functions (see \ref api-graph), this parameter does not need to
182 Can be \c NULL (equivalent to passing #bt_value_null).
184 @param[in] method_data
185 User data passed as is to the query method of \bt_p{component_class}
186 when you call bt_query_executor_query().
189 New query executor reference, or \c NULL on memory error.
191 @bt_pre_not_null{component_class}
192 @bt_pre_not_null{object}
194 @bt_post_success_frozen{component_class}
195 @bt_post_success_frozen{params}
198 bt_query_executor
*bt_query_executor_create_with_method_data(
199 const bt_component_class
*component_class
,
200 const char *object_name
, const bt_value
*params
,
206 @name Query operation
212 Status codes for bt_query_executor_query().
214 typedef enum bt_query_executor_query_status
{
219 BT_QUERY_EXECUTOR_QUERY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
223 Unknown object to query.
225 BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
= __BT_FUNC_STATUS_UNKNOWN_OBJECT
,
231 BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
237 BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
243 BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
244 } bt_query_executor_query_status
;
248 Performs a query operation using the query executor
249 \bt_p{query_executor}, setting \bt_p{*result} to the operation's
252 This function calls the query executor's target \bt_comp_cls's
253 query method, passing:
255 - The object name of \bt_p{query_executor} as the
256 \bt_p{object_name} parameter.
258 - The query parameters of \bt_p{query_executor} as the
259 \bt_p{params} parameter.
261 - The query user data of \bt_p{query_executor} as the \bt_p{method_data}
264 The three items above were set when you created \bt_p{query_executor}
265 with bt_query_executor_create() or
266 bt_query_executor_create_with_method_data().
268 @param[in] query_executor
269 Query executor to use to execute the query operation.
271 <strong>On success</strong>, \bt_p{*result} is a \em strong
272 reference of the query operation's result.
274 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
276 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
277 Unknown object to query.
278 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
280 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
282 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
285 @bt_pre_not_null{query_executor}
286 @bt_pre_not_null{result}
289 bt_query_executor_query_status
bt_query_executor_query(
290 bt_query_executor
*query_executor
, const bt_value
**result
);
301 Status codes for bt_query_executor_set_logging_level().
303 typedef enum bt_query_executor_set_logging_level_status
{
308 BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
309 } bt_query_executor_set_logging_level_status
;
313 Sets the logging level of the query executor \bt_p{query_executor}
314 to \bt_p{logging_level}.
316 See the \ref api-qexec-prop-log-lvl "logging level" property.
318 @param[in] query_executor
319 Query executor of which to set the logging level to
320 \bt_p{logging_level}.
321 @param[in] logging_level
322 New logging level of \bt_p{query_executor}.
324 @retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
327 @bt_pre_not_null{query_executor}
329 @sa bt_stream_class_get_logging_level() —
330 Returns the logging level of a query executor.
332 extern bt_query_executor_set_logging_level_status
333 bt_query_executor_set_logging_level(bt_query_executor
*query_executor
,
334 bt_logging_level logging_level
);
338 Returns the logging level of the query executor
339 \bt_p{query_executor}.
341 See the \ref api-qexec-prop-log-lvl "logging level" property.
343 @param[in] query_executor
344 Query executor of which to get the logging level.
347 Logging level of \bt_p{query_executor}.
349 @bt_pre_not_null{query_executor}
351 @sa bt_query_executor_set_logging_level() —
352 Sets the logging level of a query executor.
354 extern bt_logging_level
bt_query_executor_get_logging_level(
355 const bt_query_executor
*query_executor
);
366 Status codes for bt_query_executor_add_interrupter().
368 typedef enum bt_query_executor_add_interrupter_status
{
373 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
379 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
380 } bt_query_executor_add_interrupter_status
;
384 Adds the \bt_intr \bt_p{interrupter} to the query executor
385 \bt_p{query_executor}.
387 A \bt_comp_cls query method can check whether or not its executor is
388 interrupted (any of its interrupters, including its default interrupter,
389 is set) with bt_query_executor_is_interrupted().
393 bt_query_executor_create() and
394 bt_query_executor_create_with_method_data() return a query executor
395 which comes with its own <em>default interrupter</em>.
397 Instead of adding your own interrupter to \bt_p{query_executor}, you
398 can set its default interrupter with
401 bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
405 @param[in] query_executor
406 Query executor to which to add \bt_p{interrupter}.
407 @param[in] interrupter
408 Interrupter to add to \bt_p{query_executor}.
410 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
412 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
415 @bt_pre_not_null{query_executor}
416 @bt_pre_not_null{interrupter}
418 @sa bt_query_executor_borrow_default_interrupter() —
419 Borrows the default interrupter from a query executor.
421 extern bt_query_executor_add_interrupter_status
422 bt_query_executor_add_interrupter(bt_query_executor
*query_executor
,
423 const bt_interrupter
*interrupter
);
427 Borrows the default \bt_intr from the query executor
428 \bt_p{query_executor}.
430 @param[in] query_executor
431 Query executor from which to borrow the default interrupter.
435 \em Borrowed reference of the default interrupter of
436 \bt_p{query_executor}.
438 The returned pointer remains valid as long as \bt_p{query_executor}
442 @bt_pre_not_null{query_executor}
444 @sa bt_query_executor_add_interrupter() —
445 Adds an interrupter to a query executor.
447 extern bt_interrupter
*bt_query_executor_borrow_default_interrupter(
448 bt_query_executor
*query_executor
);
452 Returns whether or not the query executor \bt_p{query_executor}
453 is interrupted, that is, whether or not any of its \bt_p_intr,
454 including its default interrupter, is set.
456 @param[in] query_executor
457 Query executor to check.
460 #BT_TRUE if \bt_p{query_executor} is interrupted (any of its
461 interrupters is set).
463 @bt_pre_not_null{query_executor}
465 extern bt_bool
bt_query_executor_is_interrupted(
466 const bt_query_executor
*query_executor
);
471 @name Reference count
477 Increments the \ref api-fund-shared-object "reference count" of
478 the query executor \bt_p{query_executor}.
480 @param[in] query_executor
482 Query executor of which to increment the reference count.
487 @sa bt_query_executor_put_ref() —
488 Decrements the reference count of a query executor.
490 extern void bt_query_executor_get_ref(const bt_query_executor
*query_executor
);
494 Decrements the \ref api-fund-shared-object "reference count" of
495 the query executor \bt_p{query_executor}.
497 @param[in] query_executor
499 Query executor of which to decrement the reference count.
504 @sa bt_query_executor_get_ref() —
505 Increments the reference count of a query executor.
507 extern void bt_query_executor_put_ref(const bt_query_executor
*query_executor
);
511 Decrements the reference count of the query executor
512 \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.
514 @param _query_executor
516 Query executor of which to decrement the reference count.
521 @bt_pre_assign_expr{_query_executor}
523 #define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor) \
525 bt_query_executor_put_ref(_query_executor); \
526 (_query_executor) = NULL; \
531 Decrements the reference count of the query executor \bt_p{_dst}, sets
532 \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to \c NULL.
534 This macro effectively moves a query executor reference from the expression
535 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
536 \bt_p{_dst} reference.
540 Destination expression.
551 @bt_pre_assign_expr{_dst}
552 @bt_pre_assign_expr{_src}
554 #define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src) \
556 bt_query_executor_put_ref(_dst); \
569 #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */