include/babeltrace2/graph/query-executor.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
   8 #define BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
   9
  10 #ifndef __BT_IN_BABELTRACE_H
  11 # error "Please include <babeltrace2/babeltrace.h> instead."
  12 #endif
  13
  14 #include <babeltrace2/types.h>
  15 #include <babeltrace2/logging.h>
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  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 */
 143 extern
 144 bt_query_executor *bt_query_executor_create(
 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.
 159
 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 */
 195 extern
 196 bt_query_executor *bt_query_executor_create_with_method_data(
 197                 const bt_component_class *component_class,
 198                 const char *object_name, const bt_value *params,
 199                 void *method_data);
 200
 201 /*! @} */
 202
 203 /*!
 204 @name Query operation
 205 @{
 206 */
 207
 208 /*!
 209 @brief
 210     Status codes for bt_query_executor_query().
 211 */
 212 typedef enum bt_query_executor_query_status {
 213         /*!
 214         @brief
 215             Success.
 216         */
 217         BT_QUERY_EXECUTOR_QUERY_STATUS_OK               = __BT_FUNC_STATUS_OK,
 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         */
 229         BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
 230
 231         /*!
 232         @brief
 233             Out of memory.
 234         */
 235         BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 236
 237         /*!
 238         @brief
 239             Other error.
 240         */
 241         BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
 242 } bt_query_executor_query_status;
 243
 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 */
 286 extern
 287 bt_query_executor_query_status bt_query_executor_query(
 288                 bt_query_executor *query_executor, const bt_value **result);
 289
 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() &mdash;
 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() &mdash;
 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 */
 366 typedef enum bt_query_executor_add_interrupter_status {
 367         /*!
 368         @brief
 369             Success.
 370         */
 371         BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK             = __BT_FUNC_STATUS_OK,
 372
 373         /*!
 374         @brief
 375             Out of memory.
 376         */
 377         BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 378 } bt_query_executor_add_interrupter_status;
 379
 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() &mdash;
 417     Borrows the default interrupter from a query executor.
 418 */
 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
 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() &mdash;
 443     Adds an interrupter to a query executor.
 444 */
 445 extern bt_interrupter *bt_query_executor_borrow_default_interrupter(
 446                 bt_query_executor *query_executor);
 447
 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.
 453
 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() &mdash;
 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() &mdash;
 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 /*! @} */
 562
 563 #ifdef __cplusplus
 564 }
 565 #endif
 566
 567 #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */