/[ascend]/trunk/base/generic/utilities/ascMalloc.h
ViewVC logotype

Diff of /trunk/base/generic/utilities/ascMalloc.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 598 by johnpye, Fri May 12 10:03:59 2006 UTC revision 599 by johnpye, Fri May 12 12:53:57 2006 UTC
# Line 1  Line 1 
1  /*  /*  ASCEND modelling environment
2   *  Ascend Memory Allocation Routines      Copyright (C) 2006 Carnegie Mellon University
3   *  by Tom Epperly  
4   *  Created: 2/6/90      This program is free software; you can redistribute it and/or modify
5   *  Version: $Revision: 1.2 $      it under the terms of the GNU General Public License as published by
6   *  Version control file: $RCSfile: ascMalloc.h,v $      the Free Software Foundation; either version 2, or (at your option)
7   *  Date last modified: $Date: 1997/07/18 11:44:50 $      any later version.
8   *  Last modified by: $Author: mthomas $  
9   *      This program is distributed in the hope that it will be useful,
10   *  This file is part of the Ascend Language Interpreter.      but WITHOUT ANY WARRANTY; without even the implied warranty of
11   *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12   *  Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly      GNU General Public License for more details.
13   *  
14   *  The Ascend Language Interpreter is free software; you can redistribute      You should have received a copy of the GNU General Public License
15   *  it and/or modify it under the terms of the GNU General Public License as      along with this program; if not, write to the Free Software
16   *  published by the Free Software Foundation; either version 2 of the      Foundation, Inc., 59 Temple Place - Suite 330,
17   *  License, or (at your option) any later version.      Boston, MA 02111-1307, USA.
18   *  *//** @file
19   *  The Ascend Language Interpreter is distributed in hope that it will be      ASCEND memory allocation & reporting routines.
20   *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of  
21   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU      These functions provide tracking of memory events and assist
22   *  General Public License for more details.      finding and debugging memory errors.  Memory tracking options are
23   *      selected using the macros MALLOC_DEBUG and ALLOCATED_TESTS discussed
24   *  You should have received a copy of the GNU General Public License      below.  This allows the enhanced functionality to be used or turned
25   *  along with the program; if not, write to the Free Software Foundation,      off as desired.  This functionality adds considerable run-time overhead,
26   *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named      and so should generally be used for debugging purposes only.  There are
27   *  COPYING.      also routines for reporting on the status of memory blocks as well as
28   */      for the memory manager itself.<br><br>
29    
30        To use the memory tracking features, you need to use the provided
31        allocation and deallocation functions (ascmalloc(), asccalloc(),
32        ascrealloc(), ascfree()).  Direct calls to the corresponding system
33        routines will by-pass the memory manager and not be tracked.  Memory
34        allocations which return NULL are not tracked or recorded.<br><br>
35    
36        This module also standardizes critical implementation-specific features
37        such as behavior when an allocation of zero bytes is requested
38        (see MOD_ASCMALLOC), and the behavior of realloc() under purify
39        (see MOD_REALLOC).<br><br>
40    
41        The following macros affect the compilation and run-time behavior
42        of Ascend memory management.
43    
44        <pre>
45          MOD_ASCMALLOC     Forces the memory allocation functions to always
46                            allocate at least 1 byte and return a non-NULL
47                            pointer.  This macro should be defined if your
48                            allocator returns NULL when a zero-sized block is
49                            requested (e.g. alpha or rs6000; Borland and Watcom
50                            on Windows).  It need not be defined if your
51                            allocator returns a non-NULL pointer to a zero-length
52                            block, saving you a few bytes of memory.
53    
54          MALLOC_DEBUG      Causes all calls to memory allocation routines
55                            to be tracked and logged to an output file.
56                            This really slows down the memory management
57                            system, and so should be used for debugging only.
58    
59          ALLOCATED_TESTS   Forces a lot of extra assertions when defined
60                            along with MALLOC_DEBUG.
61    
62          MOD_REALLOC       If defined, ascreallocPURE() uses a homegrown
63                            realloc() that behaves properly with purify.
64                            This is more expensive, and should be used
65                            for debugging only.
66    
67        Requires:
68               #include "utilities/ascConfig.h"
69               #include "utilities/ascPanic.h"
70        </pre>
71    *//*
72        by Tom Epperly
73        Created: 2/6/90
74        Version: $Revision: 1.2 $
75        Version control file: $RCSfile: ascMalloc.h,v $
76        Date last modified: $Date: 1997/07/18 11:44:50 $
77        Last modified by: $Author: mthomas $
78    */
79    
80  #ifndef ASC_ASCMALLOC_H  #ifndef ASC_ASCMALLOC_H
81  #define ASC_ASCMALLOC_H  #define ASC_ASCMALLOC_H
82    
83  /** @file  /* MALLOC_DEBUG may be defined in config.h... */
84   *  ASCEND memory allocation & reporting routines.  #include <utilities/config.h>
  *  These functions provide tracking of memory events and assist  
  *  finding and debugging memory errors.  Memory tracking options are  
  *  selected using the macros MALLOC_DEBUG and ALLOCATED_TESTS discussed  
  *  below.  This allows the enhanced functionality to be used or turned  
  *  off as desired.  This functionality adds considerable run-time overhead,  
  *  and so should generally be used for debugging purposes only.  There are  
  *  also routines for reporting on the status of memory blocks as well as  
  *  for the memory manager itself.<br><br>  
  *  
  *  To use the memory tracking features, you need to use the provided  
  *  allocation and deallocation functions (ascmalloc(), asccalloc(),  
  *  ascrealloc(), ascfree()).  Direct calls to the corresponding system  
  *  routines will by-pass the memory manager and not be tracked.  Memory  
  *  allocations which return NULL are not tracked or recorded.<br><br>  
  *  
  *  This module also standardizes critical implementation-specific features  
  *  such as behavior when an allocation of zero bytes is requested  
  *  (see MOD_ASCMALLOC), and the behavior of realloc() under purify  
  *  (see MOD_REALLOC).<br><br>  
  *  
  *  The following macros affect the compilation and run-time behavior  
  *  of Ascend memory management.  
  *  <pre>  
  *    MOD_ASCMALLOC     Forces the memory allocation functions to always  
  *                      allocate at least 1 byte and return a non-NULL  
  *                      pointer.  This macro should be defined if your  
  *                      allocator returns NULL when a zero-sized block is  
  *                      requested (e.g. alpha or rs6000; Borland and Watcom  
  *                      on Windows).  It need not be defined if your  
  *                      allocator returns a non-NULL pointer to a zero-length  
  *                      block, saving you a few bytes of memory.  
  *  
  *    MALLOC_DEBUG      Causes all calls to memory allocation routines  
  *                      to be tracked and logged to an output file.  
  *                      This really slows down the memory management  
  *                      system, and so should be used for debugging only.  
  *  
  *    ALLOCATED_TESTS   Forces a lot of extra assertions when defined  
  *                      along with MALLOC_DEBUG.  
  *  
  *    MOD_REALLOC       If defined, ascreallocPURE() uses a homegrown  
  *                      realloc() that behaves properly with purify.  
  *                      This is more expensive, and should be used  
  *                      for debugging only.  
  *  
  *  Requires:  
  *         #include "utilities/ascConfig.h"  
  *         #include "utilities/ascPanic.h"  
  *  </pre>  
  */  
