Ways to Start MemoryScape
MemoryScape can debug programs that run in many different computing environments and which use many different parallel processing modes and systems. This section looks at few of the ways you can start MemoryScape.
In most cases, the command for starting MemoryScape looks like this:
memscape [ executable [ corefile ] ] [ options ]
where executable is the name of the executable file and corefile is the name of the core file that you want to examine.
Your environment may require you to start MemoryScape in another way. For example, if you are debugging an MPI program, you may need to invoke MemoryScape on
mpirun. For an example, see
"Debugging an MPI Program" and several other discussions in this chapter.
The following examples show different ways of starting MemoryScape:
Starting MemoryScape
memscape
Starts MemoryScape without loading a program or core file. You now select Add new program or Add parallel program to load a program.
Starting MemoryScape and Naming a program
memscape executable
Starts MemoryScape and loads the executable program.
Starting MemoryScape from TotalView
From TotalView, select the Tools menu item from the Root Window or the Debug menu item from the Process Window. Select the Open MemoryScape option.At launch, MemoryScape tries to interpret the state of TotalView and opens to the appropriate page, most likely the Home page. You can select the Memory Debugging Options page to turn memory debugging on or off, but if your program is running, you must kill it before the settings take effect.
Using core files
memscape executable corefile
Starts MemoryScape and loads the executable program and the corefile core file.
Passing arguments to the program
memscape executable -a args
Starts MemoryScape and passes all the arguments following the -a option to the executable program. When you use the -a option, you must enter it as the last MemoryScape option on the command line.
If you don’t use the -a option and you want to add arguments after MemoryScape loads your program, right click on the executable and select Properties.
Debugging a program that runs on another computer
memscape executable -remote hostname_or_address[:port]
Starts MemoryScape on your local host and the TotalView Debugger Server (tvdsvr) on a remote host. After MemoryScape begins executing, it loads the program specified by executable for remote debugging. You can specify a host name or a TCP/IP address. If you need to, you can also enter the TCP/IP port number.
If MemoryScape fails to automatically load a remote executable, you may need to disable
autolaunching for this connection and manually start the Debugger Server (
tvdsvr). (
Autolaunching is the process of automatically launching
tvdsvr processes.) You can disable autolaunching by adding the
hostname:portnumber suffix to the name you type in the
Host field of the
Add new program or
Add parallel program screens. As always, the
portnumber is the TCP/IP port number on which our server is communicating with MemoryScape. For more information on how to disable autolaunching, see “
Starting the TotalView Server Manually” in the
TotalView for HPC User Guide.
Debugging an MPI Program
memscape executable
(method 1) In many cases, you start an MPI program in much the same way as you would any other program, but you need to set its properties. One way is to select the executable’s name from within MemoryScape, right-click for the context menu, and choose Properties. In the displayed dialog box, select the MPI version, in addition to other options.
mpirun -np count -tv executable
(method 2) The MPI mpirun command starts the MemoryScape pointed to by the TOTALVIEW environment variable. MemoryScape then starts your program. This program will run using count processes.
Attaching to Programs
If a program you’re testing is using too much memory, you can attach to it while it is running. You can attach to single and multiprocess programs, and these programs can be running remotely.
NOTE >> MemoryScape requires that all programs use the MemoryScape agent. In most cases, it does this behind the scenes before the program begins executing. However, it cannot do this for an already executing program or for a core file. So, just attaching to an already running program will not provide the information you need as the agent won’t be used. In some cases, you may want to add it by starting the program using the shell env command. However, the best alternative is to link the MemoryScape agent. For details, see "Linking Your Application with the Agent". |
To attach to a process, select the Attach to running program item from the Home | Add Program page.
NOTE >> When you exit from MemoryScape, it kills all programs and processes that it started. However, programs and processes that were executing before you brought them under MemoryScape’s control continue to execute. |
If you want MemoryScape to automatically attach to programs that use fork() and execve(), you must use the MemoryScape dbfork library. However, programs that you manually attach to need not be linked with this library.