THHeap
======
by:

Tony Houghton
271 Upper Weston Lane
Southampton
SO19 9HY

Email: riscos@realh.co.uk
WWW:   http://www.realh.co.uk/riscos/

Version: 1.23

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

THIS COPY OF !System IS NOT A COMPLETE STANDALONE VERSION. IT MUST BE
INSTALLED OVER THE TOP OF A WORKING !System. DOWNLOADING THE !System FROM MY
WEBSITE IS RECOMMENDED.

Description
-----------
THHeap is a pair of modules to provide memory management with a programmers'
interface consistent across RISC OS 3.1 and later versions. The RISC OS 3.1
version (formerly known as THHeapA) uses the RMA, and the RISC OS 3.5 and
later version (formerly known as THHeapR) uses a dynamic area.
Both versions should now hopefully be 32-bit clean, but I can't check that
for sure.

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 is now released under the LGPL, but contacting me before distributing it would be appreciated.

Loading the modules
-------------------
Both versions are stored in the appropriate directory within !System and can be loaded like this:

RMEnsure THHeap 0.00 RMLoad System:Modules.THHeap
RMEnsure THHeap 1.23 Error You need THHeap 1.23 or later

Two lines are needed, because replacing an already loaded copy could cause
applications relying on it to crash. Unfortunately, older versions did not
use !System, so applications will not automatically be able to use the new
version. If you identify applications loading an older version you should
update their !Run files to use the above sequence.

Note that 3rd parties using !System is officially frowned upon, but becoming
quite common, because it makes things much simpler when different versions of
the OS require different versions of a module.

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.
