IMPORTANT !! Great Circle no longer useable under linux

Using Great Circle to Find Memory Leaks

• Everyone working on BaBar software may use Great Circle.
• We may use Great Circle for BaBar work only.
• We may use Great Circle only on BaBar Solaris and Linux machines at SLAC.

Getting Started at SLAC

• Log onto tersk (or any other solaris machine running SunOS58) or noric (or any other BaBar linux machine). Great Circle has only been tested on these BaBar machines.



• Create a release directory and build your executable in the usual way. Note that if you want to make maximum use of Great Circle's diagnostic tools you should create your executable with the "-noOptimize-Debug" option.



• Set Great Circle environment variables
  
  
  • The location of the Great Circle license must be provided prior to Great Circle usage.
    
    Under solaris

    setenv GS_LICENSE_FILE
    
         $BFROOT/package/Geodesic/gc7016/sun4x_58/greatcircle/vw6/license/gslicense.txt
    

    Under linux

    setenv GS_LICENSE_FILE
    
         $BFROOT/package/Geodesic/gc7016/i386_linux24/greatcircle/gnu/license/gslicense.txt
    

  • The maximum size of the Great Circle monitor file defaults to 40 MB. Many BaBar executables will produce significantly larger monitor files. As of September 2003 a 500 event linux Elf job will create a Great Circle monitor file almost 200 MB in size. In order to accomodate such large files the maximum monitor file size, in megabytes, must be set appropriately. However, care must be taken here. Great Circle will "map" an area of memory equal to GS_MAX_MONFILESIZE at start up. Therefore, if GS_MAX_MONFILESIZE is set too large there is a possibility that the job will run out of memory. Perhaps the best way to handle this situation is to set GS_MAX_MONFILESIZE to 500 initially, see what the actual size of the monitor file is, then reset GS_MAX_MONFILESIZE to 50MB larger. For example,

    setenv GS_MAX_MONFILESIZE 500
    

  • By default Great Circle writes monitor files with a name of the type gc27488.mon to /tmp/. Files in /tmp/ typically have a very short lifetime. If you have access to enough disk space it may be preferable to store your monitor file elsewhere. In order to achieve this set the GS_MONDIR variable. For example,

    setenv GS_MONDIR $BFROOT/work/c/cldavis
    

  • Great Circle also produces a log file which is also written to /tmp/. It may also be preferable to have this file written elsewhere.

    setenv GS_LOG_FILE_PATH $BFROOT/work/c/cldavis
    

  • As of April 2003 there have been some problems with Great Circle performing excessive writing to its log file ultimately causing the job to crash. In order prevent this Geodesic suggest we set the following GC environment variable

    setenv GS_MEM_FREED_BEFORE_NEXT_FOOTPRINT_REDUCE 1000000000
    

• Running your program.
  
  The simplest way to enable Great Circle is to use the "injection" facility. Your program is executed via the Great Circle injector as follows;
  
  Under solaris

  $BFROOT/package/Geodesic/gc7016/sun4x_58/greatcircle/vw6/bin/gsinject
  
                                   -t -d -n -v "your executable and arguments"
  

  Under linux
  

  $BFROOT/package/Geodesic/gc7016/i386_linux24/greatcircle/gnu/bin/gsinject
  
                                  -t -d -n -v "your executable and arguments"
  

  where "your executable and arguments" should be entered exactly as in a non Great Circle run, without double quotes. For example, under solaris, to run ElfUserXtcApp, from the workdir directory enter

  $BFROOT/package/Geodesic/gc7016/sun4x_58/greatcircle/vw6/bin/gsinject
  
  -t -d -n -v ./bin/$BFARCH/ElfUserXtcApp -n 5 -f xtcfile ../Elf/ElfProduction.tcl
  

• Prior to running your program, while you are running your program, or after you have run your program, you can monitor leaks, using your web browser. You will need a frames- and javascript- capable browser to use Great Circle's web-based monitoring system. Great Circle supports the use of Netscape Navigator 4.74 and 5.0 , and Microsoft Internet Explorer 4.01 + SP2, 5.0 and 5.5. The monitoring facility is enabled by activating the gcmonitor program. To start gcmonitor, under solaris go to the directory
  $BFROOT/package/Geodesic/gc7016/sun4x_58/greatcircle/vw6/bin/
  or under linux go to the directory
  $BFROOT/package/Geodesic/gc7016/i386_linux24/greatcircle/gnu/bin/
  and type

  ./gcmonitor &
  

  If gcmonitor is already running on the machine on which your executable is running it need not be restarted. If gcmonitor is running, but your browser gets a message that it cannot see any files, the account running gcmonitor probably lost the token it had when the program was launched. If you were that user, kill gcmonitor and start it again. If you were not that user, start gcmonitor again with an alternate port number.
  From the Great Circle directory above type

  ./gcmonitor -p 50566 & 
  

  In this example, 50566 is the alternate port number.



• Examining the monitor file
  
  
  • To monitor leaks, and general memory usage, point your browser to port 50565 (or the alternate port number) on whichever machine is executing your program. For example, if your code is running on (or ran on) tersk06, point your browser at
    
    http://tersk06.slac.stanford.edu:50565
    
    
  • The first page displayed is the 'Quick Start' screen. From the drop-down menu choose the 'Select Program' screen. All GC monitor files found in /tmp/ will be displayed.
  
  
  
  • If you set the GC variable GS_MONDIR you should enter the location of this directory instead of /tmp/ and click the 'refresh' button. The name of the program you ran should now appear in the 'Program Name' column.
  
  
  
  • Clicking on the program name should take you to the 'Executive Summary' screen, where the total memory and objects leaked is displayed together with other memory management statistics.
  
  
  
  • In order to view a detailed description of memory leaks for your job select 'Leaks and Allocations'. By default the ten largest leaks are displayed. If you wish to see more enter the number in the box provided and select 'refresh'.
  
  
  
  • The report tells you how much memory has been leaked by a chain of calls including the number of objects allocated and leaked and the number of bytes allocated and leaked. The chain of function calls includes the source code file names, line numbers, and full method names.
  
  
  
  • A sample report may be found here. Note that this copy is missing some javascript instructions, as is true for all images saved from a browser.