Add remote commands that pass the arguments of another process to the running plugins

Author: SineStriker

README.md

@@ -436,6 +436,7 @@ The lifecycle has the following ordering and ownership rules:
 
 - Loading and initialization follow dependency order. `loadOrder()` returns that order after loading, with only the plugins that took part.
 - `pluginsInitialized()` and `aboutToShutdown()` run in reverse dependency order.
+- `PluginSystem::remoteCommand()` passes the arguments of another process of the application, such as the files of a second start, to `IPlugin::remoteCommand()` of every running plugin in load order. A command passed before `loadPlugins()` finishes is kept until every plugin is running. A command passed after shutdown starts has no effect.
 - Shutdown unloads libraries in reverse dependency order.
 - After a spec reaches a loaded lifecycle state, `PluginSpec::plugin()` returns its non-owning `IPlugin` pointer. Hosts can cast it to the IID-specific application interface.
 - Successful shutdown clears the plugin pointer when the library is unloaded.

include/stdcorelib/pluginsystem/iplugin.h

@@ -3,7 +3,9 @@
 #ifndef STDCORELIB_PLUGINSYSTEM_IPLUGIN_H
 #define STDCORELIB_PLUGINSYSTEM_IPLUGIN_H
 
+#include <filesystem>
 #include <string>
+#include <vector>
 
 #include <stdcorelib/plugin/plugin.h>
 
@@ -28,6 +30,17 @@ namespace stdc::pluginsystem {
 
         /// Notifies this plugin during shutdown before any plugin library is unloaded.
         virtual void aboutToShutdown();
+
+        /// Handles the arguments that another process of the application passes to this
+        /// process instead of running itself, such as the files of a second start.
+        ///
+        /// \param arguments The arguments in UTF-8, without the program.
+        /// \param workingDirectory The working directory of the other process, against which a
+        ///        relative path in \a arguments resolves.
+        ///
+        /// \sa PluginSystem::remoteCommand()
+        virtual void remoteCommand(const std::vector<std::string> &arguments,
+                                   const std::filesystem::path &workingDirectory);
     };
 
     /// @}

include/stdcorelib/pluginsystem/pluginsystem.h

