home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / t / tornado / TNdemo / APIs next >
Encoding:
Text File  |  1996-12-30  |  9.0 KB  |  233 lines
  1. Tornado II support module API details:
  2. -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  3.  
  4. Note that these SWIs implement a Win32 API interface but do not provide all
  5. the facilities Win32 does (mainly in the security area). This is not apparent
  6. when using the module through the C veneers though.
  7.  
  8.  Tornado_Initialise                        (&C0000)
  9.  On entry:
  10.   R0=version of support module expected * 100
  11.   R1=ptr to name of this program instance
  12.   R2=ptr to routine to handle poll codes 17, 18 & 19
  13.   R3=RO Wimp task handle of this app
  14.  On exit:
  15.   R0=version of this support module * 100
  16.   R1=version of RISC-OS we're running on here * 100
  17.  Use:
  18.    This call initialises the program instance calling it as a preemptable
  19. multithreading multitaskable client. From this call hence the program code
  20. will be preempted. You must already have set yourself up as a Wimp task with
  21. Wimp_Initialise.
  22.    NOTE: the routine for handling 17, 18 & 19 return codes is *immediately*
  23. valid and may be started at any time - so make sure it's valid.
  24.    Note also that on return of this call the current code becomes a thread
  25. and other threads may be created that run alongside it. You must take account
  26. of this before calling this call ie; be absolutely sure you're ready for it.
  27.  
  28.  
  29.  Tornado_Closedown                        (&C0001)
  30.  On entry:
  31.   R0=wimp task handle (0 for current task)
  32.  On exit: Nothing
  33.  Use:
  34.    This call shuts down the program instance calling it as a preemptable
  35. multithreading multitaskable client. Henceforth your code will NOT be
  36. preempted. You should now exit using Wimp_CloseDown and OS_Exit and per
  37. normal - or if you wish you can continue execution. Note that you should NOT
  38. use Tornado_CloseDown and then Tornado_Initialise again to suspend preemption
  39. for a while - either make your code fully preemptable or don't use this
  40. module at all.
  41.    All threads other than the one calling this also get terminated
  42. *immediately*, so if they have any open file handles or memory they simply
  43. get lost. It might be an idea to terminate all threads through (i) waiting
  44. for them to finish using Tornado_WaitForMultipleObjects or (ii) calling
  45. Tornado_TerminateThread which will cause an exception within the thread and
  46. cause its error handler to be called.
  47.  
  48.  Tornado_Poll                            (&C0002)
  49.  On entry:
  50.   R1=ptr to 256 bytes to have poll data returned into
  51.  On exit:
  52.   R0=wimp poll reason code
  53.  Use:
  54.    Use this call to fetch wimp messages sent to you by other wimp tasks,
  55. preferably in your main thread (ie; your process thread).
  56.    Note however that if you have not called Tornado_Poll recently that the
  57. messages returned may be significantly out of date. Therefore you should
  58. follow the recommendations for writing multithreading applications as
  59. outlined in 'Guidelines'.
  60.    Messages returned are identical in format to Wimp_Poll: except that of
  61. the redraw window request message (1) which is returned as the following
  62. format instead:
  63.      +00: window handle
  64.      +04: work area min x
  65.      +08: work area min y
  66.      +12: work area max x
  67.      +16: work area max y
  68.      +20: base x of window work area
  69.      +24: base y of window work area
  70.    This message upon being received should be passed to Tornado_RedrawWindow
  71. - see its entry for details.
  72.  
  73.  Tornado_RedrawWindow                        (&C0003)
  74.  On entry:
  75.   R1=ptr to redraw block
  76.  On exit:
  77.   R0=flag on whether to continue
  78.  Use:
  79.    This call is very similar to Wimp_UpdateWindow except that when called
  80. preemption is halted. Tornado_GetRectangle should then be called as
  81. necessary in the same fashion as Wimp_GetRectangle.
  82.    As said above, preemption is halted during the redraw cycle. Therefore
  83. you should try to make the redraw as quick as possible.
  84.    Unlike Wimp_RedrawWindow, this call may also be called at any time to
  85. update a window.
  86.  
  87.  Tornado_GetRectangle                        (&C0004)
  88.  On entry:
  89.   R1=as for Wimp_GetRectangle
  90.  On exit:
  91.   R0 & R1 as for Wimp_GetRectangle
  92.  Use:
  93.    Use this call like Wimp_GetRectangle.
  94.    
  95.  Tornado_NeedReset                        (&C0005)
  96.  On entry: Nothing
  97.  On exit:
  98.   R0=zero if everything alright,
  99.        ptr to error blk of error if reset required
  100.  Use:
  101.    Use this call to check if your error handler was called through an error
  102. occuring during the execution of the tornado support module's preemption
  103. handlers.
  104.    If R0 returns a non zero result, you can check the error code to see what
  105. you should do. For example, if it is a fairly transient error (eg; Not a
  106. block) which indicates data corruption of the support module's lists then a
  107. restart will more than likely work so you should shut yourself down using
  108. Tornado_Closedown and restart with Tornado_Initialise. Remember to clean up
  109. any resources left open by the forced termination of your threads (if you
  110. can).
  111.    A nice and very tornadoey addition to this is to ASK the user what to do -
  112. quit or not quit (of course both save the files out where necessary).
  113.    Finally, note that memory full errors get dealt with internally by the
  114. preemptor routine and you should not receive these. If you do, something is
  115. seriously wrong and you should quit rather than restart.
  116.  
  117.  Tornado_SetPollMask                        (&C0006)
  118.  On entry:
  119.   R0=mask to be passed from hence to wimp poll
  120.  On exit:
  121.   R0=previous mask
  122.  Use:
  123.    Use this call to set what mask should be passed to Wimp_Poll when
  124. tornado calls it for you - this obviously affects what codes then will be
  125. returned to you via Tornado_Poll but do remember there may be a "stack" of
  126. codes still waiting to be processed that will be unaffected by the mask
  127. change.
  128.  
  129.  ************ THE FOLLOWING SWI'S ARE NOT CURRENTLY IMPLEMENTED ************
  130.  
  131.  Tornado_CreateThread                        (&Cxxxx)
  132.  On entry:
  133.   R0=ptr to security attributes (N/I)
  134.   R1=initial thread stack size in bytes or zero for default
  135.   R2=address of thread function
  136.   R3=argument for new thread
  137.   R4=creation flags (N/I - leave as zero)
  138.  On exit:
  139.   R0 corrupted if R1=0
  140.   R1=thread id
  141.  Use:
  142.    Use this call to create a thread in your code. The security attributes
  143. and the creation flags are currently N/I and should be left as zero.
  144.    If the thread id returned is zero then the thread create has failed.
  145. Examine R0 which will contain the standard error block to see why.
  146.    The thread is entered with a1 (R0) equal to R3 on entry to this
  147. call. The thread code must return an integer which then can be retreived
  148. using Tornado_GetExitCodeThread.
  149.  
  150.  Tornado_ExitThread                        (&Cxxxx)
  151.  On entry:
  152.   R0=exit code
  153.  On exit: Never returns
  154.  Use:
  155.    This call terminates the current thread and attachs the exit code to the
  156. threads handle, and then marks that handle as signaled.
  157.    This is the preferred method of ending a thread. However, the main thread
  158. (as in the one that called Tornado_Initialise) should NOT end by this method
  159. - instead it should call Tornado_Closedown.
  160.  
  161.  Tornado_TerminateThread                    (&Cxxxx)
  162.  On entry:
  163.   R0=thread id
  164.   R1=exit code to be returned by the thread
  165.  On exit: Nothing
  166.  Use:
  167.    This call forcibly terminates a thread. While the thread's stack is
  168. removed and the thread killed off, anything that the thread was doing (eg;
  169. file work etc) will NOT be killed off and thus keep using system resources.
  170. Therefore you should use this call with a great deal of care.
  171.  
  172.  Tornado_ReadMonotonicTime                    (&Cxxxx)
  173.  On entry: Nothing
  174.  On exit:
  175.   R0=low word of timer
  176.   R1=high word of timer
  177.  Use:
  178.    This call returns the value of a timer incremented 1000 times a second.
  179.  
  180.  Tornado_CallAfter                        (&Cxxxx)
  181.  On entry:
  182.   R0=time from now to call routine in ms
  183.   R1=addr of routine
  184.   R2=R12 on entry
  185.  On exit: All preserved
  186.  Use:
  187.    This call calls the specified code in R1 after R0 milliseconds have
  188. elapsed with R12 set to R2 on entry.
  189.    Your code is called in supervisor mode with interrupts enabled and so you
  190. should take the usual precautions for calling SWIs and such. Note that you
  191. should not take time when called by this method as the system is
  192. effectively hung while you are in this call. You may corrupt R0, R1 and R12
  193. if you wish.
  194.  
  195.  Tornado_StopCallAfter                        (&Cxxxx)
  196.  On entry:
  197.   R0=addr of routine
  198.   R1=R12 on entry
  199.  On exit: All preserved
  200.  Used:
  201.    This call stops the scheduled call set up by Tornado_CallAfter.
  202.  
  203.  
  204.  
  205. 17, 18 & 19 poll code API
  206. -=-=-=-=-=-=-=-=-=-=-=-=-
  207.  
  208. In C, your routine will be called as follows:
  209.  
  210. int routine(int msgno, int msgblk)
  211.  
  212. In assembler, this goes to:
  213.  
  214. R0=poll code number
  215. R1=message block attached to poll code number
  216.  
  217. You should return in R0 a value to indicate what should be done with this
  218. message - 0 causes the message to be placed in the normal message queue to be
  219. handled by Tornado_Poll called by the main process. 1 tells tornado that the
  220. message has been dealt with and to take no further action.
  221.  
  222. Note that any changes you make to the message block pointed to by R1 are
  223. permanent ie; it is directly the message block that will be put in the
  224. message queue if R0=0 on exit. This can be advantageous or not.
  225.  
  226. Note also that this routine is NOT preempted. Therefore you should be fast to
  227. finish your business. Also be aware that your have 256 bytes of stack
  228. available and currently no more - if you extend over that you will invoke the
  229. C stack extender and then things will become very nasty indeed as in fact the
  230. stack resides in 'limbo' in RMA. So *ensure* this doesn't happen.
  231.  
  232. Please see the enclosed C example for how to implement this.
  233.