home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / t / tornado / TNdemo / Guidelines < prev    next >
Encoding:
Text File  |  1996-12-30  |  5.1 KB  |  96 lines
  1. (Note that some of this refers to features not implemented as yet in the
  2. support module)
  3.  
  4.  
  5. Guidelines for writing multithreading applications:
  6. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  7.  * Do NOT share handle-based resources between threads eg; one thread opens a
  8. handle and then passes that handle to another thread and then terminates. If
  9. you MUST do this, pass the handle to the other thread, and *enter* a wait
  10. cycle on that thread after tidying up. Should that thread ever terminate
  11. unnaturally, the thread that opened the handle will be exit that loop and
  12. then should close the handle if it's still open. Conversely, should the other
  13. thread successfully finish its work and no longer need the handle, it then
  14. should terminate and let the thread that created it close it.
  15.    In other words, ALWAYS open and close a handle with the same instance of
  16. thread. This is future-proofing as a future version of this support module
  17. may shut handles for a thread if it is ever forcibly terminated.
  18.  
  19.  * Do NOT linearly program. Mutexs and semaphores are there to be used - make
  20. the main message handler *dispatch* the message by starting up a thread -
  21. don't have the message handler handle the message itself where possible. This
  22. allows maximum responsiveness to be retained.
  23.  
  24.  * Make sure you 17, 18 & 19 poll code handler executes quickly as it is not
  25. preempted and thus both your code and the entire RISC-OS Wimp is held up
  26. until it finishes. Similarly to the point above, *dispatch* tasks into
  27. threads whenever possible and signal your handler. You should NOT attempt to
  28. call Wimp_Poll yourself during the handler.
  29.  
  30.  * Do NOT take long to render your window changes/redraws ie; make the code
  31. that redraws whatever between Tornado_RedrawWindow and Tornado_GetRectangle
  32. as fast as possible as this code is not preempted
  33.  
  34.  * Do note that almost all SWI calls cannot be preempted by this support
  35. module and as a result any SWI that takes some time will hang the computer
  36. for that time
  37.  
  38.  * Do NOT call Wimp_Poll yourself. Also make sure anything you do won't end
  39. up floating ie; if you send a wimp message, make sure your 17, 18 & 19
  40. handler can handle it correctly (eg; notify you).
  41.    An example of this is:
  42. <thread sends wimp message>
  43. <thread now suspends itself *with* timeout>
  44. <when wimp message returns into 17, 18 & 19 handler, handler resumes the
  45. thread>
  46. <all okay - unless wimp message is never replied to - in which case timeout
  47. occurs and then thread should take whatever action required>
  48.  
  49. This is how you should handle wimp messages that require replies. However,
  50. should the message exchange require no Wimp_Poll in between (eg; RAM
  51. transfers), then you should have your 17, 18 & 19 handler do the arbitration
  52. as it is the only part of your code that won't get preempted.
  53.    A nice effect of doing this is that suspending a thread leaves more time
  54. for other threads too so it's best all ways you look at it.
  55.  
  56.  * Do NOT call any of Wimp_RedrawWindow, Wimp_GetRectangle and
  57. Wimp_UpdateWindow yourself. Use Tornado_RedrawWindow and Tornado_GetRectangle
  58. instead (see their APIs for details).
  59.  
  60.  * Do NOT write into memory areas outside your own slot (except your own
  61. dynamic areas). Future versions of the support module may trap this and shut
  62. down your application.
  63.    If you really must access memory in other areas eg; the RMA, switch into
  64. supervisor first. This is difficult within C to do without an assembler
  65. wrapper to help so this is the approach you should take - don't do it unless
  66. you have to!
  67.  
  68.  * Do NOT use Timer1 on the IOC/IOMB as it is used by the support module
  69.  
  70.  * Do NOT have code within your slot (ie; application space) be called under
  71. interrupts/events/RO handlers as the support module does not cater for it.
  72.  
  73.  * Note that errors that occur within the preemption handlers get dumped
  74. (when possible - it isn't always) onto the current environment's error
  75. handler ie; onto the current application usually. When this happens, it will
  76. appear to your code that an error has happened out of nowhere (it has
  77. effectively) and also preemption is now *stopped*. Now the tornado support
  78. module is in an inconsistant state.
  79.    Your code starting preemption again is possible - but it requires shutting
  80. down preemption (via Tornado_Closedown) and restarting it again
  81. (Tornado_Initialise). Remember this is not particularly advisable at ANY time
  82. but this situation can be deemed sufficiently bad to warrent it. The effects
  83. of doing this are to shut down all running threads without calling their exit
  84. handlers and thus you risk losing a great deal of resources unless you're
  85. careful. But it's unlikely you have much of a choice.
  86.    However, do NOT take this as an excuse to automatically restart tornado on
  87. occurance of an error. You can test to see if it is a preemption handler
  88. error using Tornado_NeedReset and if so take appropriate action. See that
  89. SWI's entry for more details.
  90.    Memory full errors cause the preemptor routine to dump whatever
  91. information it was trying to store in the block it was trying to claim ie;
  92. when memory runs out applications using this module simply stop responding
  93. and miss window redraw requests. This is preferable to attempting a
  94. preemption reset which usually causes a vast memory leak.
  95.  
  96.