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,
170 * The null object singleton.
172 * Use this everytime you need a null objet. The null objet singleton
173 * has no reference count; there's only one. You may compare any object
174 * to the null singleton to find out if it's a null object, or otherwise
175 * use bt_object_is_null().
177 * Functions of this API return this when the object is actually a
178 * null object (of type \link bt_object_type::BT_OBJECT_TYPE_NULL
179 * <code>BT_OBJECT_TYPE_NULL</code>\endlink), whereas \c NULL means an error
182 extern struct bt_object
*bt_object_null
;
185 * User function type for bt_object_map_foreach().
187 * \p object is a \i weak reference; you must pass it to
188 * bt_object_get() to get your own reference.
190 * Return \c true to continue the loop, or \c false to break it.
192 * @param key Key of map entry
193 * @param object Object of map entry (weak reference)
194 * @param data User data
195 * @returns \c true to continue the loop
197 typedef bool (* bt_object_map_foreach_cb
)(const char *key
,
198 struct bt_object
*object
, void *data
);
201 * Puts the object \p _object (calls bt_object_put() on it), and resets
202 * the variable to \c NULL.
204 * This is something that is often done when putting and object;
205 * resetting the variable to \c NULL makes sure it cannot be put a
208 * @param _object Object to put
210 * @see BT_OBJECT_MOVE() (moves an object from one variable to the other
211 * without putting it)
213 #define BT_OBJECT_PUT(_object) \
215 bt_object_put(_object); \
220 * Moves the object referenced by the variable \p _src_object to the
221 * \p _dst_object variable, then resets \p _src_object to \c NULL.
223 * The object's reference count is <b>not changed</b>. Resetting
224 * \p _src_object to \c NULL ensures the object will not be put
225 * twice later; its ownership is indeed \i moved from the source
226 * variable to the destination variable.
228 * @param _src_object Source object variable
229 * @param _dst_object Destination object variable
231 #define BT_OBJECT_MOVE(_dst_object, _src_object) \
233 (_dst_object) = (_src_object); \
234 (_src_object) = NULL; \
238 * Increments the reference count of \p object.
240 * @param object Object of which to increment the reference count
242 extern void bt_object_get(struct bt_object
*object
);
245 * Decrements the reference count of \p object, destroying it when this
248 * @param object Object of which to decrement the reference count
250 * @see BT_OBJECT_PUT() (puts an object and resets the variable to
253 extern void bt_object_put(struct bt_object
*object
);
256 * Returns the type of \p object.
258 * @param object Object of which to get the type
259 * @returns Object's type, or
260 * \link bt_object_type::BT_OBJECT_TYPE_NULL
261 * <code>BT_OBJECT_TYPE_UNKNOWN</code>\endlink
264 * @see enum bt_object_type (object types)
266 extern enum bt_object_type
bt_object_get_type(const struct bt_object
*object
);
269 * Checks whether \p object is a null object. The only valid null
270 * object is \ref bt_object_null.
272 * @param object Object to check
273 * @returns \c true if \p object is a null object
275 static bool bt_object_is_null(const struct bt_object
*object
)
277 return bt_object_get_type(object
) == BT_OBJECT_TYPE_NULL
;
281 * Checks whether \p object is a boolean object.
283 * @param object Object to check
284 * @returns \c true if \p object is a boolean object
286 static bool bt_object_is_bool(const struct bt_object
*object
)
288 return bt_object_get_type(object
) == BT_OBJECT_TYPE_BOOL
;
292 * Checks whether \p object is an integer object.
294 * @param object Object to check
295 * @returns \c true if \p object is an integer object
297 static bool bt_object_is_integer(const struct bt_object
*object
)
299 return bt_object_get_type(object
) == BT_OBJECT_TYPE_INTEGER
;
303 * Checks whether \p object is a floating point number object.
305 * @param object Object to check
306 * @returns \c true if \p object is a floating point number object
308 static bool bt_object_is_float(const struct bt_object
*object
)
310 return bt_object_get_type(object
) == BT_OBJECT_TYPE_FLOAT
;
314 * Checks whether \p object is a string object.
316 * @param object Object to check
317 * @returns \c true if \p object is a string object
319 static bool bt_object_is_string(const struct bt_object
*object
)
321 return bt_object_get_type(object
) == BT_OBJECT_TYPE_STRING
;
325 * Checks whether \p object is an array object.
327 * @param object Object to check
328 * @returns \c true if \p object is an array object
330 static bool bt_object_is_array(const struct bt_object
*object
)
332 return bt_object_get_type(object
) == BT_OBJECT_TYPE_ARRAY
;
336 * Checks whether \p object is a map object.
338 * @param object Object to check
339 * @returns \c true if \p object is a map object
341 static bool bt_object_is_map(const struct bt_object
*object
)
343 return bt_object_get_type(object
) == BT_OBJECT_TYPE_MAP
;
347 * Creates a boolean object. The created boolean object's initial value
350 * The created object's reference count is set to 1.
352 * @returns Created object on success, or \c NULL on error
354 extern struct bt_object
*bt_object_bool_create(void);
357 * Creates a boolean object with its initial value set to \p val.
359 * The created object's reference count is set to 1.
361 * @param val Initial value
362 * @returns Created object on success, or \c NULL on error
364 extern struct bt_object
*bt_object_bool_create_init(bool val
);
367 * Creates an integer object. The created integer object's initial value
370 * The created object's reference count is set to 1.
372 * @returns Created object on success, or \c NULL on error
374 extern struct bt_object
*bt_object_integer_create(void);
377 * Creates an integer object with its initial value set to \p val.
379 * The created object's reference count is set to 1.
381 * @param val Initial value
382 * @returns Created object on success, or \c NULL on error
384 extern struct bt_object
*bt_object_integer_create_init(int64_t val
);
387 * Creates a floating point number object. The created floating point
388 * number object's initial value is 0.
390 * The created object's reference count is set to 1.
392 * @returns Created object on success, or \c NULL on error
394 extern struct bt_object
*bt_object_float_create(void);
397 * Creates a floating point number object with its initial value set
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_float_create_init(double val
);
408 * Creates a string object. The string object is initially empty.
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_string_create(void);
417 * Creates a string object with its initial value set to \p val.
421 * The created object's reference count is set to 1.
423 * @param val Initial value (will be copied)
424 * @returns Created object on success, or \c NULL on error
426 extern struct bt_object
*bt_object_string_create_init(const char *val
);
429 * Creates an empty array object.
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_array_create(void);
438 * Creates an empty map object.
440 * The created object's reference count is set to 1.
442 * @returns Created object on success, or \c NULL on error
444 extern struct bt_object
*bt_object_map_create(void);
447 * Gets the boolean value of the boolean objet \p bool_obj.
449 * @param bool_obj Boolean object
450 * @param val Returned boolean value
451 * @returns 0 on success, negative value on error
453 extern int bt_object_bool_get(const struct bt_object
*bool_obj
, bool *val
);
456 * Sets the boolean value of the boolean object \p bool_obj to \p val.
458 * @param bool_obj Boolean object
459 * @param val New boolean value
460 * @returns 0 on success, negative value on error
462 extern int bt_object_bool_set(struct bt_object
*bool_obj
, bool val
);
465 * Gets the integer value of the integer objet \p integer_obj.
467 * @param integer_obj Integer object
468 * @param val Returned integer value
469 * @returns 0 on success, negative value on error
471 extern int bt_object_integer_get(const struct bt_object
*integer_obj
,
475 * Sets the integer value of the integer object \p integer_obj to
478 * @param integer_obj Integer object
479 * @param val New integer value
480 * @returns 0 on success, negative value on error
482 extern int bt_object_integer_set(struct bt_object
*integer_obj
, int64_t val
);
485 * Gets the floating point number value of the floating point number
486 * objet \p float_obj.
488 * @param float_obj Floating point number object
489 * @param val Returned floating point number value
490 * @returns 0 on success, negative value on error
492 extern int bt_object_float_get(const struct bt_object
*float_obj
, double *val
);
495 * Sets the floating point number value of the floating point number
496 * object \p float_obj to \p val.
498 * @param float_obj Floating point number object
499 * @param val New floating point number value
500 * @returns 0 on success, negative value on error
502 extern int bt_object_float_set(struct bt_object
*float_obj
, double val
);
505 * Gets the string value of the string objet \p string_obj. The
506 * returned string is valid as long as this object exists and is not
509 * @param string_obj String object
510 * @returns String value, or \c NULL on error
512 extern const char *bt_object_string_get(const struct bt_object
*string_obj
);
515 * Sets the string value of the string object \p string_obj to
520 * @param string_obj String object
521 * @param val New string value (copied)
522 * @returns 0 on success, negative value on error
524 extern int bt_object_string_set(struct bt_object
*string_obj
, const char *val
);
527 * Gets the size of the array object \p array_obj, that is, the number
528 * of elements contained in \p array_obj.
530 * @param array_obj Array object
531 * @returns Array size, or a negative value on error
533 extern int bt_object_array_size(const struct bt_object
*array_obj
);
536 * Returns \c true if the array object \p array_obj.
538 * @param array_obj Array object
539 * @returns \c true if \p array_obj is empty
541 extern bool bt_object_array_is_empty(const struct bt_object
*array_obj
);
544 * Gets the element object of the array object \p array_obj at the
547 * The returned object's reference count is incremented, unless it's
550 * @param array_obj Array object
551 * @param index Index of element to get
552 * @returns Element object at index \p index on success,
553 * or \c NULL on error
555 extern struct bt_object
*bt_object_array_get(const struct bt_object
*array_obj
,
559 * Appends the element object \p element_obj to the array object
562 * The appended object's reference count is incremented, unless it's
565 * @param array_obj Array object
566 * @param element_obj Element object to append
567 * @returns 0 on success, or a negative value on error
569 extern int bt_object_array_append(struct bt_object
*array_obj
,
570 struct bt_object
*element_obj
);
573 * Appends the boolean value \p val to the array object \p array_obj.
574 * This is a convenience function which creates the underlying boolean
575 * object before appending it.
577 * The created boolean object's reference count is set to 1.
579 * @param array_obj Array object
580 * @param val Boolean value to append
581 * @returns 0 on success, or a negative value on error
583 extern int bt_object_array_append_bool(struct bt_object
*array_obj
, bool val
);
586 * Appends the integer value \p val to the array object \p array_obj.
587 * This is a convenience function which creates the underlying integer
588 * object before appending it.
590 * The created integer object's reference count is set to 1.
592 * @param array_obj Array object
593 * @param val Integer value to append
594 * @returns 0 on success, or a negative value on error
596 extern int bt_object_array_append_integer(struct bt_object
*array_obj
,
600 * Appends the floating point number value \p val to the array object
601 * \p array_obj. This is a convenience function which creates the
602 * underlying floating point number object before appending it.
604 * The created floating point number object's reference count is
607 * @param array_obj Array object
608 * @param val Floating point number value to append
609 * @returns 0 on success, or a negative value on error
611 extern int bt_object_array_append_float(struct bt_object
*array_obj
,
615 * Appends the string value \p val to the array object \p array_obj.
616 * This is a convenience function which creates the underlying string
617 * object before appending it.
621 * The created string object's reference count is set to 1.
623 * @param array_obj Array object
624 * @param val String value to append (copied)
625 * @returns 0 on success, or a negative value on error
627 extern int bt_object_array_append_string(struct bt_object
*array_obj
,
631 * Appends an empty array object to the array object \p array_obj.
632 * This is a convenience function which creates the underlying array
633 * object before appending it.
635 * The created array object's reference count is set to 1.
637 * @param array_obj Array object
638 * @returns 0 on success, or a negative value on error
640 extern int bt_object_array_append_array(struct bt_object
*array_obj
);
643 * Appends an empty map object to the array object \p array_obj. This
644 * is a convenience function which creates the underlying map object
645 * before appending it.
647 * The created map object's reference count is set to 1.
649 * @param array_obj Array object
650 * @returns 0 on success, or a negative value on error
652 extern int bt_object_array_append_map(struct bt_object
*array_obj
);
655 * Gets the size of a map object, that is, the number of elements
656 * contained in a map object.
658 * @param map_obj Map object
659 * @returns Map size, or a negative value on error
661 extern int bt_object_map_size(const struct bt_object
*map_obj
);
664 * Returns \c true if the map object \p map_obj.
666 * @param map_obj Map object
667 * @returns \c true if \p map_obj is empty
669 extern bool bt_object_map_is_empty(const struct bt_object
*map_obj
);
672 * Gets the element object associated with the key \p key within the
673 * map object \p map_obj.
675 * The returned object's reference count is incremented, unless it's
678 * @param map_obj Map object
679 * @param key Key of the element to get
680 * @returns Element object associated with the key \p key
681 * on success, or \c NULL on error
683 extern struct bt_object
*bt_object_map_get(const struct bt_object
*map_obj
,
687 * Calls a provided user function \p cb for each element of the map
690 * The object passed to the user function is a <b>weak reference</b>:
691 * you must call bt_object_get() on it to obtain your own reference.
693 * The key passed to the user function is only valid in the scope of
694 * this user function.
696 * The user function must return \c true to continue the loop, or
697 * \c false to break it.
699 * @param map_obj Map object
700 * @param cb User function to call back
701 * @param data User data passed to the user function
702 * @returns 0 on success, or a negative value on error
703 * (the user function breaking the loop is \b not
704 * considered an error here)
706 extern int bt_object_map_foreach(const struct bt_object
*map_obj
,
707 bt_object_map_foreach_cb cb
, void *data
);
710 * Returns whether or not the map object \p map_obj contains the
713 * @param map_obj Map object
714 * @param key Key to check
715 * @returns \c true if \p map_obj contains the key \p key,
716 * or \c false if it doesn't have \p key or
719 extern bool bt_object_map_has_key(const struct bt_object
*map_obj
,
723 * Inserts the element object \p element_obj associated with the key
724 * \p key into the map object \p map_obj. If \p key exists in
725 * \p map_obj, the associated element object is first put, and then
726 * replaced by \p element_obj.
730 * The inserted object's reference count is incremented, unless it's
733 * @param map_obj Map object
734 * @param key Key (copied) of object to insert
735 * @param element_obj Element object to insert, associated with the
737 * @returns 0 on success, or a negative value on error
739 extern int bt_object_map_insert(struct bt_object
*map_obj
,
740 const char *key
, struct bt_object
*element_obj
);
743 * Inserts the boolean value \p val associated with the key \p key into
744 * the map object \p map_obj. This is a convenience function which
745 * creates the underlying boolean object before inserting it.
749 * The created boolean object's reference count is set to 1.
751 * @param map_obj Map object
752 * @param key Key (copied) of boolean value to insert
753 * @param val Boolean value to insert, associated with the
755 * @returns 0 on success, or a negative value on error
757 extern int bt_object_map_insert_bool(struct bt_object
*map_obj
,
758 const char *key
, bool val
);
761 * Inserts the integer value \p val associated with the key \p key into
762 * the map object \p map_obj. This is a convenience function which
763 * creates the underlying integer object before inserting it.
767 * The created integer object's reference count is set to 1.
769 * @param map_obj Map object
770 * @param key Key (copied) of integer value to insert
771 * @param val Integer value to insert, associated with the
773 * @returns 0 on success, or a negative value on error
775 extern int bt_object_map_insert_integer(struct bt_object
*map_obj
,
776 const char *key
, int64_t val
);
779 * Inserts the floating point number value \p val associated with the
780 * key \p key into the map object \p map_obj. This is a convenience
781 * function which creates the underlying floating point number object
782 * before inserting it.
786 * The created floating point number object's reference count is
789 * @param map_obj Map object
790 * @param key Key (copied) of floating point number value to
792 * @param val Floating point number value to insert,
793 * associated with the key \p key
794 * @returns 0 on success, or a negative value on error
796 extern int bt_object_map_insert_float(struct bt_object
*map_obj
,
797 const char *key
, double val
);
800 * Inserts the string value \p val associated with the key \p key into
801 * the map object \p map_obj. This is a convenience function which
802 * creates the underlying string object before inserting it.
804 * \p val and \p key are copied.
806 * The created string object's reference count is set to 1.
808 * @param map_obj Map object
809 * @param key Key (copied) of string value to insert
810 * @param val String value to insert, associated with the
812 * @returns 0 on success, or a negative value on error
814 extern int bt_object_map_insert_string(struct bt_object
*map_obj
,
815 const char *key
, const char *val
);
818 * Inserts an empty array object associated with the key \p key into
819 * the map object \p map_obj. This is a convenience function which
820 * creates the underlying array object before inserting it.
824 * The created array object's reference count is set to 1.
826 * @param map_obj Map object
827 * @param key Key (copied) of empty array to insert
828 * @returns 0 on success, or a negative value on error
830 extern int bt_object_map_insert_array(struct bt_object
*map_obj
,
834 * Inserts an empty map object associated with the key \p key into
835 * the map object \p map_obj. This is a convenience function which
836 * creates the underlying map object before inserting it.
840 * The created map object's reference count is set to 1.
842 * @param map_obj Map object
843 * @param key Key (copied) of empty map to insert
844 * @returns 0 on success, or a negative value on error
846 extern int bt_object_map_insert_map(struct bt_object
*map_obj
,
850 * Creates a deep copy of the object \p object.
852 * The created object's reference count is set to 1, unless
853 * \p object is a null object.
855 * @param object Object to copy
856 * @returns Deep copy of \p object on success, or \c NULL
859 extern struct bt_object
*bt_object_copy(const struct bt_object
*object
);
862 * Compares the objects \p object_a and \p object_b and returns \c true
863 * if they have the same content.
865 * @param object_a Object A
866 * @param object_B Object B
867 * @returns \c true if \p object_a and \p object_b have the
868 * same content, or \c false if they differ or on
871 extern bool bt_object_compare(const struct bt_object
*object_a
,
872 const struct bt_object
*object_b
);
878 #endif /* _BABELTRACE_OBJECTS_H */