Dynamic Areas

Shrinkable dynamic areas

Shrinkable dynamic areas are dynamic areas which may be resized at the request of the Kernel in order to free memory for other uses. This allows cache and buffer information to be retained as long as there is not pressure for memory in other areas. This can allow more of the system's memory to be utilised without unduly restricting the functionality of the system by fixed allocations. In order to create a shrinkable dynamic area bit 9 should be set on creation with OS_DynamicArea 0.

When the Kernel needs to increase the size of a dynamic area beyond the size available in the Free Pool or Application space it will make a call to the dynamic area handler 'test shrink' reason code. This entry point has the following interfaces :

On entry

   R0 = 4
   R4 = current size of area in bytes
   R5 = page size in bytes
   R12 = workspace for dynamic area handler

On exit

   R3 = maximum amount the area could shrink by

This entry point is called by the Kernel to determine the amount of space which is available within the dynamic area if requested. The handler should try to return the size as quickly as it can as this call may be made when the current system free space is requested. It is not used when the Kernel reclaims space, only when the space available is requested with OS_DynamicArea 5.

In order to determine the total free space available to the system, a new OS_DynamicArea reason code has been introduced.

OS_DynamicArea 5 (Return available space)

On entry

   R0 = 5
   R1 = area number to exclude from total, or -1 to include all areas

On exit

   R2 = total amount of free space (bytes)

This SWI calculates the amount of available space on the system, allowing for the shrinkable dynamic areas. The total is the sum of the free pool size and the size available from all the shrinkable dynamic areas.

Caveats

Using shrinkable dynamic areas should only be done with care. It is usually necessary to track the area size using the area handler. The PreShrink and PreGrow handlers must enforce limitations on the size changes if the area is currently being used. Any external system call may cause a memory allocation and thus the areas may need to be protected in order that, on return from the call, the memory which was allocated has been removed by the Kernel.

If multiple areas are used by a single client they should be aware of the obvious consequence of increasing the size of one causing a request to decrease the size of another. Where the areas are co-dependant it may be necessary to include special semaphores to protect against the regions being reduced due to this internal contention for memory.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015