libs/synapse/doc/unload.txt

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