Title: Elephant - A C++ Memory Observer

To build the Elephant library, unit tests and the (test) supporting Aeryn library with Microsoft Visual C++ 7.1, simply open the Elephant solution located in the top level Elephant directory and select Build Solution from the Build menu.

To run the unit tests right click on the TestClient project in the Solution Explorer and select Set as StartUp Project, then select Start Without Debugging from the Debug menu. This should give you the following output:

Aeryn 0.4.0 beta (c) Paul Grenyer 2004
http://www.paulgrenyer.co.uk/aeryn
--------------------------------------
Ran 21 tests, 21 Passed, 0 Failed.
Press any key to continue

To build the Elephant library, unit tests and the (test) supporting Aeryn library with MinGW open a command prompt and navigate to the top level Elephant directory. Making sure that the MinGW bin directory is in your path, type:

mingw32-make

To run the unit tests type the following:

bin\TestClient.exe

This should give you the following output:

Aeryn 0.4.0 beta (c) Paul Grenyer 2004
http://www.paulgrenyer.co.uk/aeryn
--------------------------------------
Ran 21 tests, 21 Passed, 0 Failed.

For mingw32-make clean to work correctly the rm tool from MSYS or cygwin must also be in your path.

To build the Elephant library, unit tests and the (test) supporting Aeryn library with g++ open a command prompt and navigate to the top level Elephant directory. Checking that g++ and make are both installed correctly, type:

make

To run the unit tests type the following:

bin/TestClient.exe

This should give you the following output:

Aeryn 0.4.0 beta (c) Paul Grenyer 2004
http://www.paulgrenyer.co.uk/aeryn
--------------------------------------
Ran 21 tests, 21 Passed, 0 Failed.

The current version of Elephant was tested with g++ 3.2.3 on Red Hat Linux ES 3.0. If any of the tests fail on your platform Elephant may not work as expected. If you do have tests that fail, please send me the complete Aeryn output along with details of your g++ version and operating system.

Once you have created a solution containing the project which is going to use Elephant to monitor memory usage, you are ready to add Elephant to your environment.

There are at least two ways to add the Elephant static library to your solution:

This description of configuring MinGW and g++ to link to Elephant assumes that you are using a make file to build your project. Of course this is not the only way.

To link Elephant to your executable (or shared library etc) two extra parameters need to be added to your link command: the path to the Elephant static library, preceded by -L and the name of library, preceded by -l. For example:

g++ myproj.o -LElephant/bin -lelephant myproj

The Elephant include files must be made available to every invocation of g++ that builds a source (cpp) file that includes, directly or indirectly, an Elephant include file. This is done by adding a single parameter, which consists of the path to the Elephant include directory preceded by -I. For example:

g++ -c -o myproj.o myproj.cpp -IElephant/include

The custom implementations of operator new and operator delete are the key to Elephant's ability to monitor memory. There are overloads for the normal and array versions with corresponding no throw versions.

To use the Elephant's custom new and delete operators simply include the newdelete.h header in your program. For example:

#include <elephant/newdelete.h>
int main() {
  return 0;
}

It only needs to be included once, although multiple inclusions will not do any harm.

Every time a call is made to new or delete the Elephant operator overloads will register the call with the Elephant memory monitor. The Elephant memory monitor is observerable and you can register one of the provided observers or write your own to react to the allocations and de-allocations.

Let's start of with a simple example of a memory leak:

#include <elephant/newdelete.h>
class SomethingToAllocate {};
int main() {
  SomethingToAllocate* p
                   = new SomethingToAllocate;
  return 0;
}

This program will compile and run and you will see absolutely no indication of the memory leak. In order to detect the memory leak you need the leak detector class, LeakDetector. The leak detector class is an observer of the memory monitor, so you need to register and unregister it as an observer:

#include <elephant/newdelete.h>
#include <elephant/memorymonitorholder.h>
#include <elephant/leakdetector.h>
class SomethingToAllocate {};

int main() {
  using namespace elephant;
  LeakDetector leakDetector;
  // Register leak detector with memory monitor.
  MemoryMonitorHolder().Instance().AddObserver(
                                   &leakDetector);
  SomethingToAllocate* p = new SomethingToAllocate;
  // Unregister leak detector with memory monitor.
  MemoryMonitorHolder().Instance().RemoveObserver(
                                   &leakDetector);
  return 0;
}

