Achor Point - A static (fixed) word in memory known to a program where it can find the dynamic (moving) address of a sliding heap block
Memory Pending return - This occurs when memory is released from the heap (and when the heap was initialise to a size that was not a multiple of eight), it is an accumulator stored in the heap until there is enough to return (depends on PageSize (see 'OS_ReadMemMap' - roughly 8k for 1MB, 16k for 2MB, 32K for 4Mb or more) as returning anything less than this is useless (and the results are undefined). When there is enough to be returned it will be returned to the wimp 'free' pool.
Change Slot: This is provided for Wimp tasks that allow for dynamic slot sizes, whenever the message is received, it should be passed straight on to the heap manager for processing.
Read heap info: This provides information about the heap and heap mangager, it is similar to 'Wimp_ReadSysInfo' in the fact that information is requested by a number. Information currently provided is: Task slot Size (sometimes useful if memory management is done by the heap manager), Memory Pending Return, Lock level (sometimes needed if the module is locked but then not unlocked - Perhaps due to bugs).
Variable and Anchor area: An area of memory where Anchors points and your prgrams variables are located. There is no destinction between the two as far as the heap manager is concerned, as the address of the anchor point is stored in the 'claimed block' header (see below). Obviously you should be careful not to overwrite anchors. The heap manager does validate the heap before every operation and if you have corrupted the anchors, it will be picked up before a system exception (address exception etc.) occurs. Saying this, you will have to use an error trap if you are using 'X' form SWIs (good practice in any case) just in case.
My advice about the variable block is that you place the address of it in r12 (or some other register that won't normally be used). r12 is a good register as it is preserved throughout SWI's and is infrequently used in applications. To read the address of a sliding block:
LDR rd,[r12,#offset]
Where 'rd' is the destination register and 'offset' is the number you passed to 'claim' when you claimed the block.
Reading a variable from the block is done in exactly the same way.
Don't exceed the limit of the variable/anchor area, as it might corrupt or be currupted. All anchor offsets are checked in Claim.
Stack block: This is another fixed block suitable for the private stacks that most wimp application software needs (If you are using BASIC there isn't problem). On return from 'Claim', add the stack address onto the stack size and move into r13.
LDR r4,varblocksize \ load size of varblock - see below for why.
LDR r5,stacksize \ could be done with move but stack sizes are almost
\ always bigger that the immediate constant range.
SWI "XWimpSupport_FlexHeap" \ call heap manager
BVS stackclaimerror \ call OS_Exit after displaying error message
\ by calling "XWimp_ReportError"
MOV r12,r4 \ r12 = varblock address
MOV r13,r5 \ r13 = (stack pointer) stack address
STR
.restofyourcode \ your program
............
............
.endofyourcode \ end of your code and fixed variables
.getendofcodeaddress
ADR r2,realendofcode
MOV pc,r14
EQUD 0 \ Safety margin
.realendofcode \ IMPORTANT that this really is the end of the code
\ otherwise program will be corrupted by heap.
Compaction: This moves all of the 'free' blocks together at the end of the heap to acheive the largest possible block (consequently the claimed blocks are positioned consecutively at the beginning of the heap). This happens when:
You request it with reason code 8
When claiming memory, but the blocks are spread out or more memory is claimed from the WIMP.
Resizing the heap with rc.5 (resize heap)
Releasing memory with the return bit (8) set.
Resizing the heap block.
Changing the slot size.
Deciding how much memory you are going to allocate to your application in the run file:
The main purpose of sliding heaps is that they can claim and return memory. My advice is that you should use a 1 Meg. computer and see how low you can really go. It is quite possible for small machine code tasks to use only 8k of memory. If after setting your size to the minimum you are having constant problems getting memory from the Wimp (due to other greedy tasks on the desktop), set the slot 8k bigger. 8k is a lot of memory and it is surprisingly difficult to claim it all.
The Final Word:
If you write your task to use this heap manager, you may well save quite a lot of wimp memory. Using variable slots can only be a good thing, have you noticed how notoriously difficult to get task to take memory put asside to them? Well, then, a variable slot deals with this totally....... Of course you can deallocate memory as well, something packages like Acorn D.T.P and First Word Plus could do with!!
