include/babeltrace/objects.h

   1 #ifndef _BABELTRACE_OBJECTS_H
   2 #define _BABELTRACE_OBJECTS_H
   3
   4 /*
   5  * Babeltrace
   6  *
   7  * Basic object system
   8  *
   9  * Copyright (c) 2015 EfficiOS Inc. and Linux Foundation
  10  * Copyright (c) 2015 Philippe Proulx <pproulx@efficios.com>
  11  *
  12  * Permission is hereby granted, free of charge, to any person obtaining a copy
  13  * of this software and associated documentation files (the "Software"), to deal
  14  * in the Software without restriction, including without limitation the rights
  15  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  16  * copies of the Software, and to permit persons to whom the Software is
  17  * furnished to do so, subject to the following conditions:
  18  *
  19  * The above copyright notice and this permission notice shall be included in
  20  * all copies or substantial portions of the Software.
  21  *
  22  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  23  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  25  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  26  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  27  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  28  * SOFTWARE.
  29  */
  30
  31 /**
  32  * @file objects.h
  33  * @brief Basic object system
  34  *
  35  * This is a basic object system API. The following functions allow you
  36  * to create, modify, and destroy:
  37  *
  38  *   - \link bt_object_null null objects\endlink
  39  *   - \link bt_object_bool_create() boolean objects\endlink
  40  *   - \link bt_object_integer_create() integer objects\endlink
  41  *   - \link bt_object_float_create() floating point number
  42  *     objects\endlink
  43  *   - \link bt_object_string_create() string objects\endlink
  44  *   - \link bt_object_array_create() array objects\endlink,
  45  *     containing zero or more objects
  46  *   - \link bt_object_map_create() map objects\endlink, mapping
  47  *     string keys to objects
  48  *
  49  * All the object types above, except for null objects (which always
  50  * point to the same \link bt_object_null singleton\endlink), have a
  51  * reference count property. Once an object is created, its reference
  52  * count is set to 1. When \link bt_object_array_append() appending an
  53  * object to an array object\endlink, or \link bt_object_map_insert()
  54  * inserting an object into a map object\endlink, its reference count
  55  * is incremented, as well as when getting an object back from those
  56  * structures. The bt_object_get() and bt_object_put() functions exist
  57  * to deal with reference counting. Once you are done with an object,
  58  * pass it to bt_object_put().
  59  *
  60  * A common action with objects is to create or get one, do something
  61  * with it, and then put it. To avoid putting it a second time later
  62  * (if an error occurs, for example), the variable is often reset to
  63  * \c NULL after putting the object it points to. Since this is so
  64  * common, you can use the BT_OBJECT_PUT() macro, which does just that:
  65  *
  66  * \code{.c}
  67  *     struct bt_object *int_obj = bt_object_integer_create_init(34);
  68  *
  69  *     if (!int_obj) {
  70  *         goto error;
  71  *     }
  72  *
  73  *     // stuff, which could jump to error
  74  *
  75  *     BT_OBJECT_PUT(int_obj);
  76  *
  77  *     // stuff, which could jump to error
  78  *
  79  *     return 0;
  80  *
  81  * error:
  82  *     // safe, even if int_obj is NULL
  83  *     BT_OBJECT_PUT(int_obj);
  84  *
  85  *     // ...
  86  * \endcode
  87  *
  88  * Another common manipulation is to move the ownership of an object
  89  * from one variable to another: since the reference count is not
  90  * incremented, and since, to avoid errors, two variables should not
  91  * point to same object without each of them having their own reference,
  92  * it is best practice to set the original variable to \c NULL. This
  93  * too can be accomplished in a single step using the BT_OBJECT_MOVE()
  94  * macro:
  95  *
  96  * \code{.c}
  97  *     struct bt_object *int_obj2 = NULL;
  98  *     struct bt_object *int_obj = bt_object_integer_create_init(-23);
  99  *
 100  *     if (!int_obj) {
 101  *         goto error;
 102  *     }
 103  *
 104  *     // stuff, which could jump to error
 105  *
 106  *     BT_OBJECT_MOVE(int_obj2, int_obj);
 107  *
 108  *     // stuff, which could jump to error
 109  *
 110  *     return 0;
 111  *
 112  * error:
 113  *     // safe, since only one of int_obj/int_obj2 (or none)
 114  *     // points to the object
 115  *     BT_OBJECT_PUT(int_obj);
 116  *     BT_OBJECT_PUT(int_obj2);
 117  *
 118  *     // ...
 119  * \endcode
 120  *
 121  * Most functions return a status code, one of the values in
 122  * #bt_object_status.
 123  *
 124  * You can create a deep copy of any object using the bt_object_copy()
 125  * function. You can compare two given objects using
 126  * bt_object_compare().
 127  *
 128  * Any object may be frozen using bt_object_freeze(). You may get the
 129  * value of a frozen object, but you cannot modify it. Reference
 130  * counting still works on frozen objects. You may also copy and compare
 131  * frozen objects.
 132  *
 133  * @author      Philippe Proulx <pproulx@efficios.com>
 134  * @bug         No known bugs
 135  */
 136
 137 #include <stdint.h>
 138 #include <stdbool.h>
 139 #include <stddef.h>
 140
 141 #ifdef __cplusplus
 142 extern "C" {
 143 #endif
 144
 145 /**
 146  * Object type.
 147  */
 148 enum bt_object_type {
 149         /** Unknown object, used as an error code. */
 150         BT_OBJECT_TYPE_UNKNOWN =        -1,
 151
 152         /** Null object. */
 153         BT_OBJECT_TYPE_NULL =           0,
 154
 155         /** Boolean object (holds \c true or \c false). */
 156         BT_OBJECT_TYPE_BOOL =           1,
 157
 158         /** Integer object (holds a signed 64-bit integer value). */
 159         BT_OBJECT_TYPE_INTEGER =        2,
 160
 161         /**
 162          * Floating point number object (holds a \c double value).
 163          */
 164         BT_OBJECT_TYPE_FLOAT =          3,
 165
 166         /** String object. */
 167         BT_OBJECT_TYPE_STRING =         4,
 168
 169         /** Array object. */
 170         BT_OBJECT_TYPE_ARRAY =          5,
 171
 172         /** Map object. */
 173         BT_OBJECT_TYPE_MAP =            6,
 174 };
 175
 176 /**
 177  * Status code.
 178  */
 179 enum bt_object_status {
 180         /** Object cannot be altered because it's frozen. */
 181         BT_OBJECT_STATUS_FROZEN =       -4,
 182
 183         /** Operation cancelled. */
 184         BT_OBJECT_STATUS_CANCELLED =    -3,
 185
 186         /** Invalid arguments. */
 187         /* -22 for compatibility with -EINVAL */
 188         BT_OBJECT_STATUS_INVAL =        -22,
 189
 190         /** General error. */
 191         BT_OBJECT_STATUS_ERROR =        -1,
 192
 193         /** Okay, no error. */
 194         BT_OBJECT_STATUS_OK =           0,
 195 };
 196
 197 /**
 198  * Object.
 199  */
 200 struct bt_object;
 201
 202 /**
 203  * The null object singleton.
 204  *
 205  * Use this everytime you need a null object.
 206  *
 207  * The null object singleton has no reference count; there's only one.
 208  * You may directly compare any object to the null object singleton to
 209  * find out if it's a null object, or otherwise use bt_object_is_null().
 210  *
 211  * The null object singleton is always frozen (see bt_object_freeze()
 212  * and bt_object_is_frozen()).
 213  *
 214  * Functions of this API return this when the object is actually a
 215  * null object (of type #BT_OBJECT_TYPE_NULL), whereas \c NULL means an
 216  * error of some sort.
 217  */
 218 extern struct bt_object *bt_object_null;
 219
 220 /**
 221  * User function type for bt_object_map_foreach().
 222  *
 223  * \p object is a \em weak reference; you must pass it to
 224  * bt_object_get() to get your own reference.
 225  *
 226  * Return \c true to continue the loop, or \c false to break it.
 227  *
 228  * @param key           Key of map entry
 229  * @param object        Object of map entry (weak reference)
 230  * @param data          User data
 231  * @returns             \c true to continue the loop
 232  */
 233 typedef bool (* bt_object_map_foreach_cb)(const char *key,
 234         struct bt_object *object, void *data);
 235
 236 /**
 237  * Puts the object \p _object (calls bt_object_put() on it), and resets
 238  * the variable to \c NULL.
 239  *
 240  * This is something that is often done when putting and object;
 241  * resetting the variable to \c NULL makes sure it cannot be put a
 242  * second time later.
 243  *
 244  * @param _object       Object to put
 245  *
 246  * @see BT_OBJECT_MOVE() (moves an object from one variable to the other
 247  *                       without putting it)
 248  */
 249 #define BT_OBJECT_PUT(_object)                          \
 250         do {                                            \
 251                 bt_object_put(_object);                 \
 252                 (_object) = NULL;                       \
 253         } while (0)
 254
 255 /**
 256  * Moves the object referenced by the variable \p _src_object to the
 257  * \p _dst_object variable, then resets \p _src_object to \c NULL.
 258  *
 259  * The object's reference count is <b>not changed</b>. Resetting
 260  * \p _src_object to \c NULL ensures the object will not be put
 261  * twice later; its ownership is indeed \em moved from the source
 262  * variable to the destination variable.
 263  *
 264  * @param _src_object   Source object variable
 265  * @param _dst_object   Destination object variable
 266  */
 267 #define BT_OBJECT_MOVE(_dst_object, _src_object)        \
 268         do {                                            \
 269                 (_dst_object) = (_src_object);          \
 270                 (_src_object) = NULL;                   \
 271         } while (0)
 272
 273 /**
 274  * Increments the reference count of \p object.
 275  *
 276  * @param object        Object of which to increment the reference count
 277  *
 278  * @see bt_object_put()
 279  */
 280 extern void bt_object_get(struct bt_object *object);
 281
 282 /**
 283  * Decrements the reference count of \p object, destroying it when this
 284  * count reaches 0.
 285  *
 286  * @param object        Object of which to decrement the reference count
 287  *
 288  * @see BT_OBJECT_PUT() (puts an object and resets the variable to
 289  *                      \c NULL)
 290  * @see bt_object_get()
 291  */
 292 extern void bt_object_put(struct bt_object *object);
 293
 294 /**
 295  * Recursively freezes the object \p object.
 296  *
 297  * A frozen object cannot be modified; it is considered immutable.
 298  * Reference counting still works on a frozen object though: you may
 299  * pass a frozen object to bt_object_get() and bt_object_put().
 300  *
 301  * @param object        Object to freeze
 302  * @returns             One of #bt_object_status values; if \p object
 303  *                      is already frozen, though, #BT_OBJECT_STATUS_OK
 304  *                      is returned anyway (i.e. this function never
 305  *                      returns #BT_OBJECT_STATUS_FROZEN)
 306  *
 307  * @see bt_object_is_frozen()
 308  */
 309 extern enum bt_object_status bt_object_freeze(struct bt_object *object);
 310
 311 /**
 312  * Checks whether \p object is frozen or not.
 313  *
 314  * @param object        Object to check
 315  * @returns             \c true if \p object is frozen
 316  *
 317  * @see bt_object_freeze()
 318  */
 319 extern bool bt_object_is_frozen(const struct bt_object *object);
 320
 321 /**
 322  * Returns the type of \p object.
 323  *
 324  * @param object        Object of which to get the type
 325  * @returns             Object's type, or #BT_OBJECT_TYPE_UNKNOWN
 326  *                      on error
 327  *
 328  * @see #bt_object_type (object types)
 329  * @see bt_object_is_null()
 330  * @see bt_object_is_bool()
 331  * @see bt_object_is_integer()
 332  * @see bt_object_is_float()
 333  * @see bt_object_is_string()
 334  * @see bt_object_is_array()
 335  * @see bt_object_is_map()
 336  */
 337 extern enum bt_object_type bt_object_get_type(const struct bt_object *object);
 338
 339 /**
 340  * Checks whether \p object is a null object. The only valid null
 341  * object is \ref bt_object_null.
 342  *
 343  * @param object        Object to check
 344  * @returns             \c true if \p object is a null object
 345  *
 346  * @see bt_object_get_type()
 347  */
 348 static inline
 349 bool bt_object_is_null(const struct bt_object *object)
 350 {
 351         return bt_object_get_type(object) == BT_OBJECT_TYPE_NULL;
 352 }
 353
 354 /**
 355  * Checks whether \p object is a boolean object.
 356  *
 357  * @param object        Object to check
 358  * @returns             \c true if \p object is a boolean object
 359  *
 360  * @see bt_object_get_type()
 361  */
 362 static inline
 363 bool bt_object_is_bool(const struct bt_object *object)
 364 {
 365         return bt_object_get_type(object) == BT_OBJECT_TYPE_BOOL;
 366 }
 367
 368 /**
 369  * Checks whether \p object is an integer object.
 370  *
 371  * @param object        Object to check
 372  * @returns             \c true if \p object is an integer object
 373  *
 374  * @see bt_object_get_type()
 375  */
 376 static inline
 377 bool bt_object_is_integer(const struct bt_object *object)
 378 {
 379         return bt_object_get_type(object) == BT_OBJECT_TYPE_INTEGER;
 380 }
 381
 382 /**
 383  * Checks whether \p object is a floating point number object.
 384  *
 385  * @param object        Object to check
 386  * @returns             \c true if \p object is a floating point
 387  *                      number object
 388  *
 389  * @see bt_object_get_type()
 390  */
 391 static inline
 392 bool bt_object_is_float(const struct bt_object *object)
 393 {
 394         return bt_object_get_type(object) == BT_OBJECT_TYPE_FLOAT;
 395 }
 396
 397 /**
 398  * Checks whether \p object is a string object.
 399  *
 400  * @param object        Object to check
 401  * @returns             \c true if \p object is a string object
 402  *
 403  * @see bt_object_get_type()
 404  */
 405 static inline
 406 bool bt_object_is_string(const struct bt_object *object)
 407 {
 408         return bt_object_get_type(object) == BT_OBJECT_TYPE_STRING;
 409 }
 410
 411 /**
 412  * Checks whether \p object is an array object.
 413  *
 414  * @param object        Object to check
 415  * @returns             \c true if \p object is an array object
 416  *
 417  * @see bt_object_get_type()
 418  */
 419 static inline
 420 bool bt_object_is_array(const struct bt_object *object)
 421 {
 422         return bt_object_get_type(object) == BT_OBJECT_TYPE_ARRAY;
 423 }
 424
 425 /**
 426  * Checks whether \p object is a map object.
 427  *
 428  * @param object        Object to check
 429  * @returns             \c true if \p object is a map object
 430  *
 431  * @see bt_object_get_type()
 432  */
 433 static inline
 434 bool bt_object_is_map(const struct bt_object *object)
 435 {
 436         return bt_object_get_type(object) == BT_OBJECT_TYPE_MAP;
 437 }
 438
 439 /**
 440  * Creates a boolean object. The created boolean object's initial value
 441  * is \c false.
 442  *
 443  * The created object's reference count is set to 1.
 444  *
 445  * @returns     Created object on success, or \c NULL on error
 446  *
 447  * @see bt_object_bool_create_init() (creates an initialized
 448  *                                   boolean object)
 449  */
 450 extern struct bt_object *bt_object_bool_create(void);
 451
 452 /**
 453  * Creates a boolean object with its initial value set to \p val.
 454  *
 455  * The created object's reference count is set to 1.
 456  *
 457  * @param val   Initial value
 458  * @returns     Created object on success, or \c NULL on error
 459  */
 460 extern struct bt_object *bt_object_bool_create_init(bool val);
 461
 462 /**
 463  * Creates an integer object. The created integer object's initial value
 464  * is 0.
 465  *
 466  * The created object's reference count is set to 1.
 467  *
 468  * @returns     Created object on success, or \c NULL on error
 469  *
 470  * @see bt_object_integer_create_init() (creates an initialized
 471  *                                      integer object)
 472  */
 473 extern struct bt_object *bt_object_integer_create(void);
 474
 475 /**
 476  * Creates an integer object with its initial value set to \p val.
 477  *
 478  * The created object's reference count is set to 1.
 479  *
 480  * @param val   Initial value
 481  * @returns     Created object on success, or \c NULL on error
 482  */
 483 extern struct bt_object *bt_object_integer_create_init(int64_t val);
 484
 485 /**
 486  * Creates a floating point number object. The created floating point
 487  * number object's initial value is 0.
 488  *
 489  * The created object's reference count is set to 1.
 490  *
 491  * @returns     Created object on success, or \c NULL on error
 492  *
 493  * @see bt_object_float_create_init() (creates an initialized floating
 494  *                                    point number object)
 495  */
 496 extern struct bt_object *bt_object_float_create(void);
 497
 498 /**
 499  * Creates a floating point number object with its initial value set
 500  * to \p val.
 501  *
 502  * The created object's reference count is set to 1.
 503  *
 504  * @param val   Initial value
 505  * @returns     Created object on success, or \c NULL on error
 506  */
 507 extern struct bt_object *bt_object_float_create_init(double val);
 508
 509 /**
 510  * Creates a string object. The string object is initially empty.
 511  *
 512  * The created object's reference count is set to 1.
 513  *
 514  * @returns     Created object on success, or \c NULL on error
 515  *
 516  * @see bt_object_string_create_init() (creates an initialized
 517  *                                     string object)
 518  */
 519 extern struct bt_object *bt_object_string_create(void);
 520
 521 /**
 522  * Creates a string object with its initial value set to \p val.
 523  *
 524  * \p val is copied.
 525  *
 526  * The created object's reference count is set to 1.
 527  *
 528  * @param val   Initial value (will be copied)
 529  * @returns     Created object on success, or \c NULL on error
 530  */
 531 extern struct bt_object *bt_object_string_create_init(const char *val);
 532
 533 /**
 534  * Creates an empty array object.
 535  *
 536  * The created object's reference count is set to 1.
 537  *
 538  * @returns     Created object on success, or \c NULL on error
 539  */
 540 extern struct bt_object *bt_object_array_create(void);
 541
 542 /**
 543  * Creates an empty map object.
 544  *
 545  * The created object's reference count is set to 1.
 546  *
 547  * @returns     Created object on success, or \c NULL on error
 548  */
 549 extern struct bt_object *bt_object_map_create(void);
 550
 551 /**
 552  * Gets the boolean value of the boolean object \p bool_obj.
 553  *
 554  * @param bool_obj      Boolean object
 555  * @param val           Returned boolean value
 556  * @returns             One of #bt_object_status values
 557  *
 558  * @see bt_object_bool_set()
 559  */
 560 extern enum bt_object_status bt_object_bool_get(
 561         const struct bt_object *bool_obj, bool *val);
 562
 563 /**
 564  * Sets the boolean value of the boolean object \p bool_obj to \p val.
 565  *
 566  * @param bool_obj      Boolean object
 567  * @param val           New boolean value
 568  * @returns             One of #bt_object_status values
 569  *
 570  * @see bt_object_bool_get()
 571  */
 572 extern enum bt_object_status bt_object_bool_set(struct bt_object *bool_obj,
 573         bool val);
 574
 575 /**
 576  * Gets the integer value of the integer object \p integer_obj.
 577  *
 578  * @param integer_obj   Integer object
 579  * @param val           Returned integer value
 580  * @returns             One of #bt_object_status values
 581  *
 582  * @see bt_object_integer_set()
 583  */
 584 extern enum bt_object_status bt_object_integer_get(
 585         const struct bt_object *integer_obj, int64_t *val);
 586
 587 /**
 588  * Sets the integer value of the integer object \p integer_obj to
 589  * \p val.
 590  *
 591  * @param integer_obj   Integer object
 592  * @param val           New integer value
 593  * @returns             One of #bt_object_status values
 594  *
 595  * @see bt_object_integer_get()
 596  */
 597 extern enum bt_object_status bt_object_integer_set(
 598         struct bt_object *integer_obj, int64_t val);
 599
 600 /**
 601  * Gets the floating point number value of the floating point number
 602  * object \p float_obj.
 603  *
 604  * @param float_obj     Floating point number object
 605  * @param val           Returned floating point number value
 606  * @returns             One of #bt_object_status values
 607  *
 608  * @see bt_object_float_set()
 609  */
 610 extern enum bt_object_status bt_object_float_get(
 611         const struct bt_object *float_obj, double *val);
 612
 613 /**
 614  * Sets the floating point number value of the floating point number
 615  * object \p float_obj to \p val.
 616  *
 617  * @param float_obj     Floating point number object
 618  * @param val           New floating point number value
 619  * @returns             One of #bt_object_status values
 620  *
 621  * @see bt_object_float_get()
 622  */
 623 extern enum bt_object_status bt_object_float_set(
 624         struct bt_object *float_obj, double val);
 625
 626 /**
 627  * Gets the string value of the string object \p string_obj. The
 628  * returned string is valid as long as this object exists and is not
 629  * modified. The ownership of the returned string is \em not
 630  * transferred to the caller.
 631  *
 632  * @param string_obj    String object
 633  * @param val           Returned string value
 634  * @returns             One of #bt_object_status values
 635  *
 636  * @see bt_object_string_set()
 637  */
 638 extern enum bt_object_status bt_object_string_get(
 639         const struct bt_object *string_obj, const char **val);
 640
 641 /**
 642  * Sets the string value of the string object \p string_obj to
 643  * \p val.
 644  *
 645  * \p val is copied.
 646  *
 647  * @param string_obj    String object
 648  * @param val           New string value (copied)
 649  * @returns             One of #bt_object_status values
 650  *
 651  * @see bt_object_string_get()
 652  */
 653 extern enum bt_object_status bt_object_string_set(struct bt_object *string_obj,
 654         const char *val);
 655
 656 /**
 657  * Gets the size of the array object \p array_obj, that is, the number
 658  * of elements contained in \p array_obj.
 659  *
 660  * @param array_obj     Array object
 661  * @returns             Array size if the return value is 0 (empty) or a
 662  *                      positive value, or one of
 663  *                      #bt_object_status negative values otherwise
 664  *
 665  * @see bt_object_array_is_empty()
 666  */
 667 extern int bt_object_array_size(const struct bt_object *array_obj);
 668
 669 /**
 670  * Returns \c true if the array object \p array_obj.
 671  *
 672  * @param array_obj     Array object
 673  * @returns             \c true if \p array_obj is empty
 674  *
 675  * @see bt_object_array_size()
 676  */
 677 extern bool bt_object_array_is_empty(const struct bt_object *array_obj);
 678
 679 /**
 680  * Gets the element object of the array object \p array_obj at the
 681  * index \p index.
 682  *
 683  * The returned object's reference count is incremented, unless it's
 684  * a null object.
 685  *
 686  * @param array_obj     Array object
 687  * @param index         Index of element to get
 688  * @returns             Element object at index \p index on success,
 689  *                      or \c NULL on error
 690  */
 691 extern struct bt_object *bt_object_array_get(const struct bt_object *array_obj,
 692         size_t index);
 693
 694 /**
 695  * Appends the element object \p element_obj to the array object
 696  * \p array_obj.
 697  *
 698  * The appended object's reference count is incremented, unless it's
 699  * a null object.
 700  *
 701  * @param array_obj     Array object
 702  * @param element_obj   Element object to append
 703  * @returns             One of #bt_object_status values
 704  *
 705  * @see bt_object_array_append_bool()
 706  * @see bt_object_array_append_integer()
 707  * @see bt_object_array_append_float()
 708  * @see bt_object_array_append_string()
 709  * @see bt_object_array_append_array()
 710  * @see bt_object_array_append_map()
 711  */
 712 extern enum bt_object_status bt_object_array_append(struct bt_object *array_obj,
 713         struct bt_object *element_obj);
 714
 715 /**
 716  * Appends the boolean value \p val to the array object \p array_obj.
 717  * This is a convenience function which creates the underlying boolean
 718  * object before appending it.
 719  *
 720  * The created boolean object's reference count is set to 1.
 721  *
 722  * @param array_obj     Array object
 723  * @param val           Boolean value to append
 724  * @returns             One of #bt_object_status values
 725  *
 726  * @see bt_object_array_append()
 727  */
 728 extern enum bt_object_status bt_object_array_append_bool(
 729         struct bt_object *array_obj, bool val);
 730
 731 /**
 732  * Appends the integer value \p val to the array object \p array_obj.
 733  * This is a convenience function which creates the underlying integer
 734  * object before appending it.
 735  *
 736  * The created integer object's reference count is set to 1.
 737  *
 738  * @param array_obj     Array object
 739  * @param val           Integer value to append
 740  * @returns             One of #bt_object_status values
 741  *
 742  * @see bt_object_array_append()
 743  */
 744 extern enum bt_object_status bt_object_array_append_integer(
 745         struct bt_object *array_obj, int64_t val);
 746
 747 /**
 748  * Appends the floating point number value \p val to the array object
 749  * \p array_obj. This is a convenience function which creates the
 750  * underlying floating point number object before appending it.
 751  *
 752  * The created floating point number object's reference count is
 753  * set to 1.
 754  *
 755  * @param array_obj     Array object
 756  * @param val           Floating point number value to append
 757  * @returns             One of #bt_object_status values
 758  *
 759  * @see bt_object_array_append()
 760  */
 761 extern enum bt_object_status bt_object_array_append_float(
 762         struct bt_object *array_obj, double val);
 763
 764 /**
 765  * Appends the string value \p val to the array object \p array_obj.
 766  * This is a convenience function which creates the underlying string
 767  * object before appending it.
 768  *
 769  * \p val is copied.
 770  *
 771  * The created string object's reference count is set to 1.
 772  *
 773  * @param array_obj     Array object
 774  * @param val           String value to append (copied)
 775  * @returns             One of #bt_object_status values
 776  *
 777  * @see bt_object_array_append()
 778  */
 779 extern enum bt_object_status bt_object_array_append_string(
 780         struct bt_object *array_obj, const char *val);
 781
 782 /**
 783  * Appends an empty array object to the array object \p array_obj.
 784  * This is a convenience function which creates the underlying array
 785  * object before appending it.
 786  *
 787  * The created array object's reference count is set to 1.
 788  *
 789  * @param array_obj     Array object
 790  * @returns             One of #bt_object_status values
 791  *
 792  * @see bt_object_array_append()
 793  */
 794 extern enum bt_object_status bt_object_array_append_array(
 795         struct bt_object *array_obj);
 796
 797 /**
 798  * Appends an empty map object to the array object \p array_obj. This
 799  * is a convenience function which creates the underlying map object
 800  * before appending it.
 801  *
 802  * The created map object's reference count is set to 1.
 803  *
 804  * @param array_obj     Array object
 805  * @returns             One of #bt_object_status values
 806  *
 807  * @see bt_object_array_append()
 808  */
 809 extern enum bt_object_status bt_object_array_append_map(
 810         struct bt_object *array_obj);
 811
 812 /**
 813  * Replaces the element object at index \p index of the array object
 814  * \p array_obj by \p element_obj.
 815  *
 816  * The replaced object's reference count is decremented, unless it's
 817  * a null object. The reference count of \p element_obj is incremented,
 818  * unless it's a null object.
 819  *
 820  * @param array_obj     Array object
 821  * @param index         Index of element object to replace
 822  * @param element_obj   New element object at position \p index of
 823  *                      \p array_obj
 824  * @returns             One of #bt_object_status values
 825  */
 826 extern enum bt_object_status bt_object_array_set(struct bt_object *array_obj,
 827         size_t index, struct bt_object *element_obj);
 828
 829 /**
 830  * Gets the size of a map object, that is, the number of elements
 831  * contained in a map object.
 832  *
 833  * @param map_obj       Map object
 834  * @returns             Map size if the return value is 0 (empty) or a
 835  *                      positive value, or one of
 836  *                      #bt_object_status negative values otherwise
 837  *
 838  * @see bt_object_map_is_empty()
 839  */
 840 extern int bt_object_map_size(const struct bt_object *map_obj);
 841
 842 /**
 843  * Returns \c true if the map object \p map_obj.
 844  *
 845  * @param map_obj       Map object
 846  * @returns             \c true if \p map_obj is empty
 847  *
 848  * @see bt_object_map_size()
 849  */
 850 extern bool bt_object_map_is_empty(const struct bt_object *map_obj);
 851
 852 /**
 853  * Gets the element object associated with the key \p key within the
 854  * map object \p map_obj.
 855  *
 856  * The returned object's reference count is incremented, unless it's
 857  * a null object.
 858  *
 859  * @param map_obj       Map object
 860  * @param key           Key of the element to get
 861  * @returns             Element object associated with the key \p key
 862  *                      on success, or \c NULL on error
 863  */
 864 extern struct bt_object *bt_object_map_get(const struct bt_object *map_obj,
 865         const char *key);
 866
 867 /**
 868  * Calls a provided user function \p cb for each element of the map
 869  * object \p map_obj.
 870  *
 871  * The object passed to the user function is a <b>weak reference</b>:
 872  * you must call bt_object_get() on it to obtain your own reference.
 873  *
 874  * The key passed to the user function is only valid in the scope of
 875  * this user function.
 876  *
 877  * The user function must return \c true to continue the loop, or
 878  * \c false to break it.
 879  *
 880  * @param map_obj       Map object
 881  * @param cb            User function to call back
 882  * @param data          User data passed to the user function
 883  * @returns             One of #bt_object_status values; more
 884  *                      specifically, #BT_OBJECT_STATUS_CANCELLED is
 885  *                      returned if the loop was cancelled by the user
 886  *                      function
 887  */
 888 extern enum bt_object_status bt_object_map_foreach(
 889         const struct bt_object *map_obj, bt_object_map_foreach_cb cb,
 890         void *data);
 891
 892 /**
 893  * Returns whether or not the map object \p map_obj contains the
 894  * key \p key.
 895  *
 896  * @param map_obj       Map object
 897  * @param key           Key to check
 898  * @returns             \c true if \p map_obj contains the key \p key,
 899  *                      or \c false if it doesn't have \p key or
 900  *                      on error
 901  */
 902 extern bool bt_object_map_has_key(const struct bt_object *map_obj,
 903         const char *key);
 904
 905 /**
 906  * Inserts the element object \p element_obj associated with the key
 907  * \p key into the map object \p map_obj. If \p key exists in
 908  * \p map_obj, the associated element object is first put, and then
 909  * replaced by \p element_obj.
 910  *
 911  * \p key is copied.
 912  *
 913  * The inserted object's reference count is incremented, unless it's
 914  * a null object.
 915  *
 916  * @param map_obj       Map object
 917  * @param key           Key (copied) of object to insert
 918  * @param element_obj   Element object to insert, associated with the
 919  *                      key \p key
 920  * @returns             One of #bt_object_status values
 921  *
 922  * @see bt_object_map_insert_bool()
 923  * @see bt_object_map_insert_integer()
 924  * @see bt_object_map_insert_float()
 925  * @see bt_object_map_insert_string()
 926  * @see bt_object_map_insert_array()
 927  * @see bt_object_map_insert_map()
 928  */
 929 extern enum bt_object_status bt_object_map_insert(
 930         struct bt_object *map_obj, const char *key,
 931         struct bt_object *element_obj);
 932
 933 /**
 934  * Inserts the boolean value \p val associated with the key \p key into
 935  * the map object \p map_obj. This is a convenience function which
 936  * creates the underlying boolean object before inserting it.
 937  *
 938  * \p key is copied.
 939  *
 940  * The created boolean object's reference count is set to 1.
 941  *
 942  * @param map_obj       Map object
 943  * @param key           Key (copied) of boolean value to insert
 944  * @param val           Boolean value to insert, associated with the
 945  *                      key \p key
 946  * @returns             One of #bt_object_status values
 947  *
 948  * @see bt_object_map_insert()
 949  */
 950 extern enum bt_object_status bt_object_map_insert_bool(
 951         struct bt_object *map_obj, const char *key, bool val);
 952
 953 /**
 954  * Inserts the integer value \p val associated with the key \p key into
 955  * the map object \p map_obj. This is a convenience function which
 956  * creates the underlying integer object before inserting it.
 957  *
 958  * \p key is copied.
 959  *
 960  * The created integer object's reference count is set to 1.
 961  *
 962  * @param map_obj       Map object
 963  * @param key           Key (copied) of integer value to insert
 964  * @param val           Integer value to insert, associated with the
 965  *                      key \p key
 966  * @returns             One of #bt_object_status values
 967  *
 968  * @see bt_object_map_insert()
 969  */
 970 extern enum bt_object_status bt_object_map_insert_integer(
 971         struct bt_object *map_obj, const char *key, int64_t val);
 972
 973 /**
 974  * Inserts the floating point number value \p val associated with the
 975  * key \p key into the map object \p map_obj. This is a convenience
 976  * function which creates the underlying floating point number object
 977  * before inserting it.
 978  *
 979  * \p key is copied.
 980  *
 981  * The created floating point number object's reference count is
 982  * set to 1.
 983  *
 984  * @param map_obj       Map object
 985  * @param key           Key (copied) of floating point number value to
 986  *                      insert
 987  * @param val           Floating point number value to insert,
 988  *                      associated with the key \p key
 989  * @returns             One of #bt_object_status values
 990  *
 991  * @see bt_object_map_insert()
 992  */
 993 extern enum bt_object_status bt_object_map_insert_float(
 994         struct bt_object *map_obj, const char *key, double val);
 995
 996 /**
 997  * Inserts the string value \p val associated with the key \p key into
 998  * the map object \p map_obj. This is a convenience function which
 999  * creates the underlying string object before inserting it.
1000  *
1001  * \p val and \p key are copied.
1002  *
1003  * The created string object's reference count is set to 1.
1004  *
1005  * @param map_obj       Map object
1006  * @param key           Key (copied) of string value to insert
1007  * @param val           String value to insert, associated with the
1008  *                      key \p key
1009  * @returns             One of #bt_object_status values
1010  *
1011  * @see bt_object_map_insert()
1012  */
1013 extern enum bt_object_status bt_object_map_insert_string(
1014         struct bt_object *map_obj, const char *key, const char *val);
1015
1016 /**
1017  * Inserts an empty array object associated with the key \p key into
1018  * the map object \p map_obj. This is a convenience function which
1019  * creates the underlying array object before inserting it.
1020  *
1021  * \p key is copied.
1022  *
1023  * The created array object's reference count is set to 1.
1024  *
1025  * @param map_obj       Map object
1026  * @param key           Key (copied) of empty array to insert
1027  * @returns             One of #bt_object_status values
1028  *
1029  * @see bt_object_map_insert()
1030  */
1031 extern enum bt_object_status bt_object_map_insert_array(
1032         struct bt_object *map_obj, const char *key);
1033
1034 /**
1035  * Inserts an empty map object associated with the key \p key into
1036  * the map object \p map_obj. This is a convenience function which
1037  * creates the underlying map object before inserting it.
1038  *
1039  * \p key is copied.
1040  *
1041  * The created map object's reference count is set to 1.
1042  *
1043  * @param map_obj       Map object
1044  * @param key           Key (copied) of empty map to insert
1045  * @returns             One of #bt_object_status values
1046  *
1047  * @see bt_object_map_insert()
1048  */
1049 extern enum bt_object_status bt_object_map_insert_map(
1050         struct bt_object *map_obj, const char *key);
1051
1052 /**
1053  * Creates a deep copy of the object \p object.
1054  *
1055  * The created object's reference count is set to 1, unless
1056  * \p object is a null object.
1057  *
1058  * Copying a frozen object is allowed: the resulting copy is not frozen.
1059  *
1060  * @param object        Object to copy
1061  * @returns             Deep copy of \p object on success, or \c NULL
1062  *                      on error
1063  */
1064 extern struct bt_object *bt_object_copy(const struct bt_object *object);
1065
1066 /**
1067  * Compares the objects \p object_a and \p object_b and returns \c true
1068  * if they have the same content.
1069  *
1070  * @param object_a      Object A
1071  * @param object_b      Object B
1072  * @returns             \c true if \p object_a and \p object_b have the
1073  *                      same content, or \c false if they differ or on
1074  *                      error
1075  */
1076 extern bool bt_object_compare(const struct bt_object *object_a,
1077         const struct bt_object *object_b);
1078
1079 #ifdef __cplusplus
1080 }
1081 #endif
1082
1083 #endif /* _BABELTRACE_OBJECTS_H */