home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / gcc / !GCC / patches / DeskLib / h / Mem < prev    next >
Encoding:
Text File  |  1994-10-03  |  8.1 KB  |  219 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Mem.h
  12.     Author:  Copyright © 1993, 1994 Jason Williams
  13.     Version: 1.01 (22 May 1994)
  14.     Purpose: Dynamic memory manager
  15. */
  16.  
  17. #ifndef __dl_mem_h
  18. #define __dl_mem_h
  19.  
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23.  
  24. /* "Flex" is the RISC OS Lib 'flexible' malloc for desktop tasks
  25.  * "Mem" is DeskLib's equivalent thereof.
  26.  *
  27.  *  Mem memory chunks are held in a 'heap' of memory above the area grabbed
  28.  *  by the SharedCLibrary for mallocs and stackspace, extending up to the
  29.  *  end of the WimpSlot, which is adjusted up & down as necessary.
  30.  *
  31.  *  The major feature that externally distinguishes Mem from flex() is that
  32.  *  the heap is NOT compacted automatically (flex keeps the entire heap
  33.  *  compacted at all times). This has several advantages:
  34.  *    - You can rely on pointers remaining constant at all times between
  35.  *      calls to Mem_Compact() (and other Mem_ calls if you allow it)
  36.  *    - everything is a lot faster if you are allocating and/or
  37.  *      deallocating many chunks in one go.
  38.  *
  39.  *  The idea behind this is that you simply call Mem_Compact before
  40.  *  calling Wimp_Poll - this returns free memory to the Wimp as effectively
  41.  *  as the flex system did, but saves us from having to waste time on
  42.  *  multiple compactions between Wimp_Polls.
  43.  *
  44.  *  Automatic compaction (a la flex) can be turned on (or off) at any time
  45.  *  so the Mem system can be made to emulate flex_ if you really want it.
  46.  *  To do this, set mem_autocompact to the values described below.
  47.  *  NOTE that by default, mem will only autocompact if it has no choice,
  48.  *  but *may* autocompact during any Mem_ call.
  49.  */
  50.  
  51.  
  52. #ifndef __dl_core_h
  53. #include "Core.h"
  54. #endif
  55.  
  56.  
  57. typedef void *mem_anchor;
  58.  
  59.  
  60. /*  Compaction control
  61.  *  Apart from compacting when you call Mem_Compact(), Mem will also
  62.  *  compact at the following times, depending on the value of mem_autocompact
  63.  *
  64.  *    mem_NOCOMPACT:    Auto compaction never occurs. This may be useful if
  65.  *                      you wish to guarantee that chunks ONLY move when you
  66.  *                      call Mem_Compact().
  67.  *
  68.  *    mem_PARTCOMPACT:  Auto compaction occurs whenever compaction might make
  69.  *                      an otherwise impossible memory claim possible. This is
  70.  *                      the recommended (and default) setting.
  71.  *
  72.  *    mem_FULLCOMPACT:  Auto compaction occurs every time a chunk is freed
  73.  *                      (the way that RISC OS Lib flex() operates)
  74.  *                      This is not reccommended, as it can be very inefficient
  75.  *
  76.  *  NOTE that the value of flex_autocompact may be changed at any time
  77.  *  and will take immediate effect. Therefore, if you wish to ensure that
  78.  *  pointers into mem chunks remain 'safe' for a short period of time, you
  79.  *  can set mem_autocompact = mem_NOCOMPACT while procssing, and return
  80.  *  it to its former value when finished.
  81.  */
  82.  
  83. #ifndef __dl_mem_c
  84.   extern int mem_autocompact;
  85. #endif
  86.  
  87. typedef enum
  88. {
  89.   mem_NOCOMPACT   = 0,               /* ONLY compacts if Mem_Compact called  */
  90.   mem_FASTCOMPACT = 1,               /* Compacts only if necessary           */
  91.   mem_PARTCOMPACT = 1,
  92.   mem_FULLCOMPACT = 2                /* Compacts on every heap change        */
  93. } mem_compaction;
  94.  
  95.  
  96.  
  97.   /*  Mem_Initialise()
  98.    *  Initialises the Mem system ready for use.
  99.    *  Note that this locks down the malloc and stack memory area to the
  100.    *  current WimpSlot size at the point of calling, and builds a mem
  101.    *  heap above this. Malloc and stack allocation will not be able to get
  102.    *  more memory than is originally available in your WimpSlot, so get it
  103.    *  right!
  104.    *  Note that Mem_Initialise() provides a function to
  105.    *  _kernel_register-slotextend() to stop the SharedCLib being able to
  106.    *  overwrite the Mem heap with the stack/malloc chunks.
  107.    */
  108. extern BOOL Mem_Initialise(void);
  109.  
  110.  
  111.   /*  Mem_Alloc()
  112.    *  Attempts to allocate the given amount of memory (in bytes) in the mem
  113.    *  heap. Updates the anchor you pass in to point to this block, or
  114.    *  to contain NULL if it is unable to allocate the requested memory.
  115.    *  The returned block of memory starts at a word-aligned address
  116.    *  Returns TRUE if it succeeded
  117.    *
  118.    *  If permitted to by the setting of mem_autocompact, this call MAY
  119.    *  relocate other mem chunks.
  120.    */
  121. extern BOOL Mem_Alloc(mem_anchor *anchor, int numbytes);
  122.  
  123.  
  124.   /*  Mem_MidExtend()
  125.    *  Attempts to alter the size of a mem chunk.
  126.    *  "at" is a byte-offset within the data chunk
  127.    *  "by" is the number of bytes to extend by (negative to reduce the chunk)
  128.    *  If "by" is positive,
  129.    *    'by' bytes of indeterminate value will be inserted at 'at', shifting
  130.    *    the rest of the data up to make room
  131.    *  else
  132.    *    'by' bytes of data BELOW 'at' will be deleted by moving the data
  133.    *    from 'at' onwards down by 'by' bytes.
  134.    *
  135.    *  Returns TRUE if the extension was successful.
  136.    *  The allocated memory starts at a word-aligned address
  137.    *
  138.    *  If permitted to by the setting of mem_autocompact, this call MAY
  139.    *  relocate other mem chunks.
  140.    */
  141. extern BOOL Mem_MidExtend(mem_anchor *anchor, int at, int by);
  142.  
  143.  
  144.   /*  Mem_MoveAnchor
  145.    *  Allows you to move an anchor from one variable to another.
  146.    *  This allows you to allocate a chunk with a temporary anchor and then
  147.    *  move the anchor into permanent storage at a later time (without having
  148.    *  to allocate a new chunk and copy, as is necessary under flex)
  149.    *
  150.    *  Use with care - i.e. remember to check anchors to see if they are NULL
  151.    *  (in which case you're using the wrong anchor!)
  152.    *
  153.    *  If all goes well (i.e. 'from' was a valid chunk), *from will be set
  154.    *  to NULL and *to will now point at the chunk. From this point on,
  155.    *  the anchor 'to' will be adjusted whenever the chunk is moved.
  156.    *
  157.    *  Otherwise, from is left as it was, and to will be set to NULL
  158.    *
  159.    *  example:
  160.    *  {
  161.    *    char *old, *new;
  162.    *    Mem_Alloc((mem_anchor *) &old, 1024);   |* Get some memory *|
  163.    *    if (old != NULL)
  164.    *    {
  165.    *      old[5] = 'a';
  166.    *      Mem_MoveAnchor((mem_anchor *) &old, (mem_anchor *) &new);
  167.    *          |* if 'old' was valid, 'new' now points to where old was, *|
  168.    *          |* and old is now NULL                                    *|
  169.    *
  170.    *      if (new == NULL)    printf("Error - old was invalid! \n");
  171.    *      if (new[5] != 'a')  printf("Error - Jason's code is buggy! \n");
  172.    */
  173. extern void Mem_MoveAnchor(mem_anchor *from, mem_anchor *to);
  174.  
  175.  
  176.   /*  Mem_Free()
  177.    *  Releases a chunk of memory back to the free pool
  178.    *  The contents of the anchor will be set to NULL to indicate it is no
  179.    *  longer a valid pointer.
  180.    *  If permitted to by the contents of mem_autocompact, this call MAY
  181.    *  relocate other mem chunks.
  182.    */
  183. extern void Mem_Free(mem_anchor *anchor);
  184.  
  185.  
  186.   /*  Mem_Compact()
  187.    *  This call compacts the mem heap, moving all free space to the end of
  188.    *  the chunk, and giving back as much memory as possible to the Wimp.
  189.    *  This may result in some mem chunks moving, so you cannot rely on
  190.    *  anchors remaining the same across this call.
  191.    *  Ideally, you should call this just before calling Wimp_Poll, to
  192.    *  ensure the Wimp has all possible available memory (and also keep the
  193.    *  heap tidy)
  194.    *  Note that this may be automatically called by other Mem_ functions
  195.    *  IF mem_autocompact allows it. However, it will NEVER be called if
  196.    *  mem_autocompact == mem_NOCOMPACT
  197.    */
  198. extern void Mem_Compact(void);
  199.  
  200.  
  201.   /*  Mem_Size()
  202.    *  Returns the current size (in bytes) of a mem chunk
  203.    */
  204. extern int  Mem_Size(mem_anchor *anchor);
  205.  
  206.  
  207.   /*  Mem_CheckHeap()
  208.    *  Returns TRUE if the heap data structure is valid (i.e. the links are all
  209.    *  intact and anchors are consistent)
  210.    */
  211. extern BOOL Mem_CheckHeap(void);
  212.  
  213.  
  214. #ifdef __cplusplus
  215.            }
  216. #endif
  217.  
  218. #endif
  219.