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 | ||
4fa90f32 PP |
10 | #ifndef __BT_IN_BABELTRACE_H |
11 | # error "Please include <babeltrace2/babeltrace.h> instead." | |
12 | #endif | |
13 | ||
3fadfbc0 | 14 | #include <babeltrace2/types.h> |
f4e38e70 PP |
15 | #include <babeltrace2/logging.h> |
16 | ||
c7eee084 PP |
17 | #ifdef __cplusplus |
18 | extern "C" { | |
19 | #endif | |
20 | ||
43c59509 PP |
21 | /*! |
22 | @defgroup api-qexec Query executor | |
23 | @ingroup api-graph | |
24 | ||
25 | @brief | |
26 | Executor of \bt_comp_cls object queries. | |
27 | ||
28 | A <strong><em>query executor</em></strong> is an executor of | |
29 | \bt_comp_cls object queries. | |
30 | ||
31 | A component class can implement a query method to offer one or more | |
32 | \em objects depending on the query parameters. | |
33 | ||
34 | Both the query parameters and the returned objects are \bt_p_val. | |
35 | ||
36 | The query operation feature exists so that you can get 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. | |
44 | ||
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. | |
51 | ||
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(). | |
57 | ||
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 | |
61 | executor. | |
62 | ||
63 | A query executor is a | |
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(). | |
67 | ||
68 | The type of a query executor is #bt_query_executor. | |
69 | ||
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 | |
77 | query method. | |
78 | ||
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. | |
84 | ||
85 | To interrupt a running query operation, either: | |
86 | ||
87 | - Borrow the query executor's default \bt_intr with | |
88 | bt_query_executor_borrow_default_interrupter() and set it with | |
89 | bt_interrupter_set(). | |
90 | ||
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. | |
94 | ||
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(). | |
98 | ||
99 | Then, set the interrupter with bt_interrupter_set(). | |
100 | ||
101 | <h1>Property</h1> | |
102 | ||
103 | A query executor has the following property: | |
104 | ||
105 | <dl> | |
106 | <dt> | |
107 | \anchor api-qexec-prop-log-lvl | |
108 | Logging level | |
109 | </dt> | |
110 | <dd> | |
111 | Logging level of the query executor's query operations. | |
112 | ||
113 | Use bt_query_executor_set_logging_level() and | |
114 | bt_query_executor_get_logging_level(). | |
115 | </dd> | |
116 | </dl> | |
117 | */ | |
118 | ||
119 | /*! @{ */ | |
120 | ||
121 | /*! | |
122 | @name Type | |
123 | @{ | |
124 | ||
125 | @typedef struct bt_query_executor bt_query_executor; | |
126 | ||
127 | @brief | |
128 | Query executor. | |
129 | ||
130 | @} | |
131 | */ | |
132 | ||
133 | /*! | |
134 | @name Creation | |
135 | @{ | |
136 | */ | |
137 | ||
138 | /*! | |
139 | @brief | |
140 | Alias of bt_query_executor_create_with_method_data() | |
141 | with the \bt_p{method_data} parameter set to \c NULL. | |
142 | */ | |
0d72b8c3 | 143 | extern |
3c729b9a | 144 | bt_query_executor *bt_query_executor_create( |
43c59509 PP |
145 | const bt_component_class *component_class, |
146 | const char *object_name, const bt_value *params); | |
147 | ||
148 | /*! | |
149 | @brief | |
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 | |
153 | \bt_p{method_data}. | |
154 | ||
155 | When you call bt_query_executor_query() with the returned query | |
156 | executor, the query method of \bt_p{component_class} receives: | |
157 | ||
158 | - \bt_p{object_name} as its own \bt_p{object_name} parameter. | |
0d72b8c3 | 159 | |
43c59509 PP |
160 | - \bt_p{params} as its own \bt_p{params} parameter |
161 | (or #bt_value_null if \bt_p{params} is \c NULL). | |
162 | ||
163 | - \bt_p{method_data} as its own \bt_p{method_data} parameter. | |
164 | ||
165 | @param[in] component_class | |
166 | Component class from which to query the object named | |
167 | \bt_p{object_name}. | |
168 | @param[in] object_name | |
169 | Name of the object to query from \bt_p{component_class}. | |
170 | @param[in] params | |
171 | @parblock | |
172 | Parameters for the query operation performed by the query executor | |
173 | to create. | |
174 | ||
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 | |
178 | be a \bt_map_val. | |
179 | ||
180 | Can be \c NULL (equivalent to passing #bt_value_null). | |
181 | @endparblock | |
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(). | |
185 | ||
186 | @returns | |
187 | New query executor reference, or \c NULL on memory error. | |
188 | ||
189 | @bt_pre_not_null{component_class} | |
190 | @bt_pre_not_null{object} | |
191 | ||
192 | @bt_post_success_frozen{component_class} | |
193 | @bt_post_success_frozen{params} | |
194 | */ | |
7c14d641 PP |
195 | extern |
196 | bt_query_executor *bt_query_executor_create_with_method_data( | |
43c59509 PP |
197 | const bt_component_class *component_class, |
198 | const char *object_name, const bt_value *params, | |
199 | void *method_data); | |
200 | ||
201 | /*! @} */ | |
7c14d641 | 202 | |
43c59509 PP |
203 | /*! |
204 | @name Query operation | |
205 | @{ | |
206 | */ | |
207 | ||
208 | /*! | |
209 | @brief | |
210 | Status codes for bt_query_executor_query(). | |
211 | */ | |
d24d5663 | 212 | typedef enum bt_query_executor_query_status { |
43c59509 PP |
213 | /*! |
214 | @brief | |
215 | Success. | |
216 | */ | |
d24d5663 | 217 | BT_QUERY_EXECUTOR_QUERY_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
218 | |
219 | /*! | |
220 | @brief | |
221 | Unknown object to query. | |
222 | */ | |
223 | BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT = __BT_FUNC_STATUS_UNKNOWN_OBJECT, | |
224 | ||
225 | /*! | |
226 | @brief | |
227 | Try again. | |
228 | */ | |
d24d5663 | 229 | BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN = __BT_FUNC_STATUS_AGAIN, |
43c59509 PP |
230 | |
231 | /*! | |
232 | @brief | |
233 | Out of memory. | |
234 | */ | |
d24d5663 | 235 | BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
43c59509 PP |
236 | |
237 | /*! | |
238 | @brief | |
239 | Other error. | |
240 | */ | |
241 | BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR = __BT_FUNC_STATUS_ERROR, | |
d24d5663 PP |
242 | } bt_query_executor_query_status; |
243 | ||
43c59509 PP |
244 | /*! |
245 | @brief | |
246 | Performs a query operation using the query executor | |
247 | \bt_p{query_executor}, setting \bt_p{*result} to the operation's | |
248 | result on success. | |
249 | ||
250 | This function calls the query executor's target \bt_comp_cls's | |
251 | query method, passing: | |
252 | ||
253 | - The object name of \bt_p{query_executor} as the | |
254 | \bt_p{object_name} parameter. | |
255 | ||
256 | - The query parameters of \bt_p{query_executor} as the | |
257 | \bt_p{params} parameter. | |
258 | ||
259 | - The query user data of \bt_p{query_executor} as the \bt_p{method_data} | |
260 | parameter. | |
261 | ||
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(). | |
265 | ||
266 | @param[in] query_executor | |
267 | Query executor to use to execute the query operation. | |
268 | @param[out] result | |
269 | <strong>On success</strong>, \bt_p{*result} is a \em strong | |
270 | reference of the query operation's result. | |
271 | ||
272 | @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_OK | |
273 | Success. | |
274 | @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_UNKNOWN_OBJECT | |
275 | Unknown object to query. | |
276 | @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN | |
277 | Try again. | |
278 | @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR | |
279 | Out of memory. | |
280 | @retval #BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR | |
281 | Other error. | |
282 | ||
283 | @bt_pre_not_null{query_executor} | |
284 | @bt_pre_not_null{result} | |
285 | */ | |
0d72b8c3 | 286 | extern |
d24d5663 | 287 | bt_query_executor_query_status bt_query_executor_query( |
3c729b9a | 288 | bt_query_executor *query_executor, const bt_value **result); |
c7eee084 | 289 | |
43c59509 PP |
290 | /*! @} */ |
291 | ||
292 | /*! | |
293 | @name Property | |
294 | @{ | |
295 | */ | |
296 | ||
297 | /*! | |
298 | @brief | |
299 | Status codes for bt_query_executor_set_logging_level(). | |
300 | */ | |
301 | typedef enum bt_query_executor_set_logging_level_status { | |
302 | /*! | |
303 | @brief | |
304 | Success. | |
305 | */ | |
306 | BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK = __BT_FUNC_STATUS_OK, | |
307 | } bt_query_executor_set_logging_level_status; | |
308 | ||
309 | /*! | |
310 | @brief | |
311 | Sets the logging level of the query executor \bt_p{query_executor} | |
312 | to \bt_p{logging_level}. | |
313 | ||
314 | See the \ref api-qexec-prop-log-lvl "logging level" property. | |
315 | ||
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}. | |
321 | ||
322 | @retval #BT_QUERY_EXECUTOR_SET_LOGGING_LEVEL_STATUS_OK | |
323 | Success. | |
324 | ||
325 | @bt_pre_not_null{query_executor} | |
326 | ||
327 | @sa bt_stream_class_get_logging_level() — | |
328 | Returns the logging level of a query executor. | |
329 | */ | |
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); | |
333 | ||
334 | /*! | |
335 | @brief | |
336 | Returns the logging level of the query executor | |
337 | \bt_p{query_executor}. | |
338 | ||
339 | See the \ref api-qexec-prop-log-lvl "logging level" property. | |
340 | ||
341 | @param[in] query_executor | |
342 | Query executor of which to get the logging level. | |
343 | ||
344 | @returns | |
345 | Logging level of \bt_p{query_executor}. | |
346 | ||
347 | @bt_pre_not_null{query_executor} | |
348 | ||
349 | @sa bt_query_executor_set_logging_level() — | |
350 | Sets the logging level of a query executor. | |
351 | */ | |
352 | extern bt_logging_level bt_query_executor_get_logging_level( | |
353 | const bt_query_executor *query_executor); | |
354 | ||
355 | /*! @} */ | |
356 | ||
357 | /*! | |
358 | @name Interruption | |
359 | @{ | |
360 | */ | |
361 | ||
362 | /*! | |
363 | @brief | |
364 | Status codes for bt_query_executor_add_interrupter(). | |
365 | */ | |
9b4f9b42 | 366 | typedef enum bt_query_executor_add_interrupter_status { |
43c59509 PP |
367 | /*! |
368 | @brief | |
369 | Success. | |
370 | */ | |
2c938e2f | 371 | BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK = __BT_FUNC_STATUS_OK, |
43c59509 PP |
372 | |
373 | /*! | |
374 | @brief | |
375 | Out of memory. | |
376 | */ | |
2c938e2f | 377 | BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR = __BT_FUNC_STATUS_MEMORY_ERROR, |
9b4f9b42 | 378 | } bt_query_executor_add_interrupter_status; |
d24d5663 | 379 | |
43c59509 PP |
380 | /*! |
381 | @brief | |
382 | Adds the \bt_intr \bt_p{interrupter} to the query executor | |
383 | \bt_p{query_executor}. | |
384 | ||
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(). | |
388 | ||
389 | @note | |
390 | @parblock | |
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>. | |
394 | ||
395 | Instead of adding your own interrupter to \bt_p{query_executor}, you | |
396 | can set its default interrupter with | |
397 | ||
398 | @code | |
399 | bt_interrupter_set(bt_query_executor_borrow_default_interrupter()); | |
400 | @endcode | |
401 | @endparblock | |
402 | ||
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}. | |
407 | ||
408 | @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK | |
409 | Success. | |
410 | @retval #BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR | |
411 | Out of memory. | |
412 | ||
413 | @bt_pre_not_null{query_executor} | |
414 | @bt_pre_not_null{interrupter} | |
415 | ||
416 | @sa bt_query_executor_borrow_default_interrupter() — | |
417 | Borrows the default interrupter from a query executor. | |
418 | */ | |
9b4f9b42 PP |
419 | extern bt_query_executor_add_interrupter_status |
420 | bt_query_executor_add_interrupter(bt_query_executor *query_executor, | |
421 | const bt_interrupter *interrupter); | |
422 | ||
43c59509 PP |
423 | /*! |
424 | @brief | |
425 | Borrows the default \bt_intr from the query executor | |
426 | \bt_p{query_executor}. | |
427 | ||
428 | @param[in] query_executor | |
429 | Query executor from which to borrow the default interrupter. | |
430 | ||
431 | @returns | |
432 | @parblock | |
433 | \em Borrowed reference of the default interrupter of | |
434 | \bt_p{query_executor}. | |
435 | ||
436 | The returned pointer remains valid as long as \bt_p{query_executor} | |
437 | exists. | |
438 | @endparblock | |
439 | ||
440 | @bt_pre_not_null{query_executor} | |
441 | ||
442 | @sa bt_query_executor_add_interrupter() — | |
443 | Adds an interrupter to a query executor. | |
444 | */ | |
88d1a0b7 SM |
445 | extern bt_interrupter *bt_query_executor_borrow_default_interrupter( |
446 | bt_query_executor *query_executor); | |
c7eee084 | 447 | |
43c59509 PP |
448 | /*! |
449 | @brief | |
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. | |
3c729b9a | 453 | |
43c59509 PP |
454 | @param[in] query_executor |
455 | Query executor to check. | |
456 | ||
457 | @returns | |
458 | #BT_TRUE if \bt_p{query_executor} is interrupted (any of its | |
459 | interrupters is set). | |
460 | ||
461 | @bt_pre_not_null{query_executor} | |
462 | */ | |
463 | extern bt_bool bt_query_executor_is_interrupted( | |
464 | const bt_query_executor *query_executor); | |
465 | ||
466 | /*! @} */ | |
467 | ||
468 | /*! | |
469 | @name Reference count | |
470 | @{ | |
471 | */ | |
472 | ||
473 | /*! | |
474 | @brief | |
475 | Increments the \ref api-fund-shared-object "reference count" of | |
476 | the query executor \bt_p{query_executor}. | |
477 | ||
478 | @param[in] query_executor | |
479 | @parblock | |
480 | Query executor of which to increment the reference count. | |
481 | ||
482 | Can be \c NULL. | |
483 | @endparblock | |
484 | ||
485 | @sa bt_query_executor_put_ref() — | |
486 | Decrements the reference count of a query executor. | |
487 | */ | |
488 | extern void bt_query_executor_get_ref(const bt_query_executor *query_executor); | |
489 | ||
490 | /*! | |
491 | @brief | |
492 | Decrements the \ref api-fund-shared-object "reference count" of | |
493 | the query executor \bt_p{query_executor}. | |
494 | ||
495 | @param[in] query_executor | |
496 | @parblock | |
497 | Query executor of which to decrement the reference count. | |
498 | ||
499 | Can be \c NULL. | |
500 | @endparblock | |
501 | ||
502 | @sa bt_query_executor_get_ref() — | |
503 | Increments the reference count of a query executor. | |
504 | */ | |
505 | extern void bt_query_executor_put_ref(const bt_query_executor *query_executor); | |
506 | ||
507 | /*! | |
508 | @brief | |
509 | Decrements the reference count of the query executor | |
510 | \bt_p{_query_executor}, and then sets \bt_p{_query_executor} to \c NULL. | |
511 | ||
512 | @param _query_executor | |
513 | @parblock | |
514 | Query executor of which to decrement the reference count. | |
515 | ||
516 | Can contain \c NULL. | |
517 | @endparblock | |
518 | ||
519 | @bt_pre_assign_expr{_query_executor} | |
520 | */ | |
521 | #define BT_QUERY_EXECUTOR_PUT_REF_AND_RESET(_query_executor) \ | |
522 | do { \ | |
523 | bt_query_executor_put_ref(_query_executor); \ | |
524 | (_query_executor) = NULL; \ | |
525 | } while (0) | |
526 | ||
527 | /*! | |
528 | @brief | |
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. | |
531 | ||
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. | |
535 | ||
536 | @param _dst | |
537 | @parblock | |
538 | Destination expression. | |
539 | ||
540 | Can contain \c NULL. | |
541 | @endparblock | |
542 | @param _src | |
543 | @parblock | |
544 | Source expression. | |
545 | ||
546 | Can contain \c NULL. | |
547 | @endparblock | |
548 | ||
549 | @bt_pre_assign_expr{_dst} | |
550 | @bt_pre_assign_expr{_src} | |
551 | */ | |
552 | #define BT_QUERY_EXECUTOR_MOVE_REF(_dst, _src) \ | |
553 | do { \ | |
554 | bt_query_executor_put_ref(_dst); \ | |
555 | (_dst) = (_src); \ | |
556 | (_src) = NULL; \ | |
557 | } while (0) | |
558 | ||
559 | /*! @} */ | |
560 | ||
561 | /*! @} */ | |
3c729b9a | 562 | |
c7eee084 PP |
563 | #ifdef __cplusplus |
564 | } | |
565 | #endif | |
566 | ||
924dc299 | 567 | #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */ |