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