# Using Rational Purify with CIAO

This document is about using Purify with Visual Studio 7.1 to track down memory leaks and other bugs in CIAO applications. For the Linux/Unix environment, Valgrind is a better-suited tool - see Will Otte's documentation on using Valgrind with CIAO in this directory.

Purify can be run from within Visual Studio, or standalone. The executable is c:\Program Files\Rational\PurifyPlus\purifyw.exe. Typing this will bring up the same Purify window you see if you run it from within Visual Studio. You can install Purify from the web by going to \\Atlantis\software\RationSuiteEnterprise-v2003-06-12 and clicking on `C57BPML.zip`. This will install a whole bunch of Rational stuff by default, so you will probaby want to deselect everything but PurifyPlus, although Quantify is a good bottleneck-finder when you're trying to improve performance, so that might be worth installing and playing with as well. During the installation process, you'll be prompted for a mode of licensing. Select the use of a license server, and then you'll be prompted for its address. Use `rational.vuse.vanderbilt.edu`.

The option to exclude all modules in Windows directories will probably be set by default, but if you notice memory leaks reported for Windows stuff, you might want to double check this and turn it off. From the PurifyPlus menu bar item in Visual Studio, it's at PurifyPlus->Purify->Settings->DefaultSettings->PowerCheck. When run for the first time, Purify will instrument all libraries linked to the executable. Select PurifyPlus->Purify->Run, and a window will pop up prompting you for the executable name, command line options, and working directory.

Purify's output will appear in the Visual Studio text editing window. This output can be saved to the given filename. The type of error reported is indicated by a 3-letter code - the most common are UMR (Unitialized Memory Read), FMM (Freeing Mismatched Memory), and MLK (Memory Leak). Each of these can be expanded to show the call stack. The depth of the call stack can be modified in Settings if it's not deep enough. FMM messages will show both allocation and deallocation call stacks.

Quite often in CIAO, we will want to Purify a process that is spawned by another process, and therefore not directly runnable in Purify. This is fairly easy to do, but it must be done from the command line. If the name of the child process we want to instrument is `child.exe`, then it can be instrumented by typing
`purifyw /Run=no /Replace=yes child.exe`
This will rename the original executable as `child.exe.Original`, and the new instrumented executable will be `child.exe`. Now when you run the parent process under Purify, you'll see one window opened up in Visual Studio's text editor for this process, and when the child process is spawned, a second window will open. A couple of caveats to make this work smoothly:

- Instrumented executables run 2 to 5 times slower than uninstrumented ones, so any timeouts in the code should be extended accordingly. For example, if an instrumented NodeApplication is spawned by NodeManager, add `-d 15` or `-d 20` to NodeManager's command line.
- If an instrumented process is simply killed, there will probably be many spurious error messages, mostly related to ORB resources that were not cleaned up by a graceful shutdown. All processes tested with Purify should have a graceful shutdown built in to eliminate these bogus memory leak messages.

Last modified: Oct 3 2005