lib: graph: add "self" and some "private" APIs
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Wed, 21 Nov 2018 22:30:33 +0000 (17:30 -0500)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Fri, 3 May 2019 22:19:35 +0000 (18:19 -0400)
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>

No differences found
This page took 0.026074 seconds and 4 git commands to generate.