| 1 |
.. _require-via: |
| 2 |
|
| 3 |
Require via |
| 4 |
=========== |
| 5 |
|
| 6 |
As described in the :ref:`spider-sub-command` design document, a loaded module |
| 7 |
that enables a modulepath is considered the *via* module of other loaded |
| 8 |
modules whose modulefiles are stored in this modulepath. |
| 9 |
|
| 10 |
This document is about considering a *via* module as a requirement for the |
| 11 |
loaded module stored in the modulepath it enables. This means, as with other |
| 12 |
kinds of requirements, that unloading a *via* module: |
| 13 |
|
| 14 |
* raises an error if ``auto_handling`` is disabled, as a dependent module is |
| 15 |
loaded |
| 16 |
* automatically unloads all dependent modules if ``auto_handling`` is enabled |
| 17 |
(*DepUn* mechanism) |
| 18 |
* automatically reloads all dependent modules if ``auto_handling`` is enabled |
| 19 |
and an alternative *via* module is loaded (*DepRe* mechanism) |
| 20 |
|
| 21 |
This feature provides a *module hierarchy* mechanism. |
| 22 |
|
| 23 |
It is controlled by the :mconfig:`require_via` configuration option, which is |
| 24 |
disabled by default to maintain compatibility in Modules version 5 branch. |
| 25 |
This option will be enabled by default when moving to Modules version 6. |
| 26 |
|
| 27 |
Via module requirement |
| 28 |
---------------------- |
| 29 |
|
| 30 |
When :mconfig:`require_via` is enabled, *via* module is considered a |
| 31 |
requirement by loaded modules whose modulefiles are stored in this enabled |
| 32 |
modulepath. The same properties as for requirements defined with |
| 33 |
:mfcmd:`prereq` apply: |
| 34 |
|
| 35 |
* active requirement if *via* module is loaded before its dependent |
| 36 |
* if *via* module is loaded after its dependent, it is considered a *Non |
| 37 |
Particular Order* (NPO) requirement: such requirement is inactive |
| 38 |
* if several loaded modules enable the same modulepath, the one considered as |
| 39 |
the *via* module depends on :mconfig:`unload_match_order` config option |
| 40 |
|
| 41 |
A module enabling an already enabled modulepath is not considered a via |
| 42 |
module. In this situation a loaded module whose modulefile is stored in this |
| 43 |
modulepath do not have a dependency on any modulepath-enabling loaded modules. |
| 44 |
Since modulepath have already been enabled before other modules are loaded. |
| 45 |
Same behavior is observed on Lmod. |
| 46 |
|
| 47 |
Modulepath enabling may be expressed with reference to external environment |
| 48 |
variables. Modulepath resolution is thus dynamic. |
| 49 |
|
| 50 |
*Via* module requirement adds to the other kinds of requirements which are |
| 51 |
checked to guarantee the consistency of the loaded environment. Depending on |
| 52 |
:mconfig:`auto_handling` value, load or unload operations that impact |
| 53 |
dependency consistency may lead to: |
| 54 |
|
| 55 |
* an error if ``auto_handling`` is disabled |
| 56 |
* automatic dependent module unload or reload if ``auto_handling`` is enabled |
| 57 |
|
| 58 |
Dependent Reload mechanism update |
| 59 |
--------------------------------- |
| 60 |
|
| 61 |
Dependent modules of a *via* module are targeted by the Dependent Reload |
| 62 |
(DepRe) mechanism if *via* module is swapped or unloaded by Conflict Unload |
| 63 |
(ConUn) mechanism. |
| 64 |
|
| 65 |
As introduced with the ConUn mechanism, a test is made prior reloading each |
| 66 |
DepRe module to check if it is loadable. If test determines module is not |
| 67 |
able to reload, the reload is skipped and the module is considered a Dependent |
| 68 |
Unload (DepUn) module. |
| 69 |
|
| 70 |
This test checks no conflicting module are loaded and requirements are loaded. |
| 71 |
A new check is added for all DepRe modules attempting to reload: it should be |
| 72 |
available in enabled modulepaths. |
| 73 |
|
| 74 |
Either the modulepath where module is stored is still enabled or module is |
| 75 |
found in enabled modulepaths. |
| 76 |
|
| 77 |
This availability new check is not linked to the ``require_via`` configuration |
| 78 |
option. It is performed even when option is disabled. What is linked to this |
| 79 |
option is to include the dependent of a *via* module in the DepRe mechanism. |
| 80 |
|
| 81 |
*NOTE*: The availability of used variants is not checked by this mechanism. |
| 82 |
Thus if modulefile is found but it does not contain anymore the used variant, |
| 83 |
a DepRe error is obtained. |
| 84 |
|
| 85 |
*FUTURE*: DepRe module reload may be attempted whatever the conditions and in |
| 86 |
case of error, this evaluation is silenced if error is of following kind: |
| 87 |
conflict present, requirement missing, module not available, variant not |
| 88 |
available. Such behavior would help if variant is not available anymore or |
| 89 |
if module in new modulepath does not express the same conflicts or |
| 90 |
requirements. |
| 91 |
|
| 92 |
In case of modulepath change and module reload, tags defined in the disabled |
| 93 |
modulepath does not apply anymore to the reloading module. Tags defined in new |
| 94 |
modulepath does. Extra tags are re-applied to the reloading module. |
| 95 |
|
| 96 |
Unused modulepath |
| 97 |
----------------- |
| 98 |
|
| 99 |
When modulepath is unused from the command-line, nothing is unloaded as |
| 100 |
dependency is based on *via* module. If *via* module is unloaded afterward, |
| 101 |
dependency link is still active if ``require_via`` is enabled. |
| 102 |
|
| 103 |
*CORNER CASE*: There is an exception if module is virtual since its modulepath |
| 104 |
cannot be guessed for sure, thus the dependency link cannot be maintained with |
| 105 |
such modules. |
| 106 |
|
| 107 |
*FUTURE*: storing modulepath of loaded modulefiles in environment would help |
| 108 |
to know for sure the modulepath where the virtual module is stored even if the |
| 109 |
modulepath is no longer enabled in environment. |
| 110 |
|
| 111 |
*NOTE*: When modulepath is unused from the command-line, Lmod inactivates |
| 112 |
modules stored in this modulepath. If modulepath is unused externally and the |
| 113 |
*via* module is then unloaded, Lmod still inactivates modules stored in this |
| 114 |
modulepath. |
| 115 |
|
| 116 |
*CORNER CASE*: if modulepath is unused, no *via* module loaded and modules |
| 117 |
stored in this path are loaded, loading the *via* module for this part does |
| 118 |
not trigger a reload of modules stored in this path. It is not known that the |
| 119 |
module to load is the *via* module, thus modules stored in this path are not |
| 120 |
set to reload prior this module load. |
| 121 |
|
| 122 |
Several modules enabling same modulepath |
| 123 |
---------------------------------------- |
| 124 |
|
| 125 |
When same modulepath is enabled by multiple modules, the *via* module is |
| 126 |
determined, like other kinds of requirements, based on |
| 127 |
:mconfig:`unload_match_order` configuration option: |
| 128 |
|
| 129 |
* when it equals ``returnlast``: lastly loaded module before dependent is the |
| 130 |
*via* module |
| 131 |
* when it equals ``returnfirst``: firstly loaded module before dependent is |
| 132 |
the *via* module |
| 133 |
|
| 134 |
Any module enabling modulepath but loaded after dependent is considered a *Non |
| 135 |
Particular Order* dependency. It is taken into account if regular *via* module |
| 136 |
loaded before dependent is unloaded. In this case, the dependent is reloaded |
| 137 |
to adopt the *via* module loaded afterward as its new dependency. |
| 138 |
|
| 139 |
When several modules enabling same modulepath are loaded before the dependent, |
| 140 |
unloading the one considered the *via* module currently unloads the dependent. |
| 141 |
The other potential *via* modules are not taken into account, unless one is |
| 142 |
loaded after the dependent module. Same behavior is observed with other kinds |
| 143 |
of requirements. |
| 144 |
|
| 145 |
*FUTURE*: take into account alternative *via* module loaded before dependent |
| 146 |
when main one is unloaded, to reload dependent and bind it to the new *via* |
| 147 |
module (lastly or firstly loaded one, depending on ``unload_match_order``). |
| 148 |
|
| 149 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |