<tr>
<th>Name
<th>Type enumerator
- <th>Creation function
+ <th>Creation function(s)
<tr>
<td><em>\ref api-tir-fc-bool "Boolean"</em>
<td>#BT_FIELD_CLASS_TYPE_BOOL
<td>#BT_FIELD_CLASS_TYPE_STATIC_ARRAY
<td>bt_field_class_array_static_create()
<tr>
- <td><em>Dynamic \ref api-tir-fc-array "array" (no length field)</em>
+ <td>
+ <em>Dynamic \ref api-tir-fc-array "array"
+ (instances without a linked length field)</em>
<td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD
- <td>bt_field_class_array_dynamic_create()
+ <td>
+ - bt_field_class_array_dynamic_create()
+ - bt_field_class_array_dynamic_without_length_field_location_create()
<tr>
- <td><em>Dynamic \ref api-tir-fc-array "array" (with length field)</em>
+ <td>
+ <em>Dynamic \ref api-tir-fc-array "array"
+ (instances with a linked length field)</em>
<td>#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD
- <td>bt_field_class_array_dynamic_create()
+ <td>
+ - bt_field_class_array_dynamic_create()
+ - bt_field_class_array_dynamic_with_length_field_location_create()
<tr>
<td><em>\ref api-tir-fc-struct "Structure"</em>
<td>#BT_FIELD_CLASS_TYPE_STRUCTURE
<td>bt_field_class_structure_create()
<tr>
- <td><em>\ref api-tir-fc-opt "Option" (no selector field)</em>
+ <td>
+ <em>\ref api-tir-fc-opt "Option"
+ (instances without a linked selector field)</em>
<td>#BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD
- <td>bt_field_class_option_without_selector_create()
+ <td>
+ - bt_field_class_option_without_selector_create()
+ - bt_field_class_option_without_selector_field_location_create()
<tr>
- <td><em>\ref api-tir-fc-opt "Option" (boolean selector field)</em>
+ <td>
+ <em>\ref api-tir-fc-opt "Option"
+ (instances with a linked boolean selector field)</em>
<td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD
- <td>bt_field_class_option_with_selector_field_bool_create()
+ <td>
+ - bt_field_class_option_with_selector_field_bool_create()
+ - bt_field_class_option_with_selector_field_location_bool_create()
<tr>
- <td><em>\ref api-tir-fc-opt "Option" (unsigned integer selector field)</em>
+ <td>
+ <em>\ref api-tir-fc-opt "Option"
+ (instances with a linked unsigned integer selector field)</em>
<td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
- <td>bt_field_class_option_with_selector_field_integer_unsigned_create()
+ <td>
+ - bt_field_class_option_with_selector_field_integer_unsigned_create()
+ - bt_field_class_option_with_selector_field_location_integer_unsigned_create()
<tr>
- <td><em>\ref api-tir-fc-opt "Option" (signed integer selector field)</em>
+ <td>
+ <em>\ref api-tir-fc-opt "Option"
+ (instances with a linked signed integer selector field)</em>
<td>#BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD
- <td>bt_field_class_option_with_selector_field_integer_signed_create()
+ <td>
+ - bt_field_class_option_with_selector_field_integer_signed_create()
+ - bt_field_class_option_with_selector_field_location_integer_signed_create()
<tr>
- <td><em>\ref api-tir-fc-var "Variant" (no selector field)</em>
+ <td>
+ <em>\ref api-tir-fc-var "Variant"
+ (instances without a linked selector field)</em>
<td>#BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD
- <td>bt_field_class_variant_create()
+ <td>
+ - bt_field_class_variant_create()
+ - bt_field_class_variant_without_selector_field_location_create()
<tr>
- <td><em>\ref api-tir-fc-var "Variant" (unsigned integer selector field)</em>
+ <td>
+ <em>\ref api-tir-fc-var "Variant"
+ (instances with a linked unsigned integer selector field)</em>
<td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD
- <td>bt_field_class_variant_create()
+ <td>
+ - bt_field_class_variant_create()
+ - bt_field_class_variant_with_selector_field_location_integer_unsigned_create()
<tr>
- <td><em>\ref api-tir-fc-var "Variant" (signed integer selector field)</em>
+ <td>
+ <em>\ref api-tir-fc-var "Variant"
+ (instances with a linked signed integer selector field)</em>
<td>#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD
- <td>bt_field_class_variant_create()
+ <td>
+ - bt_field_class_variant_create()
+ - bt_field_class_variant_with_selector_field_location_integer_signed_create()
</table>
You need a \bt_trace_cls to create a field class: create one from a
with the passed field class or with any of its contained field
classes.
-- If any of the field classes recursively contained in the passed
- field class has a \ref api-tir-fc-link "link to another field class",
- it must honor the field class link rules.
+- If an instance of any of the field classes recursively contained in
+ the passed field class has a
+ \ref api-tir-fc-link "link to an anterior field", it must
+ honor the field link rules.
Once you have called one of the four functions above, the passed field
class becomes \ref api-fund-freezing "frozen".
<dt>Dynamic array field class</dt>
<dd>
- Its instances (dynamic array fields) contain a variable number array
+ Its instances (dynamic array fields) contain a variable number
of fields.
- There are two types of dynamic array field classes: without or
- with a length field. See
- \ref api-tir-fc-link "Field classes with links to other field classes"
+ There are two types of dynamic array field classes: instances
+ without or with a linked length field. See
+ \ref api-tir-fc-link "Fields with links to other fields"
to learn more.
- @image html darray-link.png "Dynamic array field class with a length field."
+ @image html darray-link.png "A dynamic array field linked to an unsigned integer length field."
+
+ Create with, depending on the effective \bt_mip (MIP) version of the
+ trace processing \bt_graph:
+
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>bt_field_class_array_dynamic_create().</dt>
- Create with bt_field_class_array_dynamic_create().
+ <dt>MIP 1</dt>
+ <dd>
+ bt_field_class_array_dynamic_without_length_field_location_create()
+ or
+ bt_field_class_array_dynamic_with_length_field_location_create().
+ </dd>
+ </dl>
- A dynamic array field class with a length field has the
- specific property:
+ The class of a dynamic array field with a linked length field has
+ one of the following specific properties, depending on the
+ effective MIP version of the trace processing graph:
<dl>
<dt>
\anchor api-tir-fc-darray-prop-len-fp
- Length field path
+ MIP 0: Length field path
</dt>
<dd>
- Field path of the linked length field class.
+ \bt_c_field_path to locate the linked length field of
+ an instance.
- Get a dynamic array field class's length field path with
+ Borrow a dynamic array field class's length field path with
bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const().
</dd>
+
+ <dt>
+ \anchor api-tir-fc-darray-prop-len-fl
+ MIP 1: Length field location
+ </dt>
+ <dd>
+ \bt_c_field_loc to locate the linked length field of an
+ instance.
+
+ Borrow a dynamic array field class's length field location with
+ bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const().
+ </dd>
</dl>
</dd>
</dl>
is created.
Borrow an array field class's element field class with
- Use bt_field_class_array_borrow_element_field_class() and
+ bt_field_class_array_borrow_element_field_class() and
bt_field_class_array_borrow_element_field_class_const().
</dd>
</dl>
<strong><em>Option field classes</em></strong> are classes
of \bt_p_opt_field.
-An option field either does or doesn't contain a field, called its
+An option field either does or doesn't \em contain a field, called its
optional field.
An option field class is an \em abstract field class: you cannot create
-one. An option field class either has a selector field (it's linked to a
-selector field class; see
-\ref api-tir-fc-link "Field classes with links to other field classes")
+one. An instance of an option field class either has a linked selector
+field (see \ref api-tir-fc-link "Fields with links to other fields")
or none. Therefore, the concrete option field classes are:
<dl>
- <dt>Option field class without a selector field</dt>
+ <dt>Option field class (instances without a linked selector field)</dt>
<dd>
- Create with bt_field_class_option_without_selector_create().
+ Create with, depending on the effective \bt_mip (MIP) version
+ of the trace processing \bt_graph:
+
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>bt_field_class_option_without_selector_create()</dt>
- An option field class without a selector field has no specific
- properties.
+ <dt>MIP 1</dt>
+ <dd>bt_field_class_option_without_selector_field_location_create()</dd>
+ </dl>
+
+ The class of an option field without a linked selector field has no
+ specific properties.
</dd>
- <dt>Option field class with a boolean selector field</dt>
+ <dt>Option field class (instances with a linked boolean selector field)</dt>
<dd>
The linked selector field of an option field class's instance
(an option field) is a \bt_bool_field.
- Consequently, the option field class's selector field class is
- a \bt_bool_fc.
-
@image html opt-link.png "Option field class with a boolean selector field."
- Create with bt_field_class_option_with_selector_field_bool_create().
+ Create with, depending on the effective \bt_mip (MIP) version:
+
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>bt_field_class_option_with_selector_field_bool_create()</dt>
+
+ <dt>MIP 1</dt>
+ <dd>bt_field_class_option_with_selector_field_location_bool_create()</dd>
+ </dl>
- An option field class with a boolean selector field has the
- following specific property:
+ The class of an option field with a linked boolean selector field
+ has the following specific property:
<dl>
<dt>
Selector is reversed?
</dt>
<dd>
- Whether or not the linked boolean selector field makes the
- option field class's instance (an option field) contain a field
- when it's #BT_TRUE or when it's #BT_FALSE.
+ Whether or not the linked boolean selector field make the
+ option field class's instance (an option field) \em contain a
+ field when it's #BT_TRUE or when it's #BT_FALSE.
If this property is #BT_TRUE, then if the linked selector field
has the value #BT_FALSE, the option field contains a field.
</dl>
</dd>
- <dt>Option field class with an unsigned selector field</dt>
+ <dt>Option field class (instances with a linked unsigned integer selector field)</dt>
<dd>
The linked selector field of an option field class's instance
(an option field) is an \bt_uint_field.
- Consequently, the option field class's selector field class is
- an \bt_uint_fc.
+ Create with, depending on the effective \bt_mip (MIP) version
+ of the trace processing \bt_graph:
+
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>bt_field_class_option_with_selector_field_integer_unsigned_create()</dt>
- Create with
- bt_field_class_option_with_selector_field_integer_unsigned_create().
+ <dt>MIP 1</dt>
+ <dd>bt_field_class_option_with_selector_field_location_integer_unsigned_create()</dd>
+ </dl>
Pass an \bt_uint_rs on creation to set which values of the selector
field can make the option field contain a field.
- An option field class with an unsigned integer selector field has
- the following specific property:
+ The class of an option field with a linked unsigned integer selector
+ field has the following specific property:
<dl>
<dt>
If the linked unsigned integer selector field of an option
field class's instance (an option field) has a value which
intersects with the selector's unsigned integer ranges, then
- the option field contains a field.
+ the option field \em contains a field.
You cannot change the selector's unsigned integer ranges once
the option field class is created.
- Borrow the selector's unsigned integer ranges from an
- option field class with an unsigned integer selector field with
+ Borrow the selector's unsigned integer ranges from such an
+ option field class with
bt_field_class_option_with_selector_field_integer_unsigned_borrow_selector_ranges_const().
</dd>
</dl>
</dd>
- <dt>Option field class with a signed selector field</dt>
+ <dt>Option field class (instances with a linked signed integer selector field)</dt>
<dd>
The linked selector field of an option field class's instance
(an option field) is a \bt_sint_field.
- Consequently, the option field class's selector field class is
- a \bt_sint_fc.
+ Create with, depending on the effective \bt_mip (MIP) version of
+ the trace processing \bt_graph:
+
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>bt_field_class_option_with_selector_field_integer_signed_create()</dt>
- Create with
- bt_field_class_option_with_selector_field_integer_signed_create().
+ <dt>MIP 1</dt>
+ <dd>bt_field_class_option_with_selector_field_location_integer_signed_create()</dd>
+ </dl>
Pass a \bt_sint_rs on creation to set which values of the selector
field can make the option field contain a field.
- An option field class with a signed integer selector field has
- the following specific property:
+ The class of an option field class with a linked signed integer
+ selector field has the following specific property:
<dl>
<dt>
If the linked signed integer selector field of an option
field class's instance (an option field) has a value which
intersects with the selector's signed integer ranges, then
- the option field contains a field.
+ the option field \em contains a field.
You cannot change the selector's signed integer ranges once
the option field class is created.
- Borrow the selector's signed integer ranges from an
- option field class with a signed integer selector field with
+ Borrow the selector's signed integer ranges from such an
+ option field class with
bt_field_class_option_with_selector_field_integer_signed_borrow_selector_ranges_const().
</dd>
</dl>
</dd>
</dl>
-Option field classes with a selector have the following common
-property:
+The classes of option fields with a linked selector field have one of
+the following common properties, depending on the effective
+\bt_mip (MIP) version of the trace processing \bt_graph:
<dl>
<dt>
\anchor api-tir-fc-opt-prop-sel-fp
- Selector field path
+ MIP 0: Selector field path
</dt>
<dd>
- Field path of the linked selector field class.
+ \bt_c_field_path to locate the linked selector field of an instance.
Borrow such an option field class's selector field path with
bt_field_class_option_with_selector_field_borrow_selector_field_path_const().
</dd>
+
+ <dt>
+ \anchor api-tir-fc-opt-prop-sel-fl
+ MIP 1: Selector field location
+ </dt>
+ <dd>
+ \bt_c_field_loc to locate the linked selector field of an instance.
+
+ Borrow such an option field class's selector field location with
+ bt_field_class_option_with_selector_field_borrow_selector_field_location_const().
+ </dd>
</dl>
Option field classes have the following common property:
class is created.
Borrow an option field class's optional field class with
- Use bt_field_class_option_borrow_field_class() and
+ bt_field_class_option_borrow_field_class() and
bt_field_class_option_borrow_field_class_const().
</dd>
</dl>
ranges, depending on the exact type.
A variant field class is an \em abstract field class: you cannot create
-one. A variant field class either has a selector field (it's linked to a
-selector field class; see
-\ref api-tir-fc-link "Field classes with links to other field classes")
+one. An instance of a variant field class either has a linked selector
+field (see \ref api-tir-fc-link "Fields with links to other fields")
or none. Therefore, the concrete variant field classes are:
<dl>
- <dt>Variant field class without a selector field</dt>
+ <dt>Variant field class (instances without a linked selector field)</dt>
<dd>
- Create with bt_field_class_variant_create(), passing \c NULL as
- the selector field class.
+ Create with, depending on the effective \bt_mip (MIP) version
+ of the trace processing \bt_graph:
+
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>
+ bt_field_class_variant_create(), passing \c NULL as
+ the selector field class.
+ </dt>
+
+ <dt>MIP 1</dt>
+ <dd>bt_field_class_variant_without_selector_field_location_create().</dd>
+ </dl>
Append an option to such a variant field class with
bt_field_class_variant_without_selector_append_option().
- A variant field class without a selector field has no specific
- properties.
+ The class of a variant field without a linked selector field has no
+ specific properties.
</dd>
- <dt>Variant field class with an unsigned selector field</dt>
+ <dt>Variant field class (instances with a linked unsigned selector field)</dt>
<dd>
The linked selector field of a variant field class's instance
(a variant field) is an \bt_uint_field.
- Consequently, the variant field class's selector field class is
- an \bt_uint_fc.
+ @image html var-link.png "A variant field linked to an unsigned integer selector field."
+
+ Create with, depending on the effective \bt_mip (MIP) version of the
+ trace processing \bt_graph:
- @image html var-link.png "Variant field class with an unsigned integer selector field."
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>
+ bt_field_class_variant_create(), passing an unsigned integer
+ field class as the selector field class.
+ </dt>
- Create with bt_field_class_variant_create(), passing an
- unsigned integer field class as the selector field class.
+ <dt>MIP 1</dt>
+ <dd>bt_field_class_variant_with_selector_field_location_integer_unsigned_create().</dd>
+ </dl>
Append an option to such a variant field class with
bt_field_class_variant_with_selector_field_integer_unsigned_append_option().
bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const().
</dd>
- <dt>Variant field class with a signed selector field</dt>
+ <dt>Variant field class (instances with a linked signed selector field)</dt>
<dd>
The linked selector field of a variant field class's instance
(a variant field) is a \bt_sint_field.
- Consequently, the variant field class's selector field class is
- a \bt_sint_fc.
+ Create with, depending on the effective \bt_mip (MIP) version of the
+ trace processing \bt_graph:
+
+ <dl>
+ <dt>MIP 0</dt>
+ <dd>
+ bt_field_class_variant_create(), passing an signed integer
+ field class as the selector field class.
+ </dt>
- Create with bt_field_class_variant_create(), passing a
- signed integer field class as the selector field class.
+ <dt>MIP 1</dt>
+ <dd>bt_field_class_variant_with_selector_field_location_integer_signed_create().</dd>
+ </dl>
Append an option to such a variant field class with
bt_field_class_variant_with_selector_field_integer_signed_append_option().
</dd>
</dl>
-Variant field classes with a selector have the following common
-property:
+The classes of variant fields with a linked selector field have one of
+the following common properties, depending on the effective
+\bt_mip (MIP) version of the trace processing \bt_graph:
<dl>
<dt>
\anchor api-tir-fc-var-prop-sel-fp
- Selector field path
+ MIP 0: Selector field path
</dt>
<dd>
- Field path of the linked selector field class.
+ \bt_c_field_path to locate the linked selector field of an instance.
Borrow such a variant field class's selector field path with
bt_field_class_variant_with_selector_field_borrow_selector_field_path_const().
</dd>
+
+ <dt>
+ \anchor api-tir-fc-var-prop-sel-fl
+ MIP 1: Selector field location
+ </dt>
+ <dd>
+ \bt_c_field_loc to locate the linked selector field of an instance.
+
+ Borrow such a variant field class's selector field location with
+ bt_field_class_variant_with_selector_field_borrow_selector_field_location_const().
+ </dd>
</dl>
Variant field classes have the following common property:
- A field class.
- User attributes.
- If the variant field class is linked to a selector field class, then
- each option also has an \bt_int_rs. In that case, the ranges of a
- given option cannot overlap any range of any other option.
+ If an instance of the variant field class is linked to a selector
+ field, then each option also has an \bt_int_rs. In that case, the
+ ranges of a given option cannot overlap any range of any other
+ option.
A variant field class must contain at least one option.
- Depending on whether or not the variant field class has a selector
- field class, append an option to a variant field class
- with bt_field_class_variant_without_selector_append_option(),
+ Depending on whether or not an instance of the variant field class
+ has a linked selector field, append an option to a variant field
+ class with bt_field_class_variant_without_selector_append_option(),
bt_field_class_variant_with_selector_field_integer_unsigned_append_option(),
or
bt_field_class_variant_with_selector_field_integer_signed_append_option().
bt_field_class_variant_option_borrow_field_class() and
bt_field_class_variant_option_borrow_field_class_const().
- Borrow the option of a variant field classes with a selector field
- class with
+ Borrow the option of the class of a variant field with a linked
+ selector field with
bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_index_const(),
bt_field_class_variant_with_selector_field_integer_unsigned_borrow_option_by_name_const(),
bt_field_class_variant_with_selector_field_integer_signed_borrow_option_by_index_const(), or
or
bt_field_class_variant_with_selector_field_integer_signed_option_as_option_const().
- Borrow the option's ranges from a variant field class with a
- selector field class with
+ Borrow the option's ranges from the class of a variant field with a
+ linked selector field with
bt_field_class_variant_with_selector_field_integer_unsigned_option_borrow_ranges_const()
or
bt_field_class_variant_with_selector_field_integer_signed_option_borrow_ranges_const().
</dd>
</dl>
-<h1>\anchor api-tir-fc-link Field classes with links to other field classes</h1>
-
-\bt_cp_darray_fc, \bt_p_opt_fc, and \bt_p_var_fc \em can have links to
-other, preceding field classes.
+<h1>\anchor api-tir-fc-link Fields with links to other fields</h1>
-When a field class A has a link to another field class B, then
-an instance (\bt_field) of A has a link to an instance of B.
+An instance of a \bt_darray_fc, a \bt_opt_fc, or a \bt_var_fc \em may
+have a link to another, anterior field within the same \bt_pkt or
+\bt_ev.
This feature exists so that the linked field can contain the value of a
-dynamic property of the field. Those properties are:
+dynamic property of the "dependent" field. Those properties are:
<dl>
<dt>\bt_c_darray_field</dt>
</dd>
</dl>
-Having a linked field class is <em>optional</em>: you always set the
-field properties with a dedicated function anyway. For example, even if
-a dynamic array field is linked to a preceding length field, you must
-still set its length with bt_field_array_dynamic_set_length(). In that
-case, the value of the length field must match what you pass to
-bt_field_array_dynamic_set_length().
+Having a linked field is <em>optional</em>: you always set the field
+properties with a dedicated function anyway. For example, even if a
+dynamic array field is linked to an anterior length field, you must
+still set its integral length with bt_field_array_dynamic_set_length().
+In that case, the value of the linked length field \em must match what
+you pass to bt_field_array_dynamic_set_length().
The purpose of this feature is to eventually save space when a
-\bt_sink_comp writes trace files: if the trace format can convey that
-a preceding, existing field represents the length of a dynamic array
-field, then the sink component doesn't need to write the dynamic array
-field's length twice. This is the case of the
-<a href="https://diamon.org/ctf/">Common Trace Format</a>, for
-example.
-
-@image html darray-link.png "A dynamic array field class linked to an unsigned integer field class."
-
-To link a field class A to a preceding field class B, pass
-field class B when you create field class A. For example, pass
-the \bt_uint_fc to bt_field_class_array_dynamic_create() to create a
-\bt_darray_fc with a length field.
-
-When you call bt_stream_class_set_packet_context_field_class(),
-bt_stream_class_set_event_common_context_field_class(),
-bt_event_class_set_specific_context_field_class(), or
-bt_event_class_set_payload_field_class() with a field class containing
-a field class A with a linked field class B, the path to
-B becomes available in A. The functions to borrow this field path are:
-
-- bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
-- bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
-- bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
-
-A field path indicates how to reach a linked field from a given
-root <em>scope</em>. The available scopes are:
+\bt_sink_comp writes trace files: if, for example, the trace format can
+convey that an anterior, existing field represents the length of a
+dynamic array field, then the sink component doesn't need to write the
+dynamic array field's length twice. This is the case of the
+<a href="https://diamon.org/ctf/">Common Trace Format</a>, for example.
+
+@image html darray-link.png "A dynamic array field linked to an unsigned integer length field."
+
+How exactly you link a dependent field to another field at the field
+class level depends on the effective \bt_mip (MIP) version of the trace
+processing \bt_graph:
+
+<dl>
+ <dt>MIP 0: \bt_c_field_path API
+ <dd>
+ Pass the class of the linked field when you create the class of the
+ dependent field.
+
+ For example, pass the unsigned integer length field class to
+ bt_field_class_array_dynamic_create() to create a class of
+ \bt_darray_field with a linked length field.
+
+ Then, when you call
+ bt_stream_class_set_packet_context_field_class(),
+ bt_stream_class_set_event_common_context_field_class(),
+ bt_event_class_set_specific_context_field_class(), or
+ bt_event_class_set_payload_field_class() with a field class
+ containing a dependent field class with the class a linked field,
+ the path to the linked field becomes available in the dependent
+ field class. The functions to borrow said field path are:
+
+ - bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const()
+ - bt_field_class_option_with_selector_field_borrow_selector_field_path_const()
+ - bt_field_class_variant_with_selector_field_borrow_selector_field_path_const()
+ </dd>
+
+ <dt>MIP 1: \bt_c_field_loc API
+ <dd>
+ Pass the field location when you create the class of the
+ dependent field.
+
+ For example, pass the length field location to
+ bt_field_class_array_dynamic_with_length_field_location_create() to
+ create a class of \bt_darray_field with a linked length field.
+
+ The functions to borrow the field location of a field class are:
+
+ - bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const()
+ - bt_field_class_option_with_selector_field_borrow_selector_field_location_const()
+ - bt_field_class_variant_with_selector_field_borrow_selector_field_location_const()
+ </dd>
+</dl>
+
+Both \bt_p_field_path (MIP 0 API) and \bt_p_field_loc (MIP 1
+API) indicate how to reach the linked field of a dependent field from
+some specific root <em>scope</em> (the starting point). The available
+scopes are:
<dl>
<dt>#BT_FIELD_PATH_SCOPE_PACKET_CONTEXT</dt>
+ <dt>#BT_FIELD_LOCATION_SCOPE_PACKET_CONTEXT</dt>
<dd>
- Packet context field.
+ Context field of the current \bt_pkt.
See bt_packet_borrow_context_field_const().
</dd>
<dt>#BT_FIELD_PATH_SCOPE_EVENT_COMMON_CONTEXT</dt>
+ <dt>#BT_FIELD_LOCATION_SCOPE_EVENT_COMMON_CONTEXT</dt>
<dd>
- Event common context field.
+ Common context field of the current \bt_ev.
See bt_event_borrow_common_context_field_const().
</dd>
<dt>#BT_FIELD_PATH_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
+ <dt>#BT_FIELD_LOCATION_SCOPE_EVENT_SPECIFIC_CONTEXT</dt>
<dd>
- Event specific context field.
+ Specific context field of the current event.
See bt_event_borrow_specific_context_field_const().
</dd>
<dt>#BT_FIELD_PATH_SCOPE_EVENT_PAYLOAD</dt>
+ <dt>#BT_FIELD_LOCATION_SCOPE_EVENT_PAYLOAD</dt>
<dd>
- Event payload field.
+ Payload field of the current event.
See bt_event_borrow_payload_field_const().
</dd>
</dl>
-The rules regarding field class A vs. field class B (linked
-field class) are:
+The difference between a field path and a field location is that a field
+path works with \bt_struct_field member \em indexes while a field
+location works with structure field member <em>names</em>. The latter is
+more versatile because many fields may be candidates for the
+length/selector field of a dependent field (when they're all part of the
+same \bt_var_field).
-- If A is within a packet context field class, B must also be in the
- same packet context field class.
+The rules regarding the dependent field \bt_var{A} vs. the linked
+field \bt_var{B} are:
+
+- If \bt_var{A} is within some packet context field, then \bt_var{B}
+ must also be in the same packet context field.
See bt_stream_class_set_packet_context_field_class().
-- If A is within a event common context field class, B must be in one
- of:
+- If \bt_var{A} is within some common event context field, then
+ \bt_var{B} must be in one of:
- - The same event common context field class.
- - The packet context field class of the same \bt_stream_cls.
+ - The same common event context field.
+ - The context field of the same packet.
See bt_stream_class_set_event_common_context_field_class().
-- If A is within an event specific context field class, B must be in
- one of:
+- If \bt_var{A} is within some specific event context field, then
+ \bt_var{B} must be in one of:
- - The same event specific context field class.
- - The event common context field class of the same stream class.
- - The packet context field class of the same stream class.
+ - The same specific event context field.
+ - The common context field of the same event.
+ - The context field of the same packet.
See bt_event_class_set_specific_context_field_class().
-- If A is within an event payload field class, B must be in one of:
+- If \bt_var{A} is within some event payload field, then \bt_var{B} must
+ be in one of:
- - The same event payload field class.
- - The event specific context field class of the same \bt_ev_cls.
- - The event common context field class of the same stream class.
- - The packet context field class of the same stream class.
+ - The same event payload field.
+ - The specific context field of the same event.
+ - The common context field of the same event.
+ - The context field of the same packet.
See bt_event_class_set_payload_field_class().
-- If both A and B are in the same scope, then:
+- If both \bt_var{A} and \bt_var{B} are in the same scope, then:
+
+ - The lowest common ancestor field of \bt_var{A} and \bt_var{B} must
+ be a structure field.
+
+ - \bt_var{B} must precede \bt_var{A}.
+
+ Considering that the members of a structure field are ordered,
+ then \bt_var{B} must be part of a member that's before the member
+ which contains \bt_var{A} in their lowest common ancestor
+ structure field.
- - The lowest common ancestor field class of A and B must be a
- \bt_struct_fc.
+ - <strong>Under MIP 0</strong>, the path from the lowest common
+ ancestor structure field of \bt_var{A} and \bt_var{B} to \bt_var{A}
+ and to \bt_var{B} must only contain structure fields.
- - B must precede A.
+ - <strong>Under MIP 1</strong>, the path from the lowest common
+ ancestor structure field of \bt_var{A} and \bt_var{B} to \bt_var{A}
+ and to \bt_var{B} must only contain structure and variant fields.
- Considering that the members of a structure field class are ordered,
- then B must be part of a member that's before the member which
- contains A in their lowest common ancestor structure field class.
+- If \bt_var{A} is in a different scope than \bt_var{B}, then:
- - The path from the lowest common ancestor structure field class of A
- and B to A and to B must only contain structure field classes.
+ - <strong>Under MIP 0</strong>, the path from the root scope of
+ \bt_var{B} to \bt_var{B} must only contain structure fields.
-- If A is in a different scope than B, the path from the root scope of B
- to B must only contain structure field classes.
+ - <strong>Under MIP 1</strong>, the path from the root scope of
+ \bt_var{B} to \bt_var{B} must only contain structure and variant
+ fields.
*/
/*! @{ */
/*!
@brief
- \bt_c_darray_fc (without a length field).
+ \bt_c_darray_fc (instances without a linked length field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
/*!
@brief
- \bt_c_darray_fc (with a length field).
+ \bt_c_darray_fc (instances with a linked length field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY.
/*!
@brief
- \bt_c_opt_fc (without a selector field).
+ \bt_c_opt_fc (instances without a linked selector field).
*/
BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD = (1ULL << 17) | BT_FIELD_CLASS_TYPE_OPTION,
/*!
@brief
- \bt_c_opt_fc (with a selector field).
+ \bt_c_opt_fc (instances with a linked selector field).
This type conceptually inherits #BT_FIELD_CLASS_TYPE_OPTION.
/*!
@brief
- \bt_c_opt_fc (with a boolean selector field).
+ \bt_c_opt_fc (instances with a linked boolean selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
/*!
@brief
- \bt_c_opt_fc (with an integer selector field).
+ \bt_c_opt_fc (instances with a linked integer selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_OPTION_WITH_SELECTOR_FIELD.
/*!
@brief
- \bt_c_opt_fc (with an unsigned integer selector field).
+ \bt_c_opt_fc (instances with a linked unsigned integer selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
/*!
@brief
- \bt_c_opt_fc (with a signed integer selector field).
+ \bt_c_opt_fc (instances with a linked signed integer selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_OPTION_WITH_INTEGER_SELECTOR_FIELD.
/*!
@brief
- \bt_c_var_fc (without a selector field).
+ \bt_c_var_fc (instances without a linked selector field).
*/
BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD = (1ULL << 24) | BT_FIELD_CLASS_TYPE_VARIANT,
/*!
@brief
- \bt_c_var_fc (with a selector field).
+ \bt_c_var_fc (instances with a linked selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_VARIANT.
/*!
@brief
- \bt_c_var_fc (with an integer selector field).
+ \bt_c_var_fc (instances with a linked integer selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_VARIANT_WITH_SELECTOR_FIELD.
/*!
@brief
- \bt_c_opt_fc (with an unsigned integer selector field).
+ \bt_c_opt_fc (instances with a linked unsigned integer selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
/*!
@brief
- \bt_c_opt_fc (with a signed integer selector field).
+ \bt_c_opt_fc (instances with a linked signed integer selector field).
This type conceptually inherits
#BT_FIELD_CLASS_TYPE_VARIANT_WITH_INTEGER_SELECTOR_FIELD.
@bt_pre_not_null{trace_class}
@bt_pre_not_null{element_field_class}
-bt_pre_fc_not_in_tc{element_field_class}
+@bt_pre_fc_not_in_tc{element_field_class}
@bt_post_success_frozen{element_field_class}
*/
Creates a \bt_darray_fc having the element field class
\bt_p{element_field_class} from the trace class \bt_p{trace_class}.
-If \bt_p{length_field_class} is not \c NULL, then the created dynamic
-array field class has a linked length field class.
-See
-\ref api-tir-fc-link "Field classes with links to other field classes"
+@note
+ @parblock
+ This function is only available when \bt_p{trace_class} was created
+ from a \bt_self_comp which belongs to a trace processing \bt_graph
+ with the effective \bt_mip version 0.
+
+ To create a dynamic array field class from a trace class which was
+ created from a self component which belongs to a trace processing
+ graph with the effective MIP version 1, use
+ bt_field_class_array_dynamic_without_length_field_location_create()
+ or bt_field_class_array_dynamic_with_length_field_location_create().
+ @endparblock
+
+If \bt_p{length_field_class} is not \c NULL, then an instance of
+the created dynamic array field class has a linked length field.
+See \ref api-tir-fc-link "Fields with links to other fields"
to learn more.
On success, the returned dynamic array field class has the following
field class to create.
@param[in] length_field_class
@parblock
- Linked length field class of the dynamic array field class to
- create.
+ Class of a linked length field of an instance of the dynamic array
+ field class to create.
Can be \c NULL.
@endparblock
@bt_post_success_frozen{element_field_class}
@bt_post_success_frozen{length_field_class}
+
+@sa bt_field_class_array_dynamic_without_length_field_location_create() —
+ Creates a class of dynamic array field without a linked length field
+ (\bt_mip version 1).
+@sa bt_field_class_array_dynamic_with_length_field_location_create() —
+ Creates a class of dynamic array field with a linked length field
+ (\bt_mip version 1).
*/
extern bt_field_class *bt_field_class_array_dynamic_create(
bt_trace_class *trace_class,
bt_field_class *element_field_class,
bt_field_class *length_field_class) __BT_NOEXCEPT;
+/*!
+@brief
+ Creates a \bt_darray_fc (instances without a linked length field)
+ having the element field class \bt_p{element_field_class} from the
+ trace class \bt_p{trace_class}.
+
+On success, the returned dynamic array field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
+ <td>\bt_p{element_field_class}
+ <tr>
+ <td>\ref api-tir-fc-darray-prop-len-fl "Length field location"
+ <td>
+ \em None
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a dynamic array field class.
+@param[in] element_field_class
+ Class of the element fields of the instances of the dynamic array
+ field class to create.
+
+@returns
+ New dynamic array field class reference (without a length field),
+ or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+@bt_pre_not_null{element_field_class}
+@bt_pre_fc_not_in_tc{element_field_class}
+
+@bt_post_success_frozen{element_field_class}
+
+@sa bt_field_class_array_dynamic_with_length_field_location_create() —
+ Creates a class of dynamic array field with a linked length field.
+*/
+extern bt_field_class *bt_field_class_array_dynamic_without_length_field_location_create(
+ bt_trace_class *trace_class,
+ bt_field_class *element_field_class);
+
/*! @} */
/*!
-@name Dynamic array field class with length field
+@name Dynamic array field class: instances with linked length field
@{
*/
/*!
@brief
- Borrows the length field path from the \bt_darray_fc (with a length
- field) \bt_p{field_class}.
+ Creates a \bt_darray_fc (instances with a linked length field)
+ having the element field class \bt_p{element_field_class} and the
+ length \bt_field_loc \bt_p{length_field_location} from the
+ trace class \bt_p{trace_class}.
+
+On success, the returned dynamic array field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-array-prop-elem-fc "Element field class"
+ <td>\bt_p{element_field_class}
+ <tr>
+ <td>\ref api-tir-fc-darray-prop-len-fl "Length field location"
+ <td>
+ \bt_p{length_field_location}.
+
+ See \ref api-tir-fc-link "Fields with links to other fields"
+ to learn more.
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a dynamic array field class.
+@param[in] element_field_class
+ Class of the element fields of the instances of the dynamic array
+ field class to create.
+@param[in] length_field_location
+ Length field location of the dynamic array field class to create.
+
+@returns
+ New dynamic array field class reference (instances with a linked
+ length field), or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+@bt_pre_not_null{element_field_class}
+@bt_pre_fc_not_in_tc{element_field_class}
+@bt_pre_not_null{length_field_location}
+
+@bt_post_success_frozen{element_field_class}
+
+@sa bt_field_class_array_dynamic_without_length_field_location_create() —
+ Creates a class of dynamic array field without a linked
+ length field.
+*/
+extern bt_field_class *bt_field_class_array_dynamic_with_length_field_location_create(
+ bt_trace_class *trace_class,
+ bt_field_class *element_field_class,
+ const bt_field_location *length_field_location);
+
+/*!
+@brief
+ Borrows the length field path from the \bt_darray_fc (instances with
+ a linked length field) \bt_p{field_class}.
See the \ref api-tir-fc-darray-prop-len-fp "length field path" property.
-This property is only available when a \bt_struct_fc containing
-(recursively) \bt_p{field_class} is passed to one of:
+This property is only available when all the following are true:
+
+- \bt_p{field_class} was created with
+ bt_field_class_array_dynamic_create() with \bt_p{length_field_class}
+ set to an \bt_uint_fc (not \c NULL).
-- bt_stream_class_set_packet_context_field_class()
-- bt_stream_class_set_event_common_context_field_class()
-- bt_event_class_set_specific_context_field_class()
-- bt_event_class_set_payload_field_class()
+- A \bt_struct_fc containing (recursively) \bt_p{field_class} is passed
+ to one of:
-In the meantime, this function returns \c NULL.
+ - bt_stream_class_set_packet_context_field_class()
+ - bt_stream_class_set_event_common_context_field_class()
+ - bt_event_class_set_specific_context_field_class()
+ - bt_event_class_set_payload_field_class()
+
+ In the meantime, this function returns \c NULL.
@param[in] field_class
Dynamic array field class from which to borrow the length
bt_field_class_array_dynamic_with_length_field_borrow_length_field_path_const(
const bt_field_class *field_class) __BT_NOEXCEPT;
+/*!
+@brief
+ Borrows the length field location from the \bt_darray_fc (instances
+ with a linked length field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-darray-prop-len-fl "length field location"
+property.
+
+This property is only available when \bt_p{field_class} was created
+with bt_field_class_array_dynamic_with_length_field_location_create().
+
+@param[in] field_class
+ Dynamic array field class from which to borrow the length
+ field location.
+
+@returns
+ Length field location of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_darray_wl_fc{field_class}
+@bt_pre_fc_with_mip{field_class, 1}
+*/
+extern const bt_field_location *
+bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const(
+ const bt_field_class *field_class);
+
/*! @} */
/*!
/*! @} */
/*!
-@name Option field class without a selector field
+@name Option field class: instances without a linked selector field
@{
*/
/*!
@brief
- Creates an \bt_opt_fc (without a selector field) having the optional
- field class \bt_p{optional_field_class} from the trace class
- \bt_p{trace_class}.
+ Creates an \bt_opt_fc (instances without a linked selector field)
+ having the optional field class \bt_p{optional_field_class} from the
+ trace class \bt_p{trace_class}.
+
+@note
+ @parblock
+ This function is only available when \bt_p{trace_class} was created
+ from a \bt_self_comp which belongs to a trace processing \bt_graph
+ with the effective \bt_mip version 0.
+
+ To create a similar option field class from a trace class which was
+ created from a self component which belongs to a trace processing
+ graph with the effective MIP version 1, use
+ bt_field_class_option_without_selector_field_location_create().
+ @endparblock
On success, the returned option field class has the following property
values:
New option field class reference, or \c NULL on memory error.
@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 0}
@bt_pre_not_null{optional_field_class}
@bt_pre_fc_not_in_tc{optional_field_class}
@bt_post_success_frozen{optional_field_class}
+
+@sa bt_field_class_option_without_selector_field_location_create() —
+ Creates a class of option field without a linked selector field
+ (\bt_mip version 1).
*/
extern bt_field_class *bt_field_class_option_without_selector_create(
bt_trace_class *trace_class,
bt_field_class *optional_field_class) __BT_NOEXCEPT;
-/*! @} */
-
-/*!
-@name Option field class with a selector field
-@{
-*/
-
-/*!
-@brief
- Borrows the selector field path from the \bt_opt_fc (with a selector
- field) \bt_p{field_class}.
-
-See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
-
-This property is only available when a \bt_struct_fc containing
-(recursively) \bt_p{field_class} is passed to one of:
-
-- bt_stream_class_set_packet_context_field_class()
-- bt_stream_class_set_event_common_context_field_class()
-- bt_event_class_set_specific_context_field_class()
-- bt_event_class_set_payload_field_class()
-
-In the meantime, this function returns \c NULL.
-
-@param[in] field_class
- Option field class from which to borrow the selector field path.
-
-@returns
- Selector field path of \bt_p{field_class}.
-
-@bt_pre_not_null{field_class}
-@bt_pre_is_opt_ws_fc{field_class}
-@bt_pre_fc_with_mip{field_class, 0}
-*/
-extern const bt_field_path *
-bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
- const bt_field_class *field_class) __BT_NOEXCEPT;
-
-/*! @} */
-
-/*!
-@name Option field class with a boolean selector field
-@{
-*/
-
/*!
@brief
- Creates an \bt_opt_fc (with a boolean selector field) having the
- optional field class \bt_p{optional_field_class} from the trace
- class \bt_p{trace_class}.
+ Creates an \bt_opt_fc (instances without a linked selector
+ field) having the optional field class \bt_p{optional_field_class}
+ from the trace class \bt_p{trace_class}.
On success, the returned option field class has the following property
values:
<tr>
<td>\ref api-tir-fc-opt-prop-fc "Optional field class"
<td>\bt_p{optional_field_class}
- <tr>
- <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
- <td>
- \em None (this property becomes available when the returned field
- class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
- <tr>
- <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
- <td>#BT_FALSE
<tr>
<td>\ref api-tir-fc-prop-user-attrs "User attributes"
<td>Empty \bt_map_val
@param[in] optional_field_class
Class of the optional fields of the instances of the option field
class to create.
-@param[in] selector_field_class
- Linked selector field class of the option field class to create.
@returns
New option field class reference, or \c NULL on memory error.
@bt_pre_not_null{trace_class}
-@bt_pre_tc_with_mip{trace_class, 0}
+@bt_pre_tc_with_mip{trace_class, 1}
@bt_pre_not_null{optional_field_class}
@bt_pre_fc_not_in_tc{optional_field_class}
-@bt_pre_not_null{selector_field_class}
-@pre
- \bt_p{selector_field_class} is a \bt_bool_fc.
@bt_post_success_frozen{optional_field_class}
-@bt_post_success_frozen{selector_field_class}
+
+@sa bt_field_class_option_with_selector_field_location_bool_create() —
+ Creates a class of option field with a linked boolean selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
+ Creates a class of option field with a linked unsigned integer
+ selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
+ Creates a class of option field with a linked signed integer
+ selector field.
+*/
+extern bt_field_class *bt_field_class_option_without_selector_field_location_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class) __BT_NOEXCEPT;
+
+/*! @} */
+
+/*!
+@name Option field class: instances with a linked selector field
+@{
+*/
+
+/*!
+@brief
+ Borrows the selector field path from the \bt_opt_fc (instances
+ with a linked selector field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-opt-prop-sel-fp "selector field path" property.
+
+This property is only available when all the following are true:
+
+- \bt_p{field_class} was created with
+ bt_field_class_option_with_selector_field_bool_create(),
+ bt_field_class_option_with_selector_field_integer_unsigned_create(),
+ or bt_field_class_option_with_selector_field_integer_signed_create().
+
+- A \bt_struct_fc containing (recursively) \bt_p{field_class} is passed
+ to one of:
+
+ - bt_stream_class_set_packet_context_field_class()
+ - bt_stream_class_set_event_common_context_field_class()
+ - bt_event_class_set_specific_context_field_class()
+ - bt_event_class_set_payload_field_class()
+
+ In the meantime, this function returns \c NULL.
+
+@param[in] field_class
+ Option field class from which to borrow the selector field path.
+
+@returns
+ Selector field path of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_ws_fc{field_class}
+@bt_pre_fc_with_mip{field_class, 0}
+*/
+extern const bt_field_path *
+bt_field_class_option_with_selector_field_borrow_selector_field_path_const(
+ const bt_field_class *field_class) __BT_NOEXCEPT;
+
+/*!
+@brief
+ Borrows the selector field location from the \bt_opt_fc (instances
+ with a linked selector field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-opt-prop-sel-fl "selector field location"
+property.
+
+This property is only available when \bt_p{field_class} was created
+with bt_field_class_option_with_selector_field_location_bool_create(),
+
+
+@param[in] field_class
+ Option field class from which to borrow the selector field location.
+
+@returns
+ Selector field location of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_opt_ws_fc{field_class}
+@bt_pre_fc_with_mip{field_class, 1}
+*/
+extern const bt_field_location *
+bt_field_class_option_with_selector_field_borrow_selector_field_location_const(
+ const bt_field_class *field_class) __BT_NOEXCEPT;
+
+/*! @} */
+
+/*!
+@name Option field class: instances with a linked boolean selector field
+@{
+*/
+
+/*!
+@brief
+ Creates an \bt_opt_fc (instances with a linked boolean selector
+ field) having the optional field class \bt_p{optional_field_class}
+ from the trace class \bt_p{trace_class}.
+
+@note
+ @parblock
+ This function is only available when \bt_p{trace_class} was created
+ from a \bt_self_comp which belongs to a trace processing \bt_graph
+ with the effective \bt_mip version 0.
+
+ To create a similar option field class from a trace class which was
+ created from a self component which belongs to a trace processing
+ graph with the effective MIP version 1, use
+ bt_field_class_option_with_selector_field_location_bool_create().
+ @endparblock
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-fp "Selector field path"
+ <td>
+ \em None (this property becomes available when the returned field
+ class becomes part of an \bt_ev_cls or of a \bt_stream_cls)
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
+ <td>#BT_FALSE
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+@param[in] selector_field_class
+ Class of a linked boolean selector field of an instance of the
+ option field class to create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 0}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_class}
+@pre
+ \bt_p{selector_field_class} is a \bt_bool_fc.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+
+@sa bt_field_class_option_with_selector_field_location_bool_create() —
+ Creates a class of option field with a linked boolean selector field
+ (\bt_mip version 1).
*/
extern bt_field_class *bt_field_class_option_with_selector_field_bool_create(
bt_trace_class *trace_class,
bt_field_class *optional_field_class,
bt_field_class *selector_field_class) __BT_NOEXCEPT;
+/*!
+@brief
+ Creates an \bt_opt_fc (instances with a linked boolean selector
+ field) having the optional field class \bt_p{optional_field_class}
+ and the selector \bt_field_loc \bt_p{selector_field_location} from
+ the trace class \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-fl "Selector field location"
+ <td>
+ \bt_p{selector_field_location}.
+
+ See \ref api-tir-fc-link "Fields with links to other fields"
+ to learn more.
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-rev "Selector is reversed?"
+ <td>#BT_FALSE
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+@param[in] selector_field_location
+ Selector field location of the option field class to create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_location}
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{selector_field_class}
+
+@sa bt_field_class_option_without_selector_field_location_create() —
+ Creates a class of option field without a linked selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
+ Creates a class of option field with a linked unsigned integer
+ selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
+ Creates a class of option field with a linked signed integer
+ selector field.
+*/
+extern bt_field_class *bt_field_class_option_with_selector_field_location_bool_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class,
+ const bt_field_location *selector_field_location) __BT_NOEXCEPT;
+
/*!
@brief
Sets whether or not the selector of the \bt_opt_fc (with a boolean
/*! @} */
/*!
-@name Option field class with an unsigned integer selector field
+@name Option field class: instances with a linked unsigned integer selector field
@{
*/
/*!
@brief
- Creates an \bt_opt_fc (with an unsigned integer selector field)
- having the optional field class \bt_p{optional_field_class} from the
- trace class \bt_p{trace_class}.
+ Creates an \bt_opt_fc (instances with a linked unsigned integer
+ selector field) having the optional field class
+ \bt_p{optional_field_class} from the trace class \bt_p{trace_class}.
+
+@note
+ @parblock
+ This function is only available when \bt_p{trace_class} was created
+ from a \bt_self_comp which belongs to a trace processing \bt_graph
+ with the effective \bt_mip version 0.
+
+ To create a similar option field class from a trace class which was
+ created from a self component which belongs to a trace processing
+ graph with the effective MIP version 1, use
+ bt_field_class_option_with_selector_field_location_integer_unsigned_create().
+ @endparblock
On success, the returned option field class has the following property
values:
@bt_pre_fc_not_in_tc{optional_field_class}
@bt_pre_not_null{selector_field_class}
@pre
- \bt_p{selector_field_class} is a \bt_uint_fc.
+ \bt_p{selector_field_class} is an \bt_uint_fc.
@bt_pre_not_null{ranges}
@pre
\bt_p{ranges} contains one or more \bt_p_uint_rg.
@bt_post_success_frozen{optional_field_class}
@bt_post_success_frozen{selector_field_class}
@bt_post_success_frozen{ranges}
+
+@sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
+ Creates a class of option field with a linked unsigned integer
+ selector field (\bt_mip version 1).
*/
extern bt_field_class *
bt_field_class_option_with_selector_field_integer_unsigned_create(
const bt_integer_range_set_unsigned *ranges)
__BT_NOEXCEPT;
+/*!
+@brief
+ Creates an \bt_opt_fc (instances with a linked unsigned integer
+ selector field) having the optional field class
+ \bt_p{optional_field_class} and the selector \bt_field_loc
+ \bt_p{selector_field_location} from the trace class
+ \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-fl "Selector field location"
+ <td>
+ \bt_p{selector_field_location}.
+
+ See \ref api-tir-fc-link "Fields with links to other fields"
+ to learn more.
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's unsigned integer ranges"
+ <td>\bt_p{ranges}
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+@param[in] selector_field_location
+ Selector field location of the option field class to create.
+@param[in] ranges
+ Selector's unsigned integer ranges of the option field class to
+ create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_location}
+@bt_pre_not_null{ranges}
+@pre
+ \bt_p{ranges} contains one or more \bt_p_uint_rg.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{ranges}
+
+@sa bt_field_class_option_without_selector_field_location_create() —
+ Creates a class of option field without a linked selector field.
+@sa bt_field_class_option_with_selector_field_location_bool_create() —
+ Creates a class of option field with a linked boolean selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
+ Creates a class of option field with a linked signed integer
+ selector field.
+*/
+extern bt_field_class *
+bt_field_class_option_with_selector_field_location_integer_unsigned_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class,
+ const bt_field_location *selector_field_location,
+ const bt_integer_range_set_unsigned *ranges) __BT_NOEXCEPT;
+
/*!
@brief
Borrows the \bt_p_uint_rg from the \bt_opt_fc (with an unsigned
/*! @} */
/*!
-@name Option field class with a signed integer selector field
+@name Option field class: instances with a linked signed integer selector field
@{
*/
/*!
@brief
- Creates an \bt_opt_fc (with a signed integer selector field)
- having the optional field class \bt_p{optional_field_class} from the
- trace class \bt_p{trace_class}.
+ Creates an \bt_opt_fc (instances with a linked signed integer
+ selector field) having the optional field class
+ \bt_p{optional_field_class} from the trace class \bt_p{trace_class}.
+
+@note
+ @parblock
+ This function is only available when \bt_p{trace_class} was created
+ from a \bt_self_comp which belongs to a trace processing \bt_graph
+ with the effective \bt_mip version 0.
+
+ To create a similar option field class from a trace class which was
+ created from a self component which belongs to a trace processing
+ graph with the effective MIP version 1, use
+ bt_field_class_option_with_selector_field_location_integer_signed_create().
+ @endparblock
On success, the returned option field class has the following property
values:
@bt_pre_fc_not_in_tc{optional_field_class}
@bt_pre_not_null{selector_field_class}
@pre
- \bt_p{selector_field_class} is a \bt_uint_fc.
+ \bt_p{selector_field_class} is an \bt_uint_fc.
@bt_pre_not_null{ranges}
@pre
\bt_p{ranges} contains one or more \bt_p_uint_rg.
@bt_post_success_frozen{optional_field_class}
@bt_post_success_frozen{selector_field_class}
@bt_post_success_frozen{ranges}
+
+@sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
+ Creates an option field class with a linked signed integer
+ selector field (\bt_mip version 1).
*/
extern bt_field_class *
bt_field_class_option_with_selector_field_integer_signed_create(
bt_field_class *selector_field_class,
const bt_integer_range_set_signed *ranges) __BT_NOEXCEPT;
+/*!
+@brief
+ Creates an \bt_opt_fc (instances with a linked signed integer
+ selector field) having the optional field class
+ \bt_p{optional_field_class} and the selector \bt_field_loc
+ \bt_p{selector_field_location} from the trace class
+ \bt_p{trace_class}.
+
+On success, the returned option field class has the following property
+values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-fc "Optional field class"
+ <td>\bt_p{optional_field_class}
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-sel-fl "Selector field location"
+ <td>
+ \bt_p{selector_field_location}.
+
+ See \ref api-tir-fc-link "Fields with links to other fields"
+ to learn more.
+ <tr>
+ <td>\ref api-tir-fc-opt-prop-uint-rs "Selector's signed integer ranges"
+ <td>\bt_p{ranges}
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create an option field class.
+@param[in] optional_field_class
+ Class of the optional fields of the instances of the option field
+ class to create.
+@param[in] selector_field_location
+ Selector field location of the option field class to create.
+@param[in] ranges
+ Selector's signed integer ranges of the option field class to
+ create.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+@bt_pre_not_null{optional_field_class}
+@bt_pre_fc_not_in_tc{optional_field_class}
+@bt_pre_not_null{selector_field_location}
+@bt_pre_not_null{ranges}
+@pre
+ \bt_p{ranges} contains one or more \bt_p_uint_rg.
+
+@bt_post_success_frozen{optional_field_class}
+@bt_post_success_frozen{ranges}
+
+@sa bt_field_class_variant_without_selector_field_location_create() —
+ Creates a class of option field without a linked selector field.
+@sa bt_field_class_option_with_selector_field_location_bool_create() —
+ Creates a class of option field with a linked boolean selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
+ Creates a class of option field with a linked unsigned integer
+ selector field.
+*/
+extern bt_field_class *
+bt_field_class_option_with_selector_field_location_integer_signed_create(
+ bt_trace_class *trace_class,
+ bt_field_class *optional_field_class,
+ const bt_field_location *selector_field_class,
+ const bt_integer_range_set_signed *ranges) __BT_NOEXCEPT;
+
/*!
@brief
Borrows the \bt_p_sint_rg from the \bt_opt_fc (with a signed
/*!
@brief
- Creates a \bt_var_fc from the trace class \bt_p{trace_class}.
+ Creates an empty \bt_var_fc from the trace class \bt_p{trace_class}.
+
+@note
+ @parblock
+ This function is only available when \bt_p{trace_class} was created
+ from a \bt_self_comp which belongs to a trace processing \bt_graph
+ with the effective \bt_mip version 0.
+
+ To create a variant field class from a trace class which was
+ created from a self component which belongs to a trace processing
+ graph with the effective MIP version 1, use
+ bt_field_class_variant_without_selector_field_location_create(),
+ bt_field_class_variant_with_selector_field_location_integer_unsigned_create(),
+ or bt_field_class_variant_with_selector_field_location_integer_signed_create().
+ @endparblock
-If \bt_p{selector_field_class} is not \c NULL, then the created variant
-field class has a linked selector field class.
-See
-\ref api-tir-fc-link "Field classes with links to other field classes"
+If \bt_p{selector_field_class} is not \c NULL, then an instance of
+the created variant field class has a linked selector field.
+See \ref api-tir-fc-link "Fields with links to other fields"
to learn more.
On success, the returned variant field class has the following
Trace class from which to create a variant field class.
@param[in] selector_field_class
@parblock
- Linked selector field class of the variant field class to create.
+ Class of a linked selector field of an instance of the variant field
+ class to create.
Can be \c NULL.
@endparblock
@bt_post_success_frozen{element_field_class}
@bt_post_success_frozen{selector_field_class}
+
+@sa bt_field_class_variant_without_selector_field_location_create() —
+ Creates a class of variant field without a linked selector field
+ (\bt_mip version 1).
+@sa bt_field_class_variant_with_selector_field_location_integer_unsigned_create() —
+ Creates a class of variant field with a linked unsigned integer
+ selector field (\bt_mip version 1).
+@sa bt_field_class_variant_with_selector_field_location_integer_signed_create() —
+ Creates a class of variant field with a linked signed integer
+ selector field (\bt_mip version 1).
*/
extern bt_field_class *bt_field_class_variant_create(
bt_trace_class *trace_class,
/*! @} */
/*!
-@name Variant field class without a selector field
+@name Variant field class: instances without a linked selector field
@{
*/
+/*!
+@brief
+ Creates an empty \bt_var_fc (instances without a linked
+ selector field) from the trace class \bt_p{trace_class}.
+
+On success, the returned variant field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-var-prop-sel-fp "Selector field location"
+ <td>
+ \em None
+ <tr>
+ <td>\ref api-tir-fc-var-prop-opts "Options"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a variant field class.
+
+@returns
+ New option field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+
+@sa bt_field_class_variant_with_selector_field_location_integer_unsigned_create() —
+ Creates a class of variant field with a linked unsigned integer
+ selector field.
+@sa bt_field_class_variant_with_selector_field_location_integer_signed_create() —
+ Creates a class of variant field with a linked signed integer
+ selector field.
+*/
+extern bt_field_class *bt_field_class_variant_without_selector_field_location_create(
+ bt_trace_class *trace_class) __BT_NOEXCEPT;
+
/*!
@brief
Status codes for
/*!
@brief
- Appends an option to the \bt_var_fc (without a selector field)
- \bt_p{field_class} having the name \bt_p{name} and the
- field class \bt_p{option_field_class}.
+ Appends an option to the \bt_var_fc (instances without a linked
+ selector field) \bt_p{field_class} having the name \bt_p{name} and
+ the field class \bt_p{option_field_class}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*! @} */
/*!
-@name Variant field class with a selector field
+@name Variant field class: instances with a linked selector field
@{
*/
/*!
@brief
- Borrows the selector field path from the \bt_var_fc (with a selector
- field) \bt_p{field_class}.
+ Borrows the selector field path from the \bt_var_fc (instances with
+ a linked selector field) \bt_p{field_class}.
See the \ref api-tir-fc-var-prop-sel-fp "selector field path" property.
-This property is only available when a \bt_struct_fc containing
-(recursively) \bt_p{field_class} is passed to one of:
+This property is only available when all the following are true:
+
+- \bt_p{field_class} was created with
+ bt_field_class_variant_create() with \bt_p{selector_field_class}
+ set to an \bt_int_fc (not \c NULL).
+
+- A \bt_struct_fc containing (recursively) \bt_p{field_class} is passed
+ to one of:
-- bt_stream_class_set_packet_context_field_class()
-- bt_stream_class_set_event_common_context_field_class()
-- bt_event_class_set_specific_context_field_class()
-- bt_event_class_set_payload_field_class()
+ - bt_stream_class_set_packet_context_field_class()
+ - bt_stream_class_set_event_common_context_field_class()
+ - bt_event_class_set_specific_context_field_class()
+ - bt_event_class_set_payload_field_class()
-In the meantime, this function returns \c NULL.
+ In the meantime, this function returns \c NULL.
@param[in] field_class
Variant field class from which to borrow the selector field path.
bt_field_class_variant_with_selector_field_borrow_selector_field_path_const(
const bt_field_class *field_class) __BT_NOEXCEPT;
+/*!
+@brief
+ Borrows the selector field location from the \bt_var_fc (instances
+ with a linked selector field) \bt_p{field_class}.
+
+See the \ref api-tir-fc-var-prop-sel-fl "selector field location"
+property.
+
+This property is only available when \bt_p{field_class} was created with
+bt_field_class_variant_with_selector_field_location_integer_unsigned_create()
+or
+bt_field_class_variant_with_selector_field_location_integer_signed_create().
+
+@param[in] field_class
+ Option field class from which to borrow the selector field location.
+
+@returns
+ Selector field location of \bt_p{field_class}.
+
+@bt_pre_not_null{field_class}
+@bt_pre_is_var_ws_fc{field_class}
+@bt_pre_fc_with_mip{field_class, 1}
+*/
+extern const bt_field_location *
+bt_field_class_variant_with_selector_field_borrow_selector_field_location_const(
+ const bt_field_class *field_class);
+
/*! @} */
/*!
-@name Variant field class with an unsigned integer selector field
+@name Variant field class: instances with a linked unsigned integer selector field
@{
*/
/*!
@brief
- Appends an option to the \bt_var_fc (with an unsigned integer
- selector field) \bt_p{field_class} having the name \bt_p{name},
- the field class \bt_p{option_field_class}, and the
+ Creates an empty \bt_var_fc (instances with a linked
+ unsigned integer selector field) having the
+ selector \bt_field_loc \bt_p{selector_field_location}
+ from the trace class \bt_p{trace_class}.
+
+On success, the returned variant field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-var-prop-sel-fp "Selector field location"
+ <td>
+ \bt_p{selector_field_location}.
+
+ See \ref api-tir-fc-link "Fields with links to other fields"
+ to learn more.
+ <tr>
+ <td>\ref api-tir-fc-var-prop-opts "Options"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a variant field class.
+@param[in] selector_field_location
+ Selector field location of the variant field class to create.
+
+@returns
+ New variant field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+@bt_pre_not_null{selector_field_location}
+
+@sa bt_field_class_variant_without_selector_field_location_create() —
+ Creates a class of variant field without a linked selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_signed_create() —
+ Creates a class of variant field with a linked signed integer
+ selector field.
+*/
+extern bt_field_class *bt_field_class_variant_with_selector_field_location_integer_unsigned_create(
+ bt_trace_class *trace_class,
+ const bt_field_location *selector_field_location) __BT_NOEXCEPT;
+
+/*!
+@brief
+ Appends an option to the \bt_var_fc (instances with a linked
+ unsigned integer selector field) \bt_p{field_class} having the name
+ \bt_p{name}, the field class \bt_p{option_field_class}, and the
\bt_p_uint_rg \bt_p{ranges}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*!
@brief
Borrows the option at index \bt_p{index} from the
- \bt_var_fc (with an unsigned integer selector field)
+ \bt_var_fc (instances with a linked unsigned integer selector field)
\bt_p{field_class}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*!
@brief
Borrows the option having the name \bt_p{name} from the
- \bt_var_fc (with an unsigned integer selector field)
+ \bt_var_fc (instances with a linked unsigned integer selector field)
\bt_p{field_class}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*! @} */
/*!
-@name Variant field class (with an unsigned integer selector field) option
+@name Variant field class option: instances with a linked unsigned integer selector field
@{
*/
@typedef struct bt_field_class_variant_with_selector_field_integer_unsigned_option bt_field_class_variant_with_selector_field_integer_unsigned_option;
@brief
- Variant field class (with an unsigned integer selector field) option.
+ Variant field class option (instances with a linked unsigned integer selector field).
*/
/*!
@brief
- Borrows the \bt_p_uint_rg from the \bt_var_fc (with an unsigned
- integer selector field) option \bt_p{option}.
+ Borrows the \bt_p_uint_rg from the \bt_var_fc option
+ (instances with a linked unsigned integer selector field)
+ \bt_p{option}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*!
@brief
- \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with an
- unsigned integer selector field) option \bt_p{option} to the
+ \ref api-fund-c-typing "Upcasts" the \bt_var_fc option (instances
+ with a linked unsigned integer selector field) \bt_p{option} to the
common #bt_field_class_variant_option type.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*! @} */
/*!
-@name Variant field class with a signed integer selector field
+@name Variant field class: instances with a linked signed integer selector field
@{
*/
/*!
@brief
- Appends an option to the \bt_var_fc (with a signed integer
- selector field) \bt_p{field_class} having the name \bt_p{name},
- the field class \bt_p{option_field_class}, and the
+ Creates an empty \bt_var_fc (instances with a linked
+ signed integer selector field) having the
+ selector \bt_field_loc \bt_p{selector_field_location}
+ from the trace class \bt_p{trace_class}.
+
+On success, the returned variant field class has the following
+property values:
+
+<table>
+ <tr>
+ <th>Property
+ <th>Value
+ <tr>
+ <td>\ref api-tir-fc-var-prop-sel-fp "Selector field location"
+ <td>
+ \bt_p{selector_field_location}.
+
+ See \ref api-tir-fc-link "Fields with links to other fields"
+ to learn more.
+ <tr>
+ <td>\ref api-tir-fc-var-prop-opts "Options"
+ <td>\em None
+ <tr>
+ <td>\ref api-tir-fc-prop-user-attrs "User attributes"
+ <td>Empty \bt_map_val
+</table>
+
+@param[in] trace_class
+ Trace class from which to create a variant field class.
+@param[in] selector_field_location
+ Selector field location of the variant field class to create.
+
+@returns
+ New variant field class reference, or \c NULL on memory error.
+
+@bt_pre_not_null{trace_class}
+@bt_pre_tc_with_mip{trace_class, 1}
+@bt_pre_not_null{selector_field_location}
+
+@sa bt_field_class_variant_without_selector_field_location_create() —
+ Creates a class of variant field without a linked selector field.
+@sa bt_field_class_option_with_selector_field_location_integer_unsigned_create() —
+ Creates a class of variant field with a linked unsigned integer
+ selector field.
+*/
+extern bt_field_class *bt_field_class_variant_with_selector_field_location_integer_signed_create(
+ bt_trace_class *trace_class,
+ const bt_field_location *selector_field_location) __BT_NOEXCEPT;
+
+/*!
+@brief
+ Appends an option to the \bt_var_fc (instances with a linked signed
+ integer selector field) \bt_p{field_class} having the name
+ \bt_p{name}, the field class \bt_p{option_field_class}, and the
\bt_p_sint_rg \bt_p{ranges}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*!
@brief
Borrows the option at index \bt_p{index} from the
- \bt_var_fc (with a signed integer selector field)
+ \bt_var_fc (instances with a linked signed integer selector field)
\bt_p{field_class}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*!
@brief
Borrows the option having the name \bt_p{name} from the
- \bt_var_fc (with a signed integer selector field)
+ \bt_var_fc (instances with a linked signed integer selector field)
\bt_p{field_class}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*! @} */
/*!
-@name Variant field class (with a signed integer selector field) option
+@name Variant field class option: instances with a linked signed integer selector field
@{
*/
@typedef struct bt_field_class_variant_with_selector_field_integer_signed_option bt_field_class_variant_with_selector_field_integer_signed_option;
@brief
- Variant field class (with a signed integer selector field) option.
+ Variant field class option (instances with a linked signed integer selector field).
*/
/*!
@brief
- Borrows the \bt_p_sint_rg from the \bt_var_fc (with a signed
- integer selector field) option \bt_p{option}.
+ Borrows the \bt_p_sint_rg from the \bt_var_fc option
+ (instances with a linked signed integer selector field)
+ \bt_p{option}.
See the \ref api-tir-fc-var-prop-opts "options" property.
/*!
@brief
- \ref api-fund-c-typing "Upcasts" the \bt_var_fc (with a signed
- integer selector field) option \bt_p{option} to the
- common #bt_field_class_variant_option type.
+ \ref api-fund-c-typing "Upcasts" the \bt_var_fc option
+ (instances with a linked signed integer selector field)
+ \bt_p{option} to the common #bt_field_class_variant_option type.
See the \ref api-tir-fc-var-prop-opts "options" property.
struct bt_field_class_option_with_selector_field *with_sel_fc =
(void *) obj;
- BT_LOGD_STR("Putting selector field path.");
- BT_OBJECT_PUT_REF_AND_RESET(with_sel_fc->selector_field_path);
- BT_LOGD_STR("Putting selector field class.");
- BT_OBJECT_PUT_REF_AND_RESET(with_sel_fc->selector_fc);
+ switch (with_sel_fc->selector_field_xref_kind) {
+ case FIELD_XREF_KIND_PATH:
+ BT_LOGD_STR("Putting selector field path.");
+ BT_OBJECT_PUT_REF_AND_RESET(with_sel_fc->selector_field.path.path);
+ BT_LOGD_STR("Putting selector field class.");
+ BT_OBJECT_PUT_REF_AND_RESET(with_sel_fc->selector_field.path.class);
+ break;
+ case FIELD_XREF_KIND_LOCATION:
+ BT_LOGD_STR("Putting selector field location.");
+ BT_OBJECT_PUT_REF_AND_RESET(with_sel_fc->selector_field.location);
+ break;
+ };
if (fc->common.type != BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD) {
struct bt_field_class_option_with_selector_field_integer *with_int_sel_fc =
enum bt_field_class_type fc_type,
struct bt_field_class *content_fc,
struct bt_field_class *selector_fc,
+ const struct bt_field_location *selector_fl,
const char *api_func)
{
struct bt_field_class_option *opt_fc = NULL;
- BT_ASSERT_PRE_NO_ERROR_FROM_FUNC(api_func);
- BT_ASSERT_PRE_TC_NON_NULL_FROM_FUNC(api_func, trace_class);
BT_ASSERT_PRE_NON_NULL_FROM_FUNC(api_func, "content-field-class",
content_fc, "Content field class");
+
+ BT_ASSERT(!(selector_fc && selector_fl));
+
BT_LIB_LOGD("Creating option field class: "
"type=%s, %![content-fc-]+F, %![sel-fc-]+F",
bt_common_field_class_type_string(fc_type),
if (fc_type != BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD) {
struct bt_field_class_option_with_selector_field *opt_with_sel_fc = NULL;
- BT_ASSERT_PRE_NON_NULL_FROM_FUNC(api_func,
- "selector-field-class", selector_fc,
- "Selector field class");
+ BT_ASSERT(selector_fc || selector_fl);
if (fc_type == BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD) {
- BT_ASSERT_PRE_FC_HAS_TYPE_FROM_FUNC(api_func,
- "selector-field-class", selector_fc,
- "boolean-field-class", BT_FIELD_CLASS_TYPE_BOOL,
- "Selector field class");
opt_with_sel_fc = (void *) g_new0(
struct bt_field_class_option_with_selector_field_bool, 1);
} else {
- BT_ASSERT_PRE_FC_IS_INT_FROM_FUNC(api_func,
- "selector-field-class",
- selector_fc, "Selector field class");
opt_with_sel_fc = (void *) g_new0(
struct bt_field_class_option_with_selector_field_integer, 1);
}
goto error;
}
- opt_with_sel_fc->selector_fc = selector_fc;
- bt_object_get_ref_no_null_check(opt_with_sel_fc->selector_fc);
+ if (selector_fc) {
+ opt_with_sel_fc->selector_field_xref_kind = FIELD_XREF_KIND_PATH;
+ opt_with_sel_fc->selector_field.path.class = selector_fc;
+ bt_object_get_ref_no_null_check(opt_with_sel_fc->selector_field.path.class);
+ } else {
+ opt_with_sel_fc->selector_field_xref_kind = FIELD_XREF_KIND_LOCATION;
+ opt_with_sel_fc->selector_field.location = selector_fl;
+ bt_object_get_ref_no_null_check(opt_with_sel_fc->selector_field.location);
+ }
+
opt_fc = (void *) opt_with_sel_fc;
} else {
+ BT_ASSERT(!selector_fc);
+ BT_ASSERT(!selector_fl);
+
opt_fc = g_new0(struct bt_field_class_option, 1);
if (!opt_fc) {
BT_LIB_LOGE_APPEND_CAUSE(
bt_field_class_freeze(selector_fc);
}
- BT_LIB_LOGD("Created option field class object: "
- "%![opt-fc-]+F, %![sel-fc-]+F", opt_fc, selector_fc);
goto end;
error:
struct bt_trace_class *trace_class,
struct bt_field_class *content_fc)
{
- return create_option_field_class(trace_class,
+ struct bt_field_class *fc;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
+
+ fc = create_option_field_class(trace_class,
BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD,
- content_fc, NULL, __func__);
+ content_fc, NULL, NULL, __func__);
+
+ BT_LIB_LOGD("Created option field class without selector field class: "
+ "%![opt-fc-]+F", fc);
+
+ return fc;
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_option_without_selector_field_location_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *content_fc)
+{
+ struct bt_field_class *fc;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+
+ fc = create_option_field_class(trace_class,
+ BT_FIELD_CLASS_TYPE_OPTION_WITHOUT_SELECTOR_FIELD,
+ content_fc, NULL, NULL, __func__);
+
+ BT_LIB_LOGD("Created option field class without selector field location: "
+ "%![opt-fc-]+F", fc);
+
+ return fc;
}
BT_EXPORT
struct bt_field_class *content_fc,
struct bt_field_class *selector_fc)
{
+ struct bt_field_class *fc;
+
BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
+ BT_ASSERT_PRE_SELECTOR_FC_NON_NULL(selector_fc);
+ BT_ASSERT_PRE_FC_HAS_TYPE("selector-field-class", selector_fc,
+ "boolean-field-class", BT_FIELD_CLASS_TYPE_BOOL,
+ "Selector field class");
- return create_option_field_class(trace_class,
+ fc = create_option_field_class(trace_class,
BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD,
- content_fc, selector_fc, __func__);
+ content_fc, selector_fc, NULL, __func__);
+
+ BT_LIB_LOGD("Created option field class with boolean selector field class: "
+ "%![opt-fc-]+F, %![sel-fc-]+F", fc, selector_fc);
+
+ return fc;
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_option_with_selector_field_location_bool_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *content_fc,
+ const struct bt_field_location *selector_fl)
+{
+ struct bt_field_class *fc;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+ BT_ASSERT_PRE_SELECTOR_FL_NON_NULL(selector_fl);
+
+ fc = create_option_field_class(trace_class,
+ BT_FIELD_CLASS_TYPE_OPTION_WITH_BOOL_SELECTOR_FIELD,
+ content_fc, NULL, selector_fl, __func__);
+
+ BT_LIB_LOGD("Created option field class with boolean selector field location: "
+ "%![opt-fc-]+F, %![sel-fl-]+L", fc, selector_fl);
+
+ return fc;
}
BT_EXPORT
(const void *) u_range_set;
BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
+ BT_ASSERT_PRE_SELECTOR_FC_NON_NULL(selector_fc);
+ BT_ASSERT_PRE_FC_IS_UNSIGNED_INT("selector-field-class",
+ selector_fc, "Selector field class");
BT_ASSERT_PRE_INT_RANGE_SET_NON_NULL(range_set);
BT_ASSERT_PRE_INT_RANGE_SET_NOT_EMPTY(range_set);
+
fc = (void *) create_option_field_class(trace_class,
BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD,
- content_fc, selector_fc, __func__);
+ content_fc, selector_fc, NULL, __func__);
+ if (!fc) {
+ goto end;
+ }
+
+ fc->range_set = range_set;
+ bt_object_get_ref_no_null_check(fc->range_set);
+ bt_integer_range_set_freeze(range_set);
+
+ BT_LIB_LOGD("Created option field class with unsigned integer selector field class: "
+ "%![opt-fc-]+F, %![sel-fc-]+F", fc, selector_fc);
+
+end:
+ return (void *) fc;
+}
+
+BT_EXPORT
+struct bt_field_class *
+bt_field_class_option_with_selector_field_location_integer_unsigned_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *content_fc,
+ const struct bt_field_location *selector_fl,
+ const struct bt_integer_range_set_unsigned *u_range_set)
+{
+ struct bt_field_class_option_with_selector_field_integer *fc;
+ const struct bt_integer_range_set *range_set =
+ (const void *) u_range_set;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+ BT_ASSERT_PRE_SELECTOR_FL_NON_NULL(selector_fl);
+ BT_ASSERT_PRE_INT_RANGE_SET_NON_NULL(range_set);
+ BT_ASSERT_PRE_INT_RANGE_SET_NOT_EMPTY(range_set);
+ fc = (void *) create_option_field_class(trace_class,
+ BT_FIELD_CLASS_TYPE_OPTION_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD,
+ content_fc, NULL, selector_fl, __func__);
if (!fc) {
goto end;
}
bt_object_get_ref_no_null_check(fc->range_set);
bt_integer_range_set_freeze(range_set);
+ BT_LIB_LOGD("Created option field class with unsigned integer selector field location: "
+ "%![opt-fc-]+F, %![sel-fl-]+L", fc, selector_fl);
+
end:
return (void *) fc;
}
(const void *) i_range_set;
BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
+ BT_ASSERT_PRE_SELECTOR_FC_NON_NULL(selector_fc);
+ BT_ASSERT_PRE_FC_IS_SIGNED_INT("selector-field-class",
+ selector_fc, "Selector field class");
BT_ASSERT_PRE_INT_RANGE_SET_NON_NULL(range_set);
BT_ASSERT_PRE_INT_RANGE_SET_NOT_EMPTY(range_set);
+
fc = (void *) create_option_field_class(trace_class,
BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD,
- content_fc, selector_fc, __func__);
+ content_fc, selector_fc, NULL, __func__);
+ if (!fc) {
+ goto end;
+ }
+ fc->range_set = range_set;
+ bt_object_get_ref_no_null_check(fc->range_set);
+ bt_integer_range_set_freeze(range_set);
+
+ BT_LIB_LOGD("Created option field class with signed integer selector field class: "
+ "%![opt-fc-]+F, %![sel-fc-]+F", fc, selector_fc);
+
+end:
+ return (void *) fc;
+}
+
+BT_EXPORT
+struct bt_field_class *
+bt_field_class_option_with_selector_field_location_integer_signed_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *content_fc,
+ const struct bt_field_location *selector_fl,
+ const struct bt_integer_range_set_signed *i_range_set)
+{
+ struct bt_field_class_option_with_selector_field_integer *fc;
+ const struct bt_integer_range_set *range_set =
+ (const void *) i_range_set;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+ BT_ASSERT_PRE_SELECTOR_FL_NON_NULL(selector_fl);
+ BT_ASSERT_PRE_INT_RANGE_SET_NON_NULL(range_set);
+ BT_ASSERT_PRE_INT_RANGE_SET_NOT_EMPTY(range_set);
+
+ fc = (void *) create_option_field_class(trace_class,
+ BT_FIELD_CLASS_TYPE_OPTION_WITH_SIGNED_INTEGER_SELECTOR_FIELD,
+ content_fc, NULL, selector_fl, __func__);
if (!fc) {
goto end;
}
bt_object_get_ref_no_null_check(fc->range_set);
bt_integer_range_set_freeze(range_set);
+ BT_LIB_LOGD("Created option field class with signed integer selector field location: "
+ "%![opt-fc-]+F, %![sel-fl-]+L", fc, selector_fl);
+
end:
return (void *) fc;
}
BT_ASSERT_PRE_FC_NON_NULL(fc);
BT_ASSERT_PRE_FC_IS_OPTION_WITH_SEL("field-class", fc, "Field class");
BT_ASSERT_PRE_FC_MIP_VERSION_EQ(fc, 0);
- return opt_fc->selector_field_path;
+ BT_ASSERT_DBG(opt_fc->selector_field_xref_kind == FIELD_XREF_KIND_PATH);
+ return opt_fc->selector_field.path.path;
+}
+
+BT_EXPORT
+const struct bt_field_location *
+bt_field_class_option_with_selector_field_borrow_selector_field_location_const(
+ const struct bt_field_class *fc)
+{
+ const struct bt_field_class_option_with_selector_field *opt_fc =
+ (const void *) fc;
+
+ BT_ASSERT_PRE_FC_NON_NULL(fc);
+ BT_ASSERT_PRE_FC_IS_OPTION_WITH_SEL("field-class", fc, "Field class");
+ BT_ASSERT_PRE_FC_MIP_VERSION_GE(fc, 1);
+ BT_ASSERT_DBG(opt_fc->selector_field_xref_kind == FIELD_XREF_KIND_LOCATION);
+ return opt_fc->selector_field.location;
}
BT_EXPORT
BT_ASSERT(fc);
finalize_variant_field_class(&fc->common);
- BT_LOGD_STR("Putting selector field path.");
- BT_OBJECT_PUT_REF_AND_RESET(fc->selector_field_path);
- BT_LOGD_STR("Putting selector field class.");
- BT_OBJECT_PUT_REF_AND_RESET(fc->selector_fc);
+
+ if (fc->selector_field_xref_kind == FIELD_XREF_KIND_PATH) {
+ BT_LOGD_STR("Putting selector field path.");
+ BT_OBJECT_PUT_REF_AND_RESET(fc->selector_field.path.path);
+ BT_LOGD_STR("Putting selector field class.");
+ BT_OBJECT_PUT_REF_AND_RESET(fc->selector_field.path.class);
+ } else {
+ BT_ASSERT(fc->selector_field_xref_kind == FIELD_XREF_KIND_LOCATION);
+ BT_LOGD_STR("Putting selector field location.");
+ BT_OBJECT_PUT_REF_AND_RESET(fc->selector_field.location);
+ }
+
g_free(fc);
}
-BT_EXPORT
-struct bt_field_class *bt_field_class_variant_create(
- bt_trace_class *trace_class, bt_field_class *selector_fc)
+static
+struct bt_field_class *create_variant_field_class(
+ struct bt_trace_class *trace_class,
+ enum bt_field_class_type fc_type,
+ struct bt_field_class *selector_fc,
+ const struct bt_field_location *selector_fl)
{
int ret;
struct bt_field_class_variant *var_fc = NULL;
struct bt_field_class_variant_with_selector_field *var_with_sel_fc = NULL;
- enum bt_field_class_type fc_type;
- BT_ASSERT_PRE_NO_ERROR();
- BT_ASSERT_PRE_TC_NON_NULL(trace_class);
- BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
+ if (fc_type != BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD) {
+ BT_ASSERT((selector_fc && !selector_fl) ||
+ (!selector_fc && selector_fl));
- if (selector_fc) {
- BT_ASSERT_PRE_FC_IS_INT("selector-field-class", selector_fc,
- "Selector field class");
- }
- BT_LIB_LOGD("Creating default variant field class: %![sel-fc-]+F",
- selector_fc);
+ if (selector_fc) {
+ BT_LIB_LOGD("Creating default variant field class with selector field class: %![sel-fc-]+F",
+ selector_fc);
+ } else {
+ BT_LIB_LOGD("Creating default variant field class with selector field location: %![sel-fl-]+L",
+ selector_fl);
+ }
- if (selector_fc) {
var_with_sel_fc = g_new0(
struct bt_field_class_variant_with_selector_field, 1);
if (!var_with_sel_fc) {
goto error;
}
- if (bt_field_class_type_is(selector_fc->type,
- BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER)) {
- fc_type = BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD;
- } else {
- fc_type = BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD;
- }
-
ret = init_named_field_classes_container(
(void *) var_with_sel_fc, fc_type,
destroy_variant_with_selector_field_field_class,
goto error;
}
- var_with_sel_fc->selector_fc = selector_fc;
- bt_object_get_ref_no_null_check(var_with_sel_fc->selector_fc);
- bt_field_class_freeze(selector_fc);
+ if (selector_fc) {
+ var_with_sel_fc->selector_field_xref_kind = FIELD_XREF_KIND_PATH;
+ var_with_sel_fc->selector_field.path.class = selector_fc;
+ bt_object_get_ref_no_null_check(selector_fc);
+ bt_field_class_freeze(selector_fc);
+
+ BT_LIB_LOGD("Created default variant field class with selector field class: "
+ "%![var-fc-]+F, %![sel-fc-]+F", var_with_sel_fc, selector_fc);
+ } else {
+ var_with_sel_fc->selector_field_xref_kind = FIELD_XREF_KIND_LOCATION;
+ var_with_sel_fc->selector_field.location = selector_fl;
+ bt_object_get_ref_no_null_check(var_with_sel_fc->selector_field.location);
+
+ BT_LIB_LOGD("Created default variant field class with selector field location: "
+ "%![var-fc-]+F, %![sel-fl-]+L", var_fc, selector_fl);
+ }
+
var_fc = (void *) var_with_sel_fc;
- BT_LIB_LOGD("Created default variant field class with selector object: "
- "%![var-fc-]+F, %![sel-fc-]+F", var_fc, selector_fc);
} else {
+ BT_LIB_LOGD("Creating default variant field class without selector.");
+
var_fc = g_new0(struct bt_field_class_variant, 1);
if (!var_fc) {
BT_LIB_LOGE_APPEND_CAUSE(
goto error;
}
- ret = init_named_field_classes_container((void *) var_fc,
- BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD,
+ ret = init_named_field_classes_container((void *) var_fc, fc_type,
destroy_variant_field_class, destroy_named_field_class,
trace_class);
if (ret) {
return (void *) var_fc;
}
+BT_EXPORT
+struct bt_field_class *bt_field_class_variant_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *selector_fc)
+{
+ enum bt_field_class_type fc_type;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
+
+ if (selector_fc) {
+ bt_field_class_type selector_fc_type;
+
+ BT_ASSERT_PRE_FC_IS_INT("selector-field-class", selector_fc,
+ "Selector field class");
+
+ selector_fc_type = bt_field_class_get_type(selector_fc);
+
+ if (bt_field_class_type_is(selector_fc_type,
+ BT_FIELD_CLASS_TYPE_UNSIGNED_INTEGER)) {
+ fc_type = BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD;
+ } else {
+ fc_type = BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD;
+ }
+ } else {
+ fc_type = BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD;
+ }
+
+ return create_variant_field_class(trace_class, fc_type, selector_fc, NULL);
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_variant_without_selector_field_location_create(
+ struct bt_trace_class *trace_class)
+{
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+
+ return create_variant_field_class(trace_class,
+ BT_FIELD_CLASS_TYPE_VARIANT_WITHOUT_SELECTOR_FIELD, NULL, NULL);
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_variant_with_selector_field_location_integer_unsigned_create(
+ struct bt_trace_class *trace_class,
+ const struct bt_field_location *selector_fl)
+{
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+ BT_ASSERT_PRE_SELECTOR_FL_NON_NULL(selector_fl);
+
+ return create_variant_field_class(trace_class,
+ BT_FIELD_CLASS_TYPE_VARIANT_WITH_UNSIGNED_INTEGER_SELECTOR_FIELD,
+ NULL, selector_fl);
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_variant_with_selector_field_location_integer_signed_create(
+ struct bt_trace_class *trace_class,
+ const struct bt_field_location *selector_fl)
+{
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+ BT_ASSERT_PRE_SELECTOR_FL_NON_NULL(selector_fl);
+
+ return create_variant_field_class(trace_class,
+ BT_FIELD_CLASS_TYPE_VARIANT_WITH_SIGNED_INTEGER_SELECTOR_FIELD,
+ NULL, selector_fl);
+}
+
#define VAR_FC_OPT_NAME_IS_UNIQUE_ID \
"variant-field-class-option-name-is-unique"
BT_ASSERT_PRE_DEV_FC_IS_VARIANT_WITH_SEL("field-class", fc,
"Field class");
BT_ASSERT_PRE_FC_MIP_VERSION_EQ(fc, 0);
- return var_fc->selector_field_path;
+ BT_ASSERT_DBG(var_fc->selector_field_xref_kind == FIELD_XREF_KIND_PATH);
+ return var_fc->selector_field.path.path;
+}
+
+BT_EXPORT
+const struct bt_field_location *
+bt_field_class_variant_with_selector_field_borrow_selector_field_location_const(
+ const struct bt_field_class *fc)
+{
+ const struct bt_field_class_variant_with_selector_field *var_fc =
+ (const void *) fc;
+
+ BT_ASSERT_PRE_DEV_FC_NON_NULL(fc);
+ BT_ASSERT_PRE_DEV_FC_IS_VARIANT_WITH_SEL("field-class", fc,
+ "Field class");
+ BT_ASSERT_PRE_DEV_FC_MIP_VERSION_GE(fc, 1);
+ BT_ASSERT_DBG(var_fc->selector_field_xref_kind == FIELD_XREF_KIND_LOCATION);
+ return var_fc->selector_field.location;
}
static
BT_ASSERT(fc);
BT_LIB_LOGD("Destroying dynamic array field class object: %!+F", fc);
finalize_array_field_class((void *) fc);
- BT_LOGD_STR("Putting length field path.");
- BT_OBJECT_PUT_REF_AND_RESET(fc->length_field_path);
- BT_LOGD_STR("Putting length field class.");
- BT_OBJECT_PUT_REF_AND_RESET(fc->length_fc);
+
+ if (fc->common.common.type == BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD) {
+ switch (fc->length_field.xref_kind) {
+ case FIELD_XREF_KIND_PATH:
+ BT_LOGD_STR("Putting length field class.");
+ BT_OBJECT_PUT_REF_AND_RESET(fc->length_field.path.class);
+ fc->length_field.path.class = NULL;
+
+ BT_LOGD_STR("Putting length field path.");
+ BT_OBJECT_PUT_REF_AND_RESET(fc->length_field.path.path);
+ fc->length_field.path.path = NULL;
+ break;
+ case FIELD_XREF_KIND_LOCATION:
+ BT_LOGD_STR("Putting length field location.");
+ BT_OBJECT_PUT_REF_AND_RESET(fc->length_field.location);
+ fc->length_field.location = NULL;
+ break;
+ };
+ }
+
g_free(fc);
}
-BT_EXPORT
-struct bt_field_class *bt_field_class_array_dynamic_create(
+static
+struct bt_field_class_array_dynamic *create_dynamic_array_field_class(
struct bt_trace_class *trace_class,
struct bt_field_class *element_fc,
- struct bt_field_class *length_fc)
+ enum bt_field_class_type fc_type,
+ const char *api_func)
{
struct bt_field_class_array_dynamic *array_fc = NULL;
- BT_ASSERT_PRE_NO_ERROR();
- BT_ASSERT_PRE_TC_NON_NULL(trace_class);
- BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
- BT_ASSERT_PRE_NON_NULL("element-field-class", element_fc,
+ BT_ASSERT_PRE_NON_NULL_FROM_FUNC(api_func, "element-field-class", element_fc,
"Element field class");
BT_LOGD_STR("Creating default dynamic array field class object.");
array_fc = g_new0(struct bt_field_class_array_dynamic, 1);
goto error;
}
- if (init_array_field_class((void *) array_fc,
- length_fc ?
- BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD :
- BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD,
+ if (init_array_field_class((void *) array_fc, fc_type,
destroy_dynamic_array_field_class, element_fc,
trace_class)) {
goto error;
}
+ goto end;
+
+error:
+ BT_OBJECT_PUT_REF_AND_RESET(array_fc);
+
+end:
+ return array_fc;
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_array_dynamic_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *element_fc,
+ struct bt_field_class *length_fc)
+{
+ struct bt_field_class_array_dynamic *array_fc = NULL;
+
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_EQ(trace_class, 0);
+
+ array_fc = create_dynamic_array_field_class(trace_class, element_fc,
+ length_fc ?
+ BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD :
+ BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD,
+ __func__);
+ if (!array_fc) {
+ goto error;
+ }
+
if (length_fc) {
+ array_fc->length_field.xref_kind = FIELD_XREF_KIND_PATH;
+
BT_ASSERT_PRE_FC_IS_UNSIGNED_INT("length-field-class",
length_fc, "Length field class");
- array_fc->length_fc = length_fc;
- bt_object_get_ref_no_null_check(array_fc->length_fc);
+ array_fc->length_field.path.class = length_fc;
+ bt_object_get_ref_no_null_check(length_fc);
bt_field_class_freeze(length_fc);
}
BT_LIB_LOGD("Created dynamic array field class object: %!+F", array_fc);
+
+ goto end;
+
+error:
+ BT_OBJECT_PUT_REF_AND_RESET(array_fc);
+
+end:
+ return (void *) array_fc;
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_array_dynamic_without_length_field_location_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *element_field_class)
+{
+ struct bt_field_class_array_dynamic *array_fc = NULL;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+
+ array_fc = create_dynamic_array_field_class(trace_class,
+ element_field_class, BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITHOUT_LENGTH_FIELD,
+ __func__);
+ if (!array_fc) {
+ goto error;
+ }
+
+ BT_LIB_LOGD("Created dynamic array field class without field location object: %!+F",
+ array_fc);
+
+ goto end;
+
+error:
+ BT_OBJECT_PUT_REF_AND_RESET(array_fc);
+
+end:
+ return (void *) array_fc;
+}
+
+BT_EXPORT
+struct bt_field_class *bt_field_class_array_dynamic_with_length_field_location_create(
+ struct bt_trace_class *trace_class,
+ struct bt_field_class *element_field_class,
+ const struct bt_field_location *length_field_location)
+{
+ struct bt_field_class_array_dynamic *array_fc = NULL;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_TC_NON_NULL(trace_class);
+ BT_ASSERT_PRE_FL_NON_NULL(length_field_location);
+ BT_ASSERT_PRE_TC_MIP_VERSION_GE(trace_class, 1);
+
+ array_fc = create_dynamic_array_field_class(trace_class,
+ element_field_class, BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD,
+ __func__);
+ if (!array_fc) {
+ goto error;
+ }
+
+ array_fc->length_field.xref_kind = FIELD_XREF_KIND_LOCATION;
+ array_fc->length_field.location = length_field_location;
+ bt_object_get_ref_no_null_check(length_field_location);
+
+ BT_LIB_LOGD("Created dynamic array field class with field location object: %!+F",
+ array_fc);
+
goto end;
error:
const struct bt_field_class_array_dynamic *seq_fc = (const void *) fc;
BT_ASSERT_PRE_NO_ERROR();
- BT_ASSERT_PRE_DEV_FC_NON_NULL(fc);
+ BT_ASSERT_PRE_FC_NON_NULL(fc);
BT_ASSERT_PRE_FC_HAS_TYPE("field-class", fc,
"dynamic-array-field-class-with-length-field",
BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD,
"Field class");
BT_ASSERT_PRE_FC_MIP_VERSION_EQ(fc, 0);
- return seq_fc->length_field_path;
+ BT_ASSERT_DBG(seq_fc->length_field.xref_kind == FIELD_XREF_KIND_PATH);
+ return seq_fc->length_field.path.path;
+}
+
+BT_EXPORT
+const struct bt_field_location *
+bt_field_class_array_dynamic_with_length_field_borrow_length_field_location_const(
+ const struct bt_field_class *fc)
+{
+ const struct bt_field_class_array_dynamic *seq_fc = (const void *) fc;
+
+ BT_ASSERT_PRE_NO_ERROR();
+ BT_ASSERT_PRE_FC_NON_NULL(fc);
+ BT_ASSERT_PRE_FC_HAS_TYPE("field-class", fc,
+ "dynamic-array-field-class-with-length-field",
+ BT_FIELD_CLASS_TYPE_DYNAMIC_ARRAY_WITH_LENGTH_FIELD,
+ "Field class");
+ BT_ASSERT_PRE_FC_MIP_VERSION_GE(fc, 1);
+ BT_ASSERT_DBG(seq_fc->length_field.xref_kind == FIELD_XREF_KIND_LOCATION);
+ return seq_fc->length_field.location;
}
static
projects / babeltrace.git / commitdiff
