X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fobjects.h;h=420bd628c379a4a021632522e1d2a3d01c291af5;hb=cbe481eb0a71baa92c9a84c79bfd00888a76b491;hp=3b66cecb746a7b2794d30a956236065131a93ad9;hpb=347829f5b1eaf79a540f4623f7ae5ee4e9e3d4c7;p=babeltrace.git diff --git a/include/babeltrace/objects.h b/include/babeltrace/objects.h index 3b66cecb..420bd628 100644 --- a/include/babeltrace/objects.h +++ b/include/babeltrace/objects.h @@ -81,6 +81,8 @@ * error: * // safe, even if int_obj is NULL * BT_OBJECT_PUT(int_obj); + * + * // ... * \endcode * * Another common manipulation is to move the ownership of an object @@ -112,12 +114,22 @@ * // points to the object * BT_OBJECT_PUT(int_obj); * BT_OBJECT_PUT(int_obj2); + * + * // ... * \endcode * + * Most functions return a status code, one of the values in + * #bt_object_status. + * * You can create a deep copy of any object using the bt_object_copy() * function. You can compare two given objects using * bt_object_compare(). * + * Any object may be frozen using bt_object_freeze(). You may get the + * value of a frozen object, but you cannot modify it. Reference + * counting still works on frozen objects. You may also copy and compare + * frozen objects. + * * @author Philippe Proulx * @bug No known bugs */ @@ -143,7 +155,7 @@ enum bt_object_type { /** Boolean object (holds \c true or \c false). */ BT_OBJECT_TYPE_BOOL = 1, - /** Integer (holds a signed 64-bit integer value). */ + /** Integer object (holds a signed 64-bit integer value). */ BT_OBJECT_TYPE_INTEGER = 2, /** @@ -161,6 +173,27 @@ enum bt_object_type { BT_OBJECT_TYPE_MAP = 6, }; +/** + * Status code. + */ +enum bt_object_status { + /** Object cannot be altered because it's frozen. */ + BT_OBJECT_STATUS_FROZEN = -4, + + /** Operation cancelled. */ + BT_OBJECT_STATUS_CANCELLED = -3, + + /** Invalid arguments. */ + /* -22 for compatibility with -EINVAL */ + BT_OBJECT_STATUS_INVAL = -22, + + /** General error. */ + BT_OBJECT_STATUS_ERROR = -1, + + /** Okay, no error. */ + BT_OBJECT_STATUS_OK = 0, +}; + /** * Object. */ @@ -169,22 +202,25 @@ struct bt_object; /** * The null object singleton. * - * Use this everytime you need a null objet. The null objet singleton - * has no reference count; there's only one. You may compare any object - * to the null singleton to find out if it's a null object, or otherwise - * use bt_object_is_null(). + * Use this everytime you need a null object. + * + * The null object singleton has no reference count; there's only one. + * You may directly compare any object to the null object singleton to + * find out if it's a null object, or otherwise use bt_object_is_null(). + * + * The null object singleton is always frozen (see bt_object_freeze() + * and bt_object_is_frozen()). * * Functions of this API return this when the object is actually a - * null object (of type \link bt_object_type::BT_OBJECT_TYPE_NULL - * BT_OBJECT_TYPE_NULL\endlink), whereas \c NULL means an error - * of some sort. + * null object (of type #BT_OBJECT_TYPE_NULL), whereas \c NULL means an + * error of some sort. */ extern struct bt_object *bt_object_null; /** * User function type for bt_object_map_foreach(). * - * \p object is a \i weak reference; you must pass it to + * \p object is a \em weak reference; you must pass it to * bt_object_get() to get your own reference. * * Return \c true to continue the loop, or \c false to break it. @@ -222,7 +258,7 @@ typedef bool (* bt_object_map_foreach_cb)(const char *key, * * The object's reference count is not changed. Resetting * \p _src_object to \c NULL ensures the object will not be put - * twice later; its ownership is indeed \i moved from the source + * twice later; its ownership is indeed \em moved from the source * variable to the destination variable. * * @param _src_object Source object variable @@ -238,6 +274,8 @@ typedef bool (* bt_object_map_foreach_cb)(const char *key, * Increments the reference count of \p object. * * @param object Object of which to increment the reference count + * + * @see bt_object_put() */ extern void bt_object_get(struct bt_object *object); @@ -249,19 +287,52 @@ extern void bt_object_get(struct bt_object *object); * * @see BT_OBJECT_PUT() (puts an object and resets the variable to * \c NULL) + * @see bt_object_get() */ extern void bt_object_put(struct bt_object *object); +/** + * Recursively freezes the object \p object. + * + * A frozen object cannot be modified; it is considered immutable. + * Reference counting still works on a frozen object though: you may + * pass a frozen object to bt_object_get() and bt_object_put(). + * + * @param object Object to freeze + * @returns One of #bt_object_status values; if \p object + * is already frozen, though, #BT_OBJECT_STATUS_OK + * is returned anyway (i.e. this function never + * returns #BT_OBJECT_STATUS_FROZEN) + * + * @see bt_object_is_frozen() + */ +extern enum bt_object_status bt_object_freeze(struct bt_object *object); + +/** + * Checks whether \p object is frozen or not. + * + * @param object Object to check + * @returns \c true if \p object is frozen + * + * @see bt_object_freeze() + */ +extern bool bt_object_is_frozen(const struct bt_object *object); + /** * Returns the type of \p object. * * @param object Object of which to get the type - * @returns Object's type, or - * \link bt_object_type::BT_OBJECT_TYPE_NULL - * BT_OBJECT_TYPE_UNKNOWN\endlink + * @returns Object's type, or #BT_OBJECT_TYPE_UNKNOWN * on error * - * @see enum bt_object_type (object types) + * @see #bt_object_type (object types) + * @see bt_object_is_null() + * @see bt_object_is_bool() + * @see bt_object_is_integer() + * @see bt_object_is_float() + * @see bt_object_is_string() + * @see bt_object_is_array() + * @see bt_object_is_map() */ extern enum bt_object_type bt_object_get_type(const struct bt_object *object); @@ -271,7 +342,10 @@ extern enum bt_object_type bt_object_get_type(const struct bt_object *object); * * @param object Object to check * @returns \c true if \p object is a null object + * + * @see bt_object_get_type() */ +static inline bool bt_object_is_null(const struct bt_object *object) { return bt_object_get_type(object) == BT_OBJECT_TYPE_NULL; @@ -282,7 +356,10 @@ bool bt_object_is_null(const struct bt_object *object) * * @param object Object to check * @returns \c true if \p object is a boolean object + * + * @see bt_object_get_type() */ +static inline bool bt_object_is_bool(const struct bt_object *object) { return bt_object_get_type(object) == BT_OBJECT_TYPE_BOOL; @@ -293,7 +370,10 @@ bool bt_object_is_bool(const struct bt_object *object) * * @param object Object to check * @returns \c true if \p object is an integer object + * + * @see bt_object_get_type() */ +static inline bool bt_object_is_integer(const struct bt_object *object) { return bt_object_get_type(object) == BT_OBJECT_TYPE_INTEGER; @@ -303,8 +383,12 @@ bool bt_object_is_integer(const struct bt_object *object) * Checks whether \p object is a floating point number object. * * @param object Object to check - * @returns \c true if \p object is a floating point number object + * @returns \c true if \p object is a floating point + * number object + * + * @see bt_object_get_type() */ +static inline bool bt_object_is_float(const struct bt_object *object) { return bt_object_get_type(object) == BT_OBJECT_TYPE_FLOAT; @@ -315,7 +399,10 @@ bool bt_object_is_float(const struct bt_object *object) * * @param object Object to check * @returns \c true if \p object is a string object + * + * @see bt_object_get_type() */ +static inline bool bt_object_is_string(const struct bt_object *object) { return bt_object_get_type(object) == BT_OBJECT_TYPE_STRING; @@ -326,7 +413,10 @@ bool bt_object_is_string(const struct bt_object *object) * * @param object Object to check * @returns \c true if \p object is an array object + * + * @see bt_object_get_type() */ +static inline bool bt_object_is_array(const struct bt_object *object) { return bt_object_get_type(object) == BT_OBJECT_TYPE_ARRAY; @@ -337,7 +427,10 @@ bool bt_object_is_array(const struct bt_object *object) * * @param object Object to check * @returns \c true if \p object is a map object + * + * @see bt_object_get_type() */ +static inline bool bt_object_is_map(const struct bt_object *object) { return bt_object_get_type(object) == BT_OBJECT_TYPE_MAP; @@ -350,6 +443,9 @@ bool bt_object_is_map(const struct bt_object *object) * The created object's reference count is set to 1. * * @returns Created object on success, or \c NULL on error + * + * @see bt_object_bool_create_init() (creates an initialized + * boolean object) */ extern struct bt_object *bt_object_bool_create(void); @@ -370,6 +466,9 @@ extern struct bt_object *bt_object_bool_create_init(bool val); * The created object's reference count is set to 1. * * @returns Created object on success, or \c NULL on error + * + * @see bt_object_integer_create_init() (creates an initialized + * integer object) */ extern struct bt_object *bt_object_integer_create(void); @@ -390,6 +489,9 @@ extern struct bt_object *bt_object_integer_create_init(int64_t val); * The created object's reference count is set to 1. * * @returns Created object on success, or \c NULL on error + * + * @see bt_object_float_create_init() (creates an initialized floating + * point number object) */ extern struct bt_object *bt_object_float_create(void); @@ -410,6 +512,9 @@ extern struct bt_object *bt_object_float_create_init(double val); * The created object's reference count is set to 1. * * @returns Created object on success, or \c NULL on error + * + * @see bt_object_string_create_init() (creates an initialized + * string object) */ extern struct bt_object *bt_object_string_create(void); @@ -444,32 +549,40 @@ extern struct bt_object *bt_object_array_create(void); extern struct bt_object *bt_object_map_create(void); /** - * Gets the boolean value of the boolean objet \p bool_obj. + * Gets the boolean value of the boolean object \p bool_obj. * * @param bool_obj Boolean object * @param val Returned boolean value - * @returns 0 on success, negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_bool_set() */ -extern int bt_object_bool_get(const struct bt_object *bool_obj, bool *val); +extern enum bt_object_status bt_object_bool_get( + const struct bt_object *bool_obj, bool *val); /** * Sets the boolean value of the boolean object \p bool_obj to \p val. * * @param bool_obj Boolean object * @param val New boolean value - * @returns 0 on success, negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_bool_get() */ -extern int bt_object_bool_set(struct bt_object *bool_obj, bool val); +extern enum bt_object_status bt_object_bool_set(struct bt_object *bool_obj, + bool val); /** - * Gets the integer value of the integer objet \p integer_obj. + * Gets the integer value of the integer object \p integer_obj. * * @param integer_obj Integer object * @param val Returned integer value - * @returns 0 on success, negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_integer_set() */ -extern int bt_object_integer_get(const struct bt_object *integer_obj, - int64_t *val); +extern enum bt_object_status bt_object_integer_get( + const struct bt_object *integer_obj, int64_t *val); /** * Sets the integer value of the integer object \p integer_obj to @@ -477,19 +590,25 @@ extern int bt_object_integer_get(const struct bt_object *integer_obj, * * @param integer_obj Integer object * @param val New integer value - * @returns 0 on success, negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_integer_get() */ -extern int bt_object_integer_set(struct bt_object *integer_obj, int64_t val); +extern enum bt_object_status bt_object_integer_set( + struct bt_object *integer_obj, int64_t val); /** * Gets the floating point number value of the floating point number - * objet \p float_obj. + * object \p float_obj. * * @param float_obj Floating point number object * @param val Returned floating point number value - * @returns 0 on success, negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_float_set() */ -extern int bt_object_float_get(const struct bt_object *float_obj, double *val); +extern enum bt_object_status bt_object_float_get( + const struct bt_object *float_obj, double *val); /** * Sets the floating point number value of the floating point number @@ -497,19 +616,27 @@ extern int bt_object_float_get(const struct bt_object *float_obj, double *val); * * @param float_obj Floating point number object * @param val New floating point number value - * @returns 0 on success, negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_float_get() */ -extern int bt_object_float_set(struct bt_object *float_obj, double val); +extern enum bt_object_status bt_object_float_set( + struct bt_object *float_obj, double val); /** - * Gets the string value of the string objet \p string_obj. The + * Gets the string value of the string object \p string_obj. The * returned string is valid as long as this object exists and is not - * modified. + * modified. The ownership of the returned string is \em not + * transferred to the caller. * * @param string_obj String object - * @returns String value, or \c NULL on error + * @param val Returned string value + * @returns One of #bt_object_status values + * + * @see bt_object_string_set() */ -extern const char *bt_object_string_get(const struct bt_object *string_obj); +extern enum bt_object_status bt_object_string_get( + const struct bt_object *string_obj, const char **val); /** * Sets the string value of the string object \p string_obj to @@ -519,16 +646,23 @@ extern const char *bt_object_string_get(const struct bt_object *string_obj); * * @param string_obj String object * @param val New string value (copied) - * @returns 0 on success, negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_string_get() */ -extern int bt_object_string_set(struct bt_object *string_obj, const char *val); +extern enum bt_object_status bt_object_string_set(struct bt_object *string_obj, + const char *val); /** * Gets the size of the array object \p array_obj, that is, the number * of elements contained in \p array_obj. * * @param array_obj Array object - * @returns Array size, or a negative value on error + * @returns Array size if the return value is 0 (empty) or a + * positive value, or one of + * #bt_object_status negative values otherwise + * + * @see bt_object_array_is_empty() */ extern int bt_object_array_size(const struct bt_object *array_obj); @@ -537,6 +671,8 @@ extern int bt_object_array_size(const struct bt_object *array_obj); * * @param array_obj Array object * @returns \c true if \p array_obj is empty + * + * @see bt_object_array_size() */ extern bool bt_object_array_is_empty(const struct bt_object *array_obj); @@ -564,9 +700,16 @@ extern struct bt_object *bt_object_array_get(const struct bt_object *array_obj, * * @param array_obj Array object * @param element_obj Element object to append - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_array_append_bool() + * @see bt_object_array_append_integer() + * @see bt_object_array_append_float() + * @see bt_object_array_append_string() + * @see bt_object_array_append_array() + * @see bt_object_array_append_map() */ -extern int bt_object_array_append(struct bt_object *array_obj, +extern enum bt_object_status bt_object_array_append(struct bt_object *array_obj, struct bt_object *element_obj); /** @@ -578,9 +721,12 @@ extern int bt_object_array_append(struct bt_object *array_obj, * * @param array_obj Array object * @param val Boolean value to append - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_array_append() */ -extern int bt_object_array_append_bool(struct bt_object *array_obj, bool val); +extern enum bt_object_status bt_object_array_append_bool( + struct bt_object *array_obj, bool val); /** * Appends the integer value \p val to the array object \p array_obj. @@ -591,10 +737,12 @@ extern int bt_object_array_append_bool(struct bt_object *array_obj, bool val); * * @param array_obj Array object * @param val Integer value to append - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_array_append() */ -extern int bt_object_array_append_integer(struct bt_object *array_obj, - int64_t val); +extern enum bt_object_status bt_object_array_append_integer( + struct bt_object *array_obj, int64_t val); /** * Appends the floating point number value \p val to the array object @@ -606,10 +754,12 @@ extern int bt_object_array_append_integer(struct bt_object *array_obj, * * @param array_obj Array object * @param val Floating point number value to append - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_array_append() */ -extern int bt_object_array_append_float(struct bt_object *array_obj, - double val); +extern enum bt_object_status bt_object_array_append_float( + struct bt_object *array_obj, double val); /** * Appends the string value \p val to the array object \p array_obj. @@ -622,10 +772,12 @@ extern int bt_object_array_append_float(struct bt_object *array_obj, * * @param array_obj Array object * @param val String value to append (copied) - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_array_append() */ -extern int bt_object_array_append_string(struct bt_object *array_obj, - const char *val); +extern enum bt_object_status bt_object_array_append_string( + struct bt_object *array_obj, const char *val); /** * Appends an empty array object to the array object \p array_obj. @@ -635,9 +787,12 @@ extern int bt_object_array_append_string(struct bt_object *array_obj, * The created array object's reference count is set to 1. * * @param array_obj Array object - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_array_append() */ -extern int bt_object_array_append_array(struct bt_object *array_obj); +extern enum bt_object_status bt_object_array_append_array( + struct bt_object *array_obj); /** * Appends an empty map object to the array object \p array_obj. This @@ -647,16 +802,40 @@ extern int bt_object_array_append_array(struct bt_object *array_obj); * The created map object's reference count is set to 1. * * @param array_obj Array object - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_array_append() */ -extern int bt_object_array_append_map(struct bt_object *array_obj); +extern enum bt_object_status bt_object_array_append_map( + struct bt_object *array_obj); + +/** + * Replaces the element object at index \p index of the array object + * \p array_obj by \p element_obj. + * + * The replaced object's reference count is decremented, unless it's + * a null object. The reference count of \p element_obj is incremented, + * unless it's a null object. + * + * @param array_obj Array object + * @param index Index of element object to replace + * @param element_obj New element object at position \p index of + * \p array_obj + * @returns One of #bt_object_status values + */ +extern enum bt_object_status bt_object_array_set(struct bt_object *array_obj, + size_t index, struct bt_object *element_obj); /** * Gets the size of a map object, that is, the number of elements * contained in a map object. * * @param map_obj Map object - * @returns Map size, or a negative value on error + * @returns Map size if the return value is 0 (empty) or a + * positive value, or one of + * #bt_object_status negative values otherwise + * + * @see bt_object_map_is_empty() */ extern int bt_object_map_size(const struct bt_object *map_obj); @@ -665,6 +844,8 @@ extern int bt_object_map_size(const struct bt_object *map_obj); * * @param map_obj Map object * @returns \c true if \p map_obj is empty + * + * @see bt_object_map_size() */ extern bool bt_object_map_is_empty(const struct bt_object *map_obj); @@ -699,12 +880,14 @@ extern struct bt_object *bt_object_map_get(const struct bt_object *map_obj, * @param map_obj Map object * @param cb User function to call back * @param data User data passed to the user function - * @returns 0 on success, or a negative value on error - * (the user function breaking the loop is \b not - * considered an error here) + * @returns One of #bt_object_status values; more + * specifically, #BT_OBJECT_STATUS_CANCELLED is + * returned if the loop was cancelled by the user + * function */ -extern int bt_object_map_foreach(const struct bt_object *map_obj, - bt_object_map_foreach_cb cb, void *data); +extern enum bt_object_status bt_object_map_foreach( + const struct bt_object *map_obj, bt_object_map_foreach_cb cb, + void *data); /** * Returns whether or not the map object \p map_obj contains the @@ -734,10 +917,18 @@ extern bool bt_object_map_has_key(const struct bt_object *map_obj, * @param key Key (copied) of object to insert * @param element_obj Element object to insert, associated with the * key \p key - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_map_insert_bool() + * @see bt_object_map_insert_integer() + * @see bt_object_map_insert_float() + * @see bt_object_map_insert_string() + * @see bt_object_map_insert_array() + * @see bt_object_map_insert_map() */ -extern int bt_object_map_insert(struct bt_object *map_obj, - const char *key, struct bt_object *element_obj); +extern enum bt_object_status bt_object_map_insert( + struct bt_object *map_obj, const char *key, + struct bt_object *element_obj); /** * Inserts the boolean value \p val associated with the key \p key into @@ -752,10 +943,12 @@ extern int bt_object_map_insert(struct bt_object *map_obj, * @param key Key (copied) of boolean value to insert * @param val Boolean value to insert, associated with the * key \p key - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_map_insert() */ -extern int bt_object_map_insert_bool(struct bt_object *map_obj, - const char *key, bool val); +extern enum bt_object_status bt_object_map_insert_bool( + struct bt_object *map_obj, const char *key, bool val); /** * Inserts the integer value \p val associated with the key \p key into @@ -770,10 +963,12 @@ extern int bt_object_map_insert_bool(struct bt_object *map_obj, * @param key Key (copied) of integer value to insert * @param val Integer value to insert, associated with the * key \p key - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_map_insert() */ -extern int bt_object_map_insert_integer(struct bt_object *map_obj, - const char *key, int64_t val); +extern enum bt_object_status bt_object_map_insert_integer( + struct bt_object *map_obj, const char *key, int64_t val); /** * Inserts the floating point number value \p val associated with the @@ -791,10 +986,12 @@ extern int bt_object_map_insert_integer(struct bt_object *map_obj, * insert * @param val Floating point number value to insert, * associated with the key \p key - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_map_insert() */ -extern int bt_object_map_insert_float(struct bt_object *map_obj, - const char *key, double val); +extern enum bt_object_status bt_object_map_insert_float( + struct bt_object *map_obj, const char *key, double val); /** * Inserts the string value \p val associated with the key \p key into @@ -809,10 +1006,12 @@ extern int bt_object_map_insert_float(struct bt_object *map_obj, * @param key Key (copied) of string value to insert * @param val String value to insert, associated with the * key \p key - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_map_insert() */ -extern int bt_object_map_insert_string(struct bt_object *map_obj, - const char *key, const char *val); +extern enum bt_object_status bt_object_map_insert_string( + struct bt_object *map_obj, const char *key, const char *val); /** * Inserts an empty array object associated with the key \p key into @@ -825,10 +1024,12 @@ extern int bt_object_map_insert_string(struct bt_object *map_obj, * * @param map_obj Map object * @param key Key (copied) of empty array to insert - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_map_insert() */ -extern int bt_object_map_insert_array(struct bt_object *map_obj, - const char *key); +extern enum bt_object_status bt_object_map_insert_array( + struct bt_object *map_obj, const char *key); /** * Inserts an empty map object associated with the key \p key into @@ -841,10 +1042,12 @@ extern int bt_object_map_insert_array(struct bt_object *map_obj, * * @param map_obj Map object * @param key Key (copied) of empty map to insert - * @returns 0 on success, or a negative value on error + * @returns One of #bt_object_status values + * + * @see bt_object_map_insert() */ -extern int bt_object_map_insert_map(struct bt_object *map_obj, - const char *key); +extern enum bt_object_status bt_object_map_insert_map( + struct bt_object *map_obj, const char *key); /** * Creates a deep copy of the object \p object. @@ -852,6 +1055,8 @@ extern int bt_object_map_insert_map(struct bt_object *map_obj, * The created object's reference count is set to 1, unless * \p object is a null object. * + * Copying a frozen object is allowed: the resulting copy is not frozen. + * * @param object Object to copy * @returns Deep copy of \p object on success, or \c NULL * on error @@ -863,7 +1068,7 @@ extern struct bt_object *bt_object_copy(const struct bt_object *object); * if they have the same content. * * @param object_a Object A - * @param object_B Object B + * @param object_b Object B * @returns \c true if \p object_a and \p object_b have the * same content, or \c false if they differ or on * error