MemDiagnostics¶
Usage
use MemDiagnostics;
or
import MemDiagnostics;
Warning
The ‘MemDiagnostics’ module is unstable
Provides routines for reasoning about memory usage.
The MemDiagnostics
module provides procedures which report information
about memory usage. With one exception, to use these procedures you
must enable memory tracking. Do this by setting one or more of the
config vars below, using appropriate --configVarName=value
or
-sconfigVarName=value
command line options when you run the
program. If memory tracking is not enabled, calling any procedure
described here, other than locale.physicalMemory
, will cause
the program to halt with an error message.
memTrack
: bool:Enable memory tracking. This causes memory allocations and deallocations to be internally tracked, to support logging them on the fly and/or producing any of several kinds of memory-related reports, described below.
memLeaks
: bool:Enable memory tracking and produce detailed information about leaked memory by invoking
printMemAllocs
implicitly when the program terminates normally. If there are no leaks, nothing is printed.memLeaksByType
: bool:Enable memory tracking and produce summary information about leaked memory by invoking
printMemAllocsByType
implicitly when the program terminates normally. If there are no leaks, nothing is printed.memLeaksLog
: string:Enable memory tracking and append a report to the named file when the program terminates normally. The report contains the compilation command used to build the program, the execution command used to run it, the summary allocation statistics produced by
printMemAllocStats
, and the summary information about leaked memory produced byprintMemAllocsByType
.memStats
: bool:Enable memory tracking and produce summary memory statistics by invoking
printMemAllocStats
implicitly at normal program termination. Note that for a multi-locale run, each top-level locale reports its own memory statistics and these reports may appear in any order in the program output (and possibly even interleaved, though we have gone to some effort to avoid that). These statistics can be put in order by sorting the output lines that begin with the stringmemStats:
.memMax
: uint:If the value is greater than 0 (zero), enable memory tracking and use the value as a limit on the number of bytes of memory that can be allocated per top-level (network-connected) locale. If during execution the amount of allocated memory exceeds this limit on any locale, halt the program with a message saying so.
The following two config variables do not enable memory tracking; they only modify how it is done.
memThreshold
: uint:If this is set to a value greater than 0 (zero), only allocation requests larger than this are tracked and/or reported.
memLog
: string:Memory reporting is written to this file. By default it is the
stdout
associated with the process (not the Chapel channel with the same name). Setting this config variable to a file path causes the reporting to be written to that named file instead. In multilocale executions each top-level locale produces output to its own file, with a dot (‘.’) and the locale ID appended to this path.
- enum MemUnits { Bytes, KB, MB, GB }¶
The amount of memory returned by
locale.physicalMemory
can be expressed either as individual bytes or as chunks of 2**10, 2**20, or 2**30 bytes.- enum constant Bytes¶
- enum constant KB¶
- enum constant MB¶
- enum constant GB¶
- proc locale.physicalMemory(unit: MemUnits = MemUnits.Bytes, type retType = int(64))¶
How much physical memory is present on this locale?
This quantity does not take into account things like virtual memory support which might allow for allocating a larger amount, or system or user limits which might prevent allocating so much.
Note
Unlike the other procedures in the
MemDiagnostics
module, this one does not require memory tracking to be enabled.- Arguments
unit :
MemUnits
– Units in which the returned value is to be expressed.retType : type – Type of the returned value. Defaults to int(64).
- Returns
Size of physical memory on the locale where the call is made.
- Return type
retType
- proc memoryUsed()¶
How much memory is this program currently using on this locale?
This is the amount of memory known to be currently allocated on the calling top-level (network-connected) locale by the program, through Chapel mechanisms. It does not include memory allocated directly from the system, outside of Chapel mechanisms, such as allocations made by code written in other languages and linked into the program.
- Returns
Amount of allocated memory, in bytes.
- Return type
uint(64)
- proc printMemAllocs(thresh = 0)¶
Print detailed information about allocated memory to
memLog
. The report contains a section for each top-level locale, containing a table of entries for the allocations made on that locale. Each entry shows the source file and line at which the allocation was requested, the address and size (bytes) of the allocated space, and a description of the type of information the requesting code said it was going to store there.- Arguments
thresh : int – Do not print entries whose size is less than this. Defaults to 0.
- proc printMemAllocsByType()¶
Print summary information about allocated memory to
memLog
. The report contains a section for each top-level locale, containing a table of entries, one for each different allocation type for which at least one allocation exists on that locale. The entries show the type (that is, the string the code requesting the allocation used to describe what it would store there) and the total number of allocations and bytes allocated for that type.
- proc printMemAllocStats()¶
Print summary memory statistics to
memLog
. The report contains a section for each top-level locale showing the number of bytes of memory currently allocated, the maximum number allocated at any point during execution (the high-water mark), and the sum of the sizes of all allocation and deallocation requests.
- proc startVerboseMem()¶
Start on-the-fly reporting of memory allocations and deallocations done on any locale. Continue reporting until
stopVerboseMem
is called.The reporting output consists of a single line describing each memory allocation or deallocation, written to
memLog
.
- proc stopVerboseMem()¶
Stop on-the-fly reporting of memory allocations and deallocations done on any locale.
- proc startVerboseMemHere()¶
Start on-the-fly reporting of memory allocations and deallocations done on this locale. Continue reporting until
stopVerboseMemHere
is called.The reporting output consists of a single line describing each memory allocation or deallocation, written to
memLog
.
- proc stopVerboseMemHere()¶
Stop on-the-fly reporting of memory allocations and deallocations done on this locale.