Babeltrace 2 C API
2.1.1
Open-source trace manipulation framework
|
Source, filter, and sink components: nodes in a trace processing graph.
A component is a node within a trace processing graph:
A component is component class instance. Borrow the class of a component with bt_component_borrow_class_const(), bt_component_source_borrow_class_const(), bt_component_filter_borrow_class_const(), and bt_component_sink_borrow_class_const().
A component is a shared object: get a new reference with bt_component_get_ref() and put an existing reference with bt_component_put_ref().
The common C type of a port is bt_component.
There are three types of components, which come from the three types of component classes:
The message iterator of a source component emits fresh messages.
The specific type of a source component is bt_component_source and the type enumerator of its class is BT_COMPONENT_CLASS_TYPE_SOURCE.
Upcast the bt_component_source type to the bt_component type with bt_component_source_as_component_const().
Get a new source component reference with bt_component_source_get_ref() and put an existing one with bt_component_source_put_ref().
A source component has output ports only.
Get the number of output ports a source component has with bt_component_source_get_output_port_count().
Borrow the output port of a source component by index with bt_component_source_borrow_output_port_by_index_const() or by name with bt_component_source_borrow_output_port_by_name_const().
The message iterator of a filter component emits fresh and transformed messages. It can also discard existing messages.
The specific type of a filter component is bt_component_filter and the type enumerator of its class is BT_COMPONENT_CLASS_TYPE_FILTER.
Upcast the bt_component_filter type to the bt_component type with bt_component_filter_as_component_const().
Get a new filter component reference with bt_component_filter_get_ref() and put an existing one with bt_component_filter_put_ref().
A filter component has input ports and output ports.
Get the number of output ports a filter component has with bt_component_filter_get_output_port_count().
Borrow the output port of a filter component by index with bt_component_filter_borrow_output_port_by_index_const() or by name with bt_component_filter_borrow_output_port_by_name_const().
Get the number of input ports a filter component has with bt_component_filter_get_input_port_count().
Borrow the input port of a filter component by index with bt_component_filter_borrow_input_port_by_index_const() or by name with bt_component_filter_borrow_input_port_by_name_const().
A sink component consumes messages from a source or filter message iterator.
The specific type of a filter component is bt_component_sink and the type enumerator of its class is BT_COMPONENT_CLASS_TYPE_SINK.
Upcast the bt_component_sink type to the bt_component type with bt_component_sink_as_component_const().
Get a new sink component reference with bt_component_sink_get_ref() and put an existing one with bt_component_sink_put_ref().
A sink component has input ports only.
Get the number of input ports a sink component has with bt_component_sink_get_input_port_count().
Borrow the input port of a sink component by index with bt_component_sink_borrow_input_port_by_index_const() or by name with bt_component_sink_borrow_input_port_by_name_const().
Get the type enumerator of the class of a componen with bt_component_get_class_type(). You can also use the bt_component_is_source(), bt_component_is_filter(), and bt_component_is_sink() helper functions.
You cannot directly create a component: there are no bt_component_*_create()
functions. A trace processing graph creates a component from a component class when you call one of the bt_graph_add_*_component*()
functions. Those functions also return a borrowed reference of the created component through their component
parameter.
A component has the following common properties:
Name of the component.
Each component has a unique name within a given trace processing graph.
The name of a component is set when you add it to a graph with one of the bt_graph_add_*_component*()
functions (name
parameter); you cannot change it afterwards.
Get the name of a component with bt_component_get_name().
Logging level of the component (and its message iterators, if any).
The logging level of a component is set when you add it to a trace processing graph with one of the bt_graph_add_*_component*()
functions (logging_level
parameter); as of Babeltrace 2.1, you cannot change it afterwards.
Get the logging level of a component with bt_component_get_logging_level().
Modules | |
Ports | |
Component input and output ports. | |
Types | |
typedef struct bt_component | bt_component |
Component. | |
typedef struct bt_component_source | bt_component_source |
Source component. | |
typedef struct bt_component_filter | bt_component_filter |
Filter component. | |
typedef struct bt_component_sink | bt_component_sink |
Sink component. | |
Class type query | |
bt_component_class_type | bt_component_get_class_type (const bt_component *component) |
Returns the type enumerator of the class of the component component . More... | |
static bt_bool | bt_component_is_source (const bt_component *component) |
Returns whether or not the component component is a source component. More... | |
static bt_bool | bt_component_is_filter (const bt_component *component) |
Returns whether or not the component component is a filter component. More... | |
static bt_bool | bt_component_is_sink (const bt_component *component) |
Returns whether or not the component component is a sink component. More... | |
Common class access | |
const bt_component_class * | bt_component_borrow_class_const (const bt_component *component) |
Borrows the class of the component component . More... | |
Common properties | |
const char * | bt_component_get_name (const bt_component *component) |
Returns the name of the component component . More... | |
bt_logging_level | bt_component_get_logging_level (const bt_component *component) |
Returns the logging level of the component component and its message iterators, if any. More... | |
Common reference count | |
void | bt_component_get_ref (const bt_component *component) |
Increments the reference count of the component component . More... | |
void | bt_component_put_ref (const bt_component *component) |
Decrements the reference count of the component component . More... | |
#define | BT_COMPONENT_PUT_REF_AND_RESET(_component) |
Decrements the reference count of the component _component , and then sets _component to NULL . More... | |
#define | BT_COMPONENT_MOVE_REF(_dst, _src) |
Decrements the reference count of the component _dst , sets _dst to _src , and then sets _src to NULL . More... | |
Source component class access | |
const bt_component_class_source * | bt_component_source_borrow_class_const (const bt_component_source *component) |
Borrows the class of the source component component . More... | |
Source component upcast | |
static const bt_component * | bt_component_source_as_component_const (const bt_component_source *component) |
Upcasts the source component component to the common bt_component type. More... | |
Source component port access | |
uint64_t | bt_component_source_get_output_port_count (const bt_component_source *component) |
Returns the number of output ports that the source component component has. More... | |
const bt_port_output * | bt_component_source_borrow_output_port_by_index_const (const bt_component_source *component, uint64_t index) |
Borrows the output port at index index from the source component component . More... | |
const bt_port_output * | bt_component_source_borrow_output_port_by_name_const (const bt_component_source *component, const char *name) |
Borrows the output port named name from the source component component . More... | |
Source component reference count | |
void | bt_component_source_get_ref (const bt_component_source *component) |
Increments the reference count of the source component component . More... | |
void | bt_component_source_put_ref (const bt_component_source *component) |
Decrements the reference count of the source component component . More... | |
#define | BT_COMPONENT_SOURCE_PUT_REF_AND_RESET(_component) |
Decrements the reference count of the source component _component , and then sets _component to NULL . More... | |
#define | BT_COMPONENT_SOURCE_MOVE_REF(_dst, _src) |
Decrements the reference count of the source component _dst , sets _dst to _src , and then sets _src to NULL . More... | |
Filter component class access | |
const bt_component_class_filter * | bt_component_filter_borrow_class_const (const bt_component_filter *component) |
Borrows the class of the filter component component . More... | |
Filter component upcast | |
static const bt_component * | bt_component_filter_as_component_const (const bt_component_filter *component) |
Upcasts the filter component component to the common bt_component type. More... | |
Filter component reference count | |
void | bt_component_filter_get_ref (const bt_component_filter *component) |
Increments the reference count of the filter component component . More... | |
void | bt_component_filter_put_ref (const bt_component_filter *component) |
Decrements the reference count of the filter component component . More... | |
#define | BT_COMPONENT_FILTER_PUT_REF_AND_RESET(_component) |
Decrements the reference count of the filter component _component , and then sets _component to NULL . More... | |
#define | BT_COMPONENT_FILTER_MOVE_REF(_dst, _src) |
Decrements the reference count of the filter component _dst , sets _dst to _src , and then sets _src to NULL . More... | |
Sink component class access | |
const bt_component_class_sink * | bt_component_sink_borrow_class_const (const bt_component_sink *component) |
Borrows the class of the sink component component . More... | |
Sink component upcast | |
static const bt_component * | bt_component_sink_as_component_const (const bt_component_sink *component) |
Upcasts the sink component component to the common bt_component type. More... | |
Sink component port access | |
uint64_t | bt_component_sink_get_input_port_count (const bt_component_sink *component) |
Returns the number of input ports that the sink component component has. More... | |
const bt_port_input * | bt_component_sink_borrow_input_port_by_index_const (const bt_component_sink *component, uint64_t index) |
Borrows the input port at index index from the sink component component . More... | |
const bt_port_input * | bt_component_sink_borrow_input_port_by_name_const (const bt_component_sink *component, const char *name) |
Borrows the output port named name from the sink component component . More... | |
Sink component reference count | |
void | bt_component_sink_get_ref (const bt_component_sink *component) |
Increments the reference count of the sink component component . More... | |
void | bt_component_sink_put_ref (const bt_component_sink *component) |
Decrements the reference count of the sink component component . More... | |
#define | BT_COMPONENT_SINK_PUT_REF_AND_RESET(_component) |
Decrements the reference count of the sink component _component , and then sets _component to NULL . More... | |
#define | BT_COMPONENT_SINK_MOVE_REF(_dst, _src) |
Decrements the reference count of the sink component _dst , sets _dst to _src , and then sets _src to NULL . More... | |
#define BT_COMPONENT_PUT_REF_AND_RESET | ( | _component | ) |
Decrements the reference count of the component _component
, and then sets _component
to NULL
.
_component | Component of which to decrement the reference count. Can contain |
_component
is an assignable expression. #define BT_COMPONENT_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the component _dst
, sets _dst
to _src
, and then sets _src
to NULL
.
This macro effectively moves a component reference from the expression _src
to the expression _dst
, putting the existing _dst
reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
_dst
is an assignable expression. _src
is an assignable expression. #define BT_COMPONENT_SOURCE_PUT_REF_AND_RESET | ( | _component | ) |
Decrements the reference count of the source component _component
, and then sets _component
to NULL
.
_component | Source component of which to decrement the reference count. Can contain |
_component
is an assignable expression. #define BT_COMPONENT_SOURCE_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the source component _dst
, sets _dst
to _src
, and then sets _src
to NULL
.
This macro effectively moves a source component reference from the expression _src
to the expression _dst
, putting the existing _dst
reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
_dst
is an assignable expression. _src
is an assignable expression. #define BT_COMPONENT_FILTER_PUT_REF_AND_RESET | ( | _component | ) |
Decrements the reference count of the filter component _component
, and then sets _component
to NULL
.
_component | Filter component of which to decrement the reference count. Can contain |
_component
is an assignable expression. #define BT_COMPONENT_FILTER_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the filter component _dst
, sets _dst
to _src
, and then sets _src
to NULL
.
This macro effectively moves a filter component reference from the expression _src
to the expression _dst
, putting the existing _dst
reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
_dst
is an assignable expression. _src
is an assignable expression. #define BT_COMPONENT_SINK_PUT_REF_AND_RESET | ( | _component | ) |
Decrements the reference count of the sink component _component
, and then sets _component
to NULL
.
_component | Sink component of which to decrement the reference count. Can contain |
_component
is an assignable expression. #define BT_COMPONENT_SINK_MOVE_REF | ( | _dst, | |
_src | |||
) |
Decrements the reference count of the sink component _dst
, sets _dst
to _src
, and then sets _src
to NULL
.
This macro effectively moves a sink component reference from the expression _src
to the expression _dst
, putting the existing _dst
reference.
_dst | Destination expression. Can contain |
_src | Source expression. Can contain |
_dst
is an assignable expression. _src
is an assignable expression. bt_component_class_type bt_component_get_class_type | ( | const bt_component * | component | ) |
Returns the type enumerator of the class of the component component
.
[in] | component | Component of which to get the type enumerator of its class. |
component
.component
is not NULL
.
|
inlinestatic |
Returns whether or not the component component
is a source component.
[in] | component | Component to check. |
component
is a source component.component
is not NULL
.
|
inlinestatic |
Returns whether or not the component component
is a filter component.
[in] | component | Component to check. |
component
is a filter component.component
is not NULL
.
|
inlinestatic |
Returns whether or not the component component
is a sink component.
[in] | component | Component to check. |
component
is a sink component.component
is not NULL
.const bt_component_class* bt_component_borrow_class_const | ( | const bt_component * | component | ) |
Borrows the class of the component component
.
[in] | component | Component of which to borrow the class. |
component
.component
is not NULL
. const char* bt_component_get_name | ( | const bt_component * | component | ) |
Returns the name of the component component
.
See the name property.
[in] | component | Component of which to get the name. |
Name of component
.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. bt_logging_level bt_component_get_logging_level | ( | const bt_component * | component | ) |
Returns the logging level of the component component
and its message iterators, if any.
See the logging level property.
[in] | component | Component of which to get the logging level. |
component
.component
is not NULL
. void bt_component_get_ref | ( | const bt_component * | component | ) |
Increments the reference count of the component component
.
[in] | component | Component of which to increment the reference count. Can be |
void bt_component_put_ref | ( | const bt_component * | component | ) |
Decrements the reference count of the component component
.
[in] | component | Component of which to decrement the reference count. Can be |
const bt_component_class_source* bt_component_source_borrow_class_const | ( | const bt_component_source * | component | ) |
Borrows the class of the source component component
.
[in] | component | Source component of which to borrow the class. |
component
.component
is not NULL
.
|
inlinestatic |
Upcasts the source component component
to the common bt_component type.
[in] | component | Source component to upcast. Can be |
component
as a common component. uint64_t bt_component_source_get_output_port_count | ( | const bt_component_source * | component | ) |
Returns the number of output ports that the source component component
has.
[in] | component | Source component of which to get the number of output ports. |
component
has.component
is not NULL
. const bt_port_output* bt_component_source_borrow_output_port_by_index_const | ( | const bt_component_source * | component, |
uint64_t | index | ||
) |
Borrows the output port at index index
from the source component component
.
[in] | component | Source component from which to borrow the output port at index index . |
[in] | index | Index of the output port to borrow from component . |
Borrowed reference of the output port of component
at index index
.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. index
is less than the number of output ports component
has (as returned by bt_component_source_get_output_port_count()).const bt_port_output* bt_component_source_borrow_output_port_by_name_const | ( | const bt_component_source * | component, |
const char * | name | ||
) |
Borrows the output port named name
from the source component component
.
If component
has no output port named name
, then this function returns NULL
.
[in] | component | Source component from which to borrow the output port named name . |
[in] | name | Name of the output port to borrow from component . |
Borrowed reference of the output port of component
named name
, or NULL
if none.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. name
is not NULL
. void bt_component_source_get_ref | ( | const bt_component_source * | component | ) |
Increments the reference count of the source component component
.
[in] | component | Source component of which to increment the reference count. Can be |
void bt_component_source_put_ref | ( | const bt_component_source * | component | ) |
Decrements the reference count of the source component component
.
[in] | component | Source component of which to decrement the reference count. Can be |
const bt_component_class_filter* bt_component_filter_borrow_class_const | ( | const bt_component_filter * | component | ) |
Borrows the class of the filter component component
.
[in] | component | Filter component of which to borrow the class. |
component
.component
is not NULL
.
|
inlinestatic |
Upcasts the filter component component
to the common bt_component type.
[in] | component | Filter component to upcast. Can be |
component
as a common component. uint64_t bt_component_filter_get_input_port_count | ( | const bt_component_filter * | component | ) |
Returns the number of input ports that the filter component component
has.
[in] | component | Filter component of which to get the number of input ports. |
component
has.component
is not NULL
. const bt_port_input* bt_component_filter_borrow_input_port_by_index_const | ( | const bt_component_filter * | component, |
uint64_t | index | ||
) |
Borrows the input port at index index
from the filter component component
.
[in] | component | Filter component from which to borrow the input port at index index . |
[in] | index | Index of the input port to borrow from component . |
Borrowed reference of the input port of component
at index index
.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. index
is less than the number of input ports component
has (as returned by bt_component_filter_get_input_port_count()).const bt_port_input* bt_component_filter_borrow_input_port_by_name_const | ( | const bt_component_filter * | component, |
const char * | name | ||
) |
Borrows the input port named name
from the filter component component
.
If component
has no input port named name
, then this function returns NULL
.
[in] | component | Filter component from which to borrow the input port named name . |
[in] | name | Name of the input port to borrow from component . |
Borrowed reference of the input port of component
named name
, or NULL
if none.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. name
is not NULL
. uint64_t bt_component_filter_get_output_port_count | ( | const bt_component_filter * | component | ) |
Returns the number of output ports that the filter component component
has.
[in] | component | Filter component of which to get the number of output ports. |
component
has.component
is not NULL
. const bt_port_output* bt_component_filter_borrow_output_port_by_index_const | ( | const bt_component_filter * | component, |
uint64_t | index | ||
) |
Borrows the output port at index index
from the filter component component
.
[in] | component | Filter component from which to borrow the output port at index index . |
[in] | index | Index of the output port to borrow from component . |
Borrowed reference of the output port of component
at index index
.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. index
is less than the number of output ports component
has (as returned by bt_component_filter_get_output_port_count()).const bt_port_output* bt_component_filter_borrow_output_port_by_name_const | ( | const bt_component_filter * | component, |
const char * | name | ||
) |
Borrows the output port named name
from the filter component component
.
If component
has no output port named name
, then this function returns NULL
.
[in] | component | Filter component from which to borrow the output port named name . |
[in] | name | Name of the output port to borrow from component . |
Borrowed reference of the output port of component
named name
, or NULL
if none.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. name
is not NULL
. void bt_component_filter_get_ref | ( | const bt_component_filter * | component | ) |
Increments the reference count of the filter component component
.
[in] | component | Filter component of which to increment the reference count. Can be |
void bt_component_filter_put_ref | ( | const bt_component_filter * | component | ) |
Decrements the reference count of the filter component component
.
[in] | component | Filter component of which to decrement the reference count. Can be |
const bt_component_class_sink* bt_component_sink_borrow_class_const | ( | const bt_component_sink * | component | ) |
Borrows the class of the sink component component
.
[in] | component | Sink component of which to borrow the class. |
component
.component
is not NULL
.
|
inlinestatic |
Upcasts the sink component component
to the common bt_component type.
[in] | component | Sink component to upcast. Can be |
component
as a common component. uint64_t bt_component_sink_get_input_port_count | ( | const bt_component_sink * | component | ) |
Returns the number of input ports that the sink component component
has.
[in] | component | Sink component of which to get the number of input ports. |
component
has.component
is not NULL
. const bt_port_input* bt_component_sink_borrow_input_port_by_index_const | ( | const bt_component_sink * | component, |
uint64_t | index | ||
) |
Borrows the input port at index index
from the sink component component
.
[in] | component | Sink component from which to borrow the input port at index index . |
[in] | index | Index of the input port to borrow from component . |
Borrowed reference of the input port of component
at index index
.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. index
is less than the number of input ports component
has (as returned by bt_component_sink_get_input_port_count()).const bt_port_input* bt_component_sink_borrow_input_port_by_name_const | ( | const bt_component_sink * | component, |
const char * | name | ||
) |
Borrows the output port named name
from the sink component component
.
If component
has no output port named name
, then this function returns NULL
.
[in] | component | Sink component from which to borrow the output port named name . |
[in] | name | Name of the output port to borrow from component . |
Borrowed reference of the output port of component
named name
, or NULL
if none.
The returned pointer remains valid as long as component
exists.
component
is not NULL
. name
is not NULL
. void bt_component_sink_get_ref | ( | const bt_component_sink * | component | ) |
Increments the reference count of the sink component component
.
[in] | component | Sink component of which to increment the reference count. Can be |
void bt_component_sink_put_ref | ( | const bt_component_sink * | component | ) |
Decrements the reference count of the sink component component
.
[in] | component | Sink component of which to decrement the reference count. Can be |