Debian Codegraph @

doc/source/design/require-via.rst

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