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 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
  11
  12 #ifndef __BT_IN_BABELTRACE_H
  13 # error "Please include <babeltrace2/babeltrace.h> instead."
  14 #endif
  15
  16 #include <babeltrace2/types.h>
  17 #include <babeltrace2/logging.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  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
  38 The query operation feature exists so that you can benefit from a
  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 */
 145 extern
 146 bt_query_executor *bt_query_executor_create(
 147                 const bt_component_class *component_class,
 148                 const char *object_name, const bt_value *params)
 149                 __BT_NOEXCEPT;
 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.
 162
 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
 179     the <code>bt_graph_add_*_component*()</code>
 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 */
 198 extern
 199 bt_query_executor *bt_query_executor_create_with_method_data(
 200                 const bt_component_class *component_class,
 201                 const char *object_name, const bt_value *params,
 202                 void *method_data) __BT_NOEXCEPT;
 203
 204 /*! @} */
 205
 206 /*!
 207 @name Query operation
 208 @{
 209 */
 210
 211 /*!
 212 @brief
 213     Status codes for bt_query_executor_query().
 214 */
 215 typedef enum bt_query_executor_query_status {
 216         /*!
 217         @brief
 218             Success.
 219         */
 220         BT_QUERY_EXECUTOR_QUERY_STATUS_OK               = __BT_FUNC_STATUS_OK,
 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         */
 232         BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
 233
 234         /*!
 235         @brief
 236             Out of memory.
 237         */
 238         BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 239
 240         /*!
 241         @brief
 242             Other error.
 243         */
 244         BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
 245 } bt_query_executor_query_status;
 246
 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 */
 289 extern
 290 bt_query_executor_query_status bt_query_executor_query(
 291                 bt_query_executor *query_executor, const bt_value **result)
 292                 __BT_NOEXCEPT;
 293
 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() &mdash;
 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,
 336                 bt_logging_level logging_level) __BT_NOEXCEPT;
 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() &mdash;
 354     Sets the logging level of a query executor.
 355 */
 356 extern bt_logging_level bt_query_executor_get_logging_level(
 357                 const bt_query_executor *query_executor) __BT_NOEXCEPT;
 358
 359 /*! @} */
 360
 361 /*!
 362 @name Interruption
 363 @{
 364 */
 365
 366 /*!
 367 @brief
 368     Status codes for bt_query_executor_add_interrupter().
 369 */
 370 typedef enum bt_query_executor_add_interrupter_status {
 371         /*!
 372         @brief
 373             Success.
 374         */
 375         BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK             = __BT_FUNC_STATUS_OK,
 376
 377         /*!
 378         @brief
 379             Out of memory.
 380         */
 381         BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 382 } bt_query_executor_add_interrupter_status;
 383
 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() &mdash;
 421     Borrows the default interrupter from a query executor.
 422 */
 423 extern bt_query_executor_add_interrupter_status
 424 bt_query_executor_add_interrupter(bt_query_executor *query_executor,
 425                 const bt_interrupter *interrupter) __BT_NOEXCEPT;
 426
 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() &mdash;
 447     Adds an interrupter to a query executor.
 448 */
 449 extern bt_interrupter *bt_query_executor_borrow_default_interrupter(
 450                 bt_query_executor *query_executor) __BT_NOEXCEPT;
 451
 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.
 457
 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(
 468                 const bt_query_executor *query_executor) __BT_NOEXCEPT;
 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() &mdash;
 490     Decrements the reference count of a query executor.
 491 */
 492 extern void bt_query_executor_get_ref(const bt_query_executor *query_executor)
 493                 __BT_NOEXCEPT;
 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() &mdash;
 508     Increments the reference count of a query executor.
 509 */
 510 extern void bt_query_executor_put_ref(const bt_query_executor *query_executor)
 511                 __BT_NOEXCEPT;
 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 /*! @} */
 568
 569 #ifdef __cplusplus
 570 }
 571 #endif
 572
 573 #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */