home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilst / thheap / !Help next >
Encoding:
Text File  |  1996-02-05  |  3.4 KB  |  111 lines
  1. THHeap
  2. ======
  3. by:
  4.  
  5. Tony Houghton
  6. 271 Upper Weston Lane
  7. Southampton
  8. SO19 9HY
  9.  
  10. Email: tonyh@tcp.co.uk
  11. WWW:   http://www.tcp.co.uk/~tonyh/
  12.  
  13. Description
  14. -----------
  15. THHeap is a pair of modules to provide memory management with a programmers'
  16. interface consistent across RISC OS 3.1 and later versions. THHeapA will
  17. work on all versions of RISC OS ¹ and THHeapR is only for use with RISC OS
  18. 3.5 or later.
  19.  
  20. Memory management is implemented by OS_Heap with the THHeap module handling
  21. placement and overall size of the heap. THHeapA achieves this by passing
  22. calls on to OS_Module while THHeapR uses dynamic areas. Each SWI has a
  23. parameter for use by the dynamic area system; THHeapA ignores these, so if
  24. you are unable to test your programs with THHeapR take care that you are
  25. using these parameters correctly.
  26.  
  27. THHeapA does not distinguish between different heaps you tell it about, all
  28. blocks are placed in the RMA, mixed with blocks used by other programs.
  29. Therefore always free each block you use individually unless your program is
  30. guaranteed only to use THHeapR. THHeapR can create as many different heaps
  31. as you like, within any limits imposed by free memory and number of areas
  32. the OS will permit. Removing a heap will implicitly free all the blocks in
  33. it, but do not rely on this in case you are using THHeapA.
  34.  
  35. Conditions of use
  36. -----------------
  37. THHeap may be freely distributed. It may be used in applications provided it
  38. is unaltered and you credit me, the author. If possible, please include this
  39. file with it (I know that won't always be possible), or at least indicate
  40. that it is available with instructions from PD libraries. As a courtesy it
  41. would be very nice if you send me copies of any programs you write which use
  42. it.
  43.  
  44. ¹ The modules have only been tested on RISC OS 3.1 and RISC OS 3.6 but there
  45.   is no reason why they should not work on other versions.
  46.   
  47. Loading the modules
  48. -------------------
  49. It is recommended that the Obey file sequence to load THHeap is based on the
  50. following:
  51.  
  52. Set AppName$THHeap <App$Dir>.THHeapR
  53. RMEnsure UtilityModule 3.50 Set AppName$THHeap <App$Dir>.THHeapA
  54. RMEnsure THHeap 1.00 RMLoad <Appname$THeap>
  55. Unset AppName$THHeap
  56.  
  57. Technical details
  58. =================
  59. THHeap's SWI chunk is &4C680 (officially allocated by Pineapple).
  60.  
  61. SWI's
  62. -----
  63. THHeap_CreateHeap        &4c680
  64.     Entry:    R0 =>    Name to give dynamic area
  65.     Exit:    R0 =     Heap reference ('handle')
  66.  
  67. Restrict the dynamic area name to a length suitable for the Task Manager
  68. window. Use the returned handle in all subsequent calls using this heap.
  69.  
  70. THHeap_RemoveHeap
  71.     Entry:  R0 =    Heap reference
  72.     Exit:   R0    Preserved
  73.  
  74. Removes a previously created heap.
  75.  
  76. THHeap_Claim
  77.     Entry:  R0 =    Heap reference
  78.         R1 =    Required size
  79.     Exit:    R0-R1    Corrupted
  80.         R2 =>    New block
  81.  
  82. Claims a block in a heap.
  83.  
  84. THHeap_Free
  85.     Entry:    R0 =    Heap reference
  86.         R2 =>    Block
  87.     Exit:    R0-R2    Corrupted
  88.  
  89. Frees a previously claimed heap.
  90.  
  91. THHeap_Size
  92.     Entry:    R0 =    Heap reference
  93.         R2 =>    Block
  94.     Exit:    R0 =    Size
  95.         R1-R2 Preserved
  96.  
  97. Returns the size of a block. This is not guaranteed to work for THHeapA on
  98. future versions of the OS; always use THHeapR if dynamic areas are
  99. supported.
  100.  
  101. THHeap_Extend
  102.     Entry:    R0 =    Heap reference
  103.         R1 =    Required change in size
  104.         R2 =>    Block
  105.     Exit:    R0-R1    Corrupted
  106.         R2 =>    New block
  107.  
  108. Extends a previusly claimed block. This may cause the block to move, so its
  109. new address is returned. If it moves its data will be copied to the new
  110. address for you by the OS before returning.
  111.