gplugin/gplugin

Better document the example plugins and cover the shutdown parameter to unload

20 months ago, Gary Kramlich
2bf12275c35d
Parents 273e94647707
Children 62072a413983
Better document the example plugins and cover the shutdown parameter to unload

Testing Done:
Ran `codespell`

Reviewed at https://reviews.imfreedom.org/r/1694/
6 files changed, 100 insertions(+), 4 deletions(-)
  • +23 -1
    gplugin/reference/genie.md
  • +15 -1
    gplugin/reference/lua.md
  • +7 -1
    gplugin/reference/native-plugins.md
  • +18 -0
    gplugin/reference/perl5.md
  • +15 -1
    gplugin/reference/python3.md
  • +22 -0
    gplugin/reference/vala.md
    • --- a/gplugin/reference/genie.md Mon Aug 29 22:00:31 2022 -0500
    +++ b/gplugin/reference/genie.md Tue Aug 30 02:13:47 2022 -0500
    @@ -21,6 +21,9 @@
    ```genie
    uses GPlugin
    +/* You need to create a class for your plugin info. This is pretty simple as you
    + * can see in the example below.
    + */
    namespace BasicPlugin
    class Info : GPlugin.PluginInfo
    construct()
    @@ -39,17 +42,36 @@
    description: "description"
    )
    +/* gplugin_query is called when searching for plugins. The function should
    + * return an instance of the PluginInfo class you created above. If something
    + * went wrong, you can set error with an error message.
    + */
    def gplugin_query(out error : Error) : GPlugin.PluginInfo
    error = null
    return new BasicPlugin.Info()
    +/* gplugin_load is called when your plugin is loaded in the application. If
    + * something isn't quite right, you can return false and optionally set error,
    + * to signify that something went wrong and stop your plugin from being loaded.
    + */
    def gplugin_load(plugin : GPlugin.Plugin, out error : Error) : bool
    error = null
    return true
    -def gplugin_unload(plugin : GPlugin.Plugin, out error : Error) : bool
    +/* gplugin_plugin_unload is called when your plugin is unloaded in the
    + * application. The shutdown parameter tells your plugin whether or not the
    + * application is shutting down. For example, if a user unloads your plugin,
    + * shutdown will be false, but if the program is shutting down, shutdown will be
    + * true.
    + *
    + * If something went wrong with the unload or the plugin isn't ready to be
    + * unloaded, you can return false, and optionally set error, here to stop it
    + * from being unloaded. Note if shutdown is true, the return value is not
    + * honored.
    + */
    +def gplugin_unload(plugin : GPlugin.Plugin, shutdown: bool, out error : Error) : bool
    error = null
    return true
    --- a/gplugin/reference/lua.md Mon Aug 29 22:00:31 2022 -0500
    +++ b/gplugin/reference/lua.md Tue Aug 30 02:13:47 2022 -0500
    @@ -17,6 +17,8 @@
    local lgi = require "lgi"
    local GPlugin = lgi.GPlugin
    +-- gplugin_plugin_query is called when searching for plugins. The only thing
    +-- this function should do, is return a GPlugin.PluginInfo instance.
    function gplugin_query()
    return GPlugin.PluginInfo {
    id = "gplugin-lua/basic-plugin",
    @@ -32,11 +34,23 @@
    }
    end
    +-- gplugin_load is called when your plugin is loaded in the application. If
    +-- something isn't quite right, you can return false or call error() to signify
    +-- that something went wrong and stop your plugin from being loaded.
    function gplugin_load(plugin)
    return true
    end
    -function gplugin_unload(plugin)
    +-- gplugin_plugin_unload is called when your plugin is unloaded in the
    +-- application. The shutdown parameter tells your plugin whether or not the
    +-- application is shutting down. For example, if a user unloads your plugin,
    +-- shutdown will be false, but if the program is shutting down, shutdown will be
    +-- true.
    +--
    +-- If something went wrong with the unload or the plugin isn't ready to be
    +-- unloaded, you can return false here to stop it from being unloaded. Note if
    +-- shutdown is true, the return value is not honored.
    +function gplugin_unload(plugin, shutdown)
    return true
    end
    ```
    --- a/gplugin/reference/native-plugins.md Mon Aug 29 22:00:31 2022 -0500
    +++ b/gplugin/reference/native-plugins.md Tue Aug 30 02:13:47 2022 -0500
    @@ -63,9 +63,15 @@
    * g_set_error() and return %FALSE. This function needs to match the signature
    * of GPluginNativePluginUnloadFunc, and it will be passed to
    * GPLUGIN_NATIVE_PLUGIN_DECLARE which will export it properly.
    + *
    + * The shutdown parameter is set to TRUE when the application is shutting down.
    + * This is useful if you're using a library where you can only initialize it
    + * once. In this case, you'd typically always return FALSE here, but with the
    + * shutdown parameter, you can return FALSE when shutdown is FALSE, but then
    + * properly uninitialize the library when shutdown is TRUE.
    */
    static gboolean
    -gplugin_native_basic_plugin_unload(GPluginPlugin *plugin, GError *error) {
    +gplugin_native_basic_plugin_unload(GPluginPlugin *plugin, gboolean shutdown, GError *error) {
    return TRUE;
    }
    --- a/gplugin/reference/perl5.md Mon Aug 29 22:00:31 2022 -0500
    +++ b/gplugin/reference/perl5.md Tue Aug 30 02:13:47 2022 -0500
    @@ -20,6 +20,8 @@
    Glib::Object::Introspection->setup(basename => "GPlugin", version => "1.0", package=> "GPlugin");
    +# gplugin_plugin_query is called when searching for plugins. The only thing this
    +# function should do, is return a GPlugin.PluginInfo instance.
    sub gplugin_query {
    return GPlugin::PluginInfo->new(
    id => "gplugin/perl5-basic-plugin",
    @@ -35,11 +37,27 @@
    );
    }
    +# gplugin_plugin_load is called when your plugin is loaded in the application.
    +# If something isn't quite right, you can return non zero or call die() to
    +# signify that something went wrong and stop your plugin from being loaded.
    sub gplugin_load {
    + my $plugin = shift;
    +
    return 0;
    }
    +# gplugin_plugin_unload is called when your plugin is unloaded in the
    +# application. The shutdown parameter tells your plugin whether or not the
    +# application is shutting down. For example, if a user unloads your plugin,
    +# shutdown will be 1, but if the program is shutting down, shutdown will be 0.
    +#
    +# If something went wrong with the unload or the plugin isn't ready to be
    +# unloaded you can return 1 here to stop it from being unloaded. Note if
    +# shutdown is 0, the return value is not honored.
    sub gplugin_unload {
    + my $plugin = shift;
    + my $shutdown = shift;
    +
    return 0;
    }
    ```
    --- a/gplugin/reference/python3.md Mon Aug 29 22:00:31 2022 -0500
    +++ b/gplugin/reference/python3.md Tue Aug 30 02:13:47 2022 -0500
    @@ -20,6 +20,8 @@
    gi.require_version("GPlugin", "0.0")
    from gi.repository import GPlugin
    +# gplugin_plugin_query is called when searching for plugins. The only thing this
    +# function should do, is return a GPlugin.PluginInfo instance.
    def gplugin_plugin_query():
    return GPlugin.PluginInfo(
    id="gplugin-python/basic-plugin",
    @@ -34,10 +36,22 @@
    description="description",
    )
    +# gplugin_plugin_load is called when your plugin is loaded in the application.
    +# If something isn't quite right, you can return False or throw an exception to
    +# signify that something went wrong and stop your plugin from being loaded.
    def gplugin_plugin_load(plugin):
    return True
    -def gplugin_plugin_unload(plugin):
    +# gplugin_plugin_unload is called when your plugin is unloaded in the
    +# application. The shutdown parameter tells your plugin whether or not the
    +# application is shutting down. For example, if a user unloads your plugin,
    +# shutdown will be False, but if the program is shutting down, shutdown will be
    +# True.
    +#
    +# If something went wrong with the unload or the plugin isn't ready to be
    +# unloaded, you can return False here to stop it from being unloaded. Note if
    +# shutdown is True, the return value is not honored.
    +def gplugin_plugin_unload(plugin, shutdown):
    return True
    ```
    --- a/gplugin/reference/vala.md Mon Aug 29 22:00:31 2022 -0500
    +++ b/gplugin/reference/vala.md Tue Aug 30 02:13:47 2022 -0500
    @@ -23,6 +23,9 @@
    namespace BasicPlugin {
    +/* You need to create a class for your plugin info. This is pretty simple as you
    + * can see in the example below.
    + */
    public class Info : GPlugin.PluginInfo {
    public Info() {
    string[] authors = {"author1"};
    @@ -44,18 +47,37 @@
    }
    +/* gplugin_query is called when searching for plugins. The function should
    + * return an instance of the PluginInfo class you created above. If something
    + * went wrong, you can set error with an error message.
    + */
    public GPlugin.PluginInfo gplugin_query(out Error error) {
    error = null;
    return new BasicPlugin.Info();
    }
    +/* gplugin_load is called when your plugin is loaded in the application. If
    + * something isn't quite right, you can return false and optionally set error,
    + * to signify that something went wrong and stop your plugin from being loaded.
    + */
    public bool gplugin_load(GPlugin.Plugin plugin, out Error error) {
    error = null;
    return true;
    }
    +/* gplugin_plugin_unload is called when your plugin is unloaded in the
    + * application. The shutdown parameter tells your plugin whether or not the
    + * application is shutting down. For example, if a user unloads your plugin,
    + * shutdown will be false, but if the program is shutting down, shutdown will be
    + * true.
    + *
    + * If something went wrong with the unload or the plugin isn't ready to be
    + * unloaded, you can return false, and optionally set error, here to stop it
    + * from being unloaded. Note if shutdown is true, the return value is not
    + * honored.
    + */
    public bool gplugin_unload(GPlugin.Plugin plugin, out Error error) {
    error = null;