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 | */ |
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> */ |
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> |
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) |
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 |
199 | bt_query_executor *bt_query_executor_create_with_method_data( | |
43c59509 PP |
200 | const bt_component_class *component_class, |
201 | const char *object_name, const bt_value *params, | |
4c81a2b7 | 202 | void *method_data) __BT_NOEXCEPT; |
43c59509 PP |
203 | |
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; |
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) |
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 |
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) |
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) |
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 */ |