1 #ifndef _BABELTRACE_OBJECTS_H
2 #define _BABELTRACE_OBJECTS_H
9 * Copyright (c) 2015 EfficiOS Inc. and Linux Foundation
10 * Copyright (c) 2015 Philippe Proulx <pproulx@efficios.com>
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:
19 * The above copyright notice and this permission notice shall be included in
20 * all copies or substantial portions of the Software.
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
33 * @brief Basic object system
35 * This is a basic object system API. The following functions allow you
36 * to create, modify, and destroy:
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
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
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().
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:
67 * struct bt_object *int_obj = bt_object_integer_create_init(34);
73 * // stuff, which could jump to error
75 * BT_OBJECT_PUT(int_obj);
77 * // stuff, which could jump to error
82 * // safe, even if int_obj is NULL
83 * BT_OBJECT_PUT(int_obj);
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()
97 * struct bt_object *int_obj2 = NULL;
98 * struct bt_object *int_obj = bt_object_integer_create_init(-23);
104 * // stuff, which could jump to error
106 * BT_OBJECT_MOVE(int_obj2, int_obj);
108 * // stuff, which could jump to 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);
121 * Most functions return a status code, one of the values in
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().
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
133 * @author Philippe Proulx <pproulx@efficios.com>
148 enum bt_object_type
{
149 /** Unknown object, used as an error code. */
150 BT_OBJECT_TYPE_UNKNOWN
= -1,
153 BT_OBJECT_TYPE_NULL
= 0,
155 /** Boolean object (holds \c true or \c false). */
156 BT_OBJECT_TYPE_BOOL
= 1,
158 /** Integer (holds a signed 64-bit integer value). */
159 BT_OBJECT_TYPE_INTEGER
= 2,
162 * Floating point number object (holds a \c double value).
164 BT_OBJECT_TYPE_FLOAT
= 3,
166 /** String object. */
167 BT_OBJECT_TYPE_STRING
= 4,
170 BT_OBJECT_TYPE_ARRAY
= 5,
173 BT_OBJECT_TYPE_MAP
= 6,
179 enum bt_object_status
{
180 /** Object cannot be altered because it's frozen. */
181 BT_OBJECT_STATUS_FROZEN
= -4,
183 /** Operation cancelled. */
184 BT_OBJECT_STATUS_CANCELLED
= -3,
186 /** Invalid arguments. */
187 /* -22 for compatibility with -EINVAL */
188 BT_OBJECT_STATUS_INVAL
= -22,
190 /** General error. */
191 BT_OBJECT_STATUS_ERROR
= -1,
193 /** Okay, no error. */
194 BT_OBJECT_STATUS_OK
= 0,
203 * The null object singleton.
205 * Use this everytime you need a null object. The null object singleton
206 * has no reference count; there's only one. You may directly compare
207 * any object to the null singleton to find out if it's a null object,
208 * or otherwise use bt_object_is_null().
210 * Functions of this API return this when the object is actually a
211 * null object (of type #BT_OBJECT_TYPE_NULL), whereas \c NULL means an
212 * error of some sort.
214 extern struct bt_object
*bt_object_null
;
217 * User function type for bt_object_map_foreach().
219 * \p object is a \em weak reference; you must pass it to
220 * bt_object_get() to get your own reference.
222 * Return \c true to continue the loop, or \c false to break it.
224 * @param key Key of map entry
225 * @param object Object of map entry (weak reference)
226 * @param data User data
227 * @returns \c true to continue the loop
229 typedef bool (* bt_object_map_foreach_cb
)(const char *key
,
230 struct bt_object
*object
, void *data
);
233 * Puts the object \p _object (calls bt_object_put() on it), and resets
234 * the variable to \c NULL.
236 * This is something that is often done when putting and object;
237 * resetting the variable to \c NULL makes sure it cannot be put a
240 * @param _object Object to put
242 * @see BT_OBJECT_MOVE() (moves an object from one variable to the other
243 * without putting it)
245 #define BT_OBJECT_PUT(_object) \
247 bt_object_put(_object); \
252 * Moves the object referenced by the variable \p _src_object to the
253 * \p _dst_object variable, then resets \p _src_object to \c NULL.
255 * The object's reference count is <b>not changed</b>. Resetting
256 * \p _src_object to \c NULL ensures the object will not be put
257 * twice later; its ownership is indeed \em moved from the source
258 * variable to the destination variable.
260 * @param _src_object Source object variable
261 * @param _dst_object Destination object variable
263 #define BT_OBJECT_MOVE(_dst_object, _src_object) \
265 (_dst_object) = (_src_object); \
266 (_src_object) = NULL; \
270 * Increments the reference count of \p object.
272 * @param object Object of which to increment the reference count
274 extern void bt_object_get(struct bt_object
*object
);
277 * Decrements the reference count of \p object, destroying it when this
280 * @param object Object of which to decrement the reference count
282 * @see BT_OBJECT_PUT() (puts an object and resets the variable to
285 extern void bt_object_put(struct bt_object
*object
);
288 * Recursively freezes the object \p object.
290 * A frozen object cannot be modified; it is considered immutable.
291 * Reference counting still works on a frozen object though: you may
292 * pass a frozen object to bt_object_get() and bt_object_put().
294 * @param object Object to freeze
295 * @returns One of #bt_object_status values; if \p object
296 * is already frozen, though, #BT_OBJECT_STATUS_OK
297 * is returned anyway (i.e. this function never
298 * returns #BT_OBJECT_STATUS_FROZEN)
300 extern enum bt_object_status
bt_object_freeze(struct bt_object
*object
);
303 * Checks whether \p object is frozen or not.
305 * @param object Object to check
306 * @returns \c true if \p object is frozen
308 extern bool bt_object_is_frozen(const struct bt_object
*object
);
311 * Returns the type of \p object.
313 * @param object Object of which to get the type
314 * @returns Object's type, or #BT_OBJECT_TYPE_UNKNOWN
317 * @see #bt_object_type (object types)
319 extern enum bt_object_type
bt_object_get_type(const struct bt_object
*object
);
322 * Checks whether \p object is a null object. The only valid null
323 * object is \ref bt_object_null.
325 * @param object Object to check
326 * @returns \c true if \p object is a null object
329 bool bt_object_is_null(const struct bt_object
*object
)
331 return bt_object_get_type(object
) == BT_OBJECT_TYPE_NULL
;
335 * Checks whether \p object is a boolean object.
337 * @param object Object to check
338 * @returns \c true if \p object is a boolean object
341 bool bt_object_is_bool(const struct bt_object
*object
)
343 return bt_object_get_type(object
) == BT_OBJECT_TYPE_BOOL
;
347 * Checks whether \p object is an integer object.
349 * @param object Object to check
350 * @returns \c true if \p object is an integer object
353 bool bt_object_is_integer(const struct bt_object
*object
)
355 return bt_object_get_type(object
) == BT_OBJECT_TYPE_INTEGER
;
359 * Checks whether \p object is a floating point number object.
361 * @param object Object to check
362 * @returns \c true if \p object is a floating point number object
365 bool bt_object_is_float(const struct bt_object
*object
)
367 return bt_object_get_type(object
) == BT_OBJECT_TYPE_FLOAT
;
371 * Checks whether \p object is a string object.
373 * @param object Object to check
374 * @returns \c true if \p object is a string object
377 bool bt_object_is_string(const struct bt_object
*object
)
379 return bt_object_get_type(object
) == BT_OBJECT_TYPE_STRING
;
383 * Checks whether \p object is an array object.
385 * @param object Object to check
386 * @returns \c true if \p object is an array object
389 bool bt_object_is_array(const struct bt_object
*object
)
391 return bt_object_get_type(object
) == BT_OBJECT_TYPE_ARRAY
;
395 * Checks whether \p object is a map object.
397 * @param object Object to check
398 * @returns \c true if \p object is a map object
401 bool bt_object_is_map(const struct bt_object
*object
)
403 return bt_object_get_type(object
) == BT_OBJECT_TYPE_MAP
;
407 * Creates a boolean object. The created boolean object's initial value
410 * The created object's reference count is set to 1.
412 * @returns Created object on success, or \c NULL on error
414 extern struct bt_object
*bt_object_bool_create(void);
417 * Creates a boolean object with its initial value set to \p val.
419 * The created object's reference count is set to 1.
421 * @param val Initial value
422 * @returns Created object on success, or \c NULL on error
424 extern struct bt_object
*bt_object_bool_create_init(bool val
);
427 * Creates an integer object. The created integer object's initial value
430 * The created object's reference count is set to 1.
432 * @returns Created object on success, or \c NULL on error
434 extern struct bt_object
*bt_object_integer_create(void);
437 * Creates an integer object with its initial value set to \p val.
439 * The created object's reference count is set to 1.
441 * @param val Initial value
442 * @returns Created object on success, or \c NULL on error
444 extern struct bt_object
*bt_object_integer_create_init(int64_t val
);
447 * Creates a floating point number object. The created floating point
448 * number object's initial value is 0.
450 * The created object's reference count is set to 1.
452 * @returns Created object on success, or \c NULL on error
454 extern struct bt_object
*bt_object_float_create(void);
457 * Creates a floating point number object with its initial value set
460 * The created object's reference count is set to 1.
462 * @param val Initial value
463 * @returns Created object on success, or \c NULL on error
465 extern struct bt_object
*bt_object_float_create_init(double val
);
468 * Creates a string object. The string object is initially empty.
470 * The created object's reference count is set to 1.
472 * @returns Created object on success, or \c NULL on error
474 extern struct bt_object
*bt_object_string_create(void);
477 * Creates a string object with its initial value set to \p val.
481 * The created object's reference count is set to 1.
483 * @param val Initial value (will be copied)
484 * @returns Created object on success, or \c NULL on error
486 extern struct bt_object
*bt_object_string_create_init(const char *val
);
489 * Creates an empty array object.
491 * The created object's reference count is set to 1.
493 * @returns Created object on success, or \c NULL on error
495 extern struct bt_object
*bt_object_array_create(void);
498 * Creates an empty map object.
500 * The created object's reference count is set to 1.
502 * @returns Created object on success, or \c NULL on error
504 extern struct bt_object
*bt_object_map_create(void);
507 * Gets the boolean value of the boolean object \p bool_obj.
509 * @param bool_obj Boolean object
510 * @param val Returned boolean value
511 * @returns One of #bt_object_status values
513 extern enum bt_object_status
bt_object_bool_get(
514 const struct bt_object
*bool_obj
, bool *val
);
517 * Sets the boolean value of the boolean object \p bool_obj to \p val.
519 * @param bool_obj Boolean object
520 * @param val New boolean value
521 * @returns One of #bt_object_status values
523 extern enum bt_object_status
bt_object_bool_set(struct bt_object
*bool_obj
,
527 * Gets the integer value of the integer object \p integer_obj.
529 * @param integer_obj Integer object
530 * @param val Returned integer value
531 * @returns One of #bt_object_status values
533 extern enum bt_object_status
bt_object_integer_get(
534 const struct bt_object
*integer_obj
, int64_t *val
);
537 * Sets the integer value of the integer object \p integer_obj to
540 * @param integer_obj Integer object
541 * @param val New integer value
542 * @returns One of #bt_object_status values
544 extern enum bt_object_status
bt_object_integer_set(
545 struct bt_object
*integer_obj
, int64_t val
);
548 * Gets the floating point number value of the floating point number
549 * object \p float_obj.
551 * @param float_obj Floating point number object
552 * @param val Returned floating point number value
553 * @returns One of #bt_object_status values
555 extern enum bt_object_status
bt_object_float_get(
556 const struct bt_object
*float_obj
, double *val
);
559 * Sets the floating point number value of the floating point number
560 * object \p float_obj to \p val.
562 * @param float_obj Floating point number object
563 * @param val New floating point number value
564 * @returns One of #bt_object_status values
566 extern enum bt_object_status
bt_object_float_set(
567 struct bt_object
*float_obj
, double val
);
570 * Gets the string value of the string object \p string_obj. The
571 * returned string is valid as long as this object exists and is not
572 * modified. The ownership of the returned string is \em not
573 * transferred to the caller.
575 * @param string_obj String object
576 * @param val Returned string value
577 * @returns One of #bt_object_status values
579 extern enum bt_object_status
bt_object_string_get(
580 const struct bt_object
*string_obj
, const char **val
);
583 * Sets the string value of the string object \p string_obj to
588 * @param string_obj String object
589 * @param val New string value (copied)
590 * @returns One of #bt_object_status values
592 extern enum bt_object_status
bt_object_string_set(struct bt_object
*string_obj
,
596 * Gets the size of the array object \p array_obj, that is, the number
597 * of elements contained in \p array_obj.
599 * @param array_obj Array object
600 * @returns Array size if the return value is 0 (empty) or a
601 * positive value, or one of
602 * #bt_object_status negative values otherwise
604 extern int bt_object_array_size(const struct bt_object
*array_obj
);
607 * Returns \c true if the array object \p array_obj.
609 * @param array_obj Array object
610 * @returns \c true if \p array_obj is empty
612 extern bool bt_object_array_is_empty(const struct bt_object
*array_obj
);
615 * Gets the element object of the array object \p array_obj at the
618 * The returned object's reference count is incremented, unless it's
621 * @param array_obj Array object
622 * @param index Index of element to get
623 * @returns Element object at index \p index on success,
624 * or \c NULL on error
626 extern struct bt_object
*bt_object_array_get(const struct bt_object
*array_obj
,
630 * Appends the element object \p element_obj to the array object
633 * The appended object's reference count is incremented, unless it's
636 * @param array_obj Array object
637 * @param element_obj Element object to append
638 * @returns One of #bt_object_status values
640 extern enum bt_object_status
bt_object_array_append(struct bt_object
*array_obj
,
641 struct bt_object
*element_obj
);
644 * Appends the boolean value \p val to the array object \p array_obj.
645 * This is a convenience function which creates the underlying boolean
646 * object before appending it.
648 * The created boolean object's reference count is set to 1.
650 * @param array_obj Array object
651 * @param val Boolean value to append
652 * @returns One of #bt_object_status values
654 extern enum bt_object_status
bt_object_array_append_bool(
655 struct bt_object
*array_obj
, bool val
);
658 * Appends the integer value \p val to the array object \p array_obj.
659 * This is a convenience function which creates the underlying integer
660 * object before appending it.
662 * The created integer object's reference count is set to 1.
664 * @param array_obj Array object
665 * @param val Integer value to append
666 * @returns One of #bt_object_status values
668 extern enum bt_object_status
bt_object_array_append_integer(
669 struct bt_object
*array_obj
, int64_t val
);
672 * Appends the floating point number value \p val to the array object
673 * \p array_obj. This is a convenience function which creates the
674 * underlying floating point number object before appending it.
676 * The created floating point number object's reference count is
679 * @param array_obj Array object
680 * @param val Floating point number value to append
681 * @returns One of #bt_object_status values
683 extern enum bt_object_status
bt_object_array_append_float(
684 struct bt_object
*array_obj
, double val
);
687 * Appends the string value \p val to the array object \p array_obj.
688 * This is a convenience function which creates the underlying string
689 * object before appending it.
693 * The created string object's reference count is set to 1.
695 * @param array_obj Array object
696 * @param val String value to append (copied)
697 * @returns One of #bt_object_status values
699 extern enum bt_object_status
bt_object_array_append_string(
700 struct bt_object
*array_obj
, const char *val
);
703 * Appends an empty array object to the array object \p array_obj.
704 * This is a convenience function which creates the underlying array
705 * object before appending it.
707 * The created array object's reference count is set to 1.
709 * @param array_obj Array object
710 * @returns One of #bt_object_status values
712 extern enum bt_object_status
bt_object_array_append_array(
713 struct bt_object
*array_obj
);
716 * Appends an empty map object to the array object \p array_obj. This
717 * is a convenience function which creates the underlying map object
718 * before appending it.
720 * The created map object's reference count is set to 1.
722 * @param array_obj Array object
723 * @returns One of #bt_object_status values
725 extern enum bt_object_status
bt_object_array_append_map(
726 struct bt_object
*array_obj
);
729 * Replaces the element object at index \p index of the array object
730 * \p array_obj by \p element_obj.
732 * The replaced object's reference count is decremented, unless it's
733 * a null object. The reference count of \p element_obj is incremented,
734 * unless it's a null object.
736 * @param array_obj Array object
737 * @param index Index of element object to replace
738 * @param element_obj New element object at position \p index of
740 * @returns One of #bt_object_status values
742 extern enum bt_object_status
bt_object_array_set(struct bt_object
*array_obj
,
743 size_t index
, struct bt_object
*element_obj
);
746 * Gets the size of a map object, that is, the number of elements
747 * contained in a map object.
749 * @param map_obj Map object
750 * @returns Map size if the return value is 0 (empty) or a
751 * positive value, or one of
752 * #bt_object_status negative values otherwise
754 extern int bt_object_map_size(const struct bt_object
*map_obj
);
757 * Returns \c true if the map object \p map_obj.
759 * @param map_obj Map object
760 * @returns \c true if \p map_obj is empty
762 extern bool bt_object_map_is_empty(const struct bt_object
*map_obj
);
765 * Gets the element object associated with the key \p key within the
766 * map object \p map_obj.
768 * The returned object's reference count is incremented, unless it's
771 * @param map_obj Map object
772 * @param key Key of the element to get
773 * @returns Element object associated with the key \p key
774 * on success, or \c NULL on error
776 extern struct bt_object
*bt_object_map_get(const struct bt_object
*map_obj
,
780 * Calls a provided user function \p cb for each element of the map
783 * The object passed to the user function is a <b>weak reference</b>:
784 * you must call bt_object_get() on it to obtain your own reference.
786 * The key passed to the user function is only valid in the scope of
787 * this user function.
789 * The user function must return \c true to continue the loop, or
790 * \c false to break it.
792 * @param map_obj Map object
793 * @param cb User function to call back
794 * @param data User data passed to the user function
795 * @returns One of #bt_object_status values; more
796 * specifically, #BT_OBJECT_STATUS_CANCELLED is
797 * returned if the loop was cancelled by the user
800 extern enum bt_object_status
bt_object_map_foreach(
801 const struct bt_object
*map_obj
, bt_object_map_foreach_cb cb
,
805 * Returns whether or not the map object \p map_obj contains the
808 * @param map_obj Map object
809 * @param key Key to check
810 * @returns \c true if \p map_obj contains the key \p key,
811 * or \c false if it doesn't have \p key or
814 extern bool bt_object_map_has_key(const struct bt_object
*map_obj
,
818 * Inserts the element object \p element_obj associated with the key
819 * \p key into the map object \p map_obj. If \p key exists in
820 * \p map_obj, the associated element object is first put, and then
821 * replaced by \p element_obj.
825 * The inserted object's reference count is incremented, unless it's
828 * @param map_obj Map object
829 * @param key Key (copied) of object to insert
830 * @param element_obj Element object to insert, associated with the
832 * @returns One of #bt_object_status values
834 extern enum bt_object_status
bt_object_map_insert(
835 struct bt_object
*map_obj
, const char *key
,
836 struct bt_object
*element_obj
);
839 * Inserts the boolean value \p val associated with the key \p key into
840 * the map object \p map_obj. This is a convenience function which
841 * creates the underlying boolean object before inserting it.
845 * The created boolean object's reference count is set to 1.
847 * @param map_obj Map object
848 * @param key Key (copied) of boolean value to insert
849 * @param val Boolean value to insert, associated with the
851 * @returns One of #bt_object_status values
853 extern enum bt_object_status
bt_object_map_insert_bool(
854 struct bt_object
*map_obj
, const char *key
, bool val
);
857 * Inserts the integer value \p val associated with the key \p key into
858 * the map object \p map_obj. This is a convenience function which
859 * creates the underlying integer object before inserting it.
863 * The created integer object's reference count is set to 1.
865 * @param map_obj Map object
866 * @param key Key (copied) of integer value to insert
867 * @param val Integer value to insert, associated with the
869 * @returns One of #bt_object_status values
871 extern enum bt_object_status
bt_object_map_insert_integer(
872 struct bt_object
*map_obj
, const char *key
, int64_t val
);
875 * Inserts the floating point number value \p val associated with the
876 * key \p key into the map object \p map_obj. This is a convenience
877 * function which creates the underlying floating point number object
878 * before inserting it.
882 * The created floating point number object's reference count is
885 * @param map_obj Map object
886 * @param key Key (copied) of floating point number value to
888 * @param val Floating point number value to insert,
889 * associated with the key \p key
890 * @returns One of #bt_object_status values
892 extern enum bt_object_status
bt_object_map_insert_float(
893 struct bt_object
*map_obj
, const char *key
, double val
);
896 * Inserts the string value \p val associated with the key \p key into
897 * the map object \p map_obj. This is a convenience function which
898 * creates the underlying string object before inserting it.
900 * \p val and \p key are copied.
902 * The created string object's reference count is set to 1.
904 * @param map_obj Map object
905 * @param key Key (copied) of string value to insert
906 * @param val String value to insert, associated with the
908 * @returns One of #bt_object_status values
910 extern enum bt_object_status
bt_object_map_insert_string(
911 struct bt_object
*map_obj
, const char *key
, const char *val
);
914 * Inserts an empty array object associated with the key \p key into
915 * the map object \p map_obj. This is a convenience function which
916 * creates the underlying array object before inserting it.
920 * The created array object's reference count is set to 1.
922 * @param map_obj Map object
923 * @param key Key (copied) of empty array to insert
924 * @returns One of #bt_object_status values
926 extern enum bt_object_status
bt_object_map_insert_array(
927 struct bt_object
*map_obj
, const char *key
);
930 * Inserts an empty map object associated with the key \p key into
931 * the map object \p map_obj. This is a convenience function which
932 * creates the underlying map object before inserting it.
936 * The created map object's reference count is set to 1.
938 * @param map_obj Map object
939 * @param key Key (copied) of empty map to insert
940 * @returns One of #bt_object_status values
942 extern enum bt_object_status
bt_object_map_insert_map(
943 struct bt_object
*map_obj
, const char *key
);
946 * Creates a deep copy of the object \p object.
948 * The created object's reference count is set to 1, unless
949 * \p object is a null object.
951 * @param object Object to copy
952 * @returns Deep copy of \p object on success, or \c NULL
955 extern struct bt_object
*bt_object_copy(const struct bt_object
*object
);
958 * Compares the objects \p object_a and \p object_b and returns \c true
959 * if they have the same content.
961 * @param object_a Object A
962 * @param object_B Object B
963 * @returns \c true if \p object_a and \p object_b have the
964 * same content, or \c false if they differ or on
967 extern bool bt_object_compare(const struct bt_object
*object_a
,
968 const struct bt_object
*object_b
);
974 #endif /* _BABELTRACE_OBJECTS_H */