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