To use the memory monitor and the leak detector you need to include the appropriate header files as shown. Running this program will still not indicate that there is a memory leak. To indicate the memory leak you need to interrogate the LeakDetector instance. For example:

#include <elephant/newdelete.h>
#include <elephant/memorymonitorholder.h>
#include <elephant/leakdetector.h>
#include <cassert>
class SomethingToAllocate {};

int main() {
  using namespace elephant;
  LeakDetector leakDetector;
  // Register leak detector with memory monitor.
  MemoryMonitorHolder().Instance().AddObserver(
                                  &leakDetector);
  SomethingToAllocate* p = new SomethingToAllocate;
  // Unregister leak detector with memory monitor.
  MemoryMonitorHolder().Instance().RemoveObserver(
                                   &leakDetector);
  assert(!leakDetector.IsLeak());
  return 0;
}

The assert (which required the cassert header as shown) will indicate that a memory leak has occurred. This particular method of indicating a memory leak isn't particularly useful. The next step is to print the memory address and the size of the leak:

#include <elephant/newdelete.h>
#include <elephant/memorymonitorholder.h>
#include <elephant/leakdetector.h>
#include <elephant/leakdisplayfunc.h>
#include <algorithm>
class SomethingToAllocate {};

int main() {
  using namespace elephant;
  LeakDetector leakDetector;
  // Register leak detector with memory monitor.
  MemoryMonitorHolder().Instance().AddObserver(
                                   &leakDetector);
  SomethingToAllocate* p = new SomethingToAllocate;
  // Unregister leak detector with memory monitor.
  MemoryMonitorHolder().Instance().RemoveObserver(
                                   &leakDetector);
  // Display the details of the leak.
  LeakDisplayFunc leakDisplay(std::cout);
  std::for_each(leakDetector.begin(),
                leakDetector.end(), leakDisplay);
  return 0;
}

The LeakDisplayFunc class constructor takes a reference to an output stream and has a function operator that can be used, as shown, to the write memory leak information to the stream. As LeakDisplayFunc uses an output stream it is possible that memory will be allocated and not freed until the end of main. This is why the leak detector must be unregistered before the memory leak information is displayed. Otherwise the output stream allocation will appear as a further memory leak. One way to avoid having to unregister the LeakDetector is to write your own function object that displays the memory leak information without allocating memory using new. For example using printf. The output from this program should be as follows, although the address will be a different value:

Address:        00320B70
Size:           1

In the previous example the memory leak was displayed as a memory address and a size. This can be useful in finding a memory leak, but not as usual as tracking the exact site of the allocation. Elephant can do this by introducing a special macro into every translation unit where this type of tracking is needed. The macro is called ELEPHANTNEW and can be included anywhere in the translation unit. The following code shows how the macro would be added to example 1:

#include <elephant/newdelete.h>
#include <elephant/memorymonitorholder.h>
#include <elephant/leakdetector.h>
#include <elephant/leakdisplayfunc.h>
#include <algorithm>

#define new ELEPHANTNEW

class SomethingToAllocate {};
int main() {
  ...
}

The output should now look something like this:

Address:        00322878
Size:           1
Line:           22
Function:       main
File:           c:\...\example2\main.cpp

Some compilers, such as Microsoft Visual C++ 7.1 will show a fully qualified function name and a complete a full file path. Other compilers, such as g++ and MinGW will show only the local function name and file name without the full path. For example:

Address:        0x3d24f0
Size:           1
Line:           23
File:           main.cpp

The other memory observer supplied with Elephant, MaxMemoryObserver, is for measuring the maximum amount of memory used at anyone time by an application. Its use is very similar to that of LeakDetector:

#include <elephant/newdelete.h>
#include <elephant/memorymonitorholder.h>
#include <elephant/maxmemoryobserver.h>
class SomethingToAllocate {};

