Skip to main content

%SYSTEM.Memory

The %SYSTEM.Memory class provides mechanisms to allow a process to examine memory metrics of either the calling process or a different process.

There are two different syntaxes that can be used to call the class methods in this package: one uses the usual ##class syntax and the other uses $system. Here are two examples of calling ProcessStats to find information about your process.

  set stats = $system.Memory.ProcessStats()
  set stats = ##class(%SYSTEM.Memory).ProcessStats()
  

Method Inventory

Methods

classmethod Clean(cleancache As %Integer = 0, defragment As %Integer = 0) as %String
The Clean(cleancache, defragment) class method will perform a clean up of the application's memory.

Parameters

cleancache -- InterSystems IRIS maintains some memory caches internal to the process which provide a performance improvement. By passing this value as a non-zero integer, all these memory caches will be removed, removing memory caches and freeing unused memory.

defragment -- By passing a non-zero integer, the process will go through a memory defragmentation procedure. This involves writing all local arrays to temporary memory, deleting the local arrays, and then restoring the arrays from the temporary memory. Any fragmentation caused by large local arrays will be removed.

Return value -- a string containing two integers separated by a comma. The first describes how much memory was freed back to the application if the 'cleancache' parameter was non-zero. The second value gives the improvement factor in memory fragmentation caused by the defragmentation, assuming the 'defragmentation' parameter was non-zero.

Note: You can examine value 11 of the $LIST data returned from the ProcessStats() class method to determine the fragmentation index of your memory.

classmethod ProcessStats(jobID=0) as %String
The ProcessStats(jobID ) class method will return various metrics defining memory usage of either the calling process or a different process.

Parameters

jobID -- Optional: The Process ID (PID) of the job to query. A value of 0 (the default) means the caller's process will be queried. Any other value specifies the job PID of the process you want to query.

Return value -- a string containing a list of values in $LIST format. If an error occurs, then a null string will be returned and %objlasterror set to the error value. The position and description of each $LIST value is ...

1 - Heap space allocated via malloc(). This is memory from the OS heap (data segment) and typically allocated using the malloc() function call. Not available on Solaris, VMS or MacOSX
2 - Partition space allocated. This is taken from the memory maps we use to allocate partition space and includes all the overheads, unused space and space on the free space chain.
3 - Internal stack allocated. Inside the InterSystems IRIS kernel are 3 stacks, the string stack, the frame stack and the error stack. This value is the accumulation of those 3 values. Note that because we over-allocate, and use on-demand paging, it doesn't mean that we actually use this many bytes of real memory - other values returned from this function will show that.
4 - Total allocation of additional memory map collections.
5 - Private memory overhead of shared memory. Referencing shared memory has an overhead in page table entries (PTEs) and this is an estimate of how much memory will be used by the process should the process reference all of the shared memory. Windows only.
6 - Size of the 'C' stack. During program execution, the 'C' stack will grow and shrink as functions are called and returned. This value is the maximum size of the stack used so far, i.e. how much memory it is consuming. Only available on Linux, Solaris and AIX platforms.
7 - Partition space in use. The amount of partition space actually in use by the application. It does not include any returned memory that is on a free space chain, or other overheads.
8 - Partition space maximum. Equivalent to the $ZSTORAGE special variable.
9 - Partition free space size. This is the value of all the free space in the free space chains.
10 - Partition space peak usage. Accurate to the nearest 64k, this is the maximum partition space that has been used.
11 - Partition space fragmentation index. This is a logarithmic value describing how fragmented your partition space is. For small partition spaces it will return 0. A value of 200 or lower is normal. A value of 3000 or higher means it is quite fragmented and you might want to use the $system.Memory.Clean() method. Any value in between means it is fragmented, but nothing to worry about. These values are all subjective and it is really up to individual scrutiny.
12 - Long string size. This is the total memory used for long strings (i.e. strings of 32k characters or more). These strings are allocated using malloc() and are not part of your partition space calculations or limits. Normally, malloc() will allocate these strings from heap space. Sometimes this is not the case, for example Linux will allocate all strings above 256k bytes using an anonymous memory map.
13 - Shared memory total. The total amount of shared memory allocated. This is the same as the addition of values 14, 15, 16 and 17.
14 - Shared memory globals. The amount of shared memory allocated for global buffers.
15 - Shared memory routines. The amount of shared memory allocated for routine buffers.
16 - Shared memory heap. Previously known as GM heap or gmheap. The amount of memory allocated for Shared memory heap.
17 - Shared memory other. Non-specific shared memory use. For example the hash tables for globals and locks, user process space, ECP daemons.
18 - Shared memory page size. This allows you to determine the page size used for shared memory. If this value is 4k or 8k, then you have allocated normal pages. If this value is 1M or above, you have allocated large/huge pages. On systems with large shared memory sizes and large process populations, it is important that large/huge pages are used.
19 - String stack total allocated. This is the first of the 3 internal stacks used by InterSystems IRIS and is used as a temporary area during program execution where strings and other temporary values can be accumulated. This value gives the initially allocated space and is at a large size (around 7M on a 8-bit install and 14M on a 16-bit install). This does not mean InterSystems IRIS is using 7/14M of real memory as it is just reserved memory addresses -- real memory is allocated by the OS on a page-demand basis.
20 - String stack committed. While the string stack is allocated at 7/14M, as described above, the OS will only allocate real physical memory on a page-demand basis i.e. the memory becomes committed. This value shows how much committed memory is in use by the string stack. Not available on HPUX or VMS platforms. See note below on committed memory values.
21 - String stack source. This describes how we allocated the memory. The values are "MMAP" meaning an anonymous memory map, "HEAP" means heap space allocation i.e. through malloc(), "STACK" means it is part of the 'C' stack or "UNKNOWN" meaning we can't accurately determine it.
22 - Frame stack total allocated. This is the second of the 3 internal stacks used by InterSystems IRIS and is used as a program stack containing references to while {} loops, for {} loops, routine calls and so on. This value gives the initially allocated space and is about 112k at the current build. This does not mean InterSystems IRIS is using 112k of real memory as it is just reserved memory addresses -- real memory is allocated by the OS on a page-demand basis.
23 - Frame stack committed. The same comments apply to this as for the String stack committed, value 20. See note below on committed memory values.
24 - Frame stack source. The same comments apply to this as for the String stack source, value 21.
25 - Error stack total allocated. This is the third of the 3 internal stacks used by InterSystems IRIS and is used during error handling. This value gives the initially allocated space and is about 156k at the current build. This does not mean InterSystems IRIS is using 156k of real memory as it is just reserved memory addresses -- real memory is allocated by the OS on a page-demand basis.
26 - Error stack committed. The same comments apply to this as for the String stack committed, value 20. See note below on committed memory values.
27 - Error stack source. The same comments apply to this as for the String stack source, value 21.
28 - Number of errors thrown during the lifetime of this process.
29 - The reason for the last error. 0 means no error has ever been thrown. 1 means you exhausted the partition space available with the $ZSTORAGE special variable, or to put this another way, the value of the $STORAGE special variable went to 0 (or lower), 2 means your $STORAGE value went below -1048576, 3 means the OS refused to give any more memory to your process.
30 - The size of the partition space block being allocated that caused the last error. This is a power-of-2 value, so 0 means 4 bytes, 1 means 8 bytes, 2 means 16 bytes and so on.
31 - The scope value that was being used when the last error was thrown.
32 - Number of cleanup attempts. Before InterSystems IRIS throws a error, it will attempt to free cache space that can safely be released, however as this cached memory is removed there will possibly be a performance hit later. If the cleanup is successful and allows the memory allocation to succeed without throwing a error, then this value is incremented.
33 - Number of array defragmentations. When partition space gets low, but before throwing a error, we will check the fragmentation of memory. If the memory is badly fragmented, this is usually caused by local arrays and so we force an array defragmentation and increment this counter.
Note about committed memory Some of the above values are committed memory values. This is the amount actually used by the operating system and will be a multiple of the page size (usually 4k and sometimes 8k, depending upon OS). For example, if you allocate 18k of memory, you could see the value of "allocated" at 18k but "committed" at 20k, once the rounding caused by page size is taken into account.

