nucleus/library/application/memory_checker.h

   1 #ifndef MEMORY_CHECKER_CLASS
   2 #define MEMORY_CHECKER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : memory_checker                                                    *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1998-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "definitions.h"
  19
  20 #ifdef ENABLE_MEMORY_HOOK
  21
  22 #include "build_configuration.h"
  23 uhh
  24
  25 // forward.
  26 class allocation_memories;
  27 class memory_checker;
  28
  29 //////////////
  30
  31 memory_checker BASIS_EXTERN &program_wide_memories();
  32   //!< a global version of the memory checker to access memory tracking.
  33   /*!< this accesses the singleton object that tracks all memory allocations
  34   occuring in the program via calls to new and delete.  it should be used
  35   rather than creating a memory_checker anywhere else. */
  36
  37 //////////////
  38
  39 //! Debugging assistance tool that checks for memory leaks.
  40 /*!
  41   Provides allocation checking for heap memory for C++.  This is used as a
  42   replacement for the standard new and delete operations.  No object should
  43   really need to deal with this class directly; it is hooked in automatically
  44   unless the ENABLE_MEMORY_HOOK macro is defined.  Generally, release builds
  45   should not have this enabled, since it will slow things down tremendously.
  46   NOTE: this object can absolutely not be hooked into callstack tracker, since
  47   this object implements all c++ memory, including the tracker's.  This object
  48   will use the backtrace information if it's available.
  49 */
  50
  51 class memory_checker
  52 {
  53 public:
  54   void construct();  //!< faux constructor for mallocing.
  55
  56   void destruct();  //!< faux destructor shuts down object.
  57
  58   //! turn off memory checking.
  59   void disable() { _enabled = false; }
  60   //! turn memory checking back on.
  61   void enable() { _enabled = true; }
  62   //! reports on whether the memory checker is currently in service or not.
  63   bool enabled() const { return _enabled; }
  64
  65   void *provide_memory(size_t size, char *file, int line);
  66     //!< returns a chunk of memory with the "size" specified.
  67     /*!< this is the replacement method for the new operator.  we will be
  68     calling this instead of the compiler provided new.  the "file" string
  69     should be a record of the location where this is invoked, such as is
  70     provided by the __FILE__ macro.  the "line" should be set to the line
  71     number within the "file", if applicable (use __LINE__). */
  72
  73   int release_memory(void *ptr);
  74     //!< drops our record for the memory at "ptr".
  75     /*!< this is the only way to remove an entry from our listings so that
  76     it will not be reported as a leak.  we do not currently gather any info
  77     about where the release is invoked.  if there was a problem, the returned
  78     outcome will not be OKAY. */
  79
  80   char *text_form(bool show_outstanding);
  81     //!< returns a newly allocated string with the stats for this object.
  82     /*!< if "show_outstanding" is true, then all outstanding allocations are
  83     displayed in the string also.  the invoker *must* free the returned
  84     pointer. */
  85
  86 private:
  87   allocation_memories *_mems;  //!< internal object tracks all allocations.
  88   bool _unusable;  //!< true after destruct is called.
  89   bool _enabled;  //!< true if the object is okay to use.
  90 };
  91
  92 #else // enable memory hook.
  93   // this section disables the memory checker entirely.
  94   #define program_wide_memories()
  95     // define a do nothing macro for the global memory tracker.
  96 #endif // enable memory hook.
  97
  98 #endif // outer guard.
  99