home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Datafile PD-CD 4
/
DATAFILE_PDCD4.iso
/
utilities
/
utilst
/
thheap
/
!Help
next >
Wrap
Text File
|
1996-02-05
|
3KB
|
111 lines
THHeap
======
by:
Tony Houghton
271 Upper Weston Lane
Southampton
SO19 9HY
Email: tonyh@tcp.co.uk
WWW: http://www.tcp.co.uk/~tonyh/
Description
-----------
THHeap is a pair of modules to provide memory management with a programmers'
interface consistent across RISC OS 3.1 and later versions. THHeapA will
work on all versions of RISC OS ¹ and THHeapR is only for use with RISC OS
3.5 or later.
Memory management is implemented by OS_Heap with the THHeap module handling
placement and overall size of the heap. THHeapA achieves this by passing
calls on to OS_Module while THHeapR uses dynamic areas. Each SWI has a
parameter for use by the dynamic area system; THHeapA ignores these, so if
you are unable to test your programs with THHeapR take care that you are
using these parameters correctly.
THHeapA does not distinguish between different heaps you tell it about, all
blocks are placed in the RMA, mixed with blocks used by other programs.
Therefore always free each block you use individually unless your program is
guaranteed only to use THHeapR. THHeapR can create as many different heaps
as you like, within any limits imposed by free memory and number of areas
the OS will permit. Removing a heap will implicitly free all the blocks in
it, but do not rely on this in case you are using THHeapA.
Conditions of use
-----------------
THHeap may be freely distributed. It may be used in applications provided it
is unaltered and you credit me, the author. If possible, please include this
file with it (I know that won't always be possible), or at least indicate
that it is available with instructions from PD libraries. As a courtesy it
would be very nice if you send me copies of any programs you write which use
it.
¹ The modules have only been tested on RISC OS 3.1 and RISC OS 3.6 but there
is no reason why they should not work on other versions.
Loading the modules
-------------------
It is recommended that the Obey file sequence to load THHeap is based on the
following:
Set AppName$THHeap <App$Dir>.THHeapR
RMEnsure UtilityModule 3.50 Set AppName$THHeap <App$Dir>.THHeapA
RMEnsure THHeap 1.00 RMLoad <Appname$THeap>
Unset AppName$THHeap
Technical details
=================
THHeap's SWI chunk is &4C680 (officially allocated by Pineapple).
SWI's
-----
THHeap_CreateHeap &4c680
Entry: R0 => Name to give dynamic area
Exit: R0 = Heap reference ('handle')
Restrict the dynamic area name to a length suitable for the Task Manager
window. Use the returned handle in all subsequent calls using this heap.
THHeap_RemoveHeap
Entry: R0 = Heap reference
Exit: R0 Preserved
Removes a previously created heap.
THHeap_Claim
Entry: R0 = Heap reference
R1 = Required size
Exit: R0-R1 Corrupted
R2 => New block
Claims a block in a heap.
THHeap_Free
Entry: R0 = Heap reference
R2 => Block
Exit: R0-R2 Corrupted
Frees a previously claimed heap.
THHeap_Size
Entry: R0 = Heap reference
R2 => Block
Exit: R0 = Size
R1-R2 Preserved
Returns the size of a block. This is not guaranteed to work for THHeapA on
future versions of the OS; always use THHeapR if dynamic areas are
supported.
THHeap_Extend
Entry: R0 = Heap reference
R1 = Required change in size
R2 => Block
Exit: R0-R1 Corrupted
R2 => New block
Extends a previusly claimed block. This may cause the block to move, so its
new address is returned. If it moves its data will be copied to the new
address for you by the OS before returning.