The Datafile PD-CD 3/PDCD_3.iso/utilities/utilst/tornado/GBPB

Text File | 1995-05-25 | 9KB | 150 lines

A few tips for writing fully multitasking applications (which incidentally is
part of the Tornado application standard, from which this excerpt is taken):

...

Guideline 5b:
   The execution of the application, from the time the user double-clicks on
the filer icon to the time the application calls OS_Exit, must never halt the
Wimp for more than half a second unless so desired by the user, which has to
be indicated through a configuration file stored on a non-volatile media,
which can be altered and reset through the usual methods (editor, preferences
window). As usual, this half-second applies to applications running in Mode
0, RISC-OS 2 and on an Arm2 processor (no FPA).

Elaboration:
   Use SWI Tornado_StartPreemption to preempt areas of code which would
otherwise be difficult to poll continously. Note that this approach to
writing code should be on a 'have-to' basis, as using this method places an
unnecessary burden on the processor, and also deprives the user of the use of
the application, as Wimp_Poll reason codes are not acted upon. It is usually
not only easy, but desirable to work on a system of multithreading the
polling process so that full application usage & functionality may be
retained during processing. Although it is possible & acceptable for the task
to allow multiple internal processes to proceed at once, this is not
necessary and one multithreaded process can be done at once, but returning to
the previous process when the first has finished. If you must have multiple
processes occuring at once (which can be difficult and buggy to code), write
them into seperate hotlinked applications (for the time being, this is up to
you, but support for this may eventually come from the module). The method
used by C of multiple processes occuring within the one task is acknowledged
& appreciated, but it is stressed that our approach of putting these
processes into entirely seperate tasks is both easier, and less hassle to
approach. Also, a very big plus is it allows asyndrochous processing,
something we feel important as it is by no means inevitable multiple
processer microcomputer architectures will not emerge in the near future, and
in the possible future the Tornado master option window may allow subtasks to
be sent to a remote processor and executed there, pending return. If you wish
to adopt this approach, ask the Tornado group for a (currently alpha) copy of
the subtask commuinication protocol.

   For filing system use (loading, saving, searching media based files), we
suggest you use the SWI "Tornado_MultitaskLoad" and SWI
"Tornado_MultitaskSave". These are easy to use, but disable your application
during use, and the hourglass should be shown indicating the application is
now offline. Unfortunately, you can't simply call Tornado_StartPreemption
followed with an OS_File, as OS_File runs in SVC and preemption is disabled
at this time. You must do it another way.
     You can multithread the i/o routine with polling, like this:
  "Tornado_StartLoadN",task handle,ptr to file,address of buffer,blk length
TO R0 (R0=handle, if zero the file couldn't be opened)
  .startloop
  Branch to general purpose polling routine, nothing disabled
  "Tornado_LoadIntN",handle TO handle (if the handle ever becomes zero, an
error has occurred, -1 then the file is loaded)
  Test if handle =-1 or =0, if true remove ptr and exit; if false, update ptr
and branch to .startloop.
    ... or you can use SWI "Tornado_StartLoadI" and SWI "Tornado_StartSaveI",
like this:
<To start:>"Tornado_StartLoadI",task handle,ptr to file,address of
buffer,time interval TO R0 (R0=handle, if zero the file couldn't be opened)
<Regularly after:> "Tornado_LoadIntI",handle TO handle (if the handle ever
becomes zero, an error has occurred, -1 then the file is loaded). Test if
handle =-1 or =0, if true the i/o is finished; if false, update ptr and do
whatever you were doing before
   The difference is that ***I SWI's will keep on working even when the
desktop is halted eg; the user is using a non-desktop program, has hit f12,
etc. etc. The ***N SWI's don't actually multitask, it's the branch to the
polling routine that does that. The SWI "Tornado_LoadIntN" simply loads in a
section of the file at a time, a section small enough not to take more than
half a second. This is the preferred method, and should be used unless you
have a very good reason not to.
   The ***I SWI's, on the otherhand, operate above all USR mode code: on the
same level as the higher-level i/o routines, like the serial port - they will
keep on performing the i/o even when you might be playing a game, on the comm
line etc. etc. They use interrupts to load in the blocks, but while a task is
suspended it will have no control over the i/o. For this reason, it is
recommended that you write a section of module code to perform the i/o
control; note that the module does NOT need to poll the Wimp - these calls do
not even need the Wimp to function. Essentially, if you can write the i/o
routine without needing some module code, write it using ***N. It's better
all round.
   A situation which would need the ***I set would be where an application is
reading in vital data from a device and saving it to disc. Whereas before,
the data would be i/o from a section of memory, now it can be done direct to
disc. If the device absolutely needs a constant flow of data, then this
method is ideal - the module code handles the i/o between the memory buffer
and the device, and the ***I does the media i/o. This way, the device is
never left wanting for data.
  Note that this implies that the buffer space into which the i/o is being
performed must reside in non-multipaged memory, such as that in the RMA &
memory areas under RISC-OS 3.5+. This does NOT include application space, and
pointing the routine into there will almost cause undefined results. Note
also that these calls also add a huge amount of latency to the system, and
can disrupt much of the i/o system also running under standard interrupts
(eg; the serial port) and occasionally lower system functions like the mouse
pointer. However, this only affects standard IRQ code, and shouldn't touch
the lower still FIQ which handles very low system functions. Please also note
that overloading the interrupt system is unwise, and can cause many problems
for tasks in USR mode relying on system responsiveness, which is why the ***I
calls will only allow two threads running simultanously. Do not expect your
request to be guaranteed serviced.

   In !Run files, modules should be loaded using *MultitaskRMLoad which loads
in modules without halting the Wimp, which is done by starting up a module
Wimp task which performs the loading of blocks into memory in between polls.
!RunImage should be run using *MultitaskRun, also doing the i/o by the
aforementioned method. Also, during the main part of the !Run file, the
hourglass should be used, and setting the LED's appropriate to what task is
in progress. The top LED should be on during input i/o (loading, reading in),
bottom on during output i/o (saving, writing out), both on during
non-multitasking processing, and both off during multitasking processing. A
percentage should also be displayed if possible/appropriate.
   However, better still if it can utilise the Tornado timeto feature which
shows the estimated time to completion under the mouse pointer. This is
done using the *Hourglass command, and by right you should also set the
pointer to whether you are multitasking or not. See the call definition for
further details. This is also available via SWI "Tornado_Hourglass".
   Also, if your !Run file is so long as to breach the half second limit,
move bits around ie; a *MultitaskRMLoad can be placed into the middle of a
section of (say) *Set's which is too long - this allows the Wimp to be
polled, and polling continued.

   Finally, remember that you must implement the Tornado per-application
standard, allowing the Tornado module to display local application options
within the application's option window. This will allow the user to set
options, applicable to every Tornado task, which relate to this specific area
of constant multi-tasking (ie; fo