lib: graph: add "self" and some "private" APIs
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Wed, 21 Nov 2018 22:30:33 +0000 (17:30 -0500)
committerPhilippe Proulx <eeppeliteloop@gmail.com>
Thu, 2 May 2019 04:09:17 +0000 (00:09 -0400)
commitd27a81b29c34b4855f02b31f291d8c885760b3a2
treee74f1f098cc8e4b2bcdd2fd7a683aafd691ce956
parentaa4d5da576bfcbc739327d13ddd189677bcb1627
lib: graph: add "self" and some "private" APIs

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>
231 files changed:
cli/babeltrace-cfg-cli-args-connect.c
cli/babeltrace-cfg-cli-args.c
cli/babeltrace.c
extras/gen-babeltrace-h.py
include/Makefile.am
include/babeltrace/align-internal.h
include/babeltrace/babeltrace-internal.h
include/babeltrace/babeltrace.h
include/babeltrace/bitfield-internal.h
include/babeltrace/common-internal.h
include/babeltrace/compat/fcntl-internal.h
include/babeltrace/compat/glib-internal.h
include/babeltrace/compat/memstream-internal.h
include/babeltrace/compat/mman-internal.h
include/babeltrace/compat/socket-internal.h
include/babeltrace/compat/stdlib-internal.h
include/babeltrace/compat/time-internal.h
include/babeltrace/compat/unistd-internal.h
include/babeltrace/compat/uuid-internal.h
include/babeltrace/compiler-internal.h
include/babeltrace/ctf-writer/attributes-internal.h
include/babeltrace/ctf-writer/clock-class-internal.h
include/babeltrace/ctf-writer/clock-internal.h
include/babeltrace/ctf-writer/clock.h
include/babeltrace/ctf-writer/event-class-internal.h
include/babeltrace/ctf-writer/event-fields.h
include/babeltrace/ctf-writer/event-internal.h
include/babeltrace/ctf-writer/event-types.h
include/babeltrace/ctf-writer/event.h
include/babeltrace/ctf-writer/field-path-internal.h
include/babeltrace/ctf-writer/field-types-internal.h
include/babeltrace/ctf-writer/field-types.h
include/babeltrace/ctf-writer/fields-internal.h
include/babeltrace/ctf-writer/fields.h
include/babeltrace/ctf-writer/functor-internal.h
include/babeltrace/ctf-writer/resolve-internal.h
include/babeltrace/ctf-writer/stream-class-internal.h
include/babeltrace/ctf-writer/stream-class.h
include/babeltrace/ctf-writer/stream-internal.h
include/babeltrace/ctf-writer/stream.h
include/babeltrace/ctf-writer/trace-internal.h
include/babeltrace/ctf-writer/trace.h
include/babeltrace/ctf-writer/utils-internal.h
include/babeltrace/ctf-writer/utils.h
include/babeltrace/ctf-writer/validation-internal.h
include/babeltrace/ctf-writer/visitor-internal.h
include/babeltrace/ctf-writer/visitor.h
include/babeltrace/ctf-writer/writer-internal.h
include/babeltrace/ctf-writer/writer.h
include/babeltrace/endian-internal.h
include/babeltrace/graph/component-class-filter.h
include/babeltrace/graph/component-class-internal.h
include/babeltrace/graph/component-class-sink-colander-internal.h
include/babeltrace/graph/component-class-sink.h
include/babeltrace/graph/component-class-source.h
include/babeltrace/graph/component-class.h
include/babeltrace/graph/component-filter-internal.h
include/babeltrace/graph/component-filter.h
include/babeltrace/graph/component-internal.h
include/babeltrace/graph/component-sink-internal.h
include/babeltrace/graph/component-sink.h
include/babeltrace/graph/component-source-internal.h
include/babeltrace/graph/component-source.h
include/babeltrace/graph/component-status.h [deleted file]
include/babeltrace/graph/component.h
include/babeltrace/graph/connection-internal.h
include/babeltrace/graph/connection.h
include/babeltrace/graph/graph-internal.h
include/babeltrace/graph/graph.h
include/babeltrace/graph/notification-event-internal.h
include/babeltrace/graph/notification-internal.h
include/babeltrace/graph/notification-iterator-internal.h
include/babeltrace/graph/notification-iterator.h
include/babeltrace/graph/notification-packet-internal.h
include/babeltrace/graph/notification-stream-internal.h
include/babeltrace/graph/notification-stream.h
include/babeltrace/graph/notification.h
include/babeltrace/graph/output-port-notification-iterator.h [deleted file]
include/babeltrace/graph/port-input.h [new file with mode: 0644]
include/babeltrace/graph/port-internal.h
include/babeltrace/graph/port-output-notification-iterator.h [new file with mode: 0644]
include/babeltrace/graph/port-output.h [new file with mode: 0644]
include/babeltrace/graph/port.h
include/babeltrace/graph/private-component-class-filter.h [new file with mode: 0644]
include/babeltrace/graph/private-component-class-sink.h [new file with mode: 0644]
include/babeltrace/graph/private-component-class-source.h [new file with mode: 0644]
include/babeltrace/graph/private-component-class.h [new file with mode: 0644]
include/babeltrace/graph/private-component-filter.h [deleted file]
include/babeltrace/graph/private-component-sink.h [deleted file]
include/babeltrace/graph/private-component-source.h [deleted file]
include/babeltrace/graph/private-component.h [deleted file]
include/babeltrace/graph/private-connection-notification-iterator.h [deleted file]
include/babeltrace/graph/private-connection-private-notification-iterator.h [deleted file]
include/babeltrace/graph/private-connection.h [deleted file]
include/babeltrace/graph/private-graph.h
include/babeltrace/graph/private-notification-event.h
include/babeltrace/graph/private-notification-inactivity.h
include/babeltrace/graph/private-notification-packet.h
include/babeltrace/graph/private-notification-stream.h
include/babeltrace/graph/private-notification.h
include/babeltrace/graph/private-port.h [deleted file]
include/babeltrace/graph/private-query-executor.h [new file with mode: 0644]
include/babeltrace/graph/query-executor-internal.h
include/babeltrace/graph/query-executor.h
include/babeltrace/graph/self-component-class-filter.h [new file with mode: 0644]
include/babeltrace/graph/self-component-class-sink.h [new file with mode: 0644]
include/babeltrace/graph/self-component-class-source.h [new file with mode: 0644]
include/babeltrace/graph/self-component-filter.h [new file with mode: 0644]
include/babeltrace/graph/self-component-port-input-notification-iterator.h [new file with mode: 0644]
include/babeltrace/graph/self-component-port-input.h [new file with mode: 0644]
include/babeltrace/graph/self-component-port-output.h [new file with mode: 0644]
include/babeltrace/graph/self-component-port.h [new file with mode: 0644]
include/babeltrace/graph/self-component-sink.h [new file with mode: 0644]
include/babeltrace/graph/self-component-source.h [new file with mode: 0644]
include/babeltrace/graph/self-component.h [new file with mode: 0644]
include/babeltrace/graph/self-notification-iterator.h [new file with mode: 0644]
include/babeltrace/logging.h
include/babeltrace/mmap-align-internal.h
include/babeltrace/object-internal.h
include/babeltrace/object.h
include/babeltrace/plugin/plugin-dev.h
include/babeltrace/plugin/plugin-internal.h
include/babeltrace/plugin/plugin-so-internal.h
include/babeltrace/plugin/plugin.h
include/babeltrace/prio-heap-internal.h
include/babeltrace/private-values.h
include/babeltrace/trace-ir/attributes-internal.h
include/babeltrace/trace-ir/clock-class-internal.h
include/babeltrace/trace-ir/event-class-internal.h
include/babeltrace/trace-ir/event-internal.h
include/babeltrace/trace-ir/field-classes-internal.h
include/babeltrace/trace-ir/field-path-internal.h
include/babeltrace/trace-ir/fields-internal.h
include/babeltrace/trace-ir/packet-internal.h
include/babeltrace/trace-ir/private-clock-class.h
include/babeltrace/trace-ir/private-event-class.h
include/babeltrace/trace-ir/private-event.h
include/babeltrace/trace-ir/private-field-classes.h
include/babeltrace/trace-ir/private-fields.h
include/babeltrace/trace-ir/private-packet.h
include/babeltrace/trace-ir/private-stream-class.h
include/babeltrace/trace-ir/private-stream.h
include/babeltrace/trace-ir/private-trace.h
include/babeltrace/trace-ir/resolve-field-path-internal.h
include/babeltrace/trace-ir/stream-class-internal.h
include/babeltrace/trace-ir/stream-internal.h
include/babeltrace/trace-ir/trace-internal.h
include/babeltrace/trace-ir/utils-internal.h
include/babeltrace/values-internal.h
include/babeltrace/values.h
lib/babeltrace.c
lib/ctf-writer/attributes.c
lib/ctf-writer/trace.c
lib/graph/Makefile.am
lib/graph/component-class-sink-colander.c
lib/graph/component-class.c
lib/graph/component-filter.c [new file with mode: 0644]
lib/graph/component-sink.c [new file with mode: 0644]
lib/graph/component-source.c [new file with mode: 0644]
lib/graph/component.c
lib/graph/connection.c
lib/graph/filter.c [deleted file]
lib/graph/graph.c
lib/graph/iterator.c
lib/graph/notification/event.c
lib/graph/notification/inactivity.c
lib/graph/notification/notification.c
lib/graph/notification/packet.c
lib/graph/notification/stream.c
lib/graph/port.c
lib/graph/query-executor.c
lib/graph/sink.c [deleted file]
lib/graph/source.c [deleted file]
lib/lib-logging.c
lib/object.c
lib/plugin/plugin-so.c
lib/plugin/plugin.c
lib/prio_heap/prio_heap.c
lib/trace-ir/attributes.c
lib/trace-ir/clock-class.c
lib/trace-ir/event-class.c
lib/trace-ir/event.c
lib/trace-ir/field-classes.c
lib/trace-ir/field-path.c
lib/trace-ir/fields.c
lib/trace-ir/packet.c
lib/trace-ir/stream-class.c
lib/trace-ir/stream.c
lib/trace-ir/trace.c
lib/trace-ir/utils.c
lib/values.c
plugins/ctf/common/metadata/ctf-meta-translate.c
plugins/ctf/common/metadata/ctf-meta-update-default-clock-classes.c
plugins/ctf/common/metadata/ctf-meta.h
plugins/ctf/common/metadata/visitor-generate-ir.c
plugins/ctf/common/notif-iter/notif-iter.c
plugins/ctf/common/notif-iter/notif-iter.h
plugins/ctf/fs-sink/writer.c
plugins/ctf/fs-sink/writer.h
plugins/ctf/fs-src/data-stream-file.c
plugins/ctf/fs-src/data-stream-file.h
plugins/ctf/fs-src/fs.c
plugins/ctf/fs-src/fs.h
plugins/ctf/fs-src/query.c
plugins/ctf/fs-src/query.h
plugins/ctf/lttng-live/lttng-live-internal.h
plugins/ctf/lttng-live/lttng-live.c
plugins/ctf/plugin.c
plugins/lttng-utils/plugin.c
plugins/text/dmesg/dmesg.c
plugins/text/dmesg/dmesg.h
plugins/text/plugin.c
plugins/text/pretty/pretty.c
plugins/text/pretty/pretty.h
plugins/text/pretty/print.c
plugins/utils/counter/counter.c
plugins/utils/counter/counter.h
plugins/utils/dummy/dummy.c
plugins/utils/dummy/dummy.h
plugins/utils/muxer/muxer.c
plugins/utils/muxer/muxer.h
plugins/utils/plugin.c
plugins/utils/trimmer/iterator.c
plugins/utils/trimmer/iterator.h
plugins/utils/trimmer/trimmer.c
plugins/utils/trimmer/trimmer.h
tests/lib/test-plugin-plugins/sfs.c
tests/lib/test_bt_notification_iterator.c
tests/lib/test_bt_values.c
tests/lib/test_graph_topo.c
tests/lib/test_plugin.c
This page took 0.047879 seconds and 5 git commands to generate.