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