Babeltrace 2 C API  2.0.6
Open-source trace manipulation framework

Detailed Description

Component input and output ports.

A port is a point of connection between components:

component-zoom.png

A port is a shared object: get a new reference with bt_port_get_ref() and put an existing reference with bt_port_put_ref().

The common C type of a port is bt_port.

There are two types of ports:

Input port

Input connection point from which messages are received.

Filter and sink components have input ports.

An input port's specific type is bt_port_input and its type enumerator is BT_PORT_TYPE_INPUT.

Upcast the bt_port_input type to the bt_port type with bt_port_input_as_port_const().

Get a new input port reference with bt_port_input_get_ref() and put an existing one with bt_port_input_put_ref().

Output port

Output connection point to which messages are sent.

Source and filter components have output ports.

An output port's specific type is bt_port_output and its type enumerator is BT_PORT_TYPE_OUTPUT.

Upcast the bt_port_output type to the bt_port type with bt_port_output_as_port_const().

Get a new output port reference with bt_port_output_get_ref() and put an existing one with bt_port_output_put_ref().

Get a port's type enumerator with bt_port_get_type(). You can also use the bt_port_is_input() and bt_port_is_output() helper functions.

A component can add a port with:

Borrow a port's connection, if any, with bt_port_borrow_connection_const().

Borrow the component to which a port belongs with bt_port_borrow_component_const().

Properties

A port has the following common properties:

Name

Name of the port.

For a given component:

  • Each input port has a unique name.
  • Each output port has a unique name.

A port's name is set when the component adds it; you cannot change it afterwards.

Get a port's name with bt_port_get_name().

Is connected?

Whether or not the port is currently connected to another port.

Get whether or not a port is connected with bt_port_is_connected().

When a port is unconnected, bt_port_borrow_connection_const() returns NULL.

Types

typedef struct bt_port bt_port
 Port.
 
typedef struct bt_port_input bt_port_input
 Input port.
 
typedef struct bt_port_output bt_port_output
 Output port.
 

Type query

enum  bt_port_type {
  BT_PORT_TYPE_INPUT,
  BT_PORT_TYPE_OUTPUT
}
 Port type enumerators. More...
 
typedef enum bt_port_type bt_port_type
 Port type enumerators.
 
bt_port_type bt_port_get_type (const bt_port *port)
 Returns the type enumerator of the port port. More...
 
static bt_bool bt_port_is_input (const bt_port *port)
 Returns whether or not the port port is an input port. More...
 
static bt_bool bt_port_is_output (const bt_port *port)
 Returns whether or not the port port is an output port. More...
 

Connection access

const bt_connectionbt_port_borrow_connection_const (const bt_port *port)
 Borrows the connection of the port port. More...
 

Component access

const bt_componentbt_port_borrow_component_const (const bt_port *port)
 Borrows the component to which the port port belongs. More...
 

Properties

const char * bt_port_get_name (const bt_port *port)
 Returns the name of the port port. More...
 
bt_bool bt_port_is_connected (const bt_port *port)
 Returns whether or not the port port is connected. More...
 

Reference count (common)

void bt_port_get_ref (const bt_port *port)
 Increments the reference count of the port port. More...
 
void bt_port_put_ref (const bt_port *port)
 Decrements the reference count of the port port. More...
 
#define BT_PORT_PUT_REF_AND_RESET(_port)
 Decrements the reference count of the port _port, and then sets _port to NULL. More...
 
#define BT_PORT_MOVE_REF(_dst, _src)
 Decrements the reference count of the port _dst, sets _dst to _src, and then sets _src to NULL. More...
 

Input port

static const bt_portbt_port_input_as_port_const (const bt_port_input *port)
 Upcasts the input port port to the common bt_port type. More...
 
void bt_port_input_get_ref (const bt_port_input *port)
 Increments the reference count of the input port port. More...
 
void bt_port_input_put_ref (const bt_port_input *port)
 Decrements the reference count of the input port port. More...
 
#define BT_PORT_INPUT_PUT_REF_AND_RESET(_port)
 Decrements the reference count of the input port _port, and then sets _port to NULL. More...
 
#define BT_PORT_INPUT_MOVE_REF(_dst, _src)
 Decrements the reference count of the input port _dst, sets _dst to _src, and then sets _src to NULL. More...
 

Output port

static const bt_portbt_port_output_as_port_const (const bt_port_output *port)
 Upcasts the output port port to the common bt_port type. More...
 
void bt_port_output_get_ref (const bt_port_output *port)
 Increments the reference count of the output port port. More...
 
void bt_port_output_put_ref (const bt_port_output *port)
 Decrements the reference count of the output port port. More...
 
#define BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port)
 Decrements the reference count of the output port _port, and then sets _port to NULL. More...
 
#define BT_PORT_OUTPUT_MOVE_REF(_dst, _src)
 Decrements the reference count of the output port _dst, sets _dst to _src, and then sets _src to NULL. More...
 

Enumeration Type Documentation

Port type enumerators.

Enumerator
BT_PORT_TYPE_INPUT 

Input port.

BT_PORT_TYPE_OUTPUT 

Output port.

Macro Definition Documentation

#define BT_PORT_PUT_REF_AND_RESET (   _port)

