Hosts control modules in an ApplicationController. More...
#include <PhosphorControl/ModuleHost.h>
Classes | |
| struct | RefusedExtension |
| An extension that will not be shown, and why: its target module is installed but could not be placed, its target page does not exist or has no place in the sidebar, the page has no such slot, or offers the slot at another version. More... | |
| struct | ModuleExtension |
| A section a module registered while loading (ModuleContext:: registerExtension). More... | |
Public Types | |
| enum class | ModuleState : quint8 { Available , Loaded , Failed , DisabledAfterCrash } |
Signals | |
| void | moduleLoaded (const QString &moduleId) |
| void | moduleFailed (const QString &moduleId, const QString &reason) |
| void | moduleStateChanged (const QString &moduleId, PhosphorControl::ModuleHost::ModuleState state) |
| Every change of a module's state or reason, including the ones start() finds (invalid metadata, disabled after a crash), which are announced once start() has finished building the sidebar. | |
| void | refusedExtensionsChanged () |
| refusedExtensions() changed. | |
Public Member Functions | |
| ModuleHost (ApplicationController *controller, QObject *parent=nullptr) | |
| ~ModuleHost () override | |
| void | setSearchPaths (const QList< PhosphorRegistry::PluginSearchPath > &paths) |
| Directories to search for modules, highest priority first. | |
| void | setSentinelPath (const QString &path) |
| The load record: the file that holds the module being loaded and the modules disabled after a crash. | |
| void | setConfigRedirect (const QString &directory) |
Make every config file a module opens (ModuleContext::configBackend) under directory instead of where it is, so the backends modules get do not read or write the real files, as long as each module's factory opens the path it is handed: for ModuleTestHost and other tests. | |
| void | setLocale (const QLocale &locale) |
| The locale module metadata is read and sorted in. | |
| void | setLiveReload (bool enabled) |
| Turn the catalog's live reload off, for tests. Before start(). | |
| void | setSearchController (SearchController *search) |
Make search find every module's pages and Search entries, and each active extension as a section of the page it is on, before any module loads. | |
| void | start () |
| Find the modules and build the placeholder sidebar. Call once. | |
| bool | loadModule (const QString &moduleId, QString *errorString=nullptr) |
Load moduleId now. | |
| bool | retryModule (const QString &moduleId, QString *errorString=nullptr) |
Clear DisabledAfterCrash, or a Failed state that canRetry() allows, for moduleId and load it again. | |
| bool | canRetry (const QString &moduleId) const |
True when retryModule() would try to load moduleId again: it is DisabledAfterCrash, or it failed while loading and its file has not changed since. | |
| QStringList | moduleIds () const |
| Every module the host knows, sorted: the ones on offer, and the ones the catalog stopped offering, which stay (Failed, or Loaded when they had loaded). | |
| std::optional< ModuleState > | state (const QString &moduleId) const |
The state of moduleId, or nullopt for a module the host does not know. | |
| QString | stateReason (const QString &moduleId) const |
| std::optional< ModuleMetadata > | metadata (const QString &moduleId) const |
moduleId's metadata exactly as parsed. | |
| QList< PhosphorRegistry::RefusedPlugin > | refusedModules () const |
| Module files the catalog refused, with the reason. | |
| QList< RefusedExtension > | refusedExtensions () const |
| Sorted by id. | |
| QStringList | extensionsOn (const QString &pageId) const |
The scoped ids of the active extensions on pageId, across all its slots, sorted by Order, then module id, then extension id. | |
| QList< StagingDomain * > | moduleDomains (const QString &moduleId) const |
The headless domains moduleId registered while loading, in the order it registered them. | |
| QList< ModuleExtension > | moduleExtensions (const QString &moduleId) const |
The sections moduleId registered while loading, in its metadata's order, whether or not they are active. | |
| QStringList | boundPages (const QString &moduleId) const |
The page ids the module of moduleId registered while loading. | |
| QList< ISearchProvider * > | searchProviders (const QString &moduleId) const |
The search providers the module of moduleId registered while loading, but for one that is a QObject and was deleted since. | |
| PhosphorConfig::IBackend * | configBackend (const QString &path) const |
The config backend modules share for the file at path, an absolute path in any spelling of the file (ModuleContext::configBackend), or null when no module opened that file, path is relative or the ApplicationController is gone. | |
Static Public Member Functions | |
| static PhosphorRegistry::PluginSeam | seam () |
| The control seam: <root>/control/, PhosphorControlModule_iid, ControlModuleApiVersion. | |
| static QString | pageId (const QString &moduleId, const QString &localPageId) |
The scoped page id of localPageId in moduleId. | |
| static QString | categoryNodeId (const QString &categoryId) |
The page id of category categoryId's node. | |
| static QUrl | placeholderPageSource () |
| The QML page a module page shows while its module is not loaded. | |
Hosts control modules in an ApplicationController.
start() reads every module's metadata through a PluginCatalog over the control seam, without loading any module, and fills the page registry with placeholders: one node per category in use, one per module, and one page per module page, all with their real titles and icons. A module page's placeholder shows placeholderPageSource(), so it is an ordinary page in the sidebar, search and keyboard navigation. Opening a module's page (or navigating to its node) loads the module synchronously, through ApplicationController's navigation hook: its registerInto registers into a ModuleContext, and the host then binds its real controllers into the placeholders, all before the page change is announced. A search loads modules too: those whose metadata says SearchProviders (setSearchController). A module that does not load leaves its placeholder up, and the placeholder page shows why, and offers a retry when loading again can help.
Siblings follow Order, then the name: categories at the top level, and modules under their category or parent module. A module's own pages follow their declaration order and come before the modules nested under it; a page that falls back under its module (its target is missing) comes after the others. A page a module places outside itself, in a category or under another module's page, comes after everything else there, among the pages other modules placed there in the order of their modules. A module added while the app runs has its node and those pages slotted in the same way, so it lands where a restart would put it. Pages that modules place under each other's in a cycle cannot all go where they ask: the one that sorts first stays under its own module, and the others go under their targets. Once a module's pages have taken their place, the host checks their counterparts (Counterpart) as PageRegistry::validateCounterparts does, and the counterparts of the pages already there that name one of them, and warns about each that does not resolve.
Page ids: a category node is @category/<id>, a module node is the module id, and a module page is <module>:<page> (ModuleContext::pageId). These forms cannot collide with each other, because module ids contain neither @ nor :. A module whose id is already the id of one of the host application's own pages fails instead of being placed.
Extensions: a module's metadata can add sections to another module's page. start(), and every module added or removed while the app runs, resolves each against its target page's slots and their versions, and lists the ones that do not fit in refusedExtensions(). An extension aimed at a module that is not installed is skipped quietly. Opening a page also loads every module that extends it, once the page's own module has loaded, and an extension that becomes active while its page is open loads its module then. Only one module loads at a time, so a page that a slot opens while a module is loading gets the modules that extend it when that load ends. Nothing loads while a module that arrived takes its place in the sidebar either, so a page that a slot of that (pageRegistered) opens gets its own module and the modules that extend it once the module is placed. All of this needs the navigation hook (start() says when another component holds it). The host answers ApplicationController::extensionsFor() for the page's ExtensionSlots. A section is shown once its extension is active and its page's own module has loaded, and only then does its staging domain join Apply and the page's dirty mark and reset. Neither condition is ever undone, so a section that joins stays shown. When another component already answers extensionsFor (start() says so), no ExtensionSlot shows this host's sections: the host then loads no module for the sections it would add, joins no section's domain to Apply, tells no ExtensionSlot of a change, and search lists neither the sections nor what a module's providers list on the pages it extends.
A crash while a module loads is remembered. The module's id is written to the load record (setSentinelPath) before its library is loaded, and removed once its registerInto has returned, the host has checked what it registered and, with a search controller set, has asked each of its search providers for its entries once. A load record left behind at the next start disables that module (DisabledAfterCrash), and it stays disabled across starts until retryModule(). A crash later, in a page's or a section's QML, in a domain, or in a search provider asked again, is not remembered. Since opening a page loads every module that extends it, a module whose section crashes takes that page down each time it opens, until the module is removed.
The host also keeps the config backends modules share, one for each file, and hands them out through ModuleContext::configBackend. They belong to the ApplicationController, in an object the host parents to it when the host is constructed. So they outlive the host, and a domain can still be applied through its backend then. They are destroyed with the controller, before the page controllers and domains it adopted from modules (see ModuleContext::configBackend for what that asks of a module). A second host on the same controller keeps its own backends, apart from the first's, and the first's stay alive with the controller. Two hosts whose modules open one file therefore hold two documents for it, and each write drops the keys only the other holds.
GUI thread only. The ApplicationController must outlive the host.
|
strong |
| Enumerator | |
|---|---|
| Available | Found and on the sidebar, not loaded yet. |
| Loaded | |
| Failed | Its metadata is invalid, its id or a page id is already taken, its node or a page could not be placed, its library did not load, its root object is not an IControlModule, its registerInto did not match its metadata, its file changed or went away, or its file came back after its code had been loaded. See stateReason(). |
| DisabledAfterCrash | It was loading when the app last stopped unexpectedly. |
|
explicit |
|
override |
|
nodiscard |
The page ids the module of moduleId registered while loading.
|
nodiscard |
True when retryModule() would try to load moduleId again: it is DisabledAfterCrash, or it failed while loading and its file has not changed since.
False for a module that is Available, which loadModule() and retryModule() both load (its placeholder page offers that as a retry too), and for a Loaded one. A failure that loading again cannot fix (invalid metadata, a taken id, a node or page that could not be placed, a root object that is not an IControlModule or was deleted after its library loaded, a file that changed or went away) is not retryable. The catalog offers a module's file again when it is installed again after a removal, and when it changes on disk (rewritten, or replaced by a rename over it) while its library is not loaded. Then a module whose metadata is unchanged, whose pages are all placed and whose library was never loaded can be loaded again, and one that was never placed (invalid metadata, a taken id, no node) is read and placed afresh, so fixing its metadata on disk is enough. A module that had not failed, Available or DisabledAfterCrash, whose file comes back with other metadata fails then, without its library being loaded. Anything else needs a restart. That includes a module that failed with its library loaded: the process keeps running that code, so the file offered again cannot be tried. True does not promise the retry runs now: while another module loads, or modules take their place in the sidebar, retryModule() refuses it and changes nothing.
|
staticnodiscard |
The page id of category categoryId's node.
|
nodiscard |
The config backend modules share for the file at path, an absolute path in any spelling of the file (ModuleContext::configBackend), or null when no module opened that file, path is relative or the ApplicationController is gone.
With setConfigRedirect, path is still the path the module named, not where the file was made. For a host application, or a test, that wants to see which backend a file is shared under. A module gets its backend from its ModuleContext.
|
nodiscard |
The scoped ids of the active extensions on pageId, across all its slots, sorted by Order, then module id, then extension id.
| bool PhosphorControl::ModuleHost::loadModule | ( | const QString & | moduleId, |
| QString * | errorString = nullptr ) |
Load moduleId now.
True when it is loaded, at once or already. False, with the reason in errorString, for a module that failed or was turned off after a crash, and for one that cannot load now: another module is loading, modules are still taking their place in the sidebar (a pageRegistered slot, in start() or as a module arrives), or the call is off the GUI thread. A module the load record keeps turned off after a crash that is still Available, as it is for a slot that runs once its pages are placed but before addModule has disabled it (a search results update, say), becomes DisabledAfterCrash instead of loading.
|
nodiscard |
moduleId's metadata exactly as parsed.
Where the host put the module (a fallback category, a broken nesting cycle) does not change it.
|
nodiscard |
The headless domains moduleId registered while loading, in the order it registered them.
One that code the module ran while it loaded deleted, or that the application refused, reads null, and so does one deleted since.
|
nodiscard |
The sections moduleId registered while loading, in its metadata's order, whether or not they are active.
A deleted domain reads null.
|
signal |
|
nodiscard |
Every module the host knows, sorted: the ones on offer, and the ones the catalog stopped offering, which stay (Failed, or Loaded when they had loaded).
The one exception is a module that was never placed (its metadata was invalid, an id it needs was taken, or its node could not be placed) and whose plugin is gone by the time it is read again: nothing is left of it to keep.
|
signal |
|
signal |
|
staticnodiscard |
The scoped page id of localPageId in moduleId.
|
staticnodiscard |
The QML page a module page shows while its module is not loaded.
It ships in the org.phosphor.control QML module, which the host application's chrome already imports.
|
nodiscard |
Sorted by id.
Changes as modules come and go (refusedExtensionsChanged).
|
signal |
refusedExtensions() changed.
|
nodiscard |
Module files the catalog refused, with the reason.
| bool PhosphorControl::ModuleHost::retryModule | ( | const QString & | moduleId, |
| QString * | errorString = nullptr ) |
Clear DisabledAfterCrash, or a Failed state that canRetry() allows, for moduleId and load it again.
Any other module is handed to loadModule(): an Available one loads, a Loaded one answers true, and a Failed one canRetry() refuses answers false with its reason. When the load record cannot be written, a module that was disabled after a crash is retried all the same, with a warning, and the next start may disable it again. A retry that cannot run now, for the reasons loadModule() gives, changes nothing: the module keeps its state, and one turned off after a crash stays off in the load record.
|
staticnodiscard |
The control seam: <root>/control/, PhosphorControlModule_iid, ControlModuleApiVersion.
|
nodiscard |
The search providers the module of moduleId registered while loading, but for one that is a QObject and was deleted since.
| void PhosphorControl::ModuleHost::setConfigRedirect | ( | const QString & | directory | ) |
Make every config file a module opens (ModuleContext::configBackend) under directory instead of where it is, so the backends modules get do not read or write the real files, as long as each module's factory opens the path it is handed: for ModuleTestHost and other tests.
The module's factory is handed <directory>/<path>, where <path> is the file's absolute path with its symbolic links, . and .. resolved, and the host creates that file's directory. Two spellings of one file still share one backend, two files stay apart, and configBackend() goes on answering for the path the module named. Before start(), ignored with a warning after. A relative path is made absolute against the working directory of this call. The filesystem root is refused with a warning, since it would redirect nothing. Default: empty, which redirects nothing.
| void PhosphorControl::ModuleHost::setLiveReload | ( | bool | enabled | ) |
Turn the catalog's live reload off, for tests. Before start().
| void PhosphorControl::ModuleHost::setLocale | ( | const QLocale & | locale | ) |
The locale module metadata is read and sorted in.
Before start(), ignored with a warning after. Default: QLocale() as it is when start() runs, so a default locale the application sets after making the host still counts. The names of the built-in categories come from the application's installed translators instead, when start() runs.
| void PhosphorControl::ModuleHost::setSearchController | ( | SearchController * | search | ) |
Make search find every module's pages and Search entries, and each active extension as a section of the page it is on, before any module loads.
Before start(), ignored with a warning after. Default: none, and nothing is searched.
The host keeps one provider in search for all of it, listed in the order of each entry's page in the sidebar, and adds the entries of each loaded module's own search providers. It leaves out the entries of a page whose module failed or was turned off after a crash, the sections when another component answers extensionsFor, and what a module's providers list on a page it extends where none of its extensions is active (its extension there was refused), or on any page it extends when another component answers extensionsFor. Whenever the query is not blank, every module whose metadata says SearchProviders and that has not loaded yet loads, so its entries are found too: at once, once a load that is running is over, or once a module that arrived has taken its place in the sidebar. That covers a query typed before start() and a module that arrives while the query stands. The host takes its provider out of search when it is destroyed, so the modules' providers are asked only while the host lives. search may go first.
| void PhosphorControl::ModuleHost::setSearchPaths | ( | const QList< PhosphorRegistry::PluginSearchPath > & | paths | ) |
Directories to search for modules, highest priority first.
Before start(), ignored with a warning after. Default: PluginCatalog::defaultSearchPaths("control").
| void PhosphorControl::ModuleHost::setSentinelPath | ( | const QString & | path | ) |
The load record: the file that holds the module being loaded and the modules disabled after a crash.
Before start(), ignored with a warning after. Default: $XDG_STATE_HOME/phosphor-works/control-loading. A relative path is made absolute against the working directory of this call. When no state directory is available, or the path is set empty, crashes are not remembered. One ModuleHost per load record: a second host, in this process or another, needs a path of its own, or each writes its disabled list over the other's.
| void PhosphorControl::ModuleHost::start | ( | ) |
Find the modules and build the placeholder sidebar. Call once.
|
nodiscard |
The state of moduleId, or nullopt for a module the host does not know.
|
nodiscard |