polyspace.test.StackProfilingResults Class

Namespace: polyspace.test

(Python) Review stack profiling results

Since R2024b

Description

This Python^® class contains stack profiling results obtained from executing C/C++ tests.

Creation

Syntax

stackUseResults = profilingResults.Stack

Description

stackUseResults = profilingResults.Stack loads coverage results:

• From a polyspace.test.ProfilingResults object profilingResults.

• To a polyspace.test.StackProfilingResults object stackUseResults.

Properties

Details — Memory usage per function

list of polyspace.test.StackProfilingDetail objects

Function memory usage metrics, stored as a polyspace.test.StackProfilingDetail object. Each object stores the memory usage metrics for one function. Polyspace Test calculates these memory usage metrics:

Metric	Description
File	Full path of file that contains the function.
Function	Name of function whose memory usage Polyspace® Test™ calculates.
Max	The maximum amount of stack memory required by a function.
Self	The amount of stack memory required by a function along an execution path. This value is reported only if you obtain stack profiling results using the polyspace-code-profiler command with the option -stack-metric-level set to standard or detailed.
Count	Number of times the function executes. This value is reported only if you obtain stack profiling results using the polyspace-code-profiler command with the option -stack-metric-level set to detailed.

See also Memory Use.

Functions — File path and function name

list of polyspace.test.ProfilingFunction objects

File path and function name for the function whose memory usage Polyspace Test calculates. The file path and function name are stored in a list of polyspace.test.ProfilingFunction objects, where each object stores the information for one function.

Examples

Print Sorted List of Function Stack Usage

This example shows how to print the list of tested C/C++ functions sorted by their maximum stack usage.

In general, you generate and manage execution profiling results by using classes from the polyspace.project and polyspace.test modules. Before starting, make sure you can import these modules on a Python shell or in a Python script without errors. For more information, see Set Up Python API for Polyspace.

1. Import the required modules:

   import polyspace.project
   import polyspace.test
   import os

2. Add source files and xUnit test files to a project. This example uses some example source and test files available with a Polyspace Test installation. Instead, you can use your own sources and tests.

   examples_path = os.path.join(polyspace.__install_path__, "polyspace", 
                               "examples", "pstest", "Getting_Started_Example")
   polyspaceProject = polyspace.project.Project("newProject.psprjx")
   polyspaceProject.Code.Files.add(os.path.join(examples_path, "sources", "utils.c"))
   polyspaceProject.IncludePaths.add(os.path.join(examples_path, "includes"))
   polyspaceProject.Tests.Files.add(os.path.join(examples_path, "tests", "test.c"))

3. Run the tests added to the project with execution profiling enabled.

   res = polyspace.test.run(
      polyspaceProject,
      ProfilingSelection=polyspace.test.ProfilingSelection.STACK
   )

4. Read the stack profiling results from the test results.

   profilingResults = res.Profiling
   stackProfilingResults = profilingResults.Stack

5. Sort the stack profiling result details by the Max property and print the function names along with their maximum stack usage.

   stackResultDetails = stackProfilingResults.Details
   sortedDetails = sorted(stackResultDetails, 
          key=lambda detail: -detail.Max)
   for detail in sortedDetails:
       print(detail.Function + ": " + str(detail.Max) + "b")

   If you use the example source and test files, you should see an output such as the following:

   update: 176b
   addLatestReading: 128b
   checkAgainstSpeedLimit: 128b
   checkLastSpeeds: 128b
   initOrReset: 64b
   updateAcceleration: 64b
   checkAccelerations: 64b
   isGreaterThanSpeedLimit: 64b

Version History

Introduced in R2024b