int main() {
  using namespace elephant;
  MaxMemoryObserver maxMemory;
  // Register max memory observer with memory monitor.
  MemoryMonitorHolder().Instance().AddObserver(
                                        &maxMemory);
  SomethingToAllocate *p1
                     = new SomethingToAllocate[100];
  delete[] p1;
  SomethingToAllocate *p2
                     = new SomethingToAllocate[50];
  delete[] p2;
  // Unregister max memory observer.
  MemoryMonitorHolder().Instance().RemoveObserver(
                                        &maxMemory);

  // Display the max memory usage
  std::cout << "Max memory usage: " 
            << static_cast<unsigned long>(
                              maxMemory.MaxMemory())
            << " bytes\n";
  return 0;
}

The output from this simple (not very exception safe) example is as follows:

Max memory usage: 100 bytes

The size of SomethingToAllocate is 1 byte. During the execution of the program a total of 150 SomethingToAllocate instances are created and destroyed. However, the program only has up to 100 instances allocated at any one time. Therefore the maximum amount of memory used by the program is 100 bytes.

Elephant can be used for more than just detecting memory leaks and the maximum memory used by a program. Elephant can be used to monitor any characteristic of new and delete based memory usage via custom memory observers. Custom memory observers are simple to create. All that is required is the implementation of the following interface:

namespace elephant {
  class IMemoryObserver {
  protected:
    IMemoryObserver();
  public:
    virtual ~IMemoryObserver() = 0;
    virtual void OnAllocate(void* p, size_t size,
                 size_t line, const char* file) = 0;
    virtual void OnFree(void* p) = 0;
  private:
    IMemoryObserver(const IMemoryObserver&);
    IMemoryObserver& operator=(
                            const IMemoryObserver&);
  };
}

All that needs to be done to implement the interface is to inherit from it and override the OnAllocate and OnFree pure virtual member functions. The OnAllocate function has the following arguments:

p - A pointer to the memory that has been allocated. This is useful for getting the address.

size - The size of the memory that has been allocated.

line - The line number on which the memory was allocated. This is 0 unless the ELEPHANTNEW macro has been used correctly.

char - The file in which the memory was allocated. This is an empty string unless the ELEPHANTNEW macro has been used correctly.

The OnFree function has the following argument:

p - A pointer to the memory that has been allocated. This is useful for getting the address.

The default constructor of the interface is protected to show that the class should be inherited from. The copy constructor and assignment operator are private to prevent attempts to copy the interface or its subclasses (unless the subclasses define their own copy constructor and assignment operator) and the destructor is virtual to ensure proper destruction should a dynamically allocated subclass by destroyed via a pointer to the interface.

The example below is of a simple custom observer which records the total memory allocated by a program during its lifetime:

class TotalMemoryobserver : public elephant::IMemoryObserver {
private:
  size_t totalMemory_;
public:
  TotalMemoryobserver()
      : totalMemory_(0) {}
  virtual void OnAllocate(void* p, size_t size,
                   size_t line, const char* file) {
    totalMemory_ += size;
  }
  virtual void OnFree(void* p) {}
  size_t TotalMemory() const {
    return totalMemory_;
  }
}

The OnAllocate override is used to accumulate the size of every allocation. The other parameters are ignored as they are not needed. The OnFree function does nothing as we are not interested in de-allocations. In, for example, the leak detector, the value of p passed to OnFree is used to match against a previous value of p passed to OnAllocate to show that the memory has been deleted.

Replacing MaxMemoryObserver, from the previous example, with TotalMemoryobserver and making a couple of other minor changes:

int main() {
  using namespace elephant;
  TotalMemoryobserver totalMemory;
  // Register max memory observer with memory monitor.
  MemoryMonitorHolder().Instance().AddObserver(
                                      &totalMemory);
  SomethingToAllocate *p1
                    = new SomethingToAllocate[100];
  delete[] p1;
  SomethingToAllocate *p2
                    = new SomethingToAllocate[50];
  delete[] p2;
  // Unregister max memory observer.
  MemoryMonitorHolder().Instance().RemoveObserver(
                                      &totalMemory);
  // Display the max memory usage
  std::cout << "Total memory usage: " 
            << static_cast<unsigned long>(
                         totalMemory.TotalMemory())
            << " bytes\n";
  return 0;
}

gives the following output, which correctly indicates the total memory used by the program:

Total memory usage: 150 bytes

