Detailed Description

Source, filter, and sink component classes (non-development).

A component class is the class of a component:

Attention: This module (component class API) offers basic, read-only functions to get component class properties. To create a component class, see Component class development or Plugin development.

You can instantiate a given component class many times, with different initialization parameters, to create many components with the bt_graph_add_*_component*() functions (see Graph).

There are two ways to obtain a component class:

Create one programatically: see Component class development.
Borrow one from a plugin.

Note that, as of Babeltrace 2.0, you cannot access a component class's plugin, if any.

A component class is a shared object: get a new reference with bt_component_class_get_ref() and put an existing reference with bt_component_class_put_ref().

The common C type of a component class is bt_component_class.

There are three types of component classes:

Source component class

A source component class instance (a source component) message iterator emits fresh messages.

A source component class's specific type is bt_component_class_source and its type enumerator is BT_COMPONENT_CLASS_TYPE_SOURCE.

Upcast the bt_component_class_source type to the bt_component_class type with bt_component_class_source_as_component_class_const().

Get a new source component class reference with Use bt_component_class_source_get_ref() and put an existing one with bt_component_class_source_put_ref().

Filter component class

A filter component class instance (a filter component) message iterator emits fresh and transformed messages. It can also discard existing messages.

A filter component class's specific type is bt_component_class_filter and its type enumerator is BT_COMPONENT_CLASS_TYPE_FILTER.

Upcast the bt_component_class_filter type to the bt_component_class type with bt_component_class_filter_as_component_class_const().

Get a new filter component class reference with bt_component_class_filter_get_ref() and put an existing one with bt_component_class_filter_put_ref().

Sink component class

A sink component class instance (a sink component) consumes messages from a source or filter message iterator.

A filter component class's specific type is bt_component_class_sink and its type enumerator is BT_COMPONENT_CLASS_TYPE_SINK.

Upcast the bt_component_class_sink type to the bt_component_class type with bt_component_class_sink_as_component_class_const().

Get a new sink component class reference with bt_component_class_sink_get_ref() and put an existing one with bt_component_class_sink_put_ref().

Get a component's class type enumerator with bt_component_class_get_type(). You can also use the bt_component_class_is_source(), bt_component_class_is_filter(), and bt_component_class_is_sink() helper functions.

Properties

A component class has the following common properties:

Name

Name of the component class.

Within a plugin, for a given component class type, each component class has a unique name.

Get a component class's name with bt_component_class_get_name().

Optional: Description

Textual description of the component class.

Get a component class's description with bt_component_class_get_description().

Optional: Help text

Help text of the component class.

Get a component class's help text with bt_component_class_get_help().

Types
typedef struct bt_component_class	bt_component_class
	Component class.

typedef struct bt_component_class_source	bt_component_class_source
	Source component class.

typedef struct bt_component_class_filter	bt_component_class_filter
	Filter component class.

typedef struct bt_component_class_sink	bt_component_class_sink
	Sink component class.

Type query
enum	bt_component_class_type { BT_COMPONENT_CLASS_TYPE_SOURCE, BT_COMPONENT_CLASS_TYPE_FILTER, BT_COMPONENT_CLASS_TYPE_SINK }
	Component class type enumerators. More...

typedef enum bt_component_class_type	bt_component_class_type
	Component class type enumerators.

bt_component_class_type	bt_component_class_get_type (const bt_component_class *component_class)
	Returns the type enumerator of the component class component_class. More...

static bt_bool	bt_component_class_is_source (const bt_component_class *component_class)
	Returns whether or not the component class component_class is a source component class. More...

static bt_bool	bt_component_class_is_filter (const bt_component_class *component_class)
	Returns whether or not the component class component_class is a filter component class. More...

static bt_bool	bt_component_class_is_sink (const bt_component_class *component_class)
	Returns whether or not the component class component_class is a sink component class. More...

Properties
const char *	bt_component_class_get_name (const bt_component_class *component_class)
	Returns the name of the component class component_class. More...

const char *	bt_component_class_get_description (const bt_component_class *component_class)
	Returns the description of the component class component_class. More...

const char *	bt_component_class_get_help (const bt_component_class *component_class)
	Returns the help text of the component class component_class. More...

Common reference count
void	bt_component_class_get_ref (const bt_component_class *component_class)
	Increments the reference count of the component class component_class. More...

void	bt_component_class_put_ref (const bt_component_class *component_class)
	Decrements the reference count of the component class component_class. More...

