home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / DynamArea < prev    next >
Encoding:
Text File  |  1996-11-05  |  4.1 KB  |  146 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:    DynamArea.h
  12.     Author:  Copyright © 1996 Julian Smith.
  13.     Version: 1.00 
  14.     Purpose: Simple management of dynamic areas.
  15.     History: 1.00 (12 Jul 1996)
  16.  
  17.  */
  18.  
  19.  
  20. /*
  21. These functions allow dynamic areas to be easily created, resized and
  22. deleted.
  23.  
  24. The main reason for this library is that the SWI provided by RISC OS for
  25. changing the size of a DA (OS_ChangeDynamicArea) is rather tricky to
  26. use, for two reasons:
  27.  
  28. 1    It expects the change in the size of the dynamic area, rather
  29.     than an absolute size.
  30. 2    This change is relative to the actual size of the DA, rather
  31.     than the size last requested (DAs are rounded up to a multiple
  32.     of a page-size).
  33.  
  34. Also, this library keeps a list of created DAs, and can delete them all
  35. when the program finishes.
  36.  
  37. No facility is provided for heap-management within individual dynamic
  38. areas.
  39.  */
  40.  
  41. #ifndef __Desk_DynamArea_h
  42. #define __Desk_DynamArea_h
  43.  
  44.  
  45. #ifdef __cplusplus
  46.     extern "C" {
  47. #endif
  48.  
  49.  
  50.  
  51. typedef struct Desk_DynamicArea_block    {
  52.     int                id;        /* Used with OS_ChangeDynamicArea SWI etc    */
  53.     void*                data;        /* Pointer to start of dynamic area        */
  54.     size_t                datasize;    /* Last size passed to Desk_DynamicArea_SetSize    */
  55.     size_t                size;        /* Actual size of the dynamic area - probably     */
  56.                             /* 'datasize' rounded up to multiple of machine    */
  57.                             /* page-size.                    */
  58.     struct Desk_DynamicArea_block*    previous;    /* Maintains single-linked list of DAs.        */
  59.     }
  60.     Desk_DynamicArea_block;
  61. /*
  62. Information the Desk_DynamicArea library uses to keep track of all its
  63. dynamic areas.
  64.  
  65. Do /not/ use the fields directly - use only the functions/macros provided.
  66.  */
  67.  
  68.  
  69. void    Desk_DynamicArea_Create( Desk_DynamicArea_block* da, size_t maxsize, const char* name);
  70. /*
  71. Creates a dynamic area for use with Desk_DynamicArea_* calls.
  72.  
  73. da        Pointer to a Desk_DynamicArea_block that must exist for the life of
  74.         the dynamic area.
  75. maxsize        Maximum size the dynamic area will ever be. -1 means the amount
  76.         of RAM in the machine.
  77. name        Name of the dynamic area in the Tasks Manager's window.
  78.  */
  79.  
  80.  
  81. void    Desk_DynamicArea_Delete( Desk_DynamicArea_block* da);
  82. /*
  83. Completely removes the specified dynamic area.
  84.  
  85. da        Pointer to Desk_DynamicArea_block for the dynamic area
  86.         to delete.
  87.  */
  88.  
  89.  
  90. void    Desk_DynamicArea_DeleteAll( void);
  91. /*
  92. This deleted all the dynamic areas created with Desk_DynamicArea_Create.
  93. It is called automatically when the program finishes, using atexit().
  94.  
  95. Note that module builds /don't/ use atexit() in this way, because
  96. atexit() doesn't seem to work reliably in modules. You should therefore
  97. call Desk_DynamicArea_DeleteAll from a modules finalisation code.
  98.  */
  99.  
  100.  
  101. void*    Desk_DynamicArea_SetSize( Desk_DynamicArea_block* da, size_t size);
  102. /*
  103. Makes the specified dynamic area contain at least 'size' bytes. Any
  104. existing data is preserved, up to whatever is the minimum of the the old
  105. and new sizes (ie it behaves like realloc).
  106.  
  107. Returns a pointer to the data.
  108.  
  109. da        Pointer to Desk_DynamicArea_block for the dynamic area
  110.         to set size of.
  111. size        New size of dynamic area.
  112.  */
  113.  
  114.  
  115.  
  116. #define    Desk_DynamicArea_GetSize( da)        ( (da)->size)
  117. /*
  118. size_t    Desk_DynamicArea_GetSize( Desk_DynamicArea_block* da);
  119.  
  120. Returns the actual size of the DA.
  121.  */
  122.  
  123. #define    Desk_DynamicArea_GetDataSize( da)    ( (da)->datasize)
  124. /*
  125. size_t    Desk_DynamicArea_GetDataSize( Desk_DynamicArea_block* da);
  126.  
  127. Returns the last-requested size of the DA (ie the size past to the last
  128. succesfull call to Desk_DynamicArea_SetSize).
  129.  */
  130.  
  131.  
  132. #define    Desk_DynamicArea_GetData( da)        ( (da)->data)
  133. /*
  134. void*    Desk_DynamicArea_GetData( Desk_DynamicArea_block* da);
  135.  
  136. Returns a (void*) to the DA data.
  137.  */
  138.  
  139.  
  140. #ifdef __cplusplus
  141. }
  142. #endif
  143.  
  144.  
  145. #endif
  146.