| 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 */ |