summaryrefslogtreecommitdiff
path: root/modules/CIAO/docs/Purify.html
diff options
context:
space:
mode:
Diffstat (limited to 'modules/CIAO/docs/Purify.html')
-rw-r--r--modules/CIAO/docs/Purify.html72
1 files changed, 72 insertions, 0 deletions
diff --git a/modules/CIAO/docs/Purify.html b/modules/CIAO/docs/Purify.html
new file mode 100644
index 00000000000..fff258db120
--- /dev/null
+++ b/modules/CIAO/docs/Purify.html
@@ -0,0 +1,72 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <title>Using Rational Purify with CIAO</title>
+ <!-- $Id$ -->
+ </head>
+ <body>
+ <h1>Using Rational Purify with CIAO</h1>
+ <p>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.</p>
+ <p>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 <A href="file://\\Atlantis\software\RationSuiteEnterprise-v2003-06-12">
+ \\Atlantis\software\RationSuiteEnterprise-v2003-06-12</A> &nbsp;and clicking
+ on <code>C57BPML.zip</code>. 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 <code>
+ rational.vuse.vanderbilt.edu</code>.</p>
+ <p>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 <b>PurifyPlus-&gt;Purify-&gt;Settings-&gt;DefaultSettings-&gt;PowerCheck</b>.
+ When run for the first time, Purify will instrument all libraries linked to the
+ executable. Select <b>PurifyPlus-&gt;Purify-&gt;Run</b>, and a window will pop
+ up prompting you for the executable name, command line options, and working
+ directory.</p>
+ <p>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.</p>
+ 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 <code>child.exe</code>, then it can be
+ instrumented by typing
+ <br>
+ <code>purifyw /Run=no /Replace=yes child.exe</code><br>
+ This will rename the original executable as <code>child.exe.Original</code>,
+ and the new instrumented executable will be <code>child.exe</code>. 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:
+ <ul>
+ <li>
+ 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 <code>-d 15</code> or
+ <code>-d 20</code>
+ to NodeManager's command line.
+ <li>
+ 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.
+ </li>
+ </ul>
+ <hr>
+ <address>Jeff Parsons</address>
+ <!-- hhmts start --> Last modified: Oct&nbsp;3 2005
+ <!-- hhmts end -->
+ </body>
+</html>