(Note that some of this refers to features not implemented as yet in the
support module)


Guidelines for writing multithreading applications:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 * Do NOT share handle-based resources between threads eg; one thread opens a
handle and then passes that handle to another thread and then terminates. If
you MUST do this, pass the handle to the other thread, and *enter* a wait
cycle on that thread after tidying up. Should that thread ever terminate
unnaturally, the thread that opened the handle will be exit that loop and
then should close the handle if it's still open. Conversely, should the other
thread successfully finish its work and no longer need the handle, it then
should terminate and let the thread that created it close it.
   In other words, ALWAYS open and close a handle with the same instance of
thread. This is future-proofing as a future version of this support module
may shut handles for a thread if it is ever forcibly terminated.

 * Do NOT linearly program. Mutexs and semaphores are there to be used - make
the main message handler *dispatch* the message by starting up a thread -
don't have the message handler handle the message itself where possible. This
allows maximum responsiveness to be retained.

 * Make sure you 17, 18 & 19 poll code handler executes quickly as it is not
preempted and thus both your code and the entire RISC-OS Wimp is held up
until it finishes. Similarly to the point above, *dispatch* tasks into
threads whenever possible and signal your handler. You should NOT attempt to
call Wimp_Poll yourself during the handler.

 * Do NOT call Wimp_Poll yourself. Also make sure anything you do won't end
up floating ie; if you send a wimp message, make sure your 17, 18 & 19
handler can handle it correctly (eg; notify you).
   An example of this is:
<thread sends wimp message>
<thread now suspends itself *with* timeout>
<when wimp message returns into 17, 18 & 19 handler, handler resumes the
thread>
<all okay - unless wimp message is never replied to - in which case timeout
occurs and then thread should take whatever action required>

This is how you should handle wimp messages that require replies. However,
should the message exchange require no Wimp_Poll in between (eg; RAM
transfers), then you should have your 17, 18 & 19 handler do the arbitration
as it is the only part of your code that won't get preempted.
   A nice effect of doing this is that suspending a thread leaves more time
for other threads too so it's best all ways you look at it.
