Linking Your Application with the Agent

MemoryScape puts its heap agent between your program and its heap library. This allows the agent to intercept the calls that your program makes to this library. After it intercepts the call, it checks the call for errors and then sends it on to the library so that it can be processed. The MemoryScape agent does not replace standard memory functions; it just monitors what they do. For more information, see “Behind the Scenes”.

In most cases, MemoryScape arranges for the heap agent to be loaded automatically when it starts your program. However, in a few cases special steps must be taken to make sure the agent is loaded. One example is when you are starting an MPI program using a launcher that does not propagate environment variables. (If you start your MPI program in MemoryScape using the Add Parallel Program page, MemoryScape propagates the information for you.) Another is when you want to start your program outside, or independently of, TotalView, and want to attach to the program later after it has started.

There are two ways you can arrange for the heap agent to be loaded:

Link the application with the agent, as described in this section.

Request that the heap agent be preloaded by setting the runtime loader's preloading environment variable. See “Using env to Insert the Agent”.

Here is some important platform-specific information:

On AIX, the malloc replacement code and heap agent application must be in directories searched by the dynamic loader. If they are not in any of the standard directories (you can check with your system administrator), you can set LIBPATH to search these directories when you run the program. Another option is to add the directories to the program's list of search directories when you link the program. To do this, use the -L option as described in the table below. If you are in doubt about the directories being searched, you can obtain a list of the searched directories with dump -Hv <program-name>.

For additional requirements with AIX, see “Installing tvheap_mr.a on AIX”.

On Blue Gene/L and Cray computers, a special heap agent must be used. This needs to be statically linked with your program, as shown in the table below.

Blue Gene/P supports dynamic linking. If you start your job under TotalView using a launching program such as mpirun that honors the MPIRUN_ENV environment variable, you don't need to take any special steps to prepare your application for memory debugging. In this case, TotalView arranges for the heap agent to be loaded with your program. If, however, you are using a launching program that does not honor MPIRUN_ENV, or you are starting the job outside of TotalView and want to attach to it later, you must link your application with the heap agent as described in the table below.

On Apple Mac OSX, you cannot link the agent into your program.

 

The following table lists additional command-line linker options that you must use when you link your program:

 

Platform	Compiler	Binary Interface	Additional linker options
Cray CNL	–	64	–Lpath –ltvheap_cnl_static
Cray XT3	–	64	–Lpath–lgmalloc –ltvheap_xt3
IBM Blue Gene/L	–	32	–Lpath –ltvheap_bluegene
IBM Blue Gene/P	–	32	–Lpath –ltvheap –Wl,–rpath,path
IBM RS/6000 (all)	IBM/GCC	32/64	–Lpath_mr –Lpath
AIX 5	IBM/GCC	32	–Lpath_mr –Lpath path/aix_malloctype.o
		64	–Lpath_mr –Lpath path/aix_malloctype64_5.o
Linux x86	GCC/Intel/PGI	32	–Lpath –ltvheap –Wl,–rpath,path
Linux x86-64	GCC/Intel/PGI	32	–Lpath –ltvheap –Wl,–rpath,path
		64	–Lpath –ltvheap_64 –Wl,–rpath,path
Linux IA64	GCC/Intel	64	–Lpath –ltvheap –Wl,–rpath,path
Linux Power	GCC/Intel/PGI	32	–Lpath –ltvheap –Wl,–rpath,path
		64	–Lpath –ltvheap_64 –Wl,–rpath,path
Sun	Sun/Apogee	32	–Lpath –ltvheap –R path
	Sun	64	–Lpath –ltvheap_64 –R path
	GCC	32	–Lpath –ltvheap –Wl,–R,path
		64	–Lpath –ltvheap_64 –Wl,–R,path

The following list describes the options in this table:

path

The absolute path to the agent in the MemoryScape installation hierarchy. More precisely, this directory is:

installdir/toolworks/memoryscape.version/­platform/lib

installdir

The installation base directory name.

version

The MemoryScape version number.

platform

The platform tag.

path_mr

The absolute path of the malloc replacement library. This value is determined by the person who installs the MemoryScape malloc replacement library.

 

The heap agent library path can be hard to determine. If you have access to the command line interface (CLI), you can use the following command to print out its path: puts $TV::hia_local_dir

 

Other related topics are:

Using env to Insert the Agent

Installing tvheap_mr.a on AIX