THHeap
======
by:

Tony Houghton
271 Upper Weston Lane
Southampton
SO19 9HY

Email: tonyh@tcp.co.uk
WWW:   http://www.tcp.co.uk/~tonyh/

Version: 1.20

Note: The file called "THHeap" is a StrongHelp file.

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 is for
use with RISC OS 3.1 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 used to ignore the
handles, but now uses them to store granularity factors.

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.

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 0.00 RMLoad <Appname$THeap>
Unset AppName$THHeap
RMEnsure THHeap 1.20 Error 0 You need THHeap 1.20 or later

Note this is slightly different to before, because a change in implementation
means that loading a new version of THHeap while some applications are using
an older one is likely to cause a crash.

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')

[Deprecated in favour of THHeap_CreateLimited]

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		&4c681
	Entry:  R0 =	Heap reference
	Exit:   R0	Preserved

Removes a previously created heap.


THHeap_Claim			&4c682
	Entry:  R0 =	Heap reference
		R1 =	Required size
	Exit:	R0-R1	Corrupted
		R2 =>	New block

Claims a block in a heap.


THHeap_Free			&4c683
	Entry:	R0 =	Heap reference
		R2 =>	Block
	Exit:	R0-R2	Corrupted

Frees a previously claimed block.


THHeap_Size			&4c684
	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			&4c685
	Entry:	R0 =	Heap reference
		R1 =	Required change in size
		R2 =>	Block
	Exit:	R0-R1	Corrupted
		R2 =>	New block

Extends a previously 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.


THHeap_CreateLimited		&4c686
	Entry:	R0 =>	Name to give dynamic area
		R1 =	Maximum size of area
	Exit:	R0 = 	Heap reference ('handle')

As THHeap_CreateHeap, but allows a maximum size to be set for the
dynamic area to grow to, to avoid hogging address space. This now simply
calls THHeap_CreateGranular (below) with a granularity value of 3.


THHeap_CreateGranular		&4c687
	Entry:	R0 =>	Name to give dynamic area
		R1 =	Maximum size of area
		R2 =	Granularity factor
	Exit:	R0 = 	Heap reference ('handle')

As THHeap_CreateLimited, but allows a granularity factor to be set. If you
pass a factor of n, all block allocations and extensions will be rounded to
a size of 2^n. This is useful to reduce fragmentation and the overhead of
calling OS_Heap for every trivial extension. Any granularity value of less
than 3 is increased to 3.
