more eol-style
[xonotic/netradiant.git] / libs / synapse / doc / unload.txt
1 Release / Reload of modules
2 ---------------------------
3
4 The 'not active' modules are unloaded after startup
5 Plugins should be allowed to be unloaded and reloaded on the fly
6 Modules too, when possible?
7
8 Don't want to 'force' all plugins to have unload capabilities
9 Just has to be something specified at compile time wether or not they can unload 'cleanly'
10
11 Dependency implications. When you release a module, you need to remove a number of interfaces.
12 If those interfaces are being used, can you explicitely ask for them to be unloaded?
13
14 Also, problem with plugins breaking the startup process:
15 http://zerowing.idsoftware.com/bugzilla/show_bug.cgi?id=441
16
17 The most important is to provide a clean shutdown method
18 What's the != between unload and shutdown?
19
20 Means that the server proceeds to the shutdown, and nothing else is supposed to be making
21 calls through APIs post shutdown.
22
23 Should be done in 3 steps:
24 #1 prepare shutdown, all APIs are active, just release and save all the stuff you want
25 #2 tell the modules to shutdown, i.e. release the APIs they point to? (at this point they can't call through anymore)
26 #3 force all things to be unloaded, warn about reference count problems
27
28 What is different when we unload a module, and we want to keep the editor up?
29 All the interfaces obtained from this plugin need to be released
30 If some pure virtual classes have been obtained from this plugin, we need a mecanism to have them removed
31 Do we need a first path to check if the unload procedure is going to be allowed?
32
33 For instance, a plugin that provides custom entities rendering etc.
34 Need to unload first, then need to reload (scan the map again, rebuild)
35
36 Summing up, when doing a reload we need to keep track of the modules and let them know after the
37 module has been reloaded, so that the links can be rebuilt. When doing unload we need to do a
38 'check' pass prior to anything to know if the release is possible. Because it does not depend
39 on the module we unload, it depends on the other clients that use it.
40
41 Objectives:
42 -----------
43
44 - 'release check' of a module
45   walk through the interfaces this module has provided, and make sure the release will be possible
46 - 'release' of a module
47   actually drop all the interfaces. this should be done only after a 'release check'
48         if something fails here, we are in an unstable state and need to abort
49 - 'client shutdown' unused modules after initial startup
50   actual DLL unload / complete shutdown of the client interface 
51         this comes after 'release check' and 'release'
52 - 'refresh' modules
53   'release check', 'release', 'shutdown' and then, reload and build the links again
54 - 'core shutdown'
55   'release' and force 'shutdown' of all clients
56         even if we encounter some interfaces that we are not able to release cleanly
57         force things and shutdown all clients
58         then the core process is ready to exit..
59
60 Constraints:
61 ------------
62
63 - refresh and shutdown are sharing some code
64 - the 'release' part of a module refresh may not be always possible (that's what 'release check' is there for)
65 - 'core shutdown' has to be forced to happen, in the safest way possible obviously
66
67 Implementation:
68 ---------------
69
70 - 'client shutdown' comes first
71   this is used after initial startup, since we don't have to do a prior 'release' on those
72         this will be used in the 'core shutdown' and 'refresh' too 
73 - then 'core shutdown' procedure?
74   that's the most urgent thing we need
75         but 'release check' and 'release' have to be written in and used during 'core shutdown'
76 - 'refresh' takes an essential part of the design, but that's not something we need to have written right now?
77   (it mostly relies on 'release check' 'release' 'client shutdown', and then reload and rebuild the links)
78         
79 'client shutdown':
80 this is server side code though, you tell the server 'shutdown this client'
81 we don't have to exchange anything with the client while we do that
82 (written initially for unload of unused modules after startup)
83
84 'core shutdown':
85 is a shutdown of all clients