This is a refactoring of the component class and plugin subsystems of
Babeltrace 2. There's not much new code, it's mostly moved from one
file to another and some functions are renamed.
The goal of this patch is to decouple the component class objects from
plugin objects, that is, remove the dependency from the component class
to the plugin. This reference is not necessary, as component classes
can be provided by many sources, a plugin being one of them. A similar
plugin subsystem could be implemented outside of the Babeltrace library
with plugin-agnostic component class objects.
Also the component factory concept is completely removed. At the end
of this refactoring, it's nothing more than a hash table, so the name
is bad, and the object itself is just a very basic util.
Summary of changes:
* You can create a bt_component_class object manually with
bt_component_class_create(). The function accepts the same parameters
as before, except for a plugin reference.
* Internal code can use bt_component_class_add_destroy_listener() to add
a custom destroy listener to a component class. Destroy listeners are
called in reverse order just before the component class is destroyed
when its last reference is dropped.
This is needed to implement the plugin subsystem. It could be made
public eventually to allow a custom component class provider system
similar to the Babeltrace plugin subsystem. It could be generalized to
bt_object_add_destroy_listener() or bt_add_destroy_listener().
* bt_component_class_get_plugin() is removed.
* There are three functions to create a bt_plugin object (in
`babeltrace/plugin/plugin.h`):
* bt_plugin_create_from_file(): Accepts a path and creates a plugin
object from this single file. This must be a `.so` or `.la` file for
the moment, but eventually we can support other plugins like Python
plugins `.py`, Windows DLLs `.dll`, etc.
* bt_plugin_create_all_from_dir(): Traverses a directory, optionally
recursively, and creates one plugin object for each shared library
found. Errors are ignored in this function because it's possible
that a shared library in this directoy is not a Babeltrace plugin
and we still want to continue the search.
The return value is a NULL-terminated array of bt_plugin objects
which the caller must free. Each plugin object in this array has its
reference count set to 1.
* bt_plugin_create_all_from_static(): Loads all the plugins found in
the static sections of the Babeltrace binary. The return value has
the same format as with bt_plugin_create_all_from_dir().
There is no way to create an "empty", fresh bt_plugin object. It's
always created from an existing file in the end.
* A bt_plugin object is a simple provider of component classes. Once
it's created with one of the three functions above, you can access its
global properties (name, license, description, etc.), as well as its
component classes with bt_plugin_get_component_class_count(),
bt_plugin_get_component_class(), and
bt_plugin_get_component_class_by_name_and_type().
The initialization function of a plugin can add new component classes
to a bt_plugin object (passed as a parameter) thanks to the new
bt_plugin_add_component_class() function. This function is exclusive
to a plugin's initialization stage: once the initialization is done,
the plugin is marked as frozen, and you cannot call
bt_plugin_add_component_class() again on this plugin. This ensures
that all the contained component classes were created by the plugin's
code itself.
There's a mechanism which involves a global hash table of
component class adresses to shared library handles and a custom
component class destroy listener to ensure that, even if a bt_plugin
object is destroyed (reference count falls to zero), its associated
shared library is not closed until all its component classes are
also destroyed. See plugin.c:89 for more details.
* All the headers related to components, component classes, and
notifications are moved to `babeltrace/component`. Plugin-specific
headers are in `babeltrace/plugin`.
* Plugin development macros are in `babeltrace/plugin/plugin-dev.h`
(instead of `plugin-macros.h`). This is the header that any plugin's
main source file must include.
* Two new function typedefs in `plugin-dev.h`:
* bt_plugin_init_func: plugin's initialization function which
accepts a plugin object to which to add component classes.
You can set such a function with BT_PLUGIN_INIT().
* bt_plugin_exit_func: plugin's exit function, if anything global to
the plugin must be freed/released.
This is not called when the bt_plugin object is destroyed: because
component classes could still be alive when this happens, it's
called just before the shared library is closed (when it is
guaranteed that no user code found in this plugin will be called
in the future of this process).
You can set such a function with BT_PLUGIN_EXIT().
* The BT_PLUGIN_COMPONENT_CLASS_*_ENTRY() macros create a component
class of the associated type with bt_component_class_create(), and
add it to the plugin object with bt_plugin_add_component_class().
You can also do this manually in a custom initialization function.
When you use BT_PLUGIN_COMPONENT_CLASSES_BEGIN and
BT_PLUGIN_COMPONENT_CLASSES_END, BT_PLUGIN_INIT() and
BT_PLUGIN_EXIT() (no-op exit function) are automatically used.
* Everything found in `babeltrace/plugin/plugin-system.h` is moved to
the appropriate headers, depending on the types of the objects.
* Plugins, tests, and internal code are updated to use the new macros
and header files.
* The converter is updated to use the updated subsystems instead of
relying on a component factory.
A global GLib pointer array is used to keep the currently loaded
plugins. This is used instead of the component factory. When a new
plugin is found, we check in this array if it was already added (same
name) from another file or statically before adding it.
The static find_plugin() and find_component_class() are the equivalent
of the component factory interface.
print_component_classes_found() also prints the number of loaded
plugins.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>