include/babeltrace2/graph/query-executor.h

   1 #ifndef BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
   2 #define BABELTRACE2_GRAPH_QUERY_EXECUTOR_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   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
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <babeltrace2/types.h>
  31 #include <babeltrace2/logging.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  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 */
 159 extern
 160 bt_query_executor *bt_query_executor_create(
 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.
 175
 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 */
 211 extern
 212 bt_query_executor *bt_query_executor_create_with_method_data(
 213                 const bt_component_class *component_class,
 214                 const char *object_name, const bt_value *params,
 215                 void *method_data);
 216
 217 /*! @} */
 218
 219 /*!
 220 @name Query operation
 221 @{
 222 */
 223
 224 /*!
 225 @brief
 226     Status codes for bt_query_executor_query().
 227 */
 228 typedef enum bt_query_executor_query_status {
 229         /*!
 230         @brief
 231             Success.
 232         */
 233         BT_QUERY_EXECUTOR_QUERY_STATUS_OK               = __BT_FUNC_STATUS_OK,
 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         */
 245         BT_QUERY_EXECUTOR_QUERY_STATUS_AGAIN            = __BT_FUNC_STATUS_AGAIN,
 246
 247         /*!
 248         @brief
 249             Out of memory.
 250         */
 251         BT_QUERY_EXECUTOR_QUERY_STATUS_MEMORY_ERROR     = __BT_FUNC_STATUS_MEMORY_ERROR,
 252
 253         /*!
 254         @brief
 255             Other error.
 256         */
 257         BT_QUERY_EXECUTOR_QUERY_STATUS_ERROR            = __BT_FUNC_STATUS_ERROR,
 258 } bt_query_executor_query_status;
 259
 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 */
 302 extern
 303 bt_query_executor_query_status bt_query_executor_query(
 304                 bt_query_executor *query_executor, const bt_value **result);
 305
 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() &mdash;
 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() &mdash;
 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 */
 382 typedef enum bt_query_executor_add_interrupter_status {
 383         /*!
 384         @brief
 385             Success.
 386         */
 387         BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_OK             = __BT_FUNC_STATUS_OK,
 388
 389         /*!
 390         @brief
 391             Out of memory.
 392         */
 393         BT_QUERY_EXECUTOR_ADD_INTERRUPTER_STATUS_MEMORY_ERROR   = __BT_FUNC_STATUS_MEMORY_ERROR,
 394 } bt_query_executor_add_interrupter_status;
 395
 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() &mdash;
 433     Borrows the default interrupter from a query executor.
 434 */
 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
 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() &mdash;
 459     Adds an interrupter to a query executor.
 460 */
 461 extern bt_interrupter *bt_query_executor_borrow_default_interrupter(
 462                 bt_query_executor *query_executor);
 463
 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.
 469
 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() &mdash;
 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() &mdash;
 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 /*! @} */
 578
 579 #ifdef __cplusplus
 580 }
 581 #endif
 582
 583 #endif /* BABELTRACE2_GRAPH_QUERY_EXECUTOR_H */