home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilss / slflex / ReadMe
Text File  |  1995-03-25  |  4KB  |  89 lines
  1. Straylight shifting heap manager
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. Some important notes:
  5.  
  6. 1. This is supplied `as is'.  There's no warranty or anything like that.
  7.    It seems to work for me, though.
  8.  
  9. 2. Nothing stated anywhere should be taken to mean that there will be another
  10.    release of this software, because there probably won't.  This version of
  11.    flex is a part of an obsolete library, and we have better things to be
  12.    getting on with.
  13.  
  14. 3. Source code to this software won't be given out, no matter how nicely you
  15.    ask.
  16.  
  17. On with the story:
  18.  
  19. The flex shifting heap manager was one of the more useful parts of
  20. RISC_OSLib, since it allows large blocks of memory to be manipulated without
  21. causing fragmentation.  Now that RISC_OSLib has been replaced by the
  22. Toolbox, Acorn are advocating the use of malloc instead.  Unfortunately,
  23. malloc has some problems which flex solves quite nicely.
  24.  
  25. The RISC_OSLib version of flex unfortunately has a load of dependencies on
  26. other parts of RISC_OSLib, which means that it can't be used on its own
  27. without a load of hacking (and the source code).
  28.  
  29. This is a rewritten version of flex, with some big bonuses (and a slight
  30. disadvantage -- I'll come on to that later).
  31.  
  32. The pluses:
  33.  
  34. 1. It's written entirely in assembler.  The only routines it calls are also
  35.    written in assembler.  It's fast.  Faster than the Acorn one, anyway.
  36.    It's also quite a bit smaller.
  37.  
  38. 2. It doesn't have any dependencies on anything outside the standard C
  39.    library kernel.  In fact, the only symbols it needs are:
  40.  
  41.        x$stack_overflow (for stack limit checking)
  42.        _kernel_register_slotextend (to stop malloc heap from growing)
  43.        memmove (for fast memory movement)
  44.  
  45.    I don't know whether this set is small enough to allow flex to be used
  46.    under Unixlib.  It's certainly small enough for use with the
  47.    SharedCLibrary.
  48.  
  49. 3. It compacts in the background.  The Acorn version worked by moving all the
  50.    memory blocks each time you did a flex operation, so that there was no
  51.    free space in the heap.  This version will quite happily leave holes in
  52.    the heap, and will fill them in `later'.  Quite what `later' means is
  53.    something I'll deal with below.  What all this means is that the time
  54.    taken to compact the heap is spread over a long period, so you don't
  55.    notice it.
  56.  
  57. The minus:
  58.  
  59. There's only one of these.  This version of flex does *not* allow the malloc
  60. heap to grow, whereas the Acorn one did.  If you need this feature, don't use
  61. this memory manager.
  62.  
  63. What's different?
  64.  
  65. All the functions offered by Acorn's flex are implemented in this version.
  66. With the exception of flex_budge, all of these work in a compatible way.
  67. It's basically just a drop-in replacement.  Almost.
  68.  
  69. This flex version `compacts' the heap in the background.  It needs to be told
  70. when to do this compaction.  Two extra routines are needed to manage this:
  71.  
  72.   flex_reduce does a `small amount' of compaction.  Lots of calls to
  73.     flex_reduce will result in a compacted heap.
  74.  
  75.   flex_compact will completely compact the heap.
  76.  
  77. Memory will only be given back to the operating system during compaction.  If
  78. there isn't enough memory to do something, flex will compact the heap
  79. completely and try again, so you don't have anything to worry about there;
  80. it's just that your application takes up too much memory is the heap isn't
  81. compacted.
  82.  
  83. My recommendation is that you call flex_reduce every null event; this results
  84. in fairly rapid compaction, but it still happens more-or-less `in the
  85. background' and no-one notices the performance drop while this is happening.
  86. I also recommend that you compact the heap completely after doing something
  87. which has left a lot of holes in it, such as freeing lots of blocks.
  88.  
  89.