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 (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 extern void bt_object_get(struct bt_object *object);
 279
 280 /**
 281  * Decrements the reference count of \p object, destroying it when this
 282  * count reaches 0.
 283  *
 284  * @param object        Object of which to decrement the reference count
 285  *
 286  * @see BT_OBJECT_PUT() (puts an object and resets the variable to
 287  *                      \c NULL)
 288  */
 289 extern void bt_object_put(struct bt_object *object);
 290
 291 /**
 292  * Recursively freezes the object \p object.
 293  *
 294  * A frozen object cannot be modified; it is considered immutable.
 295  * Reference counting still works on a frozen object though: you may
 296  * pass a frozen object to bt_object_get() and bt_object_put().
 297  *
 298  * @param object        Object to freeze
 299  * @returns             One of #bt_object_status values; if \p object
 300  *                      is already frozen, though, #BT_OBJECT_STATUS_OK
 301  *                      is returned anyway (i.e. this function never
 302  *                      returns #BT_OBJECT_STATUS_FROZEN)
 303  */
 304 extern enum bt_object_status bt_object_freeze(struct bt_object *object);
 305
 306 /**
 307  * Checks whether \p object is frozen or not.
 308  *
 309  * @param object        Object to check
 310  * @returns             \c true if \p object is frozen
 311  */
 312 extern bool bt_object_is_frozen(const struct bt_object *object);
 313
 314 /**
 315  * Returns the type of \p object.
 316  *
 317  * @param object        Object of which to get the type
 318  * @returns             Object's type, or #BT_OBJECT_TYPE_UNKNOWN
 319  *                      on error
 320  *
 321  * @see #bt_object_type (object types)
 322  */
 323 extern enum bt_object_type bt_object_get_type(const struct bt_object *object);
 324
 325 /**
 326  * Checks whether \p object is a null object. The only valid null
 327  * object is \ref bt_object_null.
 328  *
 329  * @param object        Object to check
 330  * @returns             \c true if \p object is a null object
 331  */
 332 static inline
 333 bool bt_object_is_null(const struct bt_object *object)
 334 {
 335         return bt_object_get_type(object) == BT_OBJECT_TYPE_NULL;
 336 }
 337
 338 /**
 339  * Checks whether \p object is a boolean object.
 340  *
 341  * @param object        Object to check
 342  * @returns             \c true if \p object is a boolean object
 343  */
 344 static inline
 345 bool bt_object_is_bool(const struct bt_object *object)
 346 {
 347         return bt_object_get_type(object) == BT_OBJECT_TYPE_BOOL;
 348 }
 349
 350 /**
 351  * Checks whether \p object is an integer object.
 352  *
 353  * @param object        Object to check
 354  * @returns             \c true if \p object is an integer object
 355  */
 356 static inline
 357 bool bt_object_is_integer(const struct bt_object *object)
 358 {
 359         return bt_object_get_type(object) == BT_OBJECT_TYPE_INTEGER;
 360 }
 361
 362 /**
 363  * Checks whether \p object is a floating point number object.
 364  *
 365  * @param object        Object to check
 366  * @returns             \c true if \p object is a floating point number object
 367  */
 368 static inline
 369 bool bt_object_is_float(const struct bt_object *object)
 370 {
 371         return bt_object_get_type(object) == BT_OBJECT_TYPE_FLOAT;
 372 }
 373
 374 /**
 375  * Checks whether \p object is a string object.
 376  *
 377  * @param object        Object to check
 378  * @returns             \c true if \p object is a string object
 379  */
 380 static inline
 381 bool bt_object_is_string(const struct bt_object *object)
 382 {
 383         return bt_object_get_type(object) == BT_OBJECT_TYPE_STRING;
 384 }
 385
 386 /**
 387  * Checks whether \p object is an array object.
 388  *
 389  * @param object        Object to check
 390  * @returns             \c true if \p object is an array object
 391  */
 392 static inline
 393 bool bt_object_is_array(const struct bt_object *object)
 394 {
 395         return bt_object_get_type(object) == BT_OBJECT_TYPE_ARRAY;
 396 }
 397
 398 /**
 399  * Checks whether \p object is a map object.
 400  *
 401  * @param object        Object to check
 402  * @returns             \c true if \p object is a map object
 403  */
 404 static inline
 405 bool bt_object_is_map(const struct bt_object *object)
 406 {
 407         return bt_object_get_type(object) == BT_OBJECT_TYPE_MAP;
 408 }
 409
 410 /**
 411  * Creates a boolean object. The created boolean object's initial value
 412  * is \c false.
 413  *
 414  * The created object's reference count is set to 1.
 415  *
 416  * @returns     Created object on success, or \c NULL on error
 417  */
 418 extern struct bt_object *bt_object_bool_create(void);
 419
 420 /**
 421  * Creates a boolean object with its initial value set to \p val.
 422  *
 423  * The created object's reference count is set to 1.
 424  *
 425  * @param val   Initial value
 426  * @returns     Created object on success, or \c NULL on error
 427  */
 428 extern struct bt_object *bt_object_bool_create_init(bool val);
 429
 430 /**
 431  * Creates an integer object. The created integer object's initial value
 432  * is 0.
 433  *
 434  * The created object's reference count is set to 1.
 435  *
 436  * @returns     Created object on success, or \c NULL on error
 437  */
 438 extern struct bt_object *bt_object_integer_create(void);
 439
 440 /**
 441  * Creates an integer object with its initial value set to \p val.
 442  *
 443  * The created object's reference count is set to 1.
 444  *
 445  * @param val   Initial value
 446  * @returns     Created object on success, or \c NULL on error
 447  */
 448 extern struct bt_object *bt_object_integer_create_init(int64_t val);
 449
 450 /**
 451  * Creates a floating point number object. The created floating point
 452  * number object's initial value is 0.
 453  *
 454  * The created object's reference count is set to 1.
 455  *
 456  * @returns     Created object on success, or \c NULL on error
 457  */
 458 extern struct bt_object *bt_object_float_create(void);
 459
 460 /**
 461  * Creates a floating point number object with its initial value set
 462  * to \p val.
 463  *
 464  * The created object's reference count is set to 1.
 465  *
 466  * @param val   Initial value
 467  * @returns     Created object on success, or \c NULL on error
 468  */
 469 extern struct bt_object *bt_object_float_create_init(double val);
 470
 471 /**
 472  * Creates a string object. The string object is initially empty.
 473  *
 474  * The created object's reference count is set to 1.
 475  *
 476  * @returns     Created object on success, or \c NULL on error
 477  */
 478 extern struct bt_object *bt_object_string_create(void);
 479
 480 /**
 481  * Creates a string object with its initial value set to \p val.
 482  *
 483  * \p val is copied.
 484  *
 485  * The created object's reference count is set to 1.
 486  *
 487  * @param val   Initial value (will be copied)
 488  * @returns     Created object on success, or \c NULL on error
 489  */
 490 extern struct bt_object *bt_object_string_create_init(const char *val);
 491
 492 /**
 493  * Creates an empty array object.
 494  *
 495  * The created object's reference count is set to 1.
 496  *
 497  * @returns     Created object on success, or \c NULL on error
 498  */
 499 extern struct bt_object *bt_object_array_create(void);
 500
 501 /**
 502  * Creates an empty map object.
 503  *
 504  * The created object's reference count is set to 1.
 505  *
 506  * @returns     Created object on success, or \c NULL on error
 507  */
 508 extern struct bt_object *bt_object_map_create(void);
 509
 510 /**
 511  * Gets the boolean value of the boolean object \p bool_obj.
 512  *
 513  * @param bool_obj      Boolean object
 514  * @param val           Returned boolean value
 515  * @returns             One of #bt_object_status values
 516  */
 517 extern enum bt_object_status bt_object_bool_get(
 518         const struct bt_object *bool_obj, bool *val);
 519
 520 /**
 521  * Sets the boolean value of the boolean object \p bool_obj to \p val.
 522  *
 523  * @param bool_obj      Boolean object
 524  * @param val           New boolean value
 525  * @returns             One of #bt_object_status values
 526  */
 527 extern enum bt_object_status bt_object_bool_set(struct bt_object *bool_obj,
 528         bool val);
 529
 530 /**
 531  * Gets the integer value of the integer object \p integer_obj.
 532  *
 533  * @param integer_obj   Integer object
 534  * @param val           Returned integer value
 535  * @returns             One of #bt_object_status values
 536  */
 537 extern enum bt_object_status bt_object_integer_get(
 538         const struct bt_object *integer_obj, int64_t *val);
 539
 540 /**
 541  * Sets the integer value of the integer object \p integer_obj to
 542  * \p val.
 543  *
 544  * @param integer_obj   Integer object
 545  * @param val           New integer value
 546  * @returns             One of #bt_object_status values
 547  */
 548 extern enum bt_object_status bt_object_integer_set(
 549         struct bt_object *integer_obj, int64_t val);
 550
 551 /**
 552  * Gets the floating point number value of the floating point number
 553  * object \p float_obj.
 554  *
 555  * @param float_obj     Floating point number object
 556  * @param val           Returned floating point number value
 557  * @returns             One of #bt_object_status values
 558  */
 559 extern enum bt_object_status bt_object_float_get(
 560         const struct bt_object *float_obj, double *val);
 561
 562 /**
 563  * Sets the floating point number value of the floating point number
 564  * object \p float_obj to \p val.
 565  *
 566  * @param float_obj     Floating point number object
 567  * @param val           New floating point number value
 568  * @returns             One of #bt_object_status values
 569  */
 570 extern enum bt_object_status bt_object_float_set(
 571         struct bt_object *float_obj, double val);
 572
 573 /**
 574  * Gets the string value of the string object \p string_obj. The
 575  * returned string is valid as long as this object exists and is not
 576  * modified. The ownership of the returned string is \em not
 577  * transferred to the caller.
 578  *
 579  * @param string_obj    String object
 580  * @param val           Returned string value
 581  * @returns             One of #bt_object_status values
 582  */
 583 extern enum bt_object_status bt_object_string_get(
 584         const struct bt_object *string_obj, const char **val);
 585
 586 /**
 587  * Sets the string value of the string object \p string_obj to
 588  * \p val.
 589  *
 590  * \p val is copied.
 591  *
 592  * @param string_obj    String object
 593  * @param val           New string value (copied)
 594  * @returns             One of #bt_object_status values
 595  */
 596 extern enum bt_object_status bt_object_string_set(struct bt_object *string_obj,
 597         const char *val);
 598
 599 /**
 600  * Gets the size of the array object \p array_obj, that is, the number
 601  * of elements contained in \p array_obj.
 602  *
 603  * @param array_obj     Array object
 604  * @returns             Array size if the return value is 0 (empty) or a
 605  *                      positive value, or one of
 606  *                      #bt_object_status negative values otherwise
 607  */
 608 extern int bt_object_array_size(const struct bt_object *array_obj);
 609
 610 /**
 611  * Returns \c true if the array object \p array_obj.
 612  *
 613  * @param array_obj     Array object
 614  * @returns             \c true if \p array_obj is empty
 615  */
 616 extern bool bt_object_array_is_empty(const struct bt_object *array_obj);
 617
 618 /**
 619  * Gets the element object of the array object \p array_obj at the
 620  * index \p index.
 621  *
 622  * The returned object's reference count is incremented, unless it's
 623  * a null object.
 624  *
 625  * @param array_obj     Array object
 626  * @param index         Index of element to get
 627  * @returns             Element object at index \p index on success,
 628  *                      or \c NULL on error
 629  */
 630 extern struct bt_object *bt_object_array_get(const struct bt_object *array_obj,
 631         size_t index);
 632
 633 /**
 634  * Appends the element object \p element_obj to the array object
 635  * \p array_obj.
 636  *
 637  * The appended object's reference count is incremented, unless it's
 638  * a null object.
 639  *
 640  * @param array_obj     Array object
 641  * @param element_obj   Element object to append
 642  * @returns             One of #bt_object_status values
 643  */
 644 extern enum bt_object_status bt_object_array_append(struct bt_object *array_obj,
 645         struct bt_object *element_obj);
 646
 647 /**
 648  * Appends the boolean value \p val to the array object \p array_obj.
 649  * This is a convenience function which creates the underlying boolean
 650  * object before appending it.
 651  *
 652  * The created boolean object's reference count is set to 1.
 653  *
 654  * @param array_obj     Array object
 655  * @param val           Boolean value to append
 656  * @returns             One of #bt_object_status values
 657  */
 658 extern enum bt_object_status bt_object_array_append_bool(
 659         struct bt_object *array_obj, bool val);
 660
 661 /**
 662  * Appends the integer value \p val to the array object \p array_obj.
 663  * This is a convenience function which creates the underlying integer
 664  * object before appending it.
 665  *
 666  * The created integer object's reference count is set to 1.
 667  *
 668  * @param array_obj     Array object
 669  * @param val           Integer value to append
 670  * @returns             One of #bt_object_status values
 671  */
 672 extern enum bt_object_status bt_object_array_append_integer(
 673         struct bt_object *array_obj, int64_t val);
 674
 675 /**
 676  * Appends the floating point number value \p val to the array object
 677  * \p array_obj. This is a convenience function which creates the
 678  * underlying floating point number object before appending it.
 679  *
 680  * The created floating point number object's reference count is
 681  * set to 1.
 682  *
 683  * @param array_obj     Array object
 684  * @param val           Floating point number value to append
 685  * @returns             One of #bt_object_status values
 686  */
 687 extern enum bt_object_status bt_object_array_append_float(
 688         struct bt_object *array_obj, double val);
 689
 690 /**
 691  * Appends the string value \p val to the array object \p array_obj.
 692  * This is a convenience function which creates the underlying string
 693  * object before appending it.
 694  *
 695  * \p val is copied.
 696  *
 697  * The created string object's reference count is set to 1.
 698  *
 699  * @param array_obj     Array object
 700  * @param val           String value to append (copied)
 701  * @returns             One of #bt_object_status values
 702  */
 703 extern enum bt_object_status bt_object_array_append_string(
 704         struct bt_object *array_obj, const char *val);
 705
 706 /**
 707  * Appends an empty array object to the array object \p array_obj.
 708  * This is a convenience function which creates the underlying array
 709  * object before appending it.
 710  *
 711  * The created array object's reference count is set to 1.
 712  *
 713  * @param array_obj     Array object
 714  * @returns             One of #bt_object_status values
 715  */
 716 extern enum bt_object_status bt_object_array_append_array(
 717         struct bt_object *array_obj);
 718
 719 /**
 720  * Appends an empty map object to the array object \p array_obj. This
 721  * is a convenience function which creates the underlying map object
 722  * before appending it.
 723  *
 724  * The created map object's reference count is set to 1.
 725  *
 726  * @param array_obj     Array object
 727  * @returns             One of #bt_object_status values
 728  */
 729 extern enum bt_object_status bt_object_array_append_map(
 730         struct bt_object *array_obj);
 731
 732 /**
 733  * Replaces the element object at index \p index of the array object
 734  * \p array_obj by \p element_obj.
 735  *
 736  * The replaced object's reference count is decremented, unless it's
 737  * a null object. The reference count of \p element_obj is incremented,
 738  * unless it's a null object.
 739  *
 740  * @param array_obj     Array object
 741  * @param index         Index of element object to replace
 742  * @param element_obj   New element object at position \p index of
 743  *                      \p array_obj
 744  * @returns             One of #bt_object_status values
 745  */
 746 extern enum bt_object_status bt_object_array_set(struct bt_object *array_obj,
 747         size_t index, struct bt_object *element_obj);
 748
 749 /**
 750  * Gets the size of a map object, that is, the number of elements
 751  * contained in a map object.
 752  *
 753  * @param map_obj       Map object
 754  * @returns             Map size if the return value is 0 (empty) or a
 755  *                      positive value, or one of
 756  *                      #bt_object_status negative values otherwise
 757  */
 758 extern int bt_object_map_size(const struct bt_object *map_obj);
 759
 760 /**
 761  * Returns \c true if the map object \p map_obj.
 762  *
 763  * @param map_obj       Map object
 764  * @returns             \c true if \p map_obj is empty
 765  */
 766 extern bool bt_object_map_is_empty(const struct bt_object *map_obj);
 767
 768 /**
 769  * Gets the element object associated with the key \p key within the
 770  * map object \p map_obj.
 771  *
 772  * The returned object's reference count is incremented, unless it's
 773  * a null object.
 774  *
 775  * @param map_obj       Map object
 776  * @param key           Key of the element to get
 777  * @returns             Element object associated with the key \p key
 778  *                      on success, or \c NULL on error
 779  */
 780 extern struct bt_object *bt_object_map_get(const struct bt_object *map_obj,
 781         const char *key);
 782
 783 /**
 784  * Calls a provided user function \p cb for each element of the map
 785  * object \p map_obj.
 786  *
 787  * The object passed to the user function is a <b>weak reference</b>:
 788  * you must call bt_object_get() on it to obtain your own reference.
 789  *
 790  * The key passed to the user function is only valid in the scope of
 791  * this user function.
 792  *
 793  * The user function must return \c true to continue the loop, or
 794  * \c false to break it.
 795  *
 796  * @param map_obj       Map object
 797  * @param cb            User function to call back
 798  * @param data          User data passed to the user function
 799  * @returns             One of #bt_object_status values; more
 800  *                      specifically, #BT_OBJECT_STATUS_CANCELLED is
 801  *                      returned if the loop was cancelled by the user
 802  *                      function
 803  */
 804 extern enum bt_object_status bt_object_map_foreach(
 805         const struct bt_object *map_obj, bt_object_map_foreach_cb cb,
 806         void *data);
 807
 808 /**
 809  * Returns whether or not the map object \p map_obj contains the
 810  * key \p key.
 811  *
 812  * @param map_obj       Map object
 813  * @param key           Key to check
 814  * @returns             \c true if \p map_obj contains the key \p key,
 815  *                      or \c false if it doesn't have \p key or
 816  *                      on error
 817  */
 818 extern bool bt_object_map_has_key(const struct bt_object *map_obj,
 819         const char *key);
 820
 821 /**
 822  * Inserts the element object \p element_obj associated with the key
 823  * \p key into the map object \p map_obj. If \p key exists in
 824  * \p map_obj, the associated element object is first put, and then
 825  * replaced by \p element_obj.
 826  *
 827  * \p key is copied.
 828  *
 829  * The inserted object's reference count is incremented, unless it's
 830  * a null object.
 831  *
 832  * @param map_obj       Map object
 833  * @param key           Key (copied) of object to insert
 834  * @param element_obj   Element object to insert, associated with the
 835  *                      key \p key
 836  * @returns             One of #bt_object_status values
 837  */
 838 extern enum bt_object_status bt_object_map_insert(
 839         struct bt_object *map_obj, const char *key,
 840         struct bt_object *element_obj);
 841
 842 /**
 843  * Inserts the boolean value \p val associated with the key \p key into
 844  * the map object \p map_obj. This is a convenience function which
 845  * creates the underlying boolean object before inserting it.
 846  *
 847  * \p key is copied.
 848  *
 849  * The created boolean object's reference count is set to 1.
 850  *
 851  * @param map_obj       Map object
 852  * @param key           Key (copied) of boolean value to insert
 853  * @param val           Boolean value to insert, associated with the
 854  *                      key \p key
 855  * @returns             One of #bt_object_status values
 856  */
 857 extern enum bt_object_status bt_object_map_insert_bool(
 858         struct bt_object *map_obj, const char *key, bool val);
 859
 860 /**
 861  * Inserts the integer value \p val associated with the key \p key into
 862  * the map object \p map_obj. This is a convenience function which
 863  * creates the underlying integer object before inserting it.
 864  *
 865  * \p key is copied.
 866  *
 867  * The created integer object's reference count is set to 1.
 868  *
 869  * @param map_obj       Map object
 870  * @param key           Key (copied) of integer value to insert
 871  * @param val           Integer value to insert, associated with the
 872  *                      key \p key
 873  * @returns             One of #bt_object_status values
 874  */
 875 extern enum bt_object_status bt_object_map_insert_integer(
 876         struct bt_object *map_obj, const char *key, int64_t val);
 877
 878 /**
 879  * Inserts the floating point number value \p val associated with the
 880  * key \p key into the map object \p map_obj. This is a convenience
 881  * function which creates the underlying floating point number object
 882  * before inserting it.
 883  *
 884  * \p key is copied.
 885  *
 886  * The created floating point number object's reference count is
 887  * set to 1.
 888  *
 889  * @param map_obj       Map object
 890  * @param key           Key (copied) of floating point number value to
 891  *                      insert
 892  * @param val           Floating point number value to insert,
 893  *                      associated with the key \p key
 894  * @returns             One of #bt_object_status values
 895  */
 896 extern enum bt_object_status bt_object_map_insert_float(
 897         struct bt_object *map_obj, const char *key, double val);
 898
 899 /**
 900  * Inserts the string value \p val associated with the key \p key into
 901  * the map object \p map_obj. This is a convenience function which
 902  * creates the underlying string object before inserting it.
 903  *
 904  * \p val and \p key are copied.
 905  *
 906  * The created string object's reference count is set to 1.
 907  *
 908  * @param map_obj       Map object
 909  * @param key           Key (copied) of string value to insert
 910  * @param val           String value to insert, associated with the
 911  *                      key \p key
 912  * @returns             One of #bt_object_status values
 913  */
 914 extern enum bt_object_status bt_object_map_insert_string(
 915         struct bt_object *map_obj, const char *key, const char *val);
 916
 917 /**
 918  * Inserts an empty array object associated with the key \p key into
 919  * the map object \p map_obj. This is a convenience function which
 920  * creates the underlying array object before inserting it.
 921  *
 922  * \p key is copied.
 923  *
 924  * The created array object's reference count is set to 1.
 925  *
 926  * @param map_obj       Map object
 927  * @param key           Key (copied) of empty array to insert
 928  * @returns             One of #bt_object_status values
 929  */
 930 extern enum bt_object_status bt_object_map_insert_array(
 931         struct bt_object *map_obj, const char *key);
 932
 933 /**
 934  * Inserts an empty map object associated with the key \p key into
 935  * the map object \p map_obj. This is a convenience function which
 936  * creates the underlying map object before inserting it.
 937  *
 938  * \p key is copied.
 939  *
 940  * The created map object's reference count is set to 1.
 941  *
 942  * @param map_obj       Map object
 943  * @param key           Key (copied) of empty map to insert
 944  * @returns             One of #bt_object_status values
 945  */
 946 extern enum bt_object_status bt_object_map_insert_map(
 947         struct bt_object *map_obj, const char *key);
 948
 949 /**
 950  * Creates a deep copy of the object \p object.
 951  *
 952  * The created object's reference count is set to 1, unless
 953  * \p object is a null object.
 954  *
 955  * @param object        Object to copy
 956  * @returns             Deep copy of \p object on success, or \c NULL
 957  *                      on error
 958  */
 959 extern struct bt_object *bt_object_copy(const struct bt_object *object);
 960
 961 /**
 962  * Compares the objects \p object_a and \p object_b and returns \c true
 963  * if they have the same content.
 964  *
 965  * @param object_a      Object A
 966  * @param object_B      Object B
 967  * @returns             \c true if \p object_a and \p object_b have the
 968  *                      same content, or \c false if they differ or on
 969  *                      error
 970  */
 971 extern bool bt_object_compare(const struct bt_object *object_a,
 972         const struct bt_object *object_b);
 973
 974 #ifdef __cplusplus
 975 }
 976 #endif
 977
 978 #endif /* _BABELTRACE_OBJECTS_H */