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 \i 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 \i 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
289 static bool bt_object_is_null(const struct bt_object
*object
)
291 return bt_object_get_type(object
) == BT_OBJECT_TYPE_NULL
;
295 * Checks whether \p object is a boolean object.
297 * @param object Object to check
298 * @returns \c true if \p object is a boolean object
300 static bool bt_object_is_bool(const struct bt_object
*object
)
302 return bt_object_get_type(object
) == BT_OBJECT_TYPE_BOOL
;
306 * Checks whether \p object is an integer object.
308 * @param object Object to check
309 * @returns \c true if \p object is an integer object
311 static bool bt_object_is_integer(const struct bt_object
*object
)
313 return bt_object_get_type(object
) == BT_OBJECT_TYPE_INTEGER
;
317 * Checks whether \p object is a floating point number object.
319 * @param object Object to check
320 * @returns \c true if \p object is a floating point number object
322 static bool bt_object_is_float(const struct bt_object
*object
)
324 return bt_object_get_type(object
) == BT_OBJECT_TYPE_FLOAT
;
328 * Checks whether \p object is a string object.
330 * @param object Object to check
331 * @returns \c true if \p object is a string object
333 static bool bt_object_is_string(const struct bt_object
*object
)
335 return bt_object_get_type(object
) == BT_OBJECT_TYPE_STRING
;
339 * Checks whether \p object is an array object.
341 * @param object Object to check
342 * @returns \c true if \p object is an array object
344 static bool bt_object_is_array(const struct bt_object
*object
)
346 return bt_object_get_type(object
) == BT_OBJECT_TYPE_ARRAY
;
350 * Checks whether \p object is a map object.
352 * @param object Object to check
353 * @returns \c true if \p object is a map object
355 static bool bt_object_is_map(const struct bt_object
*object
)
357 return bt_object_get_type(object
) == BT_OBJECT_TYPE_MAP
;
361 * Creates a boolean object. The created boolean object's initial value
364 * The created object's reference count is set to 1.
366 * @returns Created object on success, or \c NULL on error
368 extern struct bt_object
*bt_object_bool_create(void);
371 * Creates a boolean object with its initial value set to \p val.
373 * The created object's reference count is set to 1.
375 * @param val Initial value
376 * @returns Created object on success, or \c NULL on error
378 extern struct bt_object
*bt_object_bool_create_init(bool val
);
381 * Creates an integer object. The created integer object's initial value
384 * The created object's reference count is set to 1.
386 * @returns Created object on success, or \c NULL on error
388 extern struct bt_object
*bt_object_integer_create(void);
391 * Creates an integer object with its initial value set to \p val.
393 * The created object's reference count is set to 1.
395 * @param val Initial value
396 * @returns Created object on success, or \c NULL on error
398 extern struct bt_object
*bt_object_integer_create_init(int64_t val
);
401 * Creates a floating point number object. The created floating point
402 * number object's initial value is 0.
404 * The created object's reference count is set to 1.
406 * @returns Created object on success, or \c NULL on error
408 extern struct bt_object
*bt_object_float_create(void);
411 * Creates a floating point number object with its initial value set
414 * The created object's reference count is set to 1.
416 * @param val Initial value
417 * @returns Created object on success, or \c NULL on error
419 extern struct bt_object
*bt_object_float_create_init(double val
);
422 * Creates a string object. The string object is initially empty.
424 * The created object's reference count is set to 1.
426 * @returns Created object on success, or \c NULL on error
428 extern struct bt_object
*bt_object_string_create(void);
431 * Creates a string object with its initial value set to \p val.
435 * The created object's reference count is set to 1.
437 * @param val Initial value (will be copied)
438 * @returns Created object on success, or \c NULL on error
440 extern struct bt_object
*bt_object_string_create_init(const char *val
);
443 * Creates an empty array object.
445 * The created object's reference count is set to 1.
447 * @returns Created object on success, or \c NULL on error
449 extern struct bt_object
*bt_object_array_create(void);
452 * Creates an empty map object.
454 * The created object's reference count is set to 1.
456 * @returns Created object on success, or \c NULL on error
458 extern struct bt_object
*bt_object_map_create(void);
461 * Gets the boolean value of the boolean objet \p bool_obj.
463 * @param bool_obj Boolean object
464 * @param val Returned boolean value
465 * @returns 0 on success, negative value on error
467 extern int bt_object_bool_get(const struct bt_object
*bool_obj
, bool *val
);
470 * Sets the boolean value of the boolean object \p bool_obj to \p val.
472 * @param bool_obj Boolean object
473 * @param val New boolean value
474 * @returns 0 on success, negative value on error
476 extern int bt_object_bool_set(struct bt_object
*bool_obj
, bool val
);
479 * Gets the integer value of the integer objet \p integer_obj.
481 * @param integer_obj Integer object
482 * @param val Returned integer value
483 * @returns 0 on success, negative value on error
485 extern int bt_object_integer_get(const struct bt_object
*integer_obj
,
489 * Sets the integer value of the integer object \p integer_obj to
492 * @param integer_obj Integer object
493 * @param val New integer value
494 * @returns 0 on success, negative value on error
496 extern int bt_object_integer_set(struct bt_object
*integer_obj
, int64_t val
);
499 * Gets the floating point number value of the floating point number
500 * objet \p float_obj.
502 * @param float_obj Floating point number object
503 * @param val Returned floating point number value
504 * @returns 0 on success, negative value on error
506 extern int bt_object_float_get(const struct bt_object
*float_obj
, double *val
);
509 * Sets the floating point number value of the floating point number
510 * object \p float_obj to \p val.
512 * @param float_obj Floating point number object
513 * @param val New floating point number value
514 * @returns 0 on success, negative value on error
516 extern int bt_object_float_set(struct bt_object
*float_obj
, double val
);
519 * Gets the string value of the string objet \p string_obj. The
520 * returned string is valid as long as this object exists and is not
523 * @param string_obj String object
524 * @returns String value, or \c NULL on error
526 extern const char *bt_object_string_get(const struct bt_object
*string_obj
);
529 * Sets the string value of the string object \p string_obj to
534 * @param string_obj String object
535 * @param val New string value (copied)
536 * @returns 0 on success, negative value on error
538 extern int bt_object_string_set(struct bt_object
*string_obj
, const char *val
);
541 * Gets the size of the array object \p array_obj, that is, the number
542 * of elements contained in \p array_obj.
544 * @param array_obj Array object
545 * @returns Array size, or a negative value on error
547 extern int bt_object_array_size(const struct bt_object
*array_obj
);
550 * Returns \c true if the array object \p array_obj.
552 * @param array_obj Array object
553 * @returns \c true if \p array_obj is empty
555 extern bool bt_object_array_is_empty(const struct bt_object
*array_obj
);
558 * Gets the element object of the array object \p array_obj at the
561 * The returned object's reference count is incremented, unless it's
564 * @param array_obj Array object
565 * @param index Index of element to get
566 * @returns Element object at index \p index on success,
567 * or \c NULL on error
569 extern struct bt_object
*bt_object_array_get(const struct bt_object
*array_obj
,
573 * Appends the element object \p element_obj to the array object
576 * The appended object's reference count is incremented, unless it's
579 * @param array_obj Array object
580 * @param element_obj Element object to append
581 * @returns 0 on success, or a negative value on error
583 extern int bt_object_array_append(struct bt_object
*array_obj
,
584 struct bt_object
*element_obj
);
587 * Appends the boolean value \p val to the array object \p array_obj.
588 * This is a convenience function which creates the underlying boolean
589 * object before appending it.
591 * The created boolean object's reference count is set to 1.
593 * @param array_obj Array object
594 * @param val Boolean value to append
595 * @returns 0 on success, or a negative value on error
597 extern int bt_object_array_append_bool(struct bt_object
*array_obj
, bool val
);
600 * Appends the integer value \p val to the array object \p array_obj.
601 * This is a convenience function which creates the underlying integer
602 * object before appending it.
604 * The created integer object's reference count is set to 1.
606 * @param array_obj Array object
607 * @param val Integer value to append
608 * @returns 0 on success, or a negative value on error
610 extern int bt_object_array_append_integer(struct bt_object
*array_obj
,
614 * Appends the floating point number value \p val to the array object
615 * \p array_obj. This is a convenience function which creates the
616 * underlying floating point number object before appending it.
618 * The created floating point number object's reference count is
621 * @param array_obj Array object
622 * @param val Floating point number value to append
623 * @returns 0 on success, or a negative value on error
625 extern int bt_object_array_append_float(struct bt_object
*array_obj
,
629 * Appends the string value \p val to the array object \p array_obj.
630 * This is a convenience function which creates the underlying string
631 * object before appending it.
635 * The created string object's reference count is set to 1.
637 * @param array_obj Array object
638 * @param val String value to append (copied)
639 * @returns 0 on success, or a negative value on error
641 extern int bt_object_array_append_string(struct bt_object
*array_obj
,
645 * Appends an empty array object to the array object \p array_obj.
646 * This is a convenience function which creates the underlying array
647 * object before appending it.
649 * The created array object's reference count is set to 1.
651 * @param array_obj Array object
652 * @returns 0 on success, or a negative value on error
654 extern int bt_object_array_append_array(struct bt_object
*array_obj
);
657 * Appends an empty map object to the array object \p array_obj. This
658 * is a convenience function which creates the underlying map object
659 * before appending it.
661 * The created map object's reference count is set to 1.
663 * @param array_obj Array object
664 * @returns 0 on success, or a negative value on error
666 extern int bt_object_array_append_map(struct bt_object
*array_obj
);
669 * Replaces the element object at index \p index of the array object
670 * \p array_obj by \p element_obj.
672 * The replaced object's reference count is decremented, unless it's
673 * a null object. The reference count of \p element_obj is incremented,
674 * unless it's a null object.
676 * @param array_obj Array object
677 * @param index Index of element object to replace
678 * @param element_obj New element object at position \p index of
680 * @returns 0 on success, or a negative value on error
682 extern int bt_object_array_set(struct bt_object
*array_obj
, size_t index
,
683 struct bt_object
*element_obj
);
686 * Gets the size of a map object, that is, the number of elements
687 * contained in a map object.
689 * @param map_obj Map object
690 * @returns Map size, or a negative value on error
692 extern int bt_object_map_size(const struct bt_object
*map_obj
);
695 * Returns \c true if the map object \p map_obj.
697 * @param map_obj Map object
698 * @returns \c true if \p map_obj is empty
700 extern bool bt_object_map_is_empty(const struct bt_object
*map_obj
);
703 * Gets the element object associated with the key \p key within the
704 * map object \p map_obj.
706 * The returned object's reference count is incremented, unless it's
709 * @param map_obj Map object
710 * @param key Key of the element to get
711 * @returns Element object associated with the key \p key
712 * on success, or \c NULL on error
714 extern struct bt_object
*bt_object_map_get(const struct bt_object
*map_obj
,
718 * Calls a provided user function \p cb for each element of the map
721 * The object passed to the user function is a <b>weak reference</b>:
722 * you must call bt_object_get() on it to obtain your own reference.
724 * The key passed to the user function is only valid in the scope of
725 * this user function.
727 * The user function must return \c true to continue the loop, or
728 * \c false to break it.
730 * @param map_obj Map object
731 * @param cb User function to call back
732 * @param data User data passed to the user function
733 * @returns \link bt_object_status::BT_OBJECT_STATUS_OK
734 * <code>BT_OBJECT_STATUS_OK</code>\endlink if
735 * there's no error and the traversal was not
736 * cancelled by the user function,
737 * \link bt_object_status::BT_OBJECT_STATUS_CANCELLED
738 * <code>BT_OBJECT_STATUS_CANCELLED</code>\endlink
739 * if the function was cancelled by the user
741 * \link bt_object_status::BT_OBJECT_STATUS_ERROR
742 * <code>BT_OBJECT_STATUS_ERROR</code>\endlink on
745 extern enum bt_object_status
bt_object_map_foreach(
746 const struct bt_object
*map_obj
, bt_object_map_foreach_cb cb
,
750 * Returns whether or not the map object \p map_obj contains the
753 * @param map_obj Map object
754 * @param key Key to check
755 * @returns \c true if \p map_obj contains the key \p key,
756 * or \c false if it doesn't have \p key or
759 extern bool bt_object_map_has_key(const struct bt_object
*map_obj
,
763 * Inserts the element object \p element_obj associated with the key
764 * \p key into the map object \p map_obj. If \p key exists in
765 * \p map_obj, the associated element object is first put, and then
766 * replaced by \p element_obj.
770 * The inserted object's reference count is incremented, unless it's
773 * @param map_obj Map object
774 * @param key Key (copied) of object to insert
775 * @param element_obj Element object to insert, associated with the
777 * @returns 0 on success, or a negative value on error
779 extern int bt_object_map_insert(struct bt_object
*map_obj
,
780 const char *key
, struct bt_object
*element_obj
);
783 * Inserts the boolean value \p val associated with the key \p key into
784 * the map object \p map_obj. This is a convenience function which
785 * creates the underlying boolean object before inserting it.
789 * The created boolean object's reference count is set to 1.
791 * @param map_obj Map object
792 * @param key Key (copied) of boolean value to insert
793 * @param val Boolean value to insert, associated with the
795 * @returns 0 on success, or a negative value on error
797 extern int bt_object_map_insert_bool(struct bt_object
*map_obj
,
798 const char *key
, bool val
);
801 * Inserts the integer value \p val associated with the key \p key into
802 * the map object \p map_obj. This is a convenience function which
803 * creates the underlying integer object before inserting it.
807 * The created integer object's reference count is set to 1.
809 * @param map_obj Map object
810 * @param key Key (copied) of integer value to insert
811 * @param val Integer value to insert, associated with the
813 * @returns 0 on success, or a negative value on error
815 extern int bt_object_map_insert_integer(struct bt_object
*map_obj
,
816 const char *key
, int64_t val
);
819 * Inserts the floating point number value \p val associated with the
820 * key \p key into the map object \p map_obj. This is a convenience
821 * function which creates the underlying floating point number object
822 * before inserting it.
826 * The created floating point number object's reference count is
829 * @param map_obj Map object
830 * @param key Key (copied) of floating point number value to
832 * @param val Floating point number value to insert,
833 * associated with the key \p key
834 * @returns 0 on success, or a negative value on error
836 extern int bt_object_map_insert_float(struct bt_object
*map_obj
,
837 const char *key
, double val
);
840 * Inserts the string value \p val associated with the key \p key into
841 * the map object \p map_obj. This is a convenience function which
842 * creates the underlying string object before inserting it.
844 * \p val and \p key are copied.
846 * The created string object's reference count is set to 1.
848 * @param map_obj Map object
849 * @param key Key (copied) of string value to insert
850 * @param val String value to insert, associated with the
852 * @returns 0 on success, or a negative value on error
854 extern int bt_object_map_insert_string(struct bt_object
*map_obj
,
855 const char *key
, const char *val
);
858 * Inserts an empty array object associated with the key \p key into
859 * the map object \p map_obj. This is a convenience function which
860 * creates the underlying array object before inserting it.
864 * The created array object's reference count is set to 1.
866 * @param map_obj Map object
867 * @param key Key (copied) of empty array to insert
868 * @returns 0 on success, or a negative value on error
870 extern int bt_object_map_insert_array(struct bt_object
*map_obj
,
874 * Inserts an empty map object associated with the key \p key into
875 * the map object \p map_obj. This is a convenience function which
876 * creates the underlying map object before inserting it.
880 * The created map object's reference count is set to 1.
882 * @param map_obj Map object
883 * @param key Key (copied) of empty map to insert
884 * @returns 0 on success, or a negative value on error
886 extern int bt_object_map_insert_map(struct bt_object
*map_obj
,
890 * Creates a deep copy of the object \p object.
892 * The created object's reference count is set to 1, unless
893 * \p object is a null object.
895 * @param object Object to copy
896 * @returns Deep copy of \p object on success, or \c NULL
899 extern struct bt_object
*bt_object_copy(const struct bt_object
*object
);
902 * Compares the objects \p object_a and \p object_b and returns \c true
903 * if they have the same content.
905 * @param object_a Object A
906 * @param object_B Object B
907 * @returns \c true if \p object_a and \p object_b have the
908 * same content, or \c false if they differ or on
911 extern bool bt_object_compare(const struct bt_object
*object_a
,
912 const struct bt_object
*object_b
);
918 #endif /* _BABELTRACE_OBJECTS_H */