Decrements the reference count of the port _port, and then sets _port to NULL.

Parameters
_port

Port of which to decrement the reference count.

Can contain NULL.

Precondition
_port is an assignable expression.
#define BT_PORT_MOVE_REF (   _dst,
  _src 
)

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

This macro effectively moves a port 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.
#define BT_PORT_INPUT_PUT_REF_AND_RESET (   _port)

Decrements the reference count of the input port _port, and then sets _port to NULL.

Parameters
_port

Input port of which to decrement the reference count.

Can contain NULL.

Precondition
_port is an assignable expression.
#define BT_PORT_INPUT_MOVE_REF (   _dst,
  _src 
)

Decrements the reference count of the input port _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves an input port 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.
#define BT_PORT_OUTPUT_PUT_REF_AND_RESET (   _port)

Decrements the reference count of the output port _port, and then sets _port to NULL.

Parameters
_port

Output port of which to decrement the reference count.

Can contain NULL.

Precondition
_port is an assignable expression.
#define BT_PORT_OUTPUT_MOVE_REF (   _dst,
  _src 
)

Decrements the reference count of the output port _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves an output port 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_port_type bt_port_get_type ( const bt_port port)

Returns the type enumerator of the port port.

Parameters
[in]portPort of which to get the type enumerator
Returns
Type enumerator of port.
Precondition
port is not NULL.
See also
bt_port_is_input() — Returns whether or not a port is an input port.
bt_port_is_output() — Returns whether or not a port is an output port.
static bt_bool bt_port_is_input ( const bt_port port)
inlinestatic

Returns whether or not the port port is an input port.

Parameters
[in]portPort to check.
Returns
BT_TRUE if port is an input port.
Precondition
port is not NULL.
See also
bt_port_get_type() — Returns the type enumerator of a port.
static bt_bool bt_port_is_output ( const bt_port port)
inlinestatic

Returns whether or not the port port is an output port.

Parameters
[in]portPort to check.
Returns
BT_TRUE if port is an output port.
Precondition
port is not NULL.
See also
bt_port_get_type() — Returns the type enumerator of a port.
const bt_connection* bt_port_borrow_connection_const ( const bt_port port)

Borrows the connection of the port port.

This function returns NULL if port is unconnected (bt_port_is_connected() returns BT_FALSE).

Parameters
[in]portPort of which to borrow the connection.
Returns
Borrowed reference of the connection of port.
Precondition
port is not NULL.
const bt_component* bt_port_borrow_component_const ( const bt_port port)

Borrows the component to which the port port belongs.

Parameters
[in]portPort of which to borrow the component which owns it.
Returns
Borrowed reference of the component which owns port.
Precondition
port is not NULL.
const char* bt_port_get_name ( const bt_port port)

Returns the name of the port port.

See the name property.

Parameters
[in]portPort of which to get the name.
Returns

Name of port, or NULL if none.

The returned pointer remains valid as long as port exists.

Precondition
port is not NULL.
bt_bool bt_port_is_connected ( const bt_port port)

Returns whether or not the port port is connected.

See the is connected? property.

Parameters
[in]portPort of which to get whether or not it's connected.
Returns
BT_TRUE if port is connected.
Precondition
port is not NULL.
void bt_port_get_ref ( const bt_port port)

Increments the reference count of the port port.

Parameters
[in]port

Port of which to increment the reference count.

Can be NULL.

See also
bt_port_put_ref() — Decrements the reference count of a port.
void bt_port_put_ref ( const bt_port port)

Decrements the reference count of the port port.

Parameters
[in]port

Port of which to decrement the reference count.

Can be NULL.

See also
bt_port_get_ref() — Increments the reference count of a port.
static const bt_port* bt_port_input_as_port_const ( const bt_port_input port)
inlinestatic

Upcasts the input port port to the common bt_port type.

Parameters
[in]port

Input port to upcast.

Can be NULL.

Returns
port as a common port.
void bt_port_input_get_ref ( const bt_port_input port)

Increments the reference count of the input port port.

Parameters
[in]port

Input port of which to increment the reference count.

Can be NULL.

See also
bt_port_input_put_ref() — Decrements the reference count of an input port.
void bt_port_input_put_ref ( const bt_port_input port)

Decrements the reference count of the input port port.

Parameters
[in]port

Input port of which to decrement the reference count.

Can be NULL.

See also
bt_port_input_get_ref() — Increments the reference count of an input port.
static const bt_port* bt_port_output_as_port_const ( const bt_port_output port)
inlinestatic

Upcasts the output port port to the common bt_port type.

Parameters
[in]port

Output port to upcast.

Can be NULL.

Returns
port as a common port.
void bt_port_output_get_ref ( const bt_port_output port)

Increments the reference count of the output port port.

Parameters
[in]port

Output port of which to increment the reference count.

Can be NULL.

See also
bt_port_output_put_ref() — Decrements the reference count of a output port.
void bt_port_output_put_ref ( const bt_port_output port)

Decrements the reference count of the output port port.

Parameters
[in]port

Output port of which to decrement the reference count.

Can be NULL.

See also
bt_port_output_get_ref() — Increments the reference count of a output port.