The main purpose of this patch is to create different "views" of the
same graph objects. The terms are as such:
Public API:
You can only read properties of the object.
Example: bt_graph_is_canceled().
Private API:
You can create the object and set properties.
Example: bt_private_graph_create().
Self API:
You conceptually inherit this object.
Example: bt_self_component_set_data().
This means that component user method now accepts a "self component",
on which:
* You can set and get user data (bt_self_component_set_data() and
bt_self_component_get_data()).
* You can add ports (for example,
bt_self_component_source_add_output_port()).
* You can borrow "self component ports", on which you can get
user data (bt_self_component_port_get_data()) that you set previously
with a port adding function.
A notification iterator method now accepts a
"self notification iterator", on which:
* You can set and get user data (bt_self_notification_iterator_set_data()
and bt_self_notification_iterator_get_data()).
* You can borrow your "self component"
(bt_self_notification_iterator_borrow_component()) or "self component
output port" (bt_self_notification_iterator_borrow_port()).
Also, you now use the private component class API to create component
classes and set optional methods, a description, and the rest.
Also in this patch:
* Component class and component APIs are split into source, filter, and
sink parts. This makes everything more type safe considering that:
* We don't need any polymorphism like we do, for example, for field
classes, for component classes and components: you always know,
contextually, with which type you're dealing.
* We don't need to have collections of components or component classes
of different types: we can just use three collections each time.
This means that the private graph API, for example, now has the three
distinct bt_private_graph_add_source_component(),
bt_private_graph_add_filter_component(), and
bt_private_graph_add_sink_component(), each of them accepting the
appropriate component class type and returning the corresponding
component type.
No function exists to borrow a source component's input port
or a sink component's output port.
* The port API is split into input and output parts, with the new
`struct bt_port_in` and `struct bt_port_out` types.
An interesting consequence is that, as a component class developer,
there are different methods for input and output ports, so that a
fitler component class, for example, can have both an "input port
connected" and an "output port connected". The `flt.utils.muxer`
component class is an example which takes advantage of this, not
having to check the port's type in its "input port connected" method
now.
* Functions to go from one type to another (private to public, self to
public, input port to port, and so on) are now `static inline` to
avoid any performance hit.
Those functions are now universally named bt_X_borrow_Y(), where `X`
is the API's prefix (for example, `private_component_class`) and `Y`
is the transformed type name (for example, `component_class`).
* The query executor API is split into private (create, query, cancel)
and public (is canceled?) parts.
A user's query method accepts a "self component class" of the
appropriate type.
* "Private connection private notification iterator" is removed in favor
of "self component input port notification iterator": you need to call
bt_self_component_port_input_notification_iterator_create() with a
self component input port (which you can only borrow from your own
self component).
Because of this, `enum bt_connection_status` is removed because it's
not needed anymore.
* `enum bt_component_status` is removed because it's not needed anymore.
Most statuses are moved to `enum bt_self_component_status` (what a
component class method returns).
* `bt_output_port_notification_iterator` is renamed to
`bt_port_output_notification_iterator` to be consistent with
`bt_self_component_port_input_notification_iterator`.
* Graph and plugin API status values are standardized.
* Precondition assertion macros are used to validate preconditions in
developer mode across the whole graph and plugin APIs.
Consequences:
* bt_plugin_get_version() returns `enum bt_property_availability`
instead of `enum bt_plugin_status`.
* Functions which return a count return `uint64_t` instead of
`int64_t`.
* Status ending with `_INVALID` are removed (not needed anymore).
* Types ending with `_UNKNOWN` are removed (not needed anymore).
* All "getting" functions in the graph/plugin APIs are removed in favor
of "borrowing" functions.
Interesting changes needed to be made to bt_connection_end() and
remove_port_by_index() to support this.
* bt_plugin_find_component_class() is removed. Let's not encourage this
because it creates a plugin object each time, whereas the recommended
approach is to create a plugin first (with bt_plugin_find() for
example), and then borrow the required component classes.
* Graph API: when an object's member is destroyed, internally, its
pointer is set to `NULL` immediately. This makes it possible to log
partial objects during destruction while keeping Valgrind's memcheck
happy.
* Generic logging is replaced by library logging in the graph and plugin
API implementations.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>