API Reference

API List

msMemScope provides open APIs to help users analyze memory and identify memory problems.

The analyzer is the new offline analysis module of msMemScope and is responsible for all offline analysis functions. You can import analyzer from msMemScope to implement memory leak analysis and custom inefficient memory identification.

msMemScope provides two methods for offline analysis: quick analysis APIs (recommended) and analyzer-based offline analysis.

• Quick analysis APIs

  The table below describes msMemScope's quick analysis APIs.

  Table 1 API list

  API	Description
  list_analyzers	Outputs all memory analysis types supported by msMemScope.
  get_analyzer_config	Views the parameters required for running a specific memory analysis type.
  analyze	Conducts a quick analysis. It supports memory leak analysis and custom inefficient memory identification.
  check_leaks	Supports memory leak analysis.
  check_inefficient	Identifies inefficient memory in a customized way.

• analyzer

  You can import analyzer from msMemScope for offline analysis. Table 2 analyzer API description describes the involved APIs. However, this mode is not recommended due to complex code implementation.

  The example code is as follows:

  # Import analyzer and the corresponding config for memory leak detection.
  from msmemscope.analyzer import LeaksAnalyzer, LeaksConfig
  # Declare parameters and generate config.
  leaks_config = LeaksConfig(
      input_path="user/memscope.csv", # Use the actual path for input_path.
      mstx_info="test",
      start_index=0
  )
  # Generate an analyzer instance for analysis.
  leaks_analyzer=LeaksAnalyzer()
  leaks_analyzer.analyze(leaks_config)
  
  # Import analyzer of inefficient memory analysis and the corresponding config.
  from msmemscope.analyzer import InefficientConfig, InefficientAnalyzer
  # Declare parameters and generate config.
  ineff_config = InefficientConfig(
      input_path="user/ineff.csv", # Use the actual path for input_path.
      mem_size=0,
      inefficient_type=["early_allocation","late_deallocation","temporary_idleness"],
      idle_threshold=3000
  )
  # Generate an analyzer instance for analysis.
  ineff_analyzer=InefficientAnalyzer()
  ineff_analyzer.analyze(ineff_config)
  

  Table 2 analyzer API description

  API	Description
  LeaksAnalyzer	Memory leak analyzer
  LeaksConfig	Memory leak analysis parameters
  InefficientConfig	Inefficiency memory analysis parameters
  InefficientAnalyzer	Inefficiency memory analyzer

list_analyzers

Function

This API outputs all memory analysis types supported by msMemScope and supports printing. Currently, only memory leak analysis and inefficient memory identification are supported.

Prototype

list_analyzers() -> List[str]

Parameter Description

Parameter	Input/Output	Description
List[str]	Output	String list

Returns

After the API is executed, the memory analysis types supported by msMemScope are displayed.

Example

import msmemscope
config_list = msmemscope.list_analyzers()
print(config_list)

get_analyzer_config

Function

This API views the parameters required for running a specific memory analysis type.

Prototype

get_analyzer_config(analyzer_type: str) -> Dict[str, Any]

Parameter Description

Parameter	Input/Output	Description
str	Input	A string that indicates the memory analysis type. For details, see the output result of list_analyzers, such as leaks or inefficient.
Dict[str, Any]	Output	A dictionary that contains all parameters and can be directly printed.

Returns

Dictionary of all parameters, which can be directly printed.

After the API is executed, the input parameters required for a specific memory analysis type are directly output.

Example

import msmemscope
leaks_para = msmemscope.get_analyzer_config("leaks")
print(leaks_para)
ineff_para = msmemscope.get_analyzer_config("inefficient")
print(ineff_para)

analyze

Function

This is an external analysis API provided by msMemScope. It supports memory leak analysis and custom inefficient memory identification.

• Memory leak analysis

  This API provides offline analysis on memory leaks in a specified range, supports offline analysis for the dumped .csv files generated by msMemScope, and triggers an alarm when memory leaks in the specified range are detected. Currently, this function applies only to HAL memory leak analysis.

  Before using this API, you need to mark the specified range using mstx and start the user process using msMemScope to obtain the dumped .csv file. Then, you can use the API to input the .csv file to be analyzed, instrumentation information, and start index for offline leak analysis.

• Custom inefficient memory identification

  Parameters can be customized to identify inefficient memory offline in the dumped .csv or .db file generated by msMemScope. You can flexibly set the memory block threshold, inefficient memory type, and temporary idle API interval based on the custom parameter specifications, thus accurately identifying inefficient memory in the dumped .csv or .db file.

  Note

  If the input .csv or .db file already has inefficient memory identification results, using the custom identification function will not remove them. The new identification results will be added instead. If you need to perform the custom inefficient memory identification function for multiple times, you are advised to back up the original file.

Prototype

analyze(analyzer_type: str, **kwargs):

Parameter Description

• Memory leak analysis

  leaks: see check_leaks for details.

• Custom inefficient memory identification

  inefficient: see check_inefficient for details.

Returns

N/A

After the API is executed, the analysis result is displayed.

Example

import msmemscope
msmemscope.analyze("leaks", input_path="user/memscope.csv", mstx_info="test",start_index=0)

msmemscope.analyze("inefficient",
  input_path="user/ineff.csv",mem_size=0,
  inefficient_type=["early_allocation","late_deallocation","temporary_idleness"],
  idle_threshold=3000
  )
# Use the actual path for input_path.

check_leaks

Function

This is a quick memory leak analysis API provided by msMemScope.

Prototype

check_leaks(input_path: str, mstx_info: str, start_index: int)

Parameter Description

All input parameters must be obtained based on list_analyzers and get_analyzer_config.

Parameter	Input/Output	Description
input_path	Input	Path of the .csv file collected using msMemScope. The absolute path is required.
mstx_info	Input	mstx text information used for mark instrumentation, which is used to identify the range of leak analysis.
start_index	Input	Index of mstx instrumentation for starting leak analysis.

Returns

N/A

After the API is executed, the memory leak analysis result is displayed.

Example

import msmemscope
msmemscope.check_leaks(input_path="user/memscope.csv",mstx_info="test",start_index=0)
# Use the actual path for input_path.

check_inefficient

Function

This is a quick analysis API provided by msMemScope for custom inefficient memory identification.

Prototype

check_inefficient(input_path: str, mem_size: int = 0, inefficient_type: List[str] = None, idle_threshold: int = 3000) # If no input is provided, the default value is used.

Parameter Description

All input parameters must be obtained based on list_analyzers and get_analyzer_config.

Parameter	Input/Output	Description
input_path	Input	Path of the .csv or .db file for which offline inefficient memory identification is required.
mem_size	Input	Inefficient memory threshold (unit: Bytes). Memory blocks below this threshold will not output results.
inefficient_type	Input	Inefficient memory types for determining evaluation policies. Only user-concerned types are outputted. Currently, the following types are supported: - early_allocation - late_deallocation - temporary_idleness
idle_threshold	Input	Threshold of the temporary idle inefficient memory API, which can be set as required.

Returns

N/A

After the API is executed, the analysis process is printed and displayed. The identification result is written to the original file.

Example

import msmemscope
msmemscope.check_inefficient(input_path="user/ineff.csv",mem_size=0,
     inefficient_type=["early_allocation","late_deallocation","temporary_idleness"],idle_threshold=3000
     )
# Use the actual path for input_path.