home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / funnel / memory.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-10-23  |  6.3 KB  |  114 lines
  1. /*##############################################################################
  2.  
  3. FUNNNELWEB COPYRIGHT
  4. ====================
  5. FunnelWeb is a literate-programming macro preprocessor.
  6.  
  7. Copyright (C) 1992 Ross N. Williams.
  8.  
  9.    Ross N. Williams
  10.    ross@spam.adelaide.edu.au
  11.    16 Lerwick Avenue, Hazelwood Park 5066, Australia.
  12.  
  13. This program is free software; you can redistribute it and/or modify
  14. it under the terms of Version 2 of the GNU General Public License as
  15. published by the Free Software Foundation.
  16.  
  17. This program is distributed WITHOUT ANY WARRANTY; without even the implied
  18. warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  19. See Version 2 of the GNU General Public License for more details.
  20.  
  21. You should have received a copy of Version 2 of the GNU General Public
  22. License along with this program. If not, you can FTP the license from
  23. prep.ai.mit.edu/pub/gnu/COPYING-2 or write to the Free Software
  24. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25.  
  26. Section 2a of the license requires that all changes to this file be
  27. recorded prominently in this file. Please record all changes here.
  28.  
  29. Programmers:
  30.    RNW  Ross N. Williams  ross@spam.adelaide.edu.au
  31.  
  32. Changes:
  33.    07-May-1992  RNW  Program prepared for release under GNU GPL V2.
  34.  
  35. ##############################################################################*/
  36.  
  37.  
  38. /******************************************************************************/
  39. /*                                  MEMORY.H                                  */
  40. /******************************************************************************/
  41. /*                                                                            */
  42. /* Introduction                                                               */
  43. /* ------------                                                               */
  44. /* This package provides a memory management facility for FunnelWeb.          */
  45. /* The conventional MALLOC does not suit the needs of FunnelWeb. The          */
  46. /* following notes give an idea of why:                                       */
  47. /*                                                                            */
  48. /* 1. At the times where FunnelWeb requires memory, it is nearly always       */
  49. /*    the case that failure to provide the memory should result in a bomb.    */
  50. /*    It therefore makes sense to wrap MALLOC up inside another function      */
  51. /*    that, at the very least, checks the status from malloc and bombs        */
  52. /*    the program if the requested memory is not available.                   */
  53. /*                                                                            */
  54. /* 2. Because FunnelWeb proper can be invoked an indefinite number of         */
  55. /*    times from the FunnelWeb command interpreter, it is very important      */
  56. /*    to reclaim all the memory used by each invocation. This could be        */
  57. /*    done by explicitly tearing apart the data structures constructed        */
  58. /*    for each run. However, this is very messy, requiring detailed           */
  59. /*    knowledge of the data structures. A far simpler, safer scheme is to     */
  60. /*    arrange for a memory manager to keep track of all the memory that it    */
  61. /*    allocates and to provide a single call to free it all. This facility    */
  62. /*    is provided by this package.                                            */
  63. /*                                                                            */
  64. /* 3. In addition to the TEMPORARY memory allocations described in (2) above, */
  65. /*    it should also be possible to make permanent allocations.               */
  66. /*                                                                            */
  67. /* 4. FunnelWeb uses linked lists a lot and hence will make many requests     */
  68. /*    for small chunks of memory (e.g 10 bytes). Legend has it that some      */
  69. /*    malloc libraries are very inefficient in this case, and that it is      */
  70. /*    better to use malloc to allocate a large chunk of memory and dole it    */
  71. /*    out yourself. This package does this too.                               */
  72. /*                                                                            */
  73. /* For all these reasons, FunnelWeb memory management has been handed over to */
  74. /* this package which provides services that satisfy the conditions outlined  */
  75. /* above.                                                                     */
  76. /*                                                                            */
  77. /******************************************************************************/
  78.  
  79. /* Ensure that the body of this header file is included at most once.         */
  80. #ifndef DONE_MEMORY
  81. #define DONE_MEMORY
  82.  
  83. /******************************************************************************/
  84.  
  85. #include "style.h"
  86.  
  87. /******************************************************************************/
  88.  
  89. EXPORT p_void mm_perm P_((size_t));
  90. /* Allocates a block of memory of the specified size (specified in bytes) and */
  91. /* returns a pointer to the new block of memory. Bombs the program if the     */
  92. /* memory is not available. Memory allocated using mm_perm is permanently     */
  93. /* allocated and cannot be freed.                                             */
  94.  
  95. EXPORT p_void mm_temp P_((size_t));
  96. /* Allocates a block of memory of the specified size (specified in bytes) and */
  97. /* returns a pointer to the new block of memory. Bombs the program if the     */
  98. /* memory is not available. Memory allocated using this function can later be */
  99. /* freed in its entirely by making a call to mm_zapt.                         */
  100.  
  101. EXPORT void mm_zapt P_((void));
  102. /* This function can be called at any time. Its effect is to free up all the  */
  103. /* memory allocated using mm_temp since the last call to mm_zapt or the start */
  104. /* of the program, whichever is the more recent.                              */
  105.  
  106. /******************************************************************************/
  107.  
  108. /* For #ifndef preventing multiple inclusion of the body of this header file. */
  109. #endif
  110.  
  111. /******************************************************************************/
  112. /*                               End of MEMORY.H                              */
  113. /******************************************************************************/
  114.