GAP (profiling) - Chapter 2: Functionality provided by the profiling package

Goto Chapter: Top 1 2 Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

2 Functionality provided by the profiling package
2.1 Reading line-by-line profiles
2.1-1 ReadLineByLineProfile
2.1-2 MergeLineByLineProfiles
2.2 Generating flame graphs
2.2-1 OutputFlameGraph
2.2-2 OutputFlameGraphInput
2.3 Generating coverage reports
2.3-1 OutputAnnotatedCodeCoverageFiles
2.3-2 OutputJsonCoverage
2.3-3 OutputLcovCoverage
2.3-4 OutputCoverallsJsonCoverage
2.4 Miscellaneous
2.4-1 LineByLineProfileFunction
2.4-2 ProfileFile
2.4-3 ProfilePackage

### 2 Functionality provided by the profiling package

#### 2.1 Reading line-by-line profiles

##### 2.1-1 ReadLineByLineProfile

`‣ ReadLineByLineProfile`( filename ) | ( function )

Read filename, a line-by-line profile which was previously generated by GAP, using the `ProfileLineByLine` (Reference: ProfileLineByLine) or `CoverageLineByLine` (Reference: CoverageLineByLine) functions from core GAP. A parsed profile can be transformed into a human-readable form using either `OutputAnnotatedCodeCoverageFiles` (2.3-1) or `OutputFlameGraph` (2.2-1)

##### 2.1-2 MergeLineByLineProfiles

`‣ MergeLineByLineProfiles`( filenames ) | ( function )

Read filenames, a list of line-by-line profiles which were previously generated by GAP, using the `ProfileLineByLine` (Reference: ProfileLineByLine) or `CoverageLineByLine` (Reference: CoverageLineByLine) functions from core GAP. The elements of filenames can be either filenames, or files previously parsed by `ReadLineByLineProfile` (2.1-1).

#### 2.2 Generating flame graphs

A 'flame graph' is a method of visualising where time is spent by a program.

##### 2.2-1 OutputFlameGraph

`‣ OutputFlameGraph`( profile[, filename][, options] ) | ( function )

Generate an 'svg' file which represents a 'flame graph', a method of visualising where time is spent by a program.

profile should be either a profile previously read by `ReadLineByLineProfile` (2.1-1), or a string giving the filename of a profile.

The flame graph will be written to filename (or returned as a string if filename is not present).

The final (optional) argument is a record of options. Currently, the allowed options are 'squash' (which is a boolean). If 'squash' is true then recursive functions calls will be squashed, so the graph will not show recursive functions calling themselves. The other allowed option is 'type', which can be "default" (a standard flamegraph), "reverse" (reverse the graph, showing the leaf functions first), and "chart" (where the graph shows the flow of time from left-to-right, rather than merging all calls from one function to another into one block).

##### 2.2-2 OutputFlameGraphInput

`‣ OutputFlameGraphInput`( profile[, filename] ) | ( function )

Generate the input required to draw a 'flame graph', a method of visualising where time is spent by a program. One program for drawing flame graphs using this output can be found at https://github.com/brendangregg/FlameGraph.

profile should be either a profile previously read by `ReadLineByLineProfile` (2.1-1), or a string giving the filename of a profile.

The flame graph input will be written to filename (or returned as a string if filename is not present).

#### 2.3 Generating coverage reports

##### 2.3-1 OutputAnnotatedCodeCoverageFiles

`‣ OutputAnnotatedCodeCoverageFiles`( coverage[, indir], outdir[, options] ) | ( function )

Takes a previously generated profile and outputs HTML which shows the lines of code that were executed, and (if this was originally recorded) how long was spent executing these lines of code.

coverage should be either a profile previously read by `ReadLineByLineProfile` (2.1-1), or a string giving the filename of a profile which will first be read with `ReadLineByLineProfile`.

Files will be written to the directory outdir.

The optional second argument gives a filter, only information about filenames starting with indir will be outputted.

The final optional argument is a record of configuration options. The only currently allowed option is 'title', which will set the title of created pages.

##### 2.3-2 OutputJsonCoverage

`‣ OutputJsonCoverage`( coverage, outfile ) | ( function )

Takes a previously generated profile and outputs a json coverage file which is amongst other things accepted by codecov.io.

coverage should be either a profile previously read by `ReadLineByLineProfile` (2.1-1), or a string giving the filename of a profile which will first be read with `ReadLineByLineProfile`.

The output will be written to the file with name outfile (a string).

##### 2.3-3 OutputLcovCoverage

`‣ OutputLcovCoverage`( coverage, outfile ) | ( function )

Takes a previously generated profile and outputs an lcov coverage file.

coverage should be either a profile previously read by `ReadLineByLineProfile` (2.1-1), or the filename of a profile which will first be read with `ReadLineByLineProfile`.

The output will be written to the file with name outfile (a string).

##### 2.3-4 OutputCoverallsJsonCoverage

`‣ OutputCoverallsJsonCoverage`( coverage, outfile, pathtoremove[, opt] ) | ( function )

Takes a previously generated profile and outputs a json coverage file which is accepted by coveralls.io.

coverage should be either a profile previously read by `ReadLineByLineProfile` (2.1-1), or a string giving the filename of a profile which will first be read with `ReadLineByLineProfile`. pathtoremove is the path to the tested repository; this path prefix will be removed from all filenames in coverage. Finally, opt is a record. Its key/value pairs are directly inserted into the produced JSON, in the form of a JSON dictionary. This can be used to set the `service_name`, `service_job_id`, and more. If this record is not given, we try to guess the correct values based on the environment (currently only supported for Travis and AppVeyor).

The output will be written to the file with name outfile (a string).

#### 2.4 Miscellaneous

##### 2.4-1 LineByLineProfileFunction

`‣ LineByLineProfileFunction`( function, arguments ) | ( function )

Calls function with the list of arguments arguments, and opens a time profile of the resulting call in the default web browser.

##### 2.4-2 ProfileFile

`‣ ProfileFile`( file[, opts] ) | ( function )

Returns: a string

Tests the file with name file in another GAP session, and produces a code coverage report of lines that were executed in the process. If file ends with `.tst` it will be called with `Test`; otherwise, it will be run directly.

The optional argument opts should be a record, and may contain any of the following components:

- `outdir`: a string denoting the directory into which the HTML files of the report will be placed (a temporary directory by default);

- `indir`: a string such that only file paths beginning with `indir` will be profiled (default `""`);

- `showOutput`: a boolean denoting whether to print test output to the screen (default `true`);

- `open`: a boolean denoting whether to open the report in a web browser on completion (default `false`).

This function returns the location of an HTML file containing the report.

##### 2.4-3 ProfilePackage

`‣ ProfilePackage`( pkg_name[, opts] ) | ( function )

Returns: a string

If pkg_name is the name of an installed package, then this function runs that package's test suite and produces a report on the code coverage of files inside the package. The string returned denotes the location of an HTML file containing the report. The optional argument opts behaves the same as in `ProfileFile` (2.4-2).

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 Ind

generated by GAPDoc2HTML