Table of Contents

Introducing Inuse
Use and abuse of dynamic memory
What does Inuse do?
Inuse by Example
Running the Inuse user interface
Compiling and linking for Inuse
Enabling runtime activity display
Running the application
The Inuse display
Is there a bug in the slowleak program?

Introducing Inuse

One of the most important features of modern computing languages is their ability to dynamically allocate memory blocks. This freedom allows algorithms to be created in much more flexible ways than is possible with static memory allocation schemes. However, the freedom to customize memory use so easily can introduce problems of its own, such as

• How much memory can be allocated? Is there an "infinite" amount of memory available?
  
• Is the algorithm's performance affected by the way it uses memory?
  
• Is the program using memory correctly, or is it allocating too much for its needs?
  
• Is the program releasing all the blocks it no longer uses?
  

These questions can usually be answered by adding a lot of extra code to your application to print out information about the memory blocks that get allocated and freed, but the process is at best tedious, and at worst not very informative.

Inuse was designed to automate this process and to present the data in an intuitive, animated graphical format that makes the answers to questions like those above easy to understand. Inuse can be used independently of the runtime checking performed by Insure++ - all you need to do is relink your application.

Use and abuse of dynamic memory

Many modern algorithms make heavy use of dynamic memory, but few take any great precautions to insure that they achieve the best possible use of the memory system. As a result, many applications can benefit from streamlining their memory usage or modifying the order of their allocation requests to reduce the fragmentation that takes place when memory is allocated and freed.

This is particularly important in applications which are nearing the limits of the available physical memory of their hosts. Once a program is using more memory than is physically available, it begins to "swap" to disk - a process that can be extremely slow. Unfortunately, this starts not when the amount of memory you have allocated exceeds the memory size, but when the amount of memory you have allocated plus the amount of overhead and waste (due to alignment requirements) exceeds the memory size. Because of this, it is very important to keep the amount of wasted memory as small as possible.

Many algorithms also contain subtle "memory leaks" in which an ever larger amount of memory is consumed as the program runs, until it finally exhausts the resources of its host and crashes, sometimes days or even weeks after starting. Some of these errors can be caught automatically by Insure++ (See "Memory leaks" in the Insure++ User's Guide), while others can only be detected by continually monitoring the memory use of the application.

What does Inuse do?

Inuse is a graphical tool designed to help in these areas by displaying and animating, in real time, the memory allocations performed by your application.

By watching your program allocate and free dynamic memory blocks, you gain a better understanding of the memory usage patterns of your algorithms and also an idea of how to optimize their behavior.

Inuse allows you to

• Look for memory leaks.
• See how much memory your application uses in response to particular user events.
• Check on the overall memory usage of your application to see if it matches your expectations.
• Look for memory fragmentation to see if different allocation strategies might improve performance.

Inuse by Example

This section is intended to show how Inuse works by stepping through a simple example. The following section, "Using Inuse", documents Inuse's features.

Running the Inuse user interface

The Inuse graphical user interface (GUI) does nothing but wait for programs to start and connect to it, at which point it can display their memory activity. When these programs terminate, the Inuse windows remain active until you choose to exit it. This allows you to analyze the data gathered during a program's run once the program has completed execution.

If you exit Inuse while the program is still running, that program will continue running as usual but will stop sending memory activity data. You will have to start the inuse process again before memory activity can be displayed.

To run the example shown in this section, execute the commands

	cp /usr/local/insure/examples/c/slowleak* .
	inuse

The first of these commands copies a set of example files to your local working directory, while the second starts Inuse. Normally, you will only have to execute the inuse command once. The inuse process will remain running in the background, accepting display requests from any application that you choose to run.

Compiling and linking for Inuse

To use Inuse, you need to link your executable program with the insure command. Compile the objects and libraries that make up your application with your regular compiler and link them with Insure++ to create a new executable.

The insure command replaces the insight command used in previous versions of Inuse.

Compile and link the sample program with the insure command:

	cc -c slowleak.c
	insure -o slowleak slowleak.o

If you are using a compiler other than cc, you can tell Insure++ to use the correct compiler during the link step by adding a line such as insure++.compiler gcc to a .psrc file.

The first command compiles the source file into an object module, while the second links with the special Inuse dynamic memory library

Inuse is already available to your program if you are compiling your program with Insure++ to debug your code. With earlier versions, if you compiled with Insure++, Inuse would also display information about the Insure++ runtime as it performs error detection. This is no longer the case, because Insure++ now uses two separate heaps for the program. Nevertheless, we still recommend following the method described above.

Enabling runtime activity display

Now that your program is linked with the appropriate libraries, you will need to enable the runtime memory activity display. To do this, you must add the following option to your .psrc file.

	insure++.inuse on

Running the application

Once you have enabled the runtime display, you can run your application just as you would normally. To run the example application, slowleak, type the command

	slowleak

The Inuse display

When you start the example application, it will connect to Inuse. The Inuse display shows which applications are currently linked to the GUI. From this screen, you can open any of Inuse's visual reports.

For a complete description of the Inuse display, see "The Inuse GUI".

If no connection appears, consult the Inuse section of the FAQ (Frequently Asked Questions) shipped with your distribution (FAQ.txt) or the up-to-date copies on our web server.

Is there a bug in the slowleak program?

Clicking on the Hist button on the Inuse display will open up the Heap History window.

Watch the window for a few moments as the slowleak program continues to run. The window should soon appear similar to the one shown below in Figure 1.

Figure 1. Heap History for the slowleak application

Figure 1 clearly shows that the program is continuously allocating more and more memory - the classic symptom of a memory leak. This type of pattern in an Inuse report is important to watch for in your own applications, since it probably means that something is wrong.

To find the problem, you can either take a look at the source code and attempt to figure it out yourself, or simply compile and run it with Insure++ using the following commands

	insure -g -o slowleak slowleak.c
	slowleak

(For a discussion of memory leaks and their detection using Insure++, see "Memory leaks" in the Insure++ User's Guide.)

To see the difference in Inuse's output for correct and incorrect programs, you can either fix the problem in the slowleak example or copy, compile, and link the corrected version, noleak, with the following commands

	cp /usr/local/insure/examples/c/noleak.c .
	cc -c noleak.c
	insure -o noleak noleak.o
	noleak

Introduction

Running Inuse

Inuse TOC