@@ -133,6 +133,17 @@ namespace stdc::pluginsystem {
         /// PluginSpec.
         void loadPlugins();
 
+        /// Passes the arguments of another process of the application to IPlugin::remoteCommand()
+        /// of every running plugin, in load order.
+        ///
+        /// - A command passed before loadPlugins() finishes is kept, and passed in the order of
+        ///   the commands once every plugin is initialized. This includes a command passed during
+        ///   loadPlugins() from an event loop that a plugin runs.
+        /// - A command passed after shutdownPlugins() starts has no effect.
+        /// - The caller is the thread that calls loadPlugins().
+        void remoteCommand(const std::vector<std::string> &arguments,
+                           const std::filesystem::path &workingDirectory);
+
         /// Shuts down and unloads plugins in reverse dependency order.
         ///
         /// Repeated calls and calls before loadPlugins() have no effect. The destructor calls this

src/pluginsystem/iplugin.cpp

@@ -12,4 +12,7 @@ namespace stdc::pluginsystem {
     void IPlugin::aboutToShutdown() {
     }
 
+    void IPlugin::remoteCommand(const std::vector<std::string> &, const std::filesystem::path &) {
+    }
+
 }

src/pluginsystem/pluginsystem.cpp

@@ -285,6 +285,17 @@ namespace stdc::pluginsystem {
         return result;
     }
 
+    void PluginSystem::Impl::dispatchRemoteCommand(const RemoteCommand &command) {
+        for (auto data : loadOrder) {
+            if (shutdownFinished) {
+                return;
+            }
+            if (data->state == PluginSpec::Running) {
+                data->plugin->remoteCommand(command.arguments, command.workingDirectory);
+            }
+        }
+    }
+
     void PluginSystem::Impl::shutdownPlugins() {
         std::lock_guard<std::mutex> lifecycleLock(lifecycleMtx);
         if (!loadStarted || shutdownFinished) {
@@ -406,7 +417,7 @@ namespace stdc::pluginsystem {
 
     void PluginSystem::loadPlugins() {
         stdc_impl_t;
-        std::lock_guard<std::mutex> lifecycleLock(impl.lifecycleMtx);
+        std::unique_lock<std::mutex> lifecycleLock(impl.lifecycleMtx);
         {
             std::unique_lock<std::shared_mutex> lock(impl.configMtx);
             if (impl.loadStarted) {
@@ -464,6 +475,32 @@ namespace stdc::pluginsystem {
             data->plugin->pluginsInitialized();
             data->state = PluginSpec::Running;
         }
+
+        // The kept commands are passed without the lifecycle lock, so that a plugin may shut
+        // down the system while it handles a command. A command passed meanwhile is kept behind
+        // them, because loadFinished is set only after the last of them.
+        lifecycleLock.unlock();
+        while (!impl.pendingRemoteCommands.empty()) {
+            const auto command = std::move(impl.pendingRemoteCommands.front());
+            impl.pendingRemoteCommands.erase(impl.pendingRemoteCommands.begin());
+            impl.dispatchRemoteCommand(command);
+        }
+        impl.loadFinished = true;
+    }
+
+    void PluginSystem::remoteCommand(const std::vector<std::string> &arguments,
+                                     const std::filesystem::path &workingDirectory) {
+        stdc_impl_t;
+        // No lock, because a plugin may run an event loop that delivers the command during
+        // loadPlugins(), which holds the lifecycle lock on the same thread.
+        if (impl.shutdownFinished) {
+            return;
+        }
+        if (!impl.loadFinished) {
+            impl.pendingRemoteCommands.push_back({arguments, workingDirectory});
+            return;
+        }
+        impl.dispatchRemoteCommand({arguments, workingDirectory});
     }
 
     void PluginSystem::shutdownPlugins() {

src/pluginsystem/pluginsystem_p.h

@@ -50,6 +50,17 @@ namespace stdc::pluginsystem {
         bool loadStarted = false;
         bool shutdownFinished = false;
 
+        struct RemoteCommand {
+            std::vector<std::string> arguments;
+            std::filesystem::path workingDirectory;
+        };
+        /// Set when loadPlugins() has initialized every plugin and passed the kept commands. Read
+        /// and written on the lifecycle thread only.
+        bool loadFinished = false;
+        /// The commands passed before loadPlugins() finished, in their order
+        std::vector<RemoteCommand> pendingRemoteCommands;
+        void dispatchRemoteCommand(const RemoteCommand &command);
+
         std::map<PluginSpecData *, ResolvedDependencies> resolvedDependencies;
         /// Written once under configMtx. The lifecycle thread reads it without the lock.
         PluginOrder loadOrder;

tests/auto/plugins/test_pluginsystem_plugin/test_pluginsystem_lifecycle_plugin.cpp

@@ -27,6 +27,17 @@ namespace {
             notify("aboutToShutdown");
         }
 
+        // Records the arguments separated by spaces and the working directory after a colon
+        void remoteCommand(const std::vector<std::string> &arguments,
+                           const std::filesystem::path &workingDirectory) override {
+            std::string event = "remoteCommand";
+            for (const auto &argument : arguments) {
+                event += " " + argument;
+            }
+            event += ":" + workingDirectory.generic_string();
+            notify(event.c_str());
+        }
+
     private:
         static void notify(const char *event) {
             if (eventCallback) {

tests/auto/test_pluginsystem.cpp

@@ -9,6 +9,7 @@
 #include <atomic>
 #include <chrono>
 #include <fstream>
+#include <functional>
 #include <thread>
 
 #include <boost/test/unit_test.hpp>
@@ -163,9 +164,14 @@ namespace {
 
     std::vector<std::string> lifecycleEvents;
     stdc::pluginsystem::PluginSystem *activePluginSystem = nullptr;
+    // Called with each recorded event, so that a test may act during the lifecycle
+    std::function<void(const std::string &)> lifecycleHook;
 
     void recordLifecycleEvent(const char *plugin, const char *event) {
         lifecycleEvents.push_back(std::string(plugin) + "." + event);
+        if (lifecycleHook) {
+            lifecycleHook(lifecycleEvents.back());
+        }
         if (activePluginSystem) {
             activePluginSystem->plugins();
             activePluginSystem->hasError();
@@ -602,6 +608,58 @@ BOOST_AUTO_TEST_CASE(test_lifecycle_dependency_order_and_reentrant_queries) {
     }
 }
 
+BOOST_AUTO_TEST_CASE(test_remote_commands_reach_running_plugins_in_load_order) {
+    TemporaryPluginSystemDirectory directory(stdc::pluginsystem::PluginSystem::Bundle, false);
+    const auto providerPath = directory.addPlugin(
+        "provider", R"({"id":"Provider","displayName":"Provider","version":"1.0"})",
+        TEST_PLUGINSYSTEM_LIFECYCLE_PROVIDER_PATH);
+    const auto consumerPath = directory.addPlugin(
+        "consumer",
+        R"({"id":"Consumer","displayName":"Consumer","version":"1.0","dependencies":[{"id":"Provider","version":"1.0","type":"required"}]})",
+        TEST_PLUGINSYSTEM_LIFECYCLE_CONSUMER_PATH);
+
+    stdc::SharedLibrary providerLibrary;
+    stdc::SharedLibrary consumerLibrary;
+    setLifecycleCallback(&providerLibrary, providerPath);
+    setLifecycleCallback(&consumerLibrary, consumerPath);
+
+    stdc::pluginsystem::PluginSystem system("org.stdcorelib.PluginSystem",
+                                            stdc::pluginsystem::PluginSystem::Bundle);
+    system.setPluginPaths(directory.path());
+    lifecycleEvents.clear();
+
+    // A command before loading and a command during the initialization are kept until every
+    // plugin is running, in their order.
+    system.remoteCommand({"before"}, "/a");
+    lifecycleHook = [&system](const std::string &event) {
+        if (event == "consumer.initialize") {
+            system.remoteCommand({"during", "x"}, "/b");
+        }
+    };
+    system.loadPlugins();
+    lifecycleHook = nullptr;
+    system.remoteCommand({"after"}, "/c");
+    system.shutdownPlugins();
+    system.remoteCommand({"shutdown"}, "/d");
+
+    const std::vector<std::string> expected{
+        "provider.initialize",
+        "consumer.initialize",
+        "consumer.pluginsInitialized",
+        "provider.pluginsInitialized",
+        "provider.remoteCommand before:/a",
+        "consumer.remoteCommand before:/a",
+        "provider.remoteCommand during x:/b",
+        "consumer.remoteCommand during x:/b",
+        "provider.remoteCommand after:/c",
+        "consumer.remoteCommand after:/c",
+        "consumer.aboutToShutdown",
+        "provider.aboutToShutdown",
+    };
+    BOOST_CHECK_EQUAL_COLLECTIONS(lifecycleEvents.begin(), lifecycleEvents.end(), expected.begin(),
+                                  expected.end());
+}
+
 BOOST_AUTO_TEST_CASE(test_load_order_puts_dependencies_first) {
     TemporaryPluginSystemDirectory directory(stdc::pluginsystem::PluginSystem::Bundle, false);
     directory.addPlugin(