Finds the plugins of one seam, reads their metadata without loading them, and loads one only when asked. More...
#include <PhosphorRegistry/PluginCatalog.h>
Signals | |
| void | pluginAdded (const QString &id) |
| A plugin id came on offer, or the file of a plugin on offer that is not loaded changed (see the class notes). | |
| void | pluginRemoved (const QString &id) |
| A plugin id left the offer: its file is gone or now refused. | |
| void | scanCompleted () |
| After every scan, whether or not anything changed. | |
Public Member Functions | |
| PluginCatalog (PluginSeam seam, QObject *parent=nullptr) | |
| ~PluginCatalog () override | |
| const PluginSeam & | seam () const |
| void | setSearchPaths (const QList< PluginSearchPath > &paths) |
| Replace the directories to search, highest priority first. | |
| QList< PluginSearchPath > | searchPaths () const |
| void | setLiveReload (bool enabled) |
| Watch the search paths and rescan when they change (on by default). | |
| void | scan () |
| Scan the search paths and read every plugin's metadata. | |
| QList< PluginMetadata > | plugins () const |
| Every plugin on offer, sorted by id. | |
| std::optional< PluginMetadata > | plugin (const QString &id) const |
| QList< RefusedPlugin > | refused () const |
| The plugin files refused by the last scan, sorted by path. | |
| QObject * | load (const QString &id, QString *errorString=nullptr) |
Load the plugin id, which must be on offer, and return its root object, or nullptr with the reason in errorString. | |
| bool | isLoaded (const QString &id) const |
| void | setMaxFilesPerScanForTest (int cap) |
| Test seam: cap the number of plugin files considered per scan. | |
Static Public Member Functions | |
| static QList< PluginSearchPath > | defaultSearchPaths (const QString &seamName) |
The directories searched for seamName when no search paths are set, highest priority first. | |
Static Public Attributes | |
| static constexpr const char * | DevelopmentPathVariable = "PHOSPHOR_WORKS_PLUGIN_PATH" |
| The environment variable holding development plugin roots, colon-separated. | |
Finds the plugins of one seam, reads their metadata without loading them, and loads one only when asked.
Search order, highest priority first (see defaultSearchPaths):
Every *.so file in a searched directory is vetted, and refused with the reason kept in refused() and logged once, when:
Loaded plugins are never unloaded. A loaded plugin whose file is removed or now refused leaves plugins() and emits pluginRemoved, even when another copy with the same id exists (that copy takes effect at the next start), and its loaded instance stays valid. A loaded plugin keeps running the code it was loaded from until the process restarts, and Qt keeps reporting the metadata of that code for its path. Replace a loaded plugin by rename (install, mv), never by writing over it in place, which changes the code the process is running.
A plugin on offer that is not loaded is offered again, with a new pluginAdded for an id already in plugins(), once the file behind it is no longer the one it was last offered with: rewritten, replaced by a rename over it, overridden by a copy found earlier, or removed while another copy of the same id takes its place. A failed load() counts as an offer of the file as it was then, so a plugin whose load failed is offered again only once its file changes after that. A file is told apart by its device, inode, size and modification time. A scan that finds every such file as it was emits neither pluginAdded nor pluginRemoved. A loaded plugin is never offered again this way, since it keeps the code it was loaded from.
Calling scan() from a slot that a scan's own signals reach defers the rescan until the running one has finished.
GUI thread only, like WatchedDirectorySet.
|
explicit |
|
override |
|
staticnodiscard |
The directories searched for seamName when no search paths are set, highest priority first.
Relative entries are skipped with a warning.
|
nodiscard |
| QObject * PhosphorRegistry::PluginCatalog::load | ( | const QString & | id, |
| QString * | errorString = nullptr ) |
Load the plugin id, which must be on offer, and return its root object, or nullptr with the reason in errorString.
The file is vetted again first. When it no longer passes, load() fails and schedules a rescan, live reload or not, which withdraws the plugin. A library with an unresolved symbol fails to load. A later call returns the same object, also after the plugin was withdrawn and offered again.
|
nodiscard |
|
signal |
A plugin id came on offer, or the file of a plugin on offer that is not loaded changed (see the class notes).
A slot can therefore see an id it already knows, and should read plugin() again.
|
signal |
A plugin id left the offer: its file is gone or now refused.
|
nodiscard |
Every plugin on offer, sorted by id.
|
nodiscard |
The plugin files refused by the last scan, sorted by path.
| void PhosphorRegistry::PluginCatalog::scan | ( | ) |
Scan the search paths and read every plugin's metadata.
The first call registers the directories, arms the watch and scans synchronously. Later calls rescan synchronously, except from inside a running scan.
|
signal |
After every scan, whether or not anything changed.
|
nodiscard |
|
nodiscard |
| void PhosphorRegistry::PluginCatalog::setLiveReload | ( | bool | enabled | ) |
Watch the search paths and rescan when they change (on by default).
Must be called before scan(). A search path that does not exist yet is picked up when it appears, unless its nearest existing ancestor is a directory the watcher refuses to watch (such as ~/.local/share or /tmp). Then it is picked up by the next scan().
| void PhosphorRegistry::PluginCatalog::setMaxFilesPerScanForTest | ( | int | cap | ) |
Test seam: cap the number of plugin files considered per scan.
A scan that reaches the cap keeps what it knew about the files it did not reach. Zero or negative restores the default.
| void PhosphorRegistry::PluginCatalog::setSearchPaths | ( | const QList< PluginSearchPath > & | paths | ) |
Replace the directories to search, highest priority first.
A relative directory is resolved against the current working directory now. Must be called before scan(). An empty list, or no call at all, means defaultSearchPaths.
|
staticconstexpr |
The environment variable holding development plugin roots, colon-separated.
Each root holds one subdirectory per seam.