git.efficios.com Git - babeltrace.git/log

Philippe Proulx [Wed, 18 Jan 2017 18:30:07 +0000 (13:30 -0500)]

Decouple component class from plugin subsystem, remove component factory

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>