Totalview Memory Debugger Getting Started Primer

The Memory Debugger integrated with TotalView Debugger contains many features that you can use in many different ways. The information in this primer will introduce its features. After reading this document, you'll be able to use the Memory Debugger. But there's much more than can be described in this short document. You'll find a complete description in our Debugging Memory Problems with the TotalView Memory Debugger Guide.

Starting the Memory Debugger

1. Select the Process > Enable Memory Debugging command before you tell your program to start executing. If you don't do this, memory debugging won't work.
2. Let your program run, then stop it after it allocates some memory. In addition, you may want to set a breakpoint on your program's last statement to see all leaks.
3. Select Tools > Memory Debugging, then select the Leak Detection or Heap Status tab.
4. Select a View (bottom left corner), then press the Generate Viewbutton.

If you make changes or run your program to another breakpoint, you’ll need to regenerate the view.

Checking for free() Errors

After enabling memory debugging, TotalView stops program execution before any of the following events occur:

• Freeing stack, bss, and data section memory
• Freeing memory that is already freed
• Freeing the wrong address
• Freeing an interior pointer
• Misaligning blocks
• Reallocating an unknown block

The Memory Debugger also displays an event window that tells you what is about to happen.

Backtraces Defined

When your program makes a memory request, the Memory Debugger records the stack frames that existed when the action occurred. This list of frames is called a backtrace.

Examining the backtrace tells you the path your program took to reach the statement that made the memory request. That is, while every memory allocation request ultimately goes to malloc(), how you got to malloc() is what's interesting.

Important: The Memory Debugger displays the backtrace that existed when the allocation occurred. That is, it is not displaying the current backtrace.

Source View Defined

The Source View shows the statement in your program that requested memory. As this can occur in many different ways, the Memory Debugger consolidates this information for all the backtraces associated with a statement.

Showing Memory Leaks

1. Stop program execution by running to a breakpoint, pressing the Halt button, and so on.
2. Select the Leak Detection tab.
3. Within the Generate View area, select either Source or Backtrace View from the pulldown list.
4. Press the Generate View button.

If is good news if you don't see anything: this means that your program isn't leaking memory.

If there are leaks, the Memory Debugger also summarizes the number of leaks and how much memory is associated with a backtrace or source line. This lets you focus on the most serious problems.

Displaying the Heap Graphically

Examining a graphical view of the heap can give you many insights into how your program is using memory. After generating a Heap Status Graphical View, you can begin investigating the display. Clicking on a block in the top area displays information at the bottom. And, clicking on information in the bottom highlights blocks in the top area that have the same backtrace.

Eliminating Information

The information displayed by the Memory Debugger can be considerable. You can simplify things by eliminating information related to a process, library, source file, class name, line number, PC, etc. For example, you can tell it not to show information in third-party libraries or parts of your code that you don't want to look at.

1. Select the button to the right of Enable Filtering.
2. Select the Add button to create a filter. Creating a filter is similar to creating a message filter within an email program such as Thunderbird.
3. After creating the filter, generate a view.

Identifying Dangling Pointers

If you've enabled memory debugging, you don't have to do anything else. Anytime TotalView display a variable's value (even if it's a tooltip), it tells you if memory is allocated, deallocated, or if you're looking at a dangling value.

Tracking Memory Blocks

The Block Properties Window can contain information about many memory blocks. After you place a block in the window, it's often hard to identify it. Adding a comment in a block's text field lets you remember why you're tracking a block.

Tracking Memory Usage

You can track how much memory your program is using by generating Memory Usage Views. Unlike other views, you do not need to enable memory debugging before displaying this information.

Block Painting

Block painting helps you locate problems caused by accessing allocated memory before you initialize it, or accessing deallocated memory.

Block painting writes a bit pattern into newly allocated or deallocated blocks. When you see this pattern, you know that a problem is occurring.

Enable Block Painting by selecting On within the pulldown list.

Tracking Deallocations

1. In a Variable Window, select the Tools > Block Propertiescommand. Be sure the Variable Window is displaying information in the pointed to location, not the pointer's value.
2. Or, in the Memory Debugger window, right-click on a selected block and select Properties.
3. Select Hide Backtrace Information, then expand the block by clicking +.
4. At the bottom of the window, select Notify when deallocated.

Now, when your program deallocates this block, TotalView stops execution and displays its Memory Event Details window.

Seeing Changes (Setting a Baseline)

1. In a Process Window, select either the Group or Process > Set Heap Baseline command.
2. Run your program. After stopping execution, select the Process > Heap Change Summary command. The Memory Debugger will now let you examine any memory allocations or leaks that occurred since you set the baseline.

Comparing Memory Usage

There are two ways to compare memory.

• If you created a baseline, go to the Memory Debugging window and select a button within the window's toolbar that shows you information relative to the baseline. This is convenient when you want to check how things are going while your program is executing.
• You can use the File > Export command to write memory information to disk. At a later time, often a different execution of the program, use the File > Import command to bring the information back into the Memory Debugger. You can now examine this information in exactly the same way as normal memory information. In addition, you can examine this information using the Memory Compare page.

If You Can't Enable Memory Debugging...

• If you're using AIX, you need to read Chapter 4 of the "Debugging Memory Problems Using TotalView' book, which is located at http://www.totalviewtech.com/Documentation.
• If you're running a program than spawns processes or threads, the problem may be that your environment isn't sending environment variables to the thread or process. If this happens, you'll need to explicitly add libraries that we provide. See Chapter 4 of the memory book for more information.