Warning, /PerfTools/MaxMemoryPreload/README.md is written in an unsupported language. File is not indexed.
0001 # PerfTools/MaxMemoryPreload Description
0002
0003 ## Introduction
0004
0005 This package generated a library that is meant to be LD_PRELOADed along with libPrefToolsAllocMonitorPreload.so which
0006 uses `cms::perftools::AllocMonitorRegistry` to register a monitor before an application begins. When the application
0007 ends the monitor reports statistics about the allocations and deallocations.
0008
0009 ## Usage
0010
0011 To use the package, one must issue the following LD_PRELOAD command before running the application (bash version
0012 shown below)
0013 ```
0014 LD_PRELOAD="libPerfToolsAllocMonitorPreload.so libPerfToolsMaxMemoryPreload.so"
0015 ```
0016
0017 the order is important.
0018
0019 ### Pausing the monitoring
0020
0021 It is possible to temporarily pause the monitoring by instrumenting the target application by definining the following functions
0022 ```cpp
0023 // in some header,
0024 void pauseMaxMemoryPreload();
0025 void unpauseMaxMemoryPreload();
0026
0027 // in an implementation source file
0028 void pauseMaxMemoryPreload() {
0029 }
0030 void unpauseMaxMemoryPreload() {
0031 }
0032 ```
0033 and then using these in code
0034 ```cpp
0035 ...
0036 pauseMaxMemoryPreload();
0037 // code that should be excluded from the monitoring
0038 unpauseMaxMemoryPreload();
0039 ...
0040 ```
0041
0042 The trick is that by default these functions are defined in the application, and the functions do nothing. The `libPerfToolsMaxMemoryPreload.so` provides also the same functions that actually pause the data collection, and the LD_PRELOADing makes the application to call the functions within `libPerfToolsMaxMemoryPreload.so`.
0043
0044 It is recommended to not pause the monitoring within a multithreaded section, because that could result in unexpected results, because the pausing setting is global.
0045
0046 ## Reporting
0047 When the application ends, the monitor will report the following to standard error:
0048
0049 - Total amount of bytes requested by all allocation calls during the job. Note that actual _used_ allocation can be greater than requested as the allocator may require additional memory be assigned.
0050 - The maximum amount of _used_ allocated memory that was in use at one time.
0051 - The amount of _used_ memory allocated during the job that has yet to be reclaimed by calling deallocation.
0052 - Number of calls made to allocation functions.
0053 - Number of calls made to deallocation functions.
0054
0055 This service is multi-thread safe. Note that when run multi-threaded the maximum reported value will vary from job to job.
0056
0057 If a job forks processes, the forked processes will also report the above information.