Sometimes you want to store information about allocations and de-allocations in a container within a custom memory observer. Containers do of course allocate memory in order to contain. This could lead to erroneous memory usage observations and, in a worst case scenario, infinite recursion.

The simple answer is to use a container that uses malloc and free instead of new and delete. Or, to be more precise, a container that uses an allocator that allocates with malloc and free instead of new and delete. Elephant comes with just such an allocator, called malloc_allocator, which can be used with any of the C++ standard library containers. It should be used as follows:

#include <elephant/tools/mallocallocator.h>
#include <vector>
...
std::vector<size_t,
      elephant::tools::malloc_allocator<size_t> >
      allocStore;

Naturally a typedef can make life a lot easier.

The following example shows a custom memory observer that uses a container with the malloc_allocator to store two lists of the addresses, allocations and de-allocations:

#include <elephant/newdelete.h>
#include <elephant/memorymonitorholder.h>
#include <elephant/imemoryobserver.h>
#include <elephant/tools/mallocallocator.h>
#include <vector>

class AllocationMemoryobserver : public
                        elephant::IMemoryObserver {
private:
  typedef std::vector<void*,
        elephant::tools::malloc_allocator<void*> >
        MAllocContainer;
  typedef MAllocContainer::const_iterator
        const_iterator;
  MAllocContainer allocations_;
  MAllocContainer deallocations_;

  void Print(const MAllocContainer& cont,
             std::ostream& out) {

    const_iterator current = cont.begin();
    const_iterator end  = cont.end();
    for(; current != end; ++current) {
      out << "\t" << (*current) << "\n";
    }
    out << "\n";
  }
public:
  AllocationMemoryobserver() : allocations_(),
                               deallocations_() {}
  virtual void OnAllocate(void* p, size_t size,
                   size_t line, const char* file) {
    allocations_.push_back(p);
  }
  virtual void OnFree(void* p) {
    deallocations_.push_back(p);
  }
  void PrintAllocations(std::ostream& out) {
    out << "Allocations:\n";
    Print(allocations_, out);
  }
  void PrintDeallocations(std::ostream& out) {
    out << "Deallocations:\n";
    Print(deallocations_, out);
  }
};

class SomethingToAllocate {};

int main() {
  using namespace elephant;
  AllocationMemoryobserver allocationObserver;
  // Register max memory observer with memory monitor.
  MemoryMonitorHolder().Instance().AddObserver(
                               &allocationObserver);
  SomethingToAllocate *p1
                     = new SomethingToAllocate[100];
  SomethingToAllocate *p2
                     = new SomethingToAllocate[50];
  delete[] p2;
  delete[] p1;
  // Unregister max memory observer.
  MemoryMonitorHolder().Instance().RemoveObserver(
                               &allocationObserver);
  allocationObserver.PrintAllocations(std::cout);
  allocationObserver.PrintDeallocations(std::cout);
  return 0;
}

The output from this example is as follows:

Allocations:
        00322850
        00322910
Deallocations:
        00322910
        00322850

If malloc_allocator is replaced by the default allocator, there is no output, not even an error message, with both Microsoft Visual C++ and MinGW.

If you open the mutex.h header file, you will see it looks like this:

#ifndef ELEPHANT_TOOLS_MUTEX_H
#define ELEPHANT_TOOLS_MUTEX_H
#include <elephant/tools/nullmutex.h>
//#include <elephant/tools/boostmutex.h>
//#include <elephant/tools/win32mutex.h>
#endif // ELEPHANT_TOOLS_MUTEX_H

There are three types of mutex supplied with Elephant:

The Null Mutex is used by default. To use one of the other mutexes simply include its header file in mutex.h instead of nullmutex.h and rebuild (a rebuild all is recommended).

A custom mutex can be written simply by implementing the following class in its own header file and including it in mutex.h instead of the other mutex header files:

namespace elephant {
  namespace tools {
    class Mutex {
    public:
      Mutex() {}
      ~Mutex() {}
      void Enter() const {}
      void Leave() const {}
    private:
      Mutex(const Mutex&);
      Mutex& operator=(const Mutex&);
    };
  }
}

Note: As the Enter and Leave member functions are const, you may need to make the object that holds the current state of the mutex mutable.