X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fvalues.h;h=89894f69ee5252bbd490d212bbf7ec9fe6f05c8b;hb=094ff7c009937bb23c056333baffe734308a6b06;hp=58aa99e202418468aec1294c42f927fe78e1fe5d;hpb=9d408fcae74602e3591f66623ceb85f482d948ed;p=babeltrace.git diff --git a/include/babeltrace/values.h b/include/babeltrace/values.h index 58aa99e2..89894f69 100644 --- a/include/babeltrace/values.h +++ b/include/babeltrace/values.h @@ -32,6 +32,9 @@ /* For bt_bool */ #include +/* For bt_get() */ +#include + #ifdef __cplusplus extern "C" { #endif @@ -73,14 +76,6 @@ values of #bt_value_status. You can create a deep copy of any value object with bt_value_copy(). You can compare two value objects with bt_value_compare(). -You can \em freeze a value object with bt_value_freeze(). You can get -the raw value of a frozen value object, but you cannot modify it. -Reference counting still works on frozen value objects. You can copy -a frozen value object: the returned copy is not frozen. You can also -compare a frozen value object to another value object (frozen or not). -Freezing a value object is typically used to make it immutable after -it's built by its initial owner. - The following matrix shows some categorized value object functions to use for each value object type: @@ -175,11 +170,8 @@ to use for each value object type: @brief Status codes. */ enum bt_value_status { - /// Value object cannot be altered because it's frozen. - BT_VALUE_STATUS_FROZEN = -4, - - /// Operation cancelled. - BT_VALUE_STATUS_CANCELLED = -3, + /// Operation canceled. + BT_VALUE_STATUS_CANCELED = -3, /* -22 for compatibility with -EINVAL */ /// Invalid argument. @@ -419,46 +411,6 @@ bt_bool bt_value_is_map(const struct bt_value *object) @{ */ -/** -@brief Recursively freezes the value object \p object. - -You cannot modify a frozen value object: it is considered immutable. -Reference counting still works on a frozen value object, however: you -can pass a frozen value object to bt_get() and bt_put(). - -If \p object is an array value object or a map value object, this -function also freezes all its children recursively. - -Freezing a value object is typically used to make it immutable after -it's built by its initial owner. - -@param[in] object Value object to freeze. -@returns Status code. If \p object - is already frozen, however, #BT_VALUE_STATUS_OK - is returned anyway (that is, this function never - returns #BT_VALUE_STATUS_FROZEN). - -@prenotnull{object} -@postrefcountsame{object} -@post On success, \p object and all its children - are frozen. - -@sa bt_value_is_frozen(): Returns whether or not a value object is - frozen. -*/ -extern enum bt_value_status bt_value_freeze(struct bt_value *object); - -/** -@brief Returns whether or not the value object \p object is frozen. - -@param[in] object Value object to check. -@returns #BT_TRUE if \p object is frozen. - -@prenotnull{object} -@postrefcountsame{object} -*/ -extern bt_bool bt_value_is_frozen(const struct bt_value *object); - /** @brief Creates a \em deep copy of the value object \p object. @@ -862,6 +814,9 @@ extern int64_t bt_value_array_size(const struct bt_value *array_obj); */ extern bt_bool bt_value_array_is_empty(const struct bt_value *array_obj); +extern struct bt_value *bt_value_array_borrow(const struct bt_value *array_obj, + uint64_t index); + /** @brief Returns the value object contained in the array value object \p array_obj at the index \p index. @@ -879,8 +834,12 @@ extern bt_bool bt_value_array_is_empty(const struct bt_value *array_obj); \ref bt_value_null, its reference count is incremented. @postrefcountsame{array_obj} */ -extern struct bt_value *bt_value_array_get(const struct bt_value *array_obj, - uint64_t index); +static inline +struct bt_value *bt_value_array_get(const struct bt_value *array_obj, + uint64_t index) +{ + return bt_get(bt_value_array_borrow(array_obj, index)); +} /** @brief Appends the value object \p element_obj to the array value @@ -1128,6 +1087,9 @@ extern int64_t bt_value_map_size(const struct bt_value *map_obj); */ extern bt_bool bt_value_map_is_empty(const struct bt_value *map_obj); +extern struct bt_value *bt_value_map_borrow(const struct bt_value *map_obj, + const char *key); + /** @brief Returns the value object associated with the key \p key within the map value object \p map_obj. @@ -1144,8 +1106,12 @@ extern bt_bool bt_value_map_is_empty(const struct bt_value *map_obj); @post On success, if the returned value object is not \ref bt_value_null, its reference count is incremented. */ -extern struct bt_value *bt_value_map_get(const struct bt_value *map_obj, - const char *key); +static inline +struct bt_value *bt_value_map_get(const struct bt_value *map_obj, + const char *key) +{ + return bt_get(bt_value_map_borrow(map_obj, key)); +} /** @brief User function type to use with bt_value_map_foreach(). @@ -1187,8 +1153,8 @@ The user function \em must return #BT_TRUE to continue the traversal of @param[in] cb User function to call back. @param[in] data User data passed to the user function. @returns Status code. More - specifically, #BT_VALUE_STATUS_CANCELLED is - returned if the loop was cancelled by the user + specifically, #BT_VALUE_STATUS_CANCELED is + returned if the loop was canceled by the user function. @prenotnull{map_obj}