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 object (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.
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().
211 * The null object singleton is always frozen (see bt_object_freeze()
212 * and bt_object_is_frozen()).
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.
218 extern struct bt_object
*bt_object_null
;
221 * User function type for bt_object_map_foreach().
223 * \p object is a \em weak reference; you must pass it to
224 * bt_object_get() to get your own reference.
226 * Return \c true to continue the loop, or \c false to break it.
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
233 typedef bool (* bt_object_map_foreach_cb
)(const char *key
,
234 struct bt_object
*object
, void *data
);
237 * Puts the object \p _object (calls bt_object_put() on it), and resets
238 * the variable to \c NULL.
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
244 * @param _object Object to put
246 * @see BT_OBJECT_MOVE() (moves an object from one variable to the other
247 * without putting it)
249 #define BT_OBJECT_PUT(_object) \
251 bt_object_put(_object); \
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.
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.
264 * @param _src_object Source object variable
265 * @param _dst_object Destination object variable
267 #define BT_OBJECT_MOVE(_dst_object, _src_object) \
269 (_dst_object) = (_src_object); \
270 (_src_object) = NULL; \
274 * Increments the reference count of \p object.
276 * @param object Object of which to increment the reference count
278 * @see bt_object_put()
280 extern void bt_object_get(struct bt_object
*object
);
283 * Decrements the reference count of \p object, destroying it when this
286 * @param object Object of which to decrement the reference count
288 * @see BT_OBJECT_PUT() (puts an object and resets the variable to
290 * @see bt_object_get()
292 extern void bt_object_put(struct bt_object
*object
);
295 * Recursively freezes the object \p object.
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().
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)
307 * @see bt_object_is_frozen()
309 extern enum bt_object_status
bt_object_freeze(struct bt_object
*object
);
312 * Checks whether \p object is frozen or not.
314 * @param object Object to check
315 * @returns \c true if \p object is frozen
317 * @see bt_object_freeze()
319 extern bool bt_object_is_frozen(const struct bt_object
*object
);
322 * Returns the type of \p object.
324 * @param object Object of which to get the type
325 * @returns Object's type, or #BT_OBJECT_TYPE_UNKNOWN
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()
337 extern enum bt_object_type
bt_object_get_type(const struct bt_object
*object
);
340 * Checks whether \p object is a null object. The only valid null
341 * object is \ref bt_object_null.
343 * @param object Object to check
344 * @returns \c true if \p object is a null object
346 * @see bt_object_get_type()
349 bool bt_object_is_null(const struct bt_object
*object
)
351 return bt_object_get_type(object
) == BT_OBJECT_TYPE_NULL
;
355 * Checks whether \p object is a boolean object.
357 * @param object Object to check
358 * @returns \c true if \p object is a boolean object
360 * @see bt_object_get_type()
363 bool bt_object_is_bool(const struct bt_object
*object
)
365 return bt_object_get_type(object
) == BT_OBJECT_TYPE_BOOL
;
369 * Checks whether \p object is an integer object.
371 * @param object Object to check
372 * @returns \c true if \p object is an integer object
374 * @see bt_object_get_type()
377 bool bt_object_is_integer(const struct bt_object
*object
)
379 return bt_object_get_type(object
) == BT_OBJECT_TYPE_INTEGER
;
383 * Checks whether \p object is a floating point number object.
385 * @param object Object to check
386 * @returns \c true if \p object is a floating point
389 * @see bt_object_get_type()
392 bool bt_object_is_float(const struct bt_object
*object
)
394 return bt_object_get_type(object
) == BT_OBJECT_TYPE_FLOAT
;
398 * Checks whether \p object is a string object.
400 * @param object Object to check
401 * @returns \c true if \p object is a string object
403 * @see bt_object_get_type()
406 bool bt_object_is_string(const struct bt_object
*object
)
408 return bt_object_get_type(object
) == BT_OBJECT_TYPE_STRING
;
412 * Checks whether \p object is an array object.
414 * @param object Object to check
415 * @returns \c true if \p object is an array object
417 * @see bt_object_get_type()
420 bool bt_object_is_array(const struct bt_object
*object
)
422 return bt_object_get_type(object
) == BT_OBJECT_TYPE_ARRAY
;
426 * Checks whether \p object is a map object.
428 * @param object Object to check
429 * @returns \c true if \p object is a map object
431 * @see bt_object_get_type()
434 bool bt_object_is_map(const struct bt_object
*object
)
436 return bt_object_get_type(object
) == BT_OBJECT_TYPE_MAP
;
440 * Creates a boolean object. The created boolean object's initial value
443 * The created object's reference count is set to 1.
445 * @returns Created object on success, or \c NULL on error
447 * @see bt_object_bool_create_init() (creates an initialized
450 extern struct bt_object
*bt_object_bool_create(void);
453 * Creates a boolean object with its initial value set to \p val.
455 * The created object's reference count is set to 1.
457 * @param val Initial value
458 * @returns Created object on success, or \c NULL on error
460 extern struct bt_object
*bt_object_bool_create_init(bool val
);
463 * Creates an integer object. The created integer object's initial value
466 * The created object's reference count is set to 1.
468 * @returns Created object on success, or \c NULL on error
470 * @see bt_object_integer_create_init() (creates an initialized
473 extern struct bt_object
*bt_object_integer_create(void);
476 * Creates an integer object with its initial value set to \p val.
478 * The created object's reference count is set to 1.
480 * @param val Initial value
481 * @returns Created object on success, or \c NULL on error
483 extern struct bt_object
*bt_object_integer_create_init(int64_t val
);
486 * Creates a floating point number object. The created floating point
487 * number object's initial value is 0.
489 * The created object's reference count is set to 1.
491 * @returns Created object on success, or \c NULL on error
493 * @see bt_object_float_create_init() (creates an initialized floating
494 * point number object)
496 extern struct bt_object
*bt_object_float_create(void);
499 * Creates a floating point number object with its initial value set
502 * The created object's reference count is set to 1.
504 * @param val Initial value
505 * @returns Created object on success, or \c NULL on error
507 extern struct bt_object
*bt_object_float_create_init(double val
);
510 * Creates a string object. The string object is initially empty.
512 * The created object's reference count is set to 1.
514 * @returns Created object on success, or \c NULL on error
516 * @see bt_object_string_create_init() (creates an initialized
519 extern struct bt_object
*bt_object_string_create(void);
522 * Creates a string object with its initial value set to \p val.
526 * The created object's reference count is set to 1.
528 * @param val Initial value (will be copied)
529 * @returns Created object on success, or \c NULL on error
531 extern struct bt_object
*bt_object_string_create_init(const char *val
);
534 * Creates an empty array object.
536 * The created object's reference count is set to 1.
538 * @returns Created object on success, or \c NULL on error
540 extern struct bt_object
*bt_object_array_create(void);
543 * Creates an empty map object.
545 * The created object's reference count is set to 1.
547 * @returns Created object on success, or \c NULL on error
549 extern struct bt_object
*bt_object_map_create(void);
552 * Gets the boolean value of the boolean object \p bool_obj.
554 * @param bool_obj Boolean object
555 * @param val Returned boolean value
556 * @returns One of #bt_object_status values
558 * @see bt_object_bool_set()
560 extern enum bt_object_status
bt_object_bool_get(
561 const struct bt_object
*bool_obj
, bool *val
);
564 * Sets the boolean value of the boolean object \p bool_obj to \p val.
566 * @param bool_obj Boolean object
567 * @param val New boolean value
568 * @returns One of #bt_object_status values
570 * @see bt_object_bool_get()
572 extern enum bt_object_status
bt_object_bool_set(struct bt_object
*bool_obj
,
576 * Gets the integer value of the integer object \p integer_obj.
578 * @param integer_obj Integer object
579 * @param val Returned integer value
580 * @returns One of #bt_object_status values
582 * @see bt_object_integer_set()
584 extern enum bt_object_status
bt_object_integer_get(
585 const struct bt_object
*integer_obj
, int64_t *val
);
588 * Sets the integer value of the integer object \p integer_obj to
591 * @param integer_obj Integer object
592 * @param val New integer value
593 * @returns One of #bt_object_status values
595 * @see bt_object_integer_get()
597 extern enum bt_object_status
bt_object_integer_set(
598 struct bt_object
*integer_obj
, int64_t val
);
601 * Gets the floating point number value of the floating point number
602 * object \p float_obj.
604 * @param float_obj Floating point number object
605 * @param val Returned floating point number value
606 * @returns One of #bt_object_status values
608 * @see bt_object_float_set()
610 extern enum bt_object_status
bt_object_float_get(
611 const struct bt_object
*float_obj
, double *val
);
614 * Sets the floating point number value of the floating point number
615 * object \p float_obj to \p val.
617 * @param float_obj Floating point number object
618 * @param val New floating point number value
619 * @returns One of #bt_object_status values
621 * @see bt_object_float_get()
623 extern enum bt_object_status
bt_object_float_set(
624 struct bt_object
*float_obj
, double val
);
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.
632 * @param string_obj String object
633 * @param val Returned string value
634 * @returns One of #bt_object_status values
636 * @see bt_object_string_set()
638 extern enum bt_object_status
bt_object_string_get(
639 const struct bt_object
*string_obj
, const char **val
);
642 * Sets the string value of the string object \p string_obj to
647 * @param string_obj String object
648 * @param val New string value (copied)
649 * @returns One of #bt_object_status values
651 * @see bt_object_string_get()
653 extern enum bt_object_status
bt_object_string_set(struct bt_object
*string_obj
,
657 * Gets the size of the array object \p array_obj, that is, the number
658 * of elements contained in \p array_obj.
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
665 * @see bt_object_array_is_empty()
667 extern int bt_object_array_size(const struct bt_object
*array_obj
);
670 * Returns \c true if the array object \p array_obj.
672 * @param array_obj Array object
673 * @returns \c true if \p array_obj is empty
675 * @see bt_object_array_size()
677 extern bool bt_object_array_is_empty(const struct bt_object
*array_obj
);
680 * Gets the element object of the array object \p array_obj at the
683 * The returned object's reference count is incremented, unless it's
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
691 extern struct bt_object
*bt_object_array_get(const struct bt_object
*array_obj
,
695 * Appends the element object \p element_obj to the array object
698 * The appended object's reference count is incremented, unless it's
701 * @param array_obj Array object
702 * @param element_obj Element object to append
703 * @returns One of #bt_object_status values
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()
712 extern enum bt_object_status
bt_object_array_append(struct bt_object
*array_obj
,
713 struct bt_object
*element_obj
);
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.
720 * The created boolean object's reference count is set to 1.
722 * @param array_obj Array object
723 * @param val Boolean value to append
724 * @returns One of #bt_object_status values
726 * @see bt_object_array_append()
728 extern enum bt_object_status
bt_object_array_append_bool(
729 struct bt_object
*array_obj
, bool val
);
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.
736 * The created integer object's reference count is set to 1.
738 * @param array_obj Array object
739 * @param val Integer value to append
740 * @returns One of #bt_object_status values
742 * @see bt_object_array_append()
744 extern enum bt_object_status
bt_object_array_append_integer(
745 struct bt_object
*array_obj
, int64_t val
);
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.
752 * The created floating point number object's reference count is
755 * @param array_obj Array object
756 * @param val Floating point number value to append
757 * @returns One of #bt_object_status values
759 * @see bt_object_array_append()
761 extern enum bt_object_status
bt_object_array_append_float(
762 struct bt_object
*array_obj
, double val
);
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.
771 * The created string object's reference count is set to 1.
773 * @param array_obj Array object
774 * @param val String value to append (copied)
775 * @returns One of #bt_object_status values
777 * @see bt_object_array_append()
779 extern enum bt_object_status
bt_object_array_append_string(
780 struct bt_object
*array_obj
, const char *val
);
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.
787 * The created array object's reference count is set to 1.
789 * @param array_obj Array object
790 * @returns One of #bt_object_status values
792 * @see bt_object_array_append()
794 extern enum bt_object_status
bt_object_array_append_array(
795 struct bt_object
*array_obj
);
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.
802 * The created map object's reference count is set to 1.
804 * @param array_obj Array object
805 * @returns One of #bt_object_status values
807 * @see bt_object_array_append()
809 extern enum bt_object_status
bt_object_array_append_map(
810 struct bt_object
*array_obj
);
813 * Replaces the element object at index \p index of the array object
814 * \p array_obj by \p element_obj.
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.
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
824 * @returns One of #bt_object_status values
826 extern enum bt_object_status
bt_object_array_set(struct bt_object
*array_obj
,
827 size_t index
, struct bt_object
*element_obj
);
830 * Gets the size of a map object, that is, the number of elements
831 * contained in a map object.
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
838 * @see bt_object_map_is_empty()
840 extern int bt_object_map_size(const struct bt_object
*map_obj
);
843 * Returns \c true if the map object \p map_obj.
845 * @param map_obj Map object
846 * @returns \c true if \p map_obj is empty
848 * @see bt_object_map_size()
850 extern bool bt_object_map_is_empty(const struct bt_object
*map_obj
);
853 * Gets the element object associated with the key \p key within the
854 * map object \p map_obj.
856 * The returned object's reference count is incremented, unless it's
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
864 extern struct bt_object
*bt_object_map_get(const struct bt_object
*map_obj
,
868 * Calls a provided user function \p cb for each element of the map
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.
874 * The key passed to the user function is only valid in the scope of
875 * this user function.
877 * The user function must return \c true to continue the loop, or
878 * \c false to break it.
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
888 extern enum bt_object_status
bt_object_map_foreach(
889 const struct bt_object
*map_obj
, bt_object_map_foreach_cb cb
,
893 * Returns whether or not the map object \p map_obj contains the
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
902 extern bool bt_object_map_has_key(const struct bt_object
*map_obj
,
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.
913 * The inserted object's reference count is incremented, unless it's
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
920 * @returns One of #bt_object_status values
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()
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
);
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.
940 * The created boolean object's reference count is set to 1.
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
946 * @returns One of #bt_object_status values
948 * @see bt_object_map_insert()
950 extern enum bt_object_status
bt_object_map_insert_bool(
951 struct bt_object
*map_obj
, const char *key
, bool val
);
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.
960 * The created integer object's reference count is set to 1.
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
966 * @returns One of #bt_object_status values
968 * @see bt_object_map_insert()
970 extern enum bt_object_status
bt_object_map_insert_integer(
971 struct bt_object
*map_obj
, const char *key
, int64_t val
);
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.
981 * The created floating point number object's reference count is
984 * @param map_obj Map object
985 * @param key Key (copied) of floating point number value to
987 * @param val Floating point number value to insert,
988 * associated with the key \p key
989 * @returns One of #bt_object_status values
991 * @see bt_object_map_insert()
993 extern enum bt_object_status
bt_object_map_insert_float(
994 struct bt_object
*map_obj
, const char *key
, double val
);
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.
1001 * \p val and \p key are copied.
1003 * The created string object's reference count is set to 1.
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
1009 * @returns One of #bt_object_status values
1011 * @see bt_object_map_insert()
1013 extern enum bt_object_status
bt_object_map_insert_string(
1014 struct bt_object
*map_obj
, const char *key
, const char *val
);
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.
1023 * The created array object's reference count is set to 1.
1025 * @param map_obj Map object
1026 * @param key Key (copied) of empty array to insert
1027 * @returns One of #bt_object_status values
1029 * @see bt_object_map_insert()
1031 extern enum bt_object_status
bt_object_map_insert_array(
1032 struct bt_object
*map_obj
, const char *key
);
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.
1041 * The created map object's reference count is set to 1.
1043 * @param map_obj Map object
1044 * @param key Key (copied) of empty map to insert
1045 * @returns One of #bt_object_status values
1047 * @see bt_object_map_insert()
1049 extern enum bt_object_status
bt_object_map_insert_map(
1050 struct bt_object
*map_obj
, const char *key
);
1053 * Creates a deep copy of the object \p object.
1055 * The created object's reference count is set to 1, unless
1056 * \p object is a null object.
1058 * @param object Object to copy
1059 * @returns Deep copy of \p object on success, or \c NULL
1062 extern struct bt_object
*bt_object_copy(const struct bt_object
*object
);
1065 * Compares the objects \p object_a and \p object_b and returns \c true
1066 * if they have the same content.
1068 * @param object_a Object A
1069 * @param object_b Object B
1070 * @returns \c true if \p object_a and \p object_b have the
1071 * same content, or \c false if they differ or on
1074 extern bool bt_object_compare(const struct bt_object
*object_a
,
1075 const struct bt_object
*object_b
);
1081 #endif /* _BABELTRACE_OBJECTS_H */