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