Memory management
-=-=-=-=-=-=-=-=-

Tornado manages its memory, and the memory of the apps under its control much
differently from convention. The application image is stored in its task
slot, allocated from the tornado memory pool, along with any internal data.
Thankfully, unlike RISC-OS's 16Mb wimpslot limit, tornado applications enjoy
a 4Gb maximum slot size. This part of the memory management is handled by the
tornado shell.
   All files loaded into tornado apps are stored in a heap located in the
tornado multitasker's memory space (on MEMC1-1a machines the memory space is
a standard wimpslot [1]; on later hardware it moves into a dynamic area).
This heap's blocks are relocatable, and the heap is garbaged regularly. Any
free space is returned immediately to the wimp's free pool. This part is
handled by the tornado kernel.

[1] Note that on current implementations of tornado, the public area space
(tornado system heap) resides in RMA, due to it being a lot easier to debug
things when your heap doesn't keep getting corrupted. It is envisaged that in
the future, files loaded into tornado will be kept in the main memory pool,
and virtual memory applied there. However, as far as the application will be
concerned the files will still be stored in the tornado system heap.


The reason why files are kept in tornado's memory space is because:
 (a): On every architecture, this method allows a slot up to machine RAM
size. Obviously, this allows files of almost infinite length to be loaded
when possible.
 (b): Virtual memory techniques can be applied to data, whereby blocks (being
relocatable) can be dumped to disc and copied back in when needed (i)
 (c): The files are at the full reach of Tornado (it owning the memory), and
so can be accessed without the owning task's permission. Obviously tornado
apps must keep a copy of the file in a saveable format at all times - if this
is not possible, the task must provide a routine to generate a saveable file
[1]. Of course, _no_ task actually owns any files loaded into torando apps -
except Tornado itself.
   Advantages of this system of centralising files:
        - Saves and insertion are/can be automated
        - OLE and hotlinking can also be automated
        - Convertors can be used to translate between formats. For example,
if the user drags a GIF file to a Tornado app that can only accept Sprites,
it gets converted first and dumped into tfs: to be loaded in. Being saved
back, it get converted back. This is done by a specialised range of subtasks
(see the appropriate docs)
        - Upon your app crashing, files currently being edited can
automatically be saved out. This of course can only be done if your app
maintains a ready-to-save copy of the file at all times (which is
recommended). (See appropriate docs)
        - You can use the Tornado renderers. These centralised renderers take
a file, in its saved format, and render it. They can render 2d vectors, text,
DTP pages, sound, 3d vectors, bitmaps, soundtrackers, movies - whatever. Once
a renderer is written and installed, it's available for all apps that can
take it (see appropriate docs)
        - You can use the Tornado multiprocessors. Although these are far
more generalised than just for this one, these can convert between file
formats (as mentioned above), but can also do complex tasks eg; rotate a
JPEG. This may be done not only on a local processor, but perhaps on a second
processor or a processor on a machine on the other end of a network see
appropriate docs)

(i): Virtual memory works by breaking up very long block into much smaller
ones (usually a multiple of the track size of the disc media upon which the
cache is being kept for speed). Each of these blocks has a time associated
with it (OS_Monotonic) ie; when it was last accessed using Tornado_Getaddr.
When necessary, blocks past a certain age (or type - for example, blocks all
belonging to a 25Mb block will be swapped in and out depending on which part
of the total block is being accessed - thus not flushing all data onto disc)
get dumped to disc and it is stored where they are (disc pathname). This
allows a 2560x2048 32 bit sprite (taking normally 20Mb) to be edited on a 1Mb
machine, as given that there would be an average 75 byte header, and with
2048 blocks of 10240 bytes each (=2 tracks on floppy E format) = about 170k
of memory + 10240 to store each block.

The common tornado heap help in RMA is a special tornado heap, and is
referenced by passing 0 as the heap start to the Tornado heap SWIs. It
features relocatable blocks with auto-garbaging, and fixed blocks are
supported too. Heaps are also relocatable, so you can have a heap in a heap.
Also, heaps can be auto-extending, ie; they will increase/decrease the
allocation of whatever they are stored in. In the case of postslot heaps,
they will automatically call Tornado_ExtendSlot to alter the size of the
heap. This makes setting up postslot heaps extremely easy.
   Blocks in these special heaps are referenced to by their handle, a
negative number. This handle is passed to all heap operations, and the
program need not worry where the data is really stored. When it needs to
access the data, it calls Tornado_Getaddr, which returns the current address
of that block. Fixed blocks are referenced a la OS_Heap style, with the
handle being a fixed address in memory.
   Another heap used by Tornado is the subtask heap, referenced by 1 - but
this is for the exclusive use of subtasks - see the appropriate
documentation.