#define	BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class)
	Decrements the reference count of the component class _component_class, and then sets _component_class to `NULL`. More...

#define	BT_COMPONENT_CLASS_MOVE_REF(_dst, _src)
	Decrements the reference count of the component class _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Source component class upcast
static const bt_component_class *	bt_component_class_source_as_component_class_const (const bt_component_class_source *component_class)
	Upcasts the source component class component_class to the common bt_component_class type. More...

Source component class reference count
void	bt_component_class_source_get_ref (const bt_component_class_source *component_class)
	Increments the reference count of the source component class component_class. More...

void	bt_component_class_source_put_ref (const bt_component_class_source *component_class)
	Decrements the reference count of the source component class component_class. More...

#define	BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class)
	Decrements the reference count of the source component class _component_class, and then sets _component_class to `NULL`. More...

#define	BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src)
	Decrements the reference count of the source component class _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Filter component class upcast
static const bt_component_class *	bt_component_class_filter_as_component_class_const (const bt_component_class_filter *component_class)
	Upcasts the filter component class component_class to the common bt_component_class type. More...

Filter component class reference count
void	bt_component_class_filter_get_ref (const bt_component_class_filter *component_class)
	Increments the reference count of the filter component class component_class. More...

void	bt_component_class_filter_put_ref (const bt_component_class_filter *component_class)
	Decrements the reference count of the filter component class component_class. More...

#define	BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class)
	Decrements the reference count of the filter component class _component_class, and then sets _component_class to `NULL`. More...

#define	BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src)
	Decrements the reference count of the filter component class _dst, setsc _dst to _src, and then sets _src to `NULL`. More...

Sink component class upcast
static const bt_component_class *	bt_component_class_sink_as_component_class_const (const bt_component_class_sink *component_class)
	Upcasts the sink component class component_class to the common bt_component_class type. More...

Sink component class reference count
void	bt_component_class_sink_get_ref (const bt_component_class_sink *component_class)
	Increments the reference count of the sink component class component_class. More...

void	bt_component_class_sink_put_ref (const bt_component_class_sink *component_class)
	Decrements the reference count of the sink component class component_class. More...

#define	BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class)
	Decrements the reference count of the sink component class _component_class, and then sets _component_class to `NULL`. More...

#define	BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src)
	Decrements the reference count of the sink component class _dst, sets _dst to _src, and then sets _src to `NULL`. More...

Enumeration Type Documentation

◆ bt_component_class_type

enum bt_component_class_type

Component class type enumerators.

Enumerator
BT_COMPONENT_CLASS_TYPE_SOURCE	Source component class.
BT_COMPONENT_CLASS_TYPE_FILTER	Filter component class.
BT_COMPONENT_CLASS_TYPE_SINK	Sink component class.

Macro Definition Documentation

◆ BT_COMPONENT_CLASS_PUT_REF_AND_RESET

#define BT_COMPONENT_CLASS_PUT_REF_AND_RESET ( _component_class )

Decrements the reference count of the component class _component_class, and then sets _component_class to NULL.

Parameters

_component_class

Component class of which to decrement the reference count.

Can contain NULL.

Precondition: _component_class is an assignable expression.

◆ BT_COMPONENT_CLASS_MOVE_REF

#define BT_COMPONENT_CLASS_MOVE_REF	(	_dst,
		_src
	)

Decrements the reference count of the component class _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a component class reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

◆ BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET

#define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET ( _component_class )

Decrements the reference count of the source component class _component_class, and then sets _component_class to NULL.

Parameters

_component_class

Source component class of which to decrement the reference count.

Can contain NULL.

Precondition: _component_class is an assignable expression.

◆ BT_COMPONENT_CLASS_SOURCE_MOVE_REF

#define BT_COMPONENT_CLASS_SOURCE_MOVE_REF	(	_dst,
		_src
	)

Decrements the reference count of the source component class _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a source component class reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

◆ BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET

#define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET ( _component_class )

Decrements the reference count of the filter component class _component_class, and then sets _component_class to NULL.

Parameters

_component_class

Filter component class of which to decrement the reference count.

Can contain NULL.

Precondition: _component_class is an assignable expression.

◆ BT_COMPONENT_CLASS_FILTER_MOVE_REF

#define BT_COMPONENT_CLASS_FILTER_MOVE_REF	(	_dst,
		_src
	)

Decrements the reference count of the filter component class _dst, setsc _dst to _src, and then sets _src to NULL.

