X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffield-types.h;h=b7e305456dabe993b27fad7b011471d112b37ae4;hb=c3c35de4da25b506dd423e74706ee302cc0d7e39;hp=9bca9bc6f8e34342686452986083b31802ea0076;hpb=4089d5a6a9f14067306f1f681dd27f5797d3c289;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index 9bca9bc6..b7e30545 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -31,6 +31,7 @@ */ #include +#include #ifdef __cplusplus extern "C" { @@ -174,10 +175,14 @@ The following functions can \em freeze field type objects: - bt_ctf_event_create() freezes the root field types of its event class parameter and of ther parent stream class of this event class. +You cannot modify a frozen field type object: it is considered +immutable, except for \link refs reference counting\endlink. + @sa ctfirfields +@sa \ref ctfirfieldtypesexamples "Examples" @file -@brief CTF IR field type type and functions. +@brief CTF IR field types type and functions. @sa ctfirfieldtypes @addtogroup ctfirfieldtypes @@ -194,6 +199,7 @@ struct bt_ctf_event_class; struct bt_ctf_event; struct bt_ctf_field; struct bt_ctf_field_path; +struct bt_ctf_field_type_enumeration_mapping_iterator; /** @cond DOCUMENT */ @@ -647,6 +653,7 @@ in the detailed description of this module). @prenotnull{field_type} @postrefcountsame{field_type} @postsuccessrefcountret1 +@post On success, the returned field type is not frozen. */ extern struct bt_ctf_field_type *bt_ctf_field_type_copy( struct bt_ctf_field_type *field_type); @@ -696,7 +703,7 @@ An integer field type has the following properties: integer fields Specified at creation bt_ctf_field_type_integer_get_size() - None: specified at creation (bt_ctf_field_type_integer_create()) + bt_ctf_field_type_integer_set_size() Signedness of the described integer fields @@ -721,13 +728,14 @@ An integer field type has the following properties: Mapped \link ctfirclockclass CTF IR clock class\endlink None - bt_ctf_field_type_integer_get_mapped_clock() - bt_ctf_field_type_integer_set_mapped_clock() + bt_ctf_field_type_integer_get_mapped_clock_class() + bt_ctf_field_type_integer_set_mapped_clock_class() @sa ctfirintfield @sa ctfirfieldtypes +@sa \ref ctfirfieldtypesexamples_intfieldtype "Examples" @addtogroup ctfirintfieldtype @{ @@ -757,6 +765,10 @@ enum bt_ctf_integer_base { @brief Creates a default @intft with \p size bits as the storage size of the @intfields it describes. +You can change the storage size of the integer fields described by +the created integer field type later with +bt_ctf_field_type_integer_set_size(). + @param[in] size Storage size (bits) of the described integer fields. @returns Created integer field type, or \c NULL on error. @@ -780,10 +792,36 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create( @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} + +@sa bt_ctf_field_type_integer_set_size(): Sets the storage size of the + integer fields described by a given integer field type. */ extern int bt_ctf_field_type_integer_get_size( struct bt_ctf_field_type *int_field_type); +/** +@brief Sets the storage size, in bits, of the @intfields described by + the @intft \p int_field_type. + +@param[in] int_field_type Integer field type which describes the + integer fields of which to set the + storage size. +@param[in] size Storage size (bits) of the integer fields + described by \p int_field_type. +@returns 0 on success, or a negative value on error. + +@prenotnull{int_field_type} +@preisintft{int_field_type} +@prehot{int_field_type} +@pre \p size is greater than 0 and lesser than or equal to 64. +@postrefcountsame{int_field_type} + +@sa bt_ctf_field_type_integer_get_size(): Returns the storage size of + the integer fields described by a given integer field type. +*/ +extern int bt_ctf_field_type_integer_set_size( + struct bt_ctf_field_type *int_field_type, size_t size); + /** @brief Returns whether or not the @intfields described by the @intft \p int_field_type are signed. @@ -822,7 +860,7 @@ extern int bt_ctf_field_type_integer_get_signed( @preisintft{int_field_type} @prehot{int_field_type} @pre \p is_signed is 0 or 1. -@postrefcountsame{event_class} +@postrefcountsame{int_field_type} @sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of the integer fields described by a given integer field type. @@ -951,15 +989,15 @@ This mapped clock class is only indicative. @postrefcountsame{int_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_integer_set_mapped_clock(): Sets the mapped +@sa bt_ctf_field_type_integer_set_mapped_clock_class(): Sets the mapped clock class of a given integer field type. */ -extern struct bt_ctf_clock *bt_ctf_field_type_integer_get_mapped_clock( +extern struct bt_ctf_clock_class *bt_ctf_field_type_integer_get_mapped_clock_class( struct bt_ctf_field_type *int_field_type); /** @brief Sets the \link ctfirclockclass CTF IR clock class\endlink mapped - to the @intft \p int_field_type to \p mapped_clock. + to the @intft \p int_field_type to \p clock_class. The mapped clock class, if any, indicates the class of the clock which an integer field described by \p int_field_type should sample or update. @@ -977,12 +1015,12 @@ This mapped clock class is only indicative. @postrefcountsame{int_field_type} @postsuccessrefcountinc{clock_class} -@sa bt_ctf_field_type_integer_get_mapped_clock(): Returns the mapped +@sa bt_ctf_field_type_integer_get_mapped_clock_class(): Returns the mapped clock class of a given integer field type. */ -extern int bt_ctf_field_type_integer_set_mapped_clock( +extern int bt_ctf_field_type_integer_set_mapped_clock_class( struct bt_ctf_field_type *int_field_type, - struct bt_ctf_clock *clock_class); + struct bt_ctf_clock_class *clock_class); /** @} */ @@ -1042,6 +1080,7 @@ A floating point number field type has the following properties: @sa ctfirfloatfield @sa ctfirfieldtypes +@sa \ref ctfirfieldtypesexamples_floatfieldtype "Examples" @addtogroup ctfirfloatfieldtype @{ @@ -1198,8 +1237,22 @@ bt_ctf_field_type_enumeration_add_mapping() or bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the signedness of the wrapped @intft. -Many mappings can share the same name, but the ranges of a given -enumeration field type must not overlap. For example, +You can find mappings by name or by value with the following find +operations: + +- bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. +- bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): + Finds the mappings which contain a given unsigned value in their + range. +- bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): + Finds the mappings which contain a given signed value in their range. + +Those functions return a @enumftiter on the result set of the find +operation. + +Many mappings can share the same name, and the ranges of a given +enumeration field type are allowed to overlap. For example, this is a valid set of mappings: @verbatim @@ -1209,7 +1262,7 @@ CHERRY -> [ 25, 34] APPLE -> [ 55, 55] @endverbatim -The following set of mappings is \em not valid, however: +The following set of mappings is also valid: @verbatim APPLE -> [ 3, 19] @@ -1221,6 +1274,7 @@ APPLE -> [ 30, 55] Here, the range of the second \c APPLE mapping overlaps the range of the \c CHERRY mapping. +@sa ctfirenumftmappingiter @sa ctfirenumfield @sa ctfirfieldtypes @@ -1291,7 +1345,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. @param[in] enum_field_type Enumeration field type of which to get the mapping at index \p index. -­@param[in] index Index of the mapping to get from +@param[in] index Index of the mapping to get from \p enum_field_type. @param[out] name Returned name of the mapping at index \p index. @@ -1317,7 +1371,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. unsigned mapping contained by a given enumeration field type at a given index. */ -extern int bt_ctf_field_type_enumeration_get_mapping( +extern int bt_ctf_field_type_enumeration_get_mapping_signed( struct bt_ctf_field_type *enum_field_type, int index, const char **name, int64_t *range_begin, int64_t *range_end); @@ -1333,7 +1387,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. @param[in] enum_field_type Enumeration field type of which to get the mapping at index \p index. -­@param[in] index Index of the mapping to get from +@param[in] index Index of the mapping to get from \p enum_field_type. @param[out] name Returned name of the mapping at index \p index. @@ -1355,7 +1409,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. bt_ctf_field_type_enumeration_get_mapping_count()). @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_get_mapping(): Returns the +@sa bt_ctf_field_type_enumeration_get_mapping_signed(): Returns the signed mapping contained by a given enumeration field type at a given index. */ @@ -1364,74 +1418,112 @@ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( const char **name, uint64_t *range_begin, uint64_t *range_end); -/** @cond DOCUMENT */ -/* - * TODO: Document once we know what to do with this function (return - * the first match?). - */ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_name( - struct bt_ctf_field_type *enum_field_type, const char *name); -/** @endcond */ - /** -@brief Returns the index of the signed mapping of the @enumft - \p field_type which contains the value \p value. +@brief Finds the mappings of the @enumft \p enum_field_type which + are named \p name. -The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be -\b signed to use this function. +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. -@param[in] enum_field_type Enumeration field type of which to get - the index of the mapping which contains - \p value. -@param[in] value Value of the mapping to find. -@returns Index of the mapping of - \p enum_field_type which contains - \p value, or a negative value if the - function cannot find such a mapping or +@param[in] enum_field_type Enumeration field type of which to find + the mappings named \p name. +@param[in] name Name of the mappings to find in + \p enum_field_type. +@returns @enumftiter on the set of mappings named + \p name in \p enum_field_type, or + \c NULL if no mappings were found or on error. @prenotnull{enum_field_type} +@prenotnull{name} @preisenumft{enum_field_type} -@pre The wrapped @intft of \p enum_field_type is signed. @postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. -@sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(): - Finds the index of an unsigned mapping of a given enumeration - field type by value. +@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds + the mappings of a given enumeration field type which contain + a given signed value in their range. +@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. */ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_value( - struct bt_ctf_field_type *enum_field_type, int64_t value); +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_name( + struct bt_ctf_field_type *enum_field_type, + const char *name); /** -@brief Returns the index of the unsigned mapping of the @enumft - \p field_type which contains the value \p value. +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the signed value \p value in their range. -The @intft wrapped by \p enum_field_type, as returned by -bt_ctf_field_type_enumeration_get_container_type(), must be -\b unsigned to use this function. +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. -@param[in] enum_field_type Enumeration field type of which to get - the index of the mapping which contains - \p value. -@param[in] value Value of the mapping to find. -@returns Index of the mapping of - \p enum_field_type which contains - \p value, or a negative value if the - function cannot find such a mapping or +@param[in] enum_field_type Enumeration field type of which to find + the mappings which contain \p value. +@param[in] value Value to find in the ranges of the + mappings of \p enum_field_type. +@returns @enumftiter on the set of mappings of + \p enum_field_type which contain + \p value in their range, or \c NULL if + no mappings were found or on error. + +@prenotnull{enum_field_type} +@preisenumft{enum_field_type} +@postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. + +@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. +*/ +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_signed_value( + struct bt_ctf_field_type *enum_field_type, + int64_t value); + +/** +@brief Finds the mappings of the @enumft \p enum_field_type which + contain the unsigned value \p value in their range. + +This function returns an iterator on the result set of this find +operation. See \ref ctfirenumftmappingiter for more details. + +@param[in] enum_field_type Enumeration field type of which to find + the mappings which contain \p value. +@param[in] value Value to find in the ranges of the + mappings of \p enum_field_type. +@returns @enumftiter on the set of mappings of + \p enum_field_type which contain + \p value in their range, or \c NULL + if no mappings were found or on error. @prenotnull{enum_field_type} @preisenumft{enum_field_type} -@pre The wrapped @intft of \p enum_field_type is unsigned. @postrefcountsame{enum_field_type} +@postsuccessrefcountret1 +@post On success, the returned @enumftiter can iterate + on at least one mapping. -@sa bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value(): - Finds the index of a signed mapping of a given enumeration - field type by value. +@sa bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings of a given enumeration field type which have a given + name. +@sa bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): Finds + the mappings of a given enumeration field type which contain + a given unsigned value in their range. */ -extern int bt_ctf_field_type_enumeration_get_mapping_index_by_unsigned_value( - struct bt_ctf_field_type *enum_field_type, uint64_t value); +extern struct bt_ctf_field_type_enumeration_mapping_iterator * +bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value( + struct bt_ctf_field_type *enum_field_type, + uint64_t value); /** @brief Adds a mapping to the @enumft \p enum_field_type which maps the @@ -1445,9 +1537,7 @@ The @intft wrapped by \p enum_field_type, as returned by bt_ctf_field_type_enumeration_get_container_type(), must be \b signed to use this function. -A mapping in \p enum_field_type can exist with the name \p name, but -there must be no overlap amongst all the ranges of -\p enum_field_type. +A mapping in \p enum_field_type can exist with the name \p name. @param[in] enum_field_type Enumeration field type to which to add a mapping. @@ -1485,9 +1575,7 @@ The @intft wrapped by \p enum_field_type, as returned by bt_ctf_field_type_enumeration_get_container_type(), must be \b unsigned to use this function. -A mapping in \p enum_field_type can exist with the name \p name, but -there must be no overlap amongst all the ranges of -\p enum_field_type. +A mapping in \p enum_field_type can exist with the name \p name. @param[in] enum_field_type Enumeration field type to which to add a mapping. @@ -1515,6 +1603,167 @@ extern int bt_ctf_field_type_enumeration_add_mapping_unsigned( /** @} */ +/** +@defgroup ctfirenumftmappingiter CTF IR enumeration field type mapping iterator +@ingroup ctfirenumfieldtype +@brief CTF IR enumeration field type mapping iterator. + +@code +#include +@endcode + +A CTF IR enumeration field type mapping +iterator is an iterator on @enumft mappings. + +You can get an enumeration mapping iterator from one of the following +functions: + +- Find operations of an @enumft object: + - bt_ctf_field_type_enumeration_find_mappings_by_name(): Finds the + mappings with a given name. + - bt_ctf_field_type_enumeration_find_mappings_by_unsigned_value(): + Finds the mappings which contain a given unsigned value in their + range. + - bt_ctf_field_type_enumeration_find_mappings_by_signed_value(): + Finds the mappings which contain a given signed value in their range. +- bt_ctf_field_enumeration_get_mappings(): Finds the mappings in the + @enumft of an @enumfield containing its current integral value in + their range. + +Those functions guarantee that the returned iterator can iterate on +at least one mapping. Otherwise, they return \c NULL. + +You can get the name and the range of a mapping iterator's current +mapping with +bt_ctf_field_type_enumeration_mapping_iterator_get_signed() +or +bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(), +depending on the signedness of the @intft wrapped by the +@enumft. If you only need the name of the current mapping, you can +use any of the two functions and set the \p range_begin and \p range_end +parameters to \c NULL. + +You can advance an enumeration field type mapping iterator to the next +mapping with +bt_ctf_field_type_enumeration_mapping_iterator_next(). This +function returns a negative value when you reach the end of the +result set. + +As with any Babeltrace object, CTF IR enumeration field type mapping +iterator objects have reference +counts. See \ref refs to learn more about the reference counting +management of Babeltrace objects. + +@sa ctfirenumfieldtype + +@addtogroup ctfirenumftmappingiter +@{ +*/ + +/** +@struct bt_ctf_field_type_enumeration_mapping_iterator +@brief A CTF IR enumeration field type mapping iterator. +@sa ctfirenumftmappingiter +*/ + +/** +@brief Returns the name and the range of the current (signed) mapping + of the @enumftiter \p iter. + +If one of \p range_begin or \p range_end is not \c NULL, the @intft +wrapped by the @enumft from which \p iter was obtained, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b signed to use this function. Otherwise, if you only need to get the +name of the current mapping, set \p range_begin and \p range_end to +\c NULL. + +On success, if \p name is not \c NULL, \p *name remains valid as long +as \p iter exists and +bt_ctf_field_type_enumeration_mapping_iterator_next() is +\em not called on \p iter. + +@param[in] iter Enumeration field type mapping iterator + of which to get the range of the current + mapping. +@param[out] name Returned name of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_begin Returned beginning of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_end Returned end of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@postrefcountsame{iter} + +@sa bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned(): + Returns the name and the unsigned range of the current mapping + of a given enumeration field type mapping iterator. +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_get_signed( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **name, int64_t *range_begin, int64_t *range_end); + +/** +@brief Returns the name and the range of the current (unsigned) mapping + of the @enumftiter \p iter. + +If one of \p range_begin or \p range_end is not \c NULL, the @intft +wrapped by the @enumft from which \p iter was obtained, as returned by +bt_ctf_field_type_enumeration_get_container_type(), must be +\b unsigned to use this function. Otherwise, if you only need to get the +name of the current mapping, set \p range_begin and \p range_end to +\c NULL. + +On success, if \p name is not \c NULL, \p *name remains valid as long +as \p iter exists and +bt_ctf_field_type_enumeration_mapping_iterator_next() is +\em not called on \p iter. + +@param[in] iter Enumeration field type mapping iterator + of which to get the range of the current + mapping. +@param[out] name Returned name of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_begin Returned beginning of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@param[out] range_end Returned end of the range + (included) of the current mapping of + \p iter (can be \c NULL to ignore). +@returns 0 on success, or a negative value on error. + +@prenotnull{iter} +@postrefcountsame{iter} + +@sa + bt_ctf_field_type_enumeration_mapping_iterator_get_signed(): + Returns the name and the signed range of the current mapping of + a given enumeration field type mapping iterator. +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_get_unsigned( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter, + const char **name, uint64_t *range_begin, uint64_t *range_end); + +/** +@brief Advances the @enumftiter \p iter to the next mapping. + +@param[in] iter Enumeration field type mapping iterator to + advance. +@returns 0 on success, or a negative value on error or + when you reach the end of the set. + +@prenotnull{iter} +@postrefcountsame{iter} +*/ +extern int bt_ctf_field_type_enumeration_mapping_iterator_next( + struct bt_ctf_field_type_enumeration_mapping_iterator *iter); + +/** @} */ + /** @defgroup ctfirstringfieldtype CTF IR string field type @ingroup ctfirfieldtypes