classmethod VariableStats(jobID=0) as %ListOfDataTypes
The VariableStats(jobID) class method will return details about all the variables in use by either the calling process or a different process.

Parameters

jobID -- Optional: The Process ID (PID) of the job to query. A value of 0 (the default) means the caller's process will be queried. Any other value specifies the job PID of the process you want to query.

Return value -- An object of type %ListOfDataTypes which contains an array of strings. Each string contains a number of values in $LIST format that define a single variable and any associated array.

In the example below, we display the size of all known variables for process id 12345.

  set stats = $system.Memory.VariableStats(12345)
  if (stats = "") {
      write "Unable to find any statistics, error "_%objlasterror,!
  } else {
      for varnext = 1:1:stats.Count() {
  	set vardetails = stats.Data(varnext)            // Get all details for a single variable
  	set varname = $lg(vardetails,1)                 // Name of variable
  	set varmemused = $lg(vardetails,5)              // Total memory used by this variable
  	write "The memory used for variable '",varname,"' is ",$fnumber(varmemused,",")," bytes.",!
      }
  }
  

The position and description of each value within a single $LIST element is ...

1 - The name of the variable
2 - The procedure level. When a single named array is specified, this value will be -1. When no variable name is specified, and a search of all variables in all procedure levels takes place, this is the procedure level the variable was found on. The top procedure is level 0, parent levels are 1,2,3...This allows you to differentiate between private variables with the same name in different procedures
3 - The memory scope of the variable
4 - Array Type. A value of 1 is the old style string array, 2 is the small integer array, 3 is the new style string array. This value is true only for the root array -- sub-arrays might be different types. If there is no array associated with a variable, then this value is -1
5 - Total size of application memory in use by this array. This includes the array overheads, objects, the descriptors and the actual data. This is the application memory as calculated by the $STORAGE variable and limited by the $ZSTORAGE variable and does not include long strings - these are taken from a different heap space and the memory used for these is given in value 6
6 - Total size of memory used by long strings (a long string is when the data exceeds 32k characters). This memory uses a different heap space to normal application memory and is not included in the $STORAGE value.
7 - Object reference adjustments. An object might have a number of variables reference it, and yet only one copy exists in memory. This value is an estimate of how much memory to subtract from value 5 to compensate for an object being counted more than once.
8 - Long string adjustments. A long string might have a number of variables reference it, and yet only one copy exists in memory. This value is an estimate of how much memory to subtract from value 6 to compensate for a long string being counted more than once.
9 - Number of long strings found in the variable
10 - Number of objects found in the variable.
11 - Number of subscripts found in the variable.
12 - Number of descriptors found in the variable
13 - Number of arrays. including sub-arrays, found in the variable
14 - Number of values found in the variable
15 - Maximum depth of nested arrays.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab