new home directory
[feisty_meow.git] / 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