85    
86  #ifdef MALLOC_DEBUG  #ifdef MALLOC_DEBUG
87  #  define ascstrdup(str) ascstrdupf_dbg(str)  #  define ascstrdup(str) ascstrdupf_dbg(str)
# Line 103  Line 103 
103  ASC_DLLSPEC(char) *ascstrdupf(CONST char *str);  ASC_DLLSPEC(char) *ascstrdupf(CONST char *str);
104  /**<  /**<
105   *  Implementation function for ascstrdup() if MALLOC_DEBUG   *  Implementation function for ascstrdup() if MALLOC_DEBUG
106   *  is not defined.  Do not call this function directly - use   *  is not defined.  Do not call this function directly - use
107   *  ascstrdup() instead.   *  ascstrdup() instead.
108   */   */
109    
# Line 118  ASC_DLLSPEC(char *) asc_memcpy(char *des Line 118  ASC_DLLSPEC(char *) asc_memcpy(char *des
118  /**<  /**<
119   *  Copies n bytes from memory address src to dest.   *  Copies n bytes from memory address src to dest.
120   *  This version of memcpy handles overlapping memory ranges   *  This version of memcpy handles overlapping memory ranges
121   *  properly. It could be more efficient internally. As it is,   *  properly. It could be more efficient internally. As it is,
122   *  it moves data a char at a time.  Unless n is 0, neither dest   *  it moves data a char at a time.  Unless n is 0, neither dest
123   *  nor src may be NULL (checked by asc_assertion).   *  nor src may be NULL (checked by asc_assertion).
124   *   *
125   *  @param dest Pointer to address to which to copy (non-NULL).   *  @param dest Pointer to address to which to copy (non-NULL).
# Line 141  ASC_DLLSPEC(char *) asc_memcpy(char *des Line 141  ASC_DLLSPEC(char *) asc_memcpy(char *des
141   *  purify realloc() function for debugging purposes.   *  purify realloc() function for debugging purposes.
142   *  In some OS, realloc() fools purify into thinking there   *  In some OS, realloc() fools purify into thinking there
143   *  is a memory leak.  If MOD_REALLOC is defined at compile   *  is a memory leak.  If MOD_REALLOC is defined at compile
144   *  time for all software referencing this header, then all   *  time for all software referencing this header, then all
145   *  calls to ascreallocPURE() will use a homegrown realloc   *  calls to ascreallocPURE() will use a homegrown realloc
146   *  that does not fool purify.  Leaks of memory reported   *  that does not fool purify.  Leaks of memory reported
147   *  around realloc() when MOD_REALLOC is defined should be   *  around realloc() when MOD_REALLOC is defined should be
148   *  real leaks and not OS noise.<br><br>   *  real leaks and not OS noise.<br><br>
149   *   *
150   *  The custom function is somewhat more expensive than most   *  The custom function is somewhat more expensive than most
151   *  system-supplied realloc()'s, so should only be used for   *  system-supplied realloc()'s, so should only be used for
152   *  debugging.  Note that ascreallocPURE() will provide memory   *  debugging.  Note that ascreallocPURE() will provide memory
153   *  event tracking if MALLOC_DEBUG is also defined when this   *  event tracking if MALLOC_DEBUG is also defined when this
154   *  header is included.   *  header is included.
155   *   *
# Line 165  extern char *ascreallocPUREF(char *ptr, Line 165  extern char *ascreallocPUREF(char *ptr,
165   *  Implementation function for release version of ascreallocPURE().   *  Implementation function for release version of ascreallocPURE().
166   *  Do not call this function directly - use ascreallocPURE()   *  Do not call this function directly - use ascreallocPURE()
167   *  (by #defining MOD_REALLOC) instead.  This version does not have   *  (by #defining MOD_REALLOC) instead.  This version does not have
168   *  its memory tracked.  This is a custom realloc() which behaves   *  its memory tracked.  This is a custom realloc() which behaves
169   *  properly with purify.  It bypasses the standard realloc() function.     *  properly with purify.  It bypasses the standard realloc() function.
170   *  The caller must indicate the old size of the memory region.   *  The caller must indicate the old size of the memory region.
171   *   *
172   *  @param ptr      Pointer to the memory block to reallocate.   *  @param ptr      Pointer to the memory block to reallocate.
# Line 519  extern int InMemoryBlockF(CONST VOIDPTR Line 519  extern int InMemoryBlockF(CONST VOIDPTR
519  #  define AssertMemory(ptr)  #  define AssertMemory(ptr)
520  #endif  #endif
521  /**<  /**<
522   *  Assertion that ptr points to (or into) an allocated memory   *  Assertion that ptr points to (or into) an allocated memory
523   *  block.  This assertion is only active if both MALLOC_DEBUG   *  block.  This assertion is only active if both MALLOC_DEBUG
524   *  and ALLOCATED_TESTS are defined.   *  and ALLOCATED_TESTS are defined.
525   *   *

Legend:
Removed from v.598  
changed lines
  Added in v.599

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22