Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorRegistry::PluginCatalog Class Reference

Finds the plugins of one seam, reads their metadata without loading them, and loads one only when asked. More...

#include <PhosphorRegistry/PluginCatalog.h>

Inheritance diagram for PhosphorRegistry::PluginCatalog:
[legend]

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.

Detailed Description

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):

  1. each directory in PHOSPHOR_WORKS_PLUGIN_PATH, plus /<seam>
  2. $XDG_DATA_HOME/phosphor-works/plugins/<seam>
  3. each Qt plugin directory (QT_PLUGIN_PATH, then Qt's own), plus /phosphor-works/<seam> A plugin found earlier overrides one with the same id found later, and the override is logged.

Every *.so file in a searched directory is vetted, and refused with the reason kept in refused() and logged once, when:

  • it is a symlink, or not a regular file, or not readable
  • it or its directory is group- or world-writable, or owned by someone other than this user or root
  • a <file>.avx2 sibling exists, which Qt would load in its place
  • it is not a Qt plugin, or its IID is not the seam's
  • it is built against a Qt this process cannot load
  • its metadata has no valid "Id", or no integer "ApiVersion"
  • its "ApiVersion" is not the seam's
  • another plugin in the same directory has the same id The file is vetted again right before load() maps it. Only the plugin file and its directory are vetted: libraries the plugin links or opens are its own trust decision. Hidden files are not considered.

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.

Constructor & Destructor Documentation

◆ PluginCatalog()

PhosphorRegistry::PluginCatalog::PluginCatalog ( PluginSeam seam,
QObject * parent = nullptr )
explicit

◆ ~PluginCatalog()

PhosphorRegistry::PluginCatalog::~PluginCatalog ( )
override

Member Function Documentation

◆ defaultSearchPaths()

QList< PluginSearchPath > PhosphorRegistry::PluginCatalog::defaultSearchPaths ( const QString & seamName)
staticnodiscard

The directories searched for seamName when no search paths are set, highest priority first.

Relative entries are skipped with a warning.

◆ isLoaded()

bool PhosphorRegistry::PluginCatalog::isLoaded ( const QString & id) const
nodiscard

◆ load()

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.

◆ plugin()

std::optional< PluginMetadata > PhosphorRegistry::PluginCatalog::plugin ( const QString & id) const
nodiscard

◆ pluginAdded

void PhosphorRegistry::PluginCatalog::pluginAdded ( const QString & id)
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.

◆ pluginRemoved

void PhosphorRegistry::PluginCatalog::pluginRemoved ( const QString & id)
signal

A plugin id left the offer: its file is gone or now refused.

◆ plugins()

QList< PluginMetadata > PhosphorRegistry::PluginCatalog::plugins ( ) const
nodiscard

Every plugin on offer, sorted by id.

◆ refused()

QList< RefusedPlugin > PhosphorRegistry::PluginCatalog::refused ( ) const
nodiscard

The plugin files refused by the last scan, sorted by path.

◆ scan()

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.

◆ scanCompleted

void PhosphorRegistry::PluginCatalog::scanCompleted ( )
signal

After every scan, whether or not anything changed.

◆ seam()

const PluginSeam & PhosphorRegistry::PluginCatalog::seam ( ) const
nodiscard

◆ searchPaths()

QList< PluginSearchPath > PhosphorRegistry::PluginCatalog::searchPaths ( ) const
nodiscard

◆ setLiveReload()

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().

◆ setMaxFilesPerScanForTest()

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.

◆ setSearchPaths()

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.

Member Data Documentation

◆ DevelopmentPathVariable

const char* PhosphorRegistry::PluginCatalog::DevelopmentPathVariable = "PHOSPHOR_WORKS_PLUGIN_PATH"
staticconstexpr

The environment variable holding development plugin roots, colon-separated.

Each root holds one subdirectory per seam.


The documentation for this class was generated from the following file: