1 #ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
2 #define BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
5 * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
26 #ifndef __BT_IN_BABELTRACE_H
27 # error "Please include <babeltrace2/babeltrace.h> instead."
30 #include <babeltrace2/types.h>
31 #include <babeltrace2/logging.h>
38 @defgroup api-qexec Query executor
42 Executor of \bt_comp_cls object queries.
44 A <strong><em>query executor</em></strong> is an executor of
45 \bt_comp_cls object queries.
47 A component class can implement a query method to offer one or more
48 \em objects depending on the query parameters.
50 Both the query parameters and the returned objects are \bt_p_val.
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.
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.
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().
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
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().
84 The type of a query executor is #bt_query_executor.
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
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.
101 To interrupt a running query operation, either:
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().
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.
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().
115 Then, set the interrupter with bt_interrupter_set().
119 A query executor has the following property:
123 \anchor api-qexec-prop-log-lvl
127 Logging level of the query executor's query operations.
129 Use bt_query_executor_set_logging_level() and
130 bt_query_executor_get_logging_level().
141 @typedef struct bt_query_executor bt_query_executor;
156 Alias of bt_query_executor_create_with_method_data()
157 with the \bt_p{method_data} parameter set to \c NULL.
160 bt_query_executor
*bt_query_executor_create(
161 const bt_component_class
*component_class
,
162 const char *object_name
, const bt_value
*params
);
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
171 When you call bt_query_executor_query() with the returned query
172 executor, the query method of \bt_p{component_class} receives:
174 - \bt_p{object_name} as its own \bt_p{object_name} parameter.
176 - \bt_p{params} as its own \bt_p{params} parameter
177 (or #bt_value_null if \bt_p{params} is \c NULL).
179 - \bt_p{method_data} as its own \bt_p{method_data} parameter.
181 @param[in] component_class
182 Component class from which to query the object named
184 @param[in] object_name
185 Name of the object to query from \bt_p{component_class}.
188 Parameters for the query operation performed by the query executor
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
196 Can be \c NULL (equivalent to passing #bt_value_null).
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().
203 New query executor reference, or \c NULL on memory error.
205 @bt_pre_not_null{component_class}
206 @bt_pre_not_null{object}
208 @bt_post_success_frozen{component_class}
209 @bt_post_success_frozen{params}
212 bt_query_executor
*bt_query_executor_create_with_method_data(
213 const bt_component_class
*component_class
,
214 const char *object_name
, const bt_value
*params
,
220 @name Query operation
226 Status codes for bt_query_executor_query().
228 typedef enum bt_query_executor_query_status
{
233 BT_QUERY_EXECUTOR_QUERY_STATUS_OK
= __BT_FUNC_STATUS_OK
,
237 Unknown object to query.
239 BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
= __BT_FUNC_STATUS_UNKNOWN_OBJECT
,
245 BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
= __BT_FUNC_STATUS_AGAIN
,
251 BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
257 BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
= __BT_FUNC_STATUS_ERROR
,
258 } bt_query_executor_query_status
;
262 Performs a query operation using the query executor
263 \bt_p{query_executor}, setting \bt_p{*result} to the operation's
266 This function calls the query executor's target \bt_comp_cls's
267 query method, passing:
269 - The object name of \bt_p{query_executor} as the
270 \bt_p{object_name} parameter.
272 - The query parameters of \bt_p{query_executor} as the
273 \bt_p{params} parameter.
275 - The query user data of \bt_p{query_executor} as the \bt_p{method_data}
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().
282 @param[in] query_executor
283 Query executor to use to execute the query operation.
285 <strong>On success</strong>, \bt_p{*result} is a \em strong
286 reference of the query operation's result.
288 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK
290 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT
291 Unknown object to query.
292 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN
294 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR
296 @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR
299 @bt_pre_not_null{query_executor}
300 @bt_pre_not_null{result}
303 bt_query_executor_query_status
bt_query_executor_query(
304 bt_query_executor
*query_executor
, const bt_value
**result
);
315 Status codes for bt_query_executor_set_logging_level().
317 typedef enum bt_query_executor_set_logging_level_status
{
322 BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
= __BT_FUNC_STATUS_OK
,
323 } bt_query_executor_set_logging_level_status
;
327 Sets the logging level of the query executor \bt_p{query_executor}
328 to \bt_p{logging_level}.
330 See the \ref api-qexec-prop-log-lvl "logging level" property.
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}.
338 @retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK
341 @bt_pre_not_null{query_executor}
343 @sa bt_stream_class_get_logging_level() —
344 Returns the logging level of a query executor.
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
);
352 Returns the logging level of the query executor
353 \bt_p{query_executor}.
355 See the \ref api-qexec-prop-log-lvl "logging level" property.
357 @param[in] query_executor
358 Query executor of which to get the logging level.
361 Logging level of \bt_p{query_executor}.
363 @bt_pre_not_null{query_executor}
365 @sa bt_query_executor_set_logging_level() —
366 Sets the logging level of a query executor.
368 extern bt_logging_level
bt_query_executor_get_logging_level(
369 const bt_query_executor
*query_executor
);
380 Status codes for bt_query_executor_add_interrupter().
382 typedef enum bt_query_executor_add_interrupter_status
{
387 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
= __BT_FUNC_STATUS_OK
,
393 BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
= __BT_FUNC_STATUS_MEMORY_ERROR
,
394 } bt_query_executor_add_interrupter_status
;
398 Adds the \bt_intr \bt_p{interrupter} to the query executor
399 \bt_p{query_executor}.
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().
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>.
411 Instead of adding your own interrupter to \bt_p{query_executor}, you
412 can set its default interrupter with
415 bt_interrupter_set(bt_query_executor_borrow_default_interrupter());
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}.
424 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK
426 @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR
429 @bt_pre_not_null{query_executor}
430 @bt_pre_not_null{interrupter}
432 @sa bt_query_executor_borrow_default_interrupter() —
433 Borrows the default interrupter from a query executor.
435 extern bt_query_executor_add_interrupter_status
436 bt_query_executor_add_interrupter(bt_query_executor
*query_executor
,
437 const bt_interrupter
*interrupter
);
441 Borrows the default \bt_intr from the query executor
442 \bt_p{query_executor}.
444 @param[in] query_executor
445 Query executor from which to borrow the default interrupter.
449 \em Borrowed reference of the default interrupter of
450 \bt_p{query_executor}.
452 The returned pointer remains valid as long as \bt_p{query_executor}
456 @bt_pre_not_null{query_executor}
458 @sa bt_query_executor_add_interrupter() —
459 Adds an interrupter to a query executor.
461 extern bt_interrupter
*bt_query_executor_borrow_default_interrupter(
462 bt_query_executor
*query_executor
);
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.
470 @param[in] query_executor
471 Query executor to check.
474 #BT_TRUE if \bt_p{query_executor} is interrupted (any of its
475 interrupters is set).
477 @bt_pre_not_null{query_executor}
479 extern bt_bool
bt_query_executor_is_interrupted(
480 const bt_query_executor
*query_executor
);
485 @name Reference count
491 Increments the \ref api-fund-shared-object "reference count" of
492 the query executor \bt_p{query_executor}.
494 @param[in] query_executor
496 Query executor of which to increment the reference count.
501 @sa bt_query_executor_put_ref() —
502 Decrements the reference count of a query executor.
504 extern void bt_query_executor_get_ref(const bt_query_executor
*query_executor
);
508 Decrements the \ref api-fund-shared-object "reference count" of
509 the query executor \bt_p{query_executor}.
511 @param[in] query_executor
513 Query executor of which to decrement the reference count.
518 @sa bt_query_executor_get_ref() —
519 Increments the reference count of a query executor.
521 extern void bt_query_executor_put_ref(const bt_query_executor
*query_executor
);
525 Decrements the reference count of the query executor
526 \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL.
528 @param _query_executor
530 Query executor of which to decrement the reference count.
535 @bt_pre_assign_expr{_query_executor}
537 #define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor) \
539 bt_query_executor_put_ref(_query_executor); \
540 (_query_executor) = NULL; \
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.
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.
554 Destination expression.
565 @bt_pre_assign_expr{_dst}
566 @bt_pre_assign_expr{_src}
568 #define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src) \
570 bt_query_executor_put_ref(_dst); \
583 #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */