Visibility: split graph API into public and private interfaces
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Tue, 28 Mar 2017 18:14:42 +0000 (14:14 -0400)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Sun, 28 May 2017 16:57:39 +0000 (12:57 -0400)
commit890882eff34b4cba6f08a25f8ca56866c20b3fbe
tree167683b13756e4ba2059dc8602af008d30365aa6
parent1bf957a039dfe5a1cd00659779fdb004aacd706b
Visibility: split graph API into public and private interfaces

The goal here is to avoid that a component or a graph user calls methods
that do not logically apply to itself, but should according to the API's
intention. For example, a component should not be able to remove the
ports of another component, and a graph user should not be able to
create a notification iterator directly.

Therefore the existing bt_component, bt_port, bt_connection, and
bt_notification_iterator objects are considered "public": any user can
call their API.

The user-defined methods (callbacks) now accept private versions of
those objects:

* bt_private_component
* bt_private_port
* bt_private_connection
* bt_private_notification_iterator

This ensures that only the user which is called back with those private
objects can call specific, private methods, which start with the
`bt_private_` prefix.

For example, any user can get a sink component's input port by name with
bt_component_sink_get_input_port(). This function accepts a bt_component
object parameter and returns a bt_port object. However, only the called
back user can get its private version of the port with the equivalent
bt_private_component_sink_get_input_private_port(). This function
accepts a bt_private_component object parameter and returns a
bt_private_port object. The private port API has the
bt_private_port_remove_from_component() function: thus only the owner
component of a port can remove it from itself.

Each private API has a bt_OBJ_from_private_OBJ() function which
returns a _new reference_ to the equivalent public object of a private
object to be able to call public functions.

With all this, if a user calls a private function with a public object,
the compiler emits a warning similar to:

    warning: assignment from incompatible pointer type

With GCC and Clang, you can make this warning an error with:

    -Werror=incompatible-pointer-types

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
43 files changed:
include/Makefile.am
include/babeltrace/component/component-class-sink.h
include/babeltrace/component/component-class.h
include/babeltrace/component/component-filter-internal.h
include/babeltrace/component/component-filter.h
include/babeltrace/component/component-internal.h
include/babeltrace/component/component-sink.h
include/babeltrace/component/component-source-internal.h
include/babeltrace/component/component-source.h
include/babeltrace/component/component.h
include/babeltrace/component/connection-internal.h
include/babeltrace/component/connection.h
include/babeltrace/component/notification/iterator-internal.h
include/babeltrace/component/notification/iterator.h
include/babeltrace/component/notification/private-iterator.h [new file with mode: 0644]
include/babeltrace/component/port-internal.h
include/babeltrace/component/private-component-filter.h [new file with mode: 0644]
include/babeltrace/component/private-component-sink.h [new file with mode: 0644]
include/babeltrace/component/private-component-source.h [new file with mode: 0644]
include/babeltrace/component/private-component.h [new file with mode: 0644]
include/babeltrace/component/private-connection.h [new file with mode: 0644]
include/babeltrace/component/private-port.h [new file with mode: 0644]
lib/component/component.c
lib/component/connection.c
lib/component/filter.c
lib/component/iterator.c
lib/component/port.c
lib/component/sink.c
lib/component/source.c
plugins/ctf/fs/fs.c
plugins/ctf/fs/fs.h
plugins/ctf/lttng-live/lttng-live-internal.h
plugins/ctf/lttng-live/lttng-live.c
plugins/muxer/muxer.c
plugins/text/text.c
plugins/utils/dummy/dummy.c
plugins/utils/dummy/dummy.h
plugins/utils/trimmer/iterator.c
plugins/utils/trimmer/iterator.h
plugins/utils/trimmer/trimmer.c
plugins/utils/trimmer/trimmer.h
plugins/writer/writer.c
tests/lib/test-plugin-plugins/sfs.c
This page took 0.031238 seconds and 4 git commands to generate.