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);
86 * Another common manipulation is to move the ownership of an object
87 * from one variable to another: since the reference count is not
88 * incremented, and since, to avoid errors, two variables should not
89 * point to same object without each of them having their own reference,
90 * it is best practice to set the original variable to \c NULL. This
91 * too can be accomplished in a single step using the BT_OBJECT_MOVE()
95 * struct bt_object *int_obj2 = NULL;
96 * struct bt_object *int_obj = bt_object_integer_create_init(-23);
102 * // stuff, which could jump to error
104 * BT_OBJECT_MOVE(int_obj2, int_obj);
106 * // stuff, which could jump to error
111 * // safe, since only one of int_obj/int_obj2 (or none)
112 * // points to the object
113 * BT_OBJECT_PUT(int_obj);
114 * BT_OBJECT_PUT(int_obj2);
117 * You can create a deep copy of any object using the bt_object_copy()
118 * function. You can compare two given objects using
119 * bt_object_compare().
121 * @author Philippe Proulx <pproulx@efficios.com>
136 enum bt_object_type
{
137 /** Unknown object, used as an error code. */
138 BT_OBJECT_TYPE_UNKNOWN
= -1,
141 BT_OBJECT_TYPE_NULL
= 0,
143 /** Boolean object (holds \c true or \c false). */
144 BT_OBJECT_TYPE_BOOL
= 1,
146 /** Integer (holds a signed 64-bit integer value). */
147 BT_OBJECT_TYPE_INTEGER
= 2,
150 * Floating point number object (holds a \c double value).
152 BT_OBJECT_TYPE_FLOAT
= 3,
154 /** String object. */
155 BT_OBJECT_TYPE_STRING
= 4,
158 BT_OBJECT_TYPE_ARRAY
= 5,
161 BT_OBJECT_TYPE_MAP
= 6,
165 * Status (return value of some functions).
167 enum bt_object_status
{
168 /** Operation cancelled. */
169 BT_OBJECT_STATUS_CANCELLED
= -2,
172 BT_OBJECT_STATUS_ERROR
= -1,
174 /** Okay, no error. */
175 BT_OBJECT_STATUS_OK
= 0,
184 * The null object singleton.
186 * Use this everytime you need a null objet. The null objet singleton
187 * has no reference count; there's only one. You may compare any object
188 * to the null singleton to find out if it's a null object, or otherwise
189 * use bt_object_is_null().
191 * Functions of this API return this when the object is actually a
192 * null object (of type \link bt_object_type::BT_OBJECT_TYPE_NULL
193 * <code>BT_OBJECT_TYPE_NULL</code>\endlink), whereas \c NULL means an error
196 extern struct bt_object
*bt_object_null
;
199 * User function type for bt_object_map_foreach().
201 * \p object is a \em weak reference; you must pass it to
202 * bt_object_get() to get your own reference.
204 * Return \c true to continue the loop, or \c false to break it.
206 * @param key Key of map entry
207 * @param object Object of map entry (weak reference)
208 * @param data User data
209 * @returns \c true to continue the loop
211 typedef bool (* bt_object_map_foreach_cb
)(const char *key
,
212 struct bt_object
*object
, void *data
);
215 * Puts the object \p _object (calls bt_object_put() on it), and resets
216 * the variable to \c NULL.
218 * This is something that is often done when putting and object;
219 * resetting the variable to \c NULL makes sure it cannot be put a
222 * @param _object Object to put
224 * @see BT_OBJECT_MOVE() (moves an object from one variable to the other
225 * without putting it)
227 #define BT_OBJECT_PUT(_object) \
229 bt_object_put(_object); \
234 * Moves the object referenced by the variable \p _src_object to the
235 * \p _dst_object variable, then resets \p _src_object to \c NULL.
237 * The object's reference count is <b>not changed</b>. Resetting
238 * \p _src_object to \c NULL ensures the object will not be put
239 * twice later; its ownership is indeed \em moved from the source
240 * variable to the destination variable.
242 * @param _src_object Source object variable
243 * @param _dst_object Destination object variable
245 #define BT_OBJECT_MOVE(_dst_object, _src_object) \
247 (_dst_object) = (_src_object); \
248 (_src_object) = NULL; \
252 * Increments the reference count of \p object.
254 * @param object Object of which to increment the reference count
256 extern void bt_object_get(struct bt_object
*object
);
259 * Decrements the reference count of \p object, destroying it when this
262 * @param object Object of which to decrement the reference count
264 * @see BT_OBJECT_PUT() (puts an object and resets the variable to
267 extern void bt_object_put(struct bt_object
*object
);
270 * Returns the type of \p object.
272 * @param object Object of which to get the type
273 * @returns Object's type, or
274 * \link bt_object_type::BT_OBJECT_TYPE_NULL
275 * <code>BT_OBJECT_TYPE_UNKNOWN</code>\endlink
278 * @see enum bt_object_type (object types)
280 extern enum bt_object_type
bt_object_get_type(const struct bt_object
*object
);
283 * Checks whether \p object is a null object. The only valid null
284 * object is \ref bt_object_null.
286 * @param object Object to check
287 * @returns \c true if \p object is a null object
290 bool bt_object_is_null(const struct bt_object
*object
)
292 return bt_object_get_type(object
) == BT_OBJECT_TYPE_NULL
;
296 * Checks whether \p object is a boolean object.
298 * @param object Object to check
299 * @returns \c true if \p object is a boolean object
302 bool bt_object_is_bool(const struct bt_object
*object
)
304 return bt_object_get_type(object
) == BT_OBJECT_TYPE_BOOL
;
308 * Checks whether \p object is an integer object.
310 * @param object Object to check
311 * @returns \c true if \p object is an integer object
314 bool bt_object_is_integer(const struct bt_object
*object
)
316 return bt_object_get_type(object
) == BT_OBJECT_TYPE_INTEGER
;
320 * Checks whether \p object is a floating point number object.
322 * @param object Object to check
323 * @returns \c true if \p object is a floating point number object
326 bool bt_object_is_float(const struct bt_object
*object
)
328 return bt_object_get_type(object
) == BT_OBJECT_TYPE_FLOAT
;
332 * Checks whether \p object is a string object.
334 * @param object Object to check
335 * @returns \c true if \p object is a string object
338 bool bt_object_is_string(const struct bt_object
*object
)
340 return bt_object_get_type(object
) == BT_OBJECT_TYPE_STRING
;
344 * Checks whether \p object is an array object.
346 * @param object Object to check
347 * @returns \c true if \p object is an array object
350 bool bt_object_is_array(const struct bt_object
*object
)
352 return bt_object_get_type(object
) == BT_OBJECT_TYPE_ARRAY
;
356 * Checks whether \p object is a map object.
358 * @param object Object to check
359 * @returns \c true if \p object is a map object
362 bool bt_object_is_map(const struct bt_object
*object
)
364 return bt_object_get_type(object
) == BT_OBJECT_TYPE_MAP
;
368 * Creates a boolean object. The created boolean object's initial value
371 * The created object's reference count is set to 1.
373 * @returns Created object on success, or \c NULL on error
375 extern struct bt_object
*bt_object_bool_create(void);
378 * Creates a boolean object with its initial value set to \p val.
380 * The created object's reference count is set to 1.
382 * @param val Initial value
383 * @returns Created object on success, or \c NULL on error
385 extern struct bt_object
*bt_object_bool_create_init(bool val
);
388 * Creates an integer object. The created integer object's initial value
391 * The created object's reference count is set to 1.
393 * @returns Created object on success, or \c NULL on error
395 extern struct bt_object
*bt_object_integer_create(void);
398 * Creates an integer object with its initial value set to \p val.
400 * The created object's reference count is set to 1.
402 * @param val Initial value
403 * @returns Created object on success, or \c NULL on error
405 extern struct bt_object
*bt_object_integer_create_init(int64_t val
);
408 * Creates a floating point number object. The created floating point
409 * number object's initial value is 0.
411 * The created object's reference count is set to 1.
413 * @returns Created object on success, or \c NULL on error
415 extern struct bt_object
*bt_object_float_create(void);
418 * Creates a floating point number object with its initial value set
421 * The created object's reference count is set to 1.
423 * @param val Initial value
424 * @returns Created object on success, or \c NULL on error
426 extern struct bt_object
*bt_object_float_create_init(double val
);
429 * Creates a string object. The string object is initially empty.
431 * The created object's reference count is set to 1.
433 * @returns Created object on success, or \c NULL on error
435 extern struct bt_object
*bt_object_string_create(void);
438 * Creates a string object with its initial value set to \p val.
442 * The created object's reference count is set to 1.
444 * @param val Initial value (will be copied)
445 * @returns Created object on success, or \c NULL on error
447 extern struct bt_object
*bt_object_string_create_init(const char *val
);
450 * Creates an empty array object.
452 * The created object's reference count is set to 1.
454 * @returns Created object on success, or \c NULL on error
456 extern struct bt_object
*bt_object_array_create(void);
459 * Creates an empty map object.
461 * The created object's reference count is set to 1.
463 * @returns Created object on success, or \c NULL on error
465 extern struct bt_object
*bt_object_map_create(void);
468 * Gets the boolean value of the boolean objet \p bool_obj.
470 * @param bool_obj Boolean object
471 * @param val Returned boolean value
472 * @returns 0 on success, negative value on error
474 extern int bt_object_bool_get(const struct bt_object
*bool_obj
, bool *val
);
477 * Sets the boolean value of the boolean object \p bool_obj to \p val.
479 * @param bool_obj Boolean object
480 * @param val New boolean value
481 * @returns 0 on success, negative value on error
483 extern int bt_object_bool_set(struct bt_object
*bool_obj
, bool val
);
486 * Gets the integer value of the integer objet \p integer_obj.
488 * @param integer_obj Integer object
489 * @param val Returned integer value
490 * @returns 0 on success, negative value on error
492 extern int bt_object_integer_get(const struct bt_object
*integer_obj
,
496 * Sets the integer value of the integer object \p integer_obj to
499 * @param integer_obj Integer object
500 * @param val New integer value
501 * @returns 0 on success, negative value on error
503 extern int bt_object_integer_set(struct bt_object
*integer_obj
, int64_t val
);
506 * Gets the floating point number value of the floating point number
507 * objet \p float_obj.
509 * @param float_obj Floating point number object
510 * @param val Returned floating point number value
511 * @returns 0 on success, negative value on error
513 extern int bt_object_float_get(const struct bt_object
*float_obj
, double *val
);
516 * Sets the floating point number value of the floating point number
517 * object \p float_obj to \p val.
519 * @param float_obj Floating point number object
520 * @param val New floating point number value
521 * @returns 0 on success, negative value on error
523 extern int bt_object_float_set(struct bt_object
*float_obj
, double val
);
526 * Gets the string value of the string objet \p string_obj. The
527 * returned string is valid as long as this object exists and is not
530 * @param string_obj String object
531 * @returns String value, or \c NULL on error
533 extern const char *bt_object_string_get(const struct bt_object
*string_obj
);
536 * Sets the string value of the string object \p string_obj to
541 * @param string_obj String object
542 * @param val New string value (copied)
543 * @returns 0 on success, negative value on error
545 extern int bt_object_string_set(struct bt_object
*string_obj
, const char *val
);
548 * Gets the size of the array object \p array_obj, that is, the number
549 * of elements contained in \p array_obj.
551 * @param array_obj Array object
552 * @returns Array size, or a negative value on error
554 extern int bt_object_array_size(const struct bt_object
*array_obj
);
557 * Returns \c true if the array object \p array_obj.
559 * @param array_obj Array object
560 * @returns \c true if \p array_obj is empty
562 extern bool bt_object_array_is_empty(const struct bt_object
*array_obj
);
565 * Gets the element object of the array object \p array_obj at the
568 * The returned object's reference count is incremented, unless it's
571 * @param array_obj Array object
572 * @param index Index of element to get
573 * @returns Element object at index \p index on success,
574 * or \c NULL on error
576 extern struct bt_object
*bt_object_array_get(const struct bt_object
*array_obj
,
580 * Appends the element object \p element_obj to the array object
583 * The appended object's reference count is incremented, unless it's
586 * @param array_obj Array object
587 * @param element_obj Element object to append
588 * @returns 0 on success, or a negative value on error
590 extern int bt_object_array_append(struct bt_object
*array_obj
,
591 struct bt_object
*element_obj
);
594 * Appends the boolean value \p val to the array object \p array_obj.
595 * This is a convenience function which creates the underlying boolean
596 * object before appending it.
598 * The created boolean object's reference count is set to 1.
600 * @param array_obj Array object
601 * @param val Boolean value to append
602 * @returns 0 on success, or a negative value on error
604 extern int bt_object_array_append_bool(struct bt_object
*array_obj
, bool val
);
607 * Appends the integer value \p val to the array object \p array_obj.
608 * This is a convenience function which creates the underlying integer
609 * object before appending it.
611 * The created integer object's reference count is set to 1.
613 * @param array_obj Array object
614 * @param val Integer value to append
615 * @returns 0 on success, or a negative value on error
617 extern int bt_object_array_append_integer(struct bt_object
*array_obj
,
621 * Appends the floating point number value \p val to the array object
622 * \p array_obj. This is a convenience function which creates the
623 * underlying floating point number object before appending it.
625 * The created floating point number object's reference count is
628 * @param array_obj Array object
629 * @param val Floating point number value to append
630 * @returns 0 on success, or a negative value on error
632 extern int bt_object_array_append_float(struct bt_object
*array_obj
,
636 * Appends the string value \p val to the array object \p array_obj.
637 * This is a convenience function which creates the underlying string
638 * object before appending it.
642 * The created string object's reference count is set to 1.
644 * @param array_obj Array object
645 * @param val String value to append (copied)
646 * @returns 0 on success, or a negative value on error
648 extern int bt_object_array_append_string(struct bt_object
*array_obj
,
652 * Appends an empty array object to the array object \p array_obj.
653 * This is a convenience function which creates the underlying array
654 * object before appending it.
656 * The created array object's reference count is set to 1.
658 * @param array_obj Array object
659 * @returns 0 on success, or a negative value on error
661 extern int bt_object_array_append_array(struct bt_object
*array_obj
);
664 * Appends an empty map object to the array object \p array_obj. This
665 * is a convenience function which creates the underlying map object
666 * before appending it.
668 * The created map object's reference count is set to 1.
670 * @param array_obj Array object
671 * @returns 0 on success, or a negative value on error
673 extern int bt_object_array_append_map(struct bt_object
*array_obj
);
676 * Replaces the element object at index \p index of the array object
677 * \p array_obj by \p element_obj.
679 * The replaced object's reference count is decremented, unless it's
680 * a null object. The reference count of \p element_obj is incremented,
681 * unless it's a null object.
683 * @param array_obj Array object
684 * @param index Index of element object to replace
685 * @param element_obj New element object at position \p index of
687 * @returns 0 on success, or a negative value on error
689 extern int bt_object_array_set(struct bt_object
*array_obj
, size_t index
,
690 struct bt_object
*element_obj
);
693 * Gets the size of a map object, that is, the number of elements
694 * contained in a map object.
696 * @param map_obj Map object
697 * @returns Map size, or a negative value on error
699 extern int bt_object_map_size(const struct bt_object
*map_obj
);
702 * Returns \c true if the map object \p map_obj.
704 * @param map_obj Map object
705 * @returns \c true if \p map_obj is empty
707 extern bool bt_object_map_is_empty(const struct bt_object
*map_obj
);
710 * Gets the element object associated with the key \p key within the
711 * map object \p map_obj.
713 * The returned object's reference count is incremented, unless it's
716 * @param map_obj Map object
717 * @param key Key of the element to get
718 * @returns Element object associated with the key \p key
719 * on success, or \c NULL on error
721 extern struct bt_object
*bt_object_map_get(const struct bt_object
*map_obj
,
725 * Calls a provided user function \p cb for each element of the map
728 * The object passed to the user function is a <b>weak reference</b>:
729 * you must call bt_object_get() on it to obtain your own reference.
731 * The key passed to the user function is only valid in the scope of
732 * this user function.
734 * The user function must return \c true to continue the loop, or
735 * \c false to break it.
737 * @param map_obj Map object
738 * @param cb User function to call back
739 * @param data User data passed to the user function
740 * @returns \link bt_object_status::BT_OBJECT_STATUS_OK
741 * <code>BT_OBJECT_STATUS_OK</code>\endlink if
742 * there's no error and the traversal was not
743 * cancelled by the user function,
744 * \link bt_object_status::BT_OBJECT_STATUS_CANCELLED
745 * <code>BT_OBJECT_STATUS_CANCELLED</code>\endlink
746 * if the function was cancelled by the user
748 * \link bt_object_status::BT_OBJECT_STATUS_ERROR
749 * <code>BT_OBJECT_STATUS_ERROR</code>\endlink on
752 extern enum bt_object_status
bt_object_map_foreach(
753 const struct bt_object
*map_obj
, bt_object_map_foreach_cb cb
,
757 * Returns whether or not the map object \p map_obj contains the
760 * @param map_obj Map object
761 * @param key Key to check
762 * @returns \c true if \p map_obj contains the key \p key,
763 * or \c false if it doesn't have \p key or
766 extern bool bt_object_map_has_key(const struct bt_object
*map_obj
,
770 * Inserts the element object \p element_obj associated with the key
771 * \p key into the map object \p map_obj. If \p key exists in
772 * \p map_obj, the associated element object is first put, and then
773 * replaced by \p element_obj.
777 * The inserted object's reference count is incremented, unless it's
780 * @param map_obj Map object
781 * @param key Key (copied) of object to insert
782 * @param element_obj Element object to insert, associated with the
784 * @returns 0 on success, or a negative value on error
786 extern int bt_object_map_insert(struct bt_object
*map_obj
,
787 const char *key
, struct bt_object
*element_obj
);
790 * Inserts the boolean value \p val associated with the key \p key into
791 * the map object \p map_obj. This is a convenience function which
792 * creates the underlying boolean object before inserting it.
796 * The created boolean object's reference count is set to 1.
798 * @param map_obj Map object
799 * @param key Key (copied) of boolean value to insert
800 * @param val Boolean value to insert, associated with the
802 * @returns 0 on success, or a negative value on error
804 extern int bt_object_map_insert_bool(struct bt_object
*map_obj
,
805 const char *key
, bool val
);
808 * Inserts the integer value \p val associated with the key \p key into
809 * the map object \p map_obj. This is a convenience function which
810 * creates the underlying integer object before inserting it.
814 * The created integer object's reference count is set to 1.
816 * @param map_obj Map object
817 * @param key Key (copied) of integer value to insert
818 * @param val Integer value to insert, associated with the
820 * @returns 0 on success, or a negative value on error
822 extern int bt_object_map_insert_integer(struct bt_object
*map_obj
,
823 const char *key
, int64_t val
);
826 * Inserts the floating point number value \p val associated with the
827 * key \p key into the map object \p map_obj. This is a convenience
828 * function which creates the underlying floating point number object
829 * before inserting it.
833 * The created floating point number object's reference count is
836 * @param map_obj Map object
837 * @param key Key (copied) of floating point number value to
839 * @param val Floating point number value to insert,
840 * associated with the key \p key
841 * @returns 0 on success, or a negative value on error
843 extern int bt_object_map_insert_float(struct bt_object
*map_obj
,
844 const char *key
, double val
);
847 * Inserts the string value \p val associated with the key \p key into
848 * the map object \p map_obj. This is a convenience function which
849 * creates the underlying string object before inserting it.
851 * \p val and \p key are copied.
853 * The created string object's reference count is set to 1.
855 * @param map_obj Map object
856 * @param key Key (copied) of string value to insert
857 * @param val String value to insert, associated with the
859 * @returns 0 on success, or a negative value on error
861 extern int bt_object_map_insert_string(struct bt_object
*map_obj
,
862 const char *key
, const char *val
);
865 * Inserts an empty array object associated with the key \p key into
866 * the map object \p map_obj. This is a convenience function which
867 * creates the underlying array object before inserting it.
871 * The created array object's reference count is set to 1.
873 * @param map_obj Map object
874 * @param key Key (copied) of empty array to insert
875 * @returns 0 on success, or a negative value on error
877 extern int bt_object_map_insert_array(struct bt_object
*map_obj
,
881 * Inserts an empty map object associated with the key \p key into
882 * the map object \p map_obj. This is a convenience function which
883 * creates the underlying map object before inserting it.
887 * The created map object's reference count is set to 1.
889 * @param map_obj Map object
890 * @param key Key (copied) of empty map to insert
891 * @returns 0 on success, or a negative value on error
893 extern int bt_object_map_insert_map(struct bt_object
*map_obj
,
897 * Creates a deep copy of the object \p object.
899 * The created object's reference count is set to 1, unless
900 * \p object is a null object.
902 * @param object Object to copy
903 * @returns Deep copy of \p object on success, or \c NULL
906 extern struct bt_object
*bt_object_copy(const struct bt_object
*object
);
909 * Compares the objects \p object_a and \p object_b and returns \c true
910 * if they have the same content.
912 * @param object_a Object A
913 * @param object_B Object B
914 * @returns \c true if \p object_a and \p object_b have the
915 * same content, or \c false if they differ or on
918 extern bool bt_object_compare(const struct bt_object
*object_a
,
919 const struct bt_object
*object_b
);
925 #endif /* _BABELTRACE_OBJECTS_H */