This macro effectively moves a filter component class reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

◆ BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET

#define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET ( _component_class )

Decrements the reference count of the sink component class _component_class, and then sets _component_class to NULL.

Parameters

_component_class

Sink component class of which to decrement the reference count.

Can contain NULL.

Precondition: _component_class is an assignable expression.

◆ BT_COMPONENT_CLASS_SINK_MOVE_REF

#define BT_COMPONENT_CLASS_SINK_MOVE_REF	(	_dst,
		_src
	)

Decrements the reference count of the sink component class _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a sink component class reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst

Destination expression.

Can contain NULL.

_src

Source expression.

Can contain NULL.

Precondition: _dst is an assignable expression.; _src is an assignable expression.

Function Documentation

◆ bt_component_class_get_type()

bt_component_class_type bt_component_class_get_type ( const bt_component_class * component_class )

Returns the type enumerator of the component class component_class.

Parameters

[in] component_class Component class of which to get the type enumerator.

Returns: Type enumerator of component_class.

Precondition: component_class is not NULL.

See also: bt_component_class_is_source() — Returns whether or not a component class is a source component class.; bt_component_class_is_filter() — Returns whether or not a component class is a filter component class.; bt_component_class_is_sink() — Returns whether or not a component class is a sink component class.

◆ bt_component_class_is_source()

static bt_bool bt_component_class_is_source ( const bt_component_class * component_class )

inlinestatic

Returns whether or not the component class component_class is a source component class.

Parameters

[in] component_class Component class to check.

Returns: BT_TRUE if component_class is a source component class.

Precondition: component_class is not NULL.

See also: bt_component_class_get_type() — Returns the type enumerator of a component class.

◆ bt_component_class_is_filter()

static bt_bool bt_component_class_is_filter ( const bt_component_class * component_class )

inlinestatic

Returns whether or not the component class component_class is a filter component class.

Parameters

[in] component_class Component class to check.

Returns: BT_TRUE if component_class is a filter component class.

Precondition: component_class is not NULL.

See also: bt_component_class_get_type() — Returns the type enumerator of a component class.

◆ bt_component_class_is_sink()

static bt_bool bt_component_class_is_sink ( const bt_component_class * component_class )

inlinestatic

Returns whether or not the component class component_class is a sink component class.

Parameters

[in] component_class Component class to check.

Returns: BT_TRUE if component_class is a sink component class.

Precondition: component_class is not NULL.

See also: bt_component_class_get_type() — Returns the type enumerator of a component class.

◆ bt_component_class_get_name()

const char* bt_component_class_get_name ( const bt_component_class * component_class )

Returns the name of the component class component_class.

See the name property.

Parameters

[in] component_class Component class of which to get the name.

Returns

Name of component_class.

The returned pointer remains valid as long as component_class exists.

Precondition: component_class is not NULL.

◆ bt_component_class_get_description()

const char* bt_component_class_get_description ( const bt_component_class * component_class )

Returns the description of the component class component_class.

See the description property.

Parameters

[in] component_class Component class of which to get the description.

Returns

Description of component_class, or NULL if none.

The returned pointer remains valid as long as component_class exists.

Precondition: component_class is not NULL.

◆ bt_component_class_get_help()

const char* bt_component_class_get_help ( const bt_component_class * component_class )

Returns the help text of the component class component_class.

See the help text property.

Parameters

[in] component_class Component class of which to get the help text.

Returns

Help text of component_class, or NULL if none.

The returned pointer remains valid as long as component_class exists.

Precondition: component_class is not NULL.

◆ bt_component_class_get_ref()

void bt_component_class_get_ref ( const bt_component_class * component_class )

Increments the reference count of the component class component_class.

Parameters

[in]

component_class

Component class of which to increment the reference count.

Can be NULL.

See also: bt_component_put_ref() — Decrements the reference count of a component class.

◆ bt_component_class_put_ref()

void bt_component_class_put_ref ( const bt_component_class * component_class )

Decrements the reference count of the component class component_class.

Parameters

[in]

component_class

Component class of which to decrement the reference count.

Can be NULL.

See also: bt_component_get_ref() — Increments the reference count of a component class.

◆ bt_component_class_source_as_component_class_const()

static const bt_component_class* bt_component_class_source_as_component_class_const ( const bt_component_class_source * component_class )

inlinestatic

Upcasts the source component class component_class to the common bt_component_class type.

Parameters

[in]

component_class

Source component class to upcast.

Can be NULL.

Returns: component_class as a common component class.

◆ bt_component_class_source_get_ref()

void bt_component_class_source_get_ref ( const bt_component_class_source * component_class )

Increments the reference count of the source component class component_class.

Parameters

[in]

component_class

Source component class of which to increment the reference count.

Can be NULL.

See also: bt_component_class_source_put_ref() — Decrements the reference count of a source component class.

◆ bt_component_class_source_put_ref()

void bt_component_class_source_put_ref ( const bt_component_class_source * component_class )

Decrements the reference count of the source component class component_class.

Parameters

[in]

component_class

Source component class of which to decrement the reference count.

Can be NULL.

See also: bt_component_class_source_get_ref() — Increments the reference count of a source component class.

◆ bt_component_class_filter_as_component_class_const()

static const bt_component_class* bt_component_class_filter_as_component_class_const ( const bt_component_class_filter * component_class )

inlinestatic

Upcasts the filter component class component_class to the common bt_component_class type.

Parameters

[in]

component_class

Filter component class to upcast.

Can be NULL.

Returns: component_class as a common component class.

◆ bt_component_class_filter_get_ref()

void bt_component_class_filter_get_ref ( const bt_component_class_filter * component_class )

Increments the reference count of the filter component class component_class.

Parameters

[in]

component_class

Filter component class of which to increment the reference count.

Can be NULL.

See also: bt_component_class_filter_put_ref() — Decrements the reference count of a filter component class.

◆ bt_component_class_filter_put_ref()

void bt_component_class_filter_put_ref ( const bt_component_class_filter * component_class )

Decrements the reference count of the filter component class component_class.

Parameters

[in]

component_class

Filter component class of which to decrement the reference count.

Can be NULL.

See also: bt_component_class_filter_get_ref() — Increments the reference count of a filter component class.

◆ bt_component_class_sink_as_component_class_const()

static const bt_component_class* bt_component_class_sink_as_component_class_const ( const bt_component_class_sink * component_class )

inlinestatic

Upcasts the sink component class component_class to the common bt_component_class type.

Parameters

[in]

component_class

Sink component class to upcast.

Can be NULL.

Returns: component_class as a common component class.

◆ bt_component_class_sink_get_ref()

void bt_component_class_sink_get_ref ( const bt_component_class_sink * component_class )

Increments the reference count of the sink component class component_class.

Parameters

[in]

component_class

Sink component class of which to increment the reference count.

Can be NULL.

See also: bt_component_class_sink_put_ref() — Decrements the reference count of a sink component class.

◆ bt_component_class_sink_put_ref()

void bt_component_class_sink_put_ref ( const bt_component_class_sink * component_class )

Decrements the reference count of the sink component class component_class.

Parameters

[in]

component_class

Sink component class of which to decrement the reference count.

Can be NULL.

See also: bt_component_class_sink_get_ref() — Increments the reference count of a sink component class.

Detailed Description

Properties

Types

Type query

Properties

Common reference count

Source component class upcast

Source component class reference count

Filter component class upcast

Filter component class reference count

Sink component class upcast

Sink component class reference count

Enumeration Type Documentation

◆ bt_component_class_type

Macro Definition Documentation

◆ BT_COMPONENT_CLASS_PUT_REF_AND_RESET

◆ BT_COMPONENT_CLASS_MOVE_REF

◆ BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET

◆ BT_COMPONENT_CLASS_SOURCE_MOVE_REF

◆ BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET

◆ BT_COMPONENT_CLASS_FILTER_MOVE_REF

◆ BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET

◆ BT_COMPONENT_CLASS_SINK_MOVE_REF

Function Documentation

◆ bt_component_class_get_type()

◆ bt_component_class_is_source()

◆ bt_component_class_is_filter()

◆ bt_component_class_is_sink()

◆ bt_component_class_get_name()

◆ bt_component_class_get_description()

◆ bt_component_class_get_help()

◆ bt_component_class_get_ref()

◆ bt_component_class_put_ref()

◆ bt_component_class_source_as_component_class_const()

◆ bt_component_class_source_get_ref()

◆ bt_component_class_source_put_ref()

◆ bt_component_class_filter_as_component_class_const()

◆ bt_component_class_filter_get_ref()

◆ bt_component_class_filter_put_ref()

◆ bt_component_class_sink_as_component_class_const()

◆ bt_component_class_sink_get_ref()

◆ bt_component_class_sink_put_ref()