generate-code-coverage

generate-code-coverage Function

Summary

Switches code coverage generation on or off.

Package

hcl

Signature

generate-code-coverage &key on atomic-p counters force count-implicit-branch => on

Arguments

`on`⇩	A boolean.
`atomic-p`⇩	A boolean.
`counters`⇩	A boolean.
`force`⇩	A boolean.
`count-implicit-branch`⇩
	A boolean.

Values

`on`	A boolean.

Description

The function generate-code-coverage switches code coverage generation on or off.

on determines whether code coverage is generated. If on is true, code coverage generation is switched on, which means that when compile-file is called in the conventional way, that is generate a binary file from a source file, it generates code coverage code. If on is nil, code coverage generation is switched off and in this case the other keyword arguments are ignored. The default value of on is t.

generate-code-coverage returns t or nil, depending on the value of on.

atomic-p controls whether counting is done atomically or not. It is ignored when counters is nil. Passing atomic-p true makes the counters atomic, which may be much slower than counting non-atomically, but guarantees that the code is not going to drop counts when running multiprocessing. The default value of atomic-p is nil.

counters controls whether the code coverage code actually counts executions, or simply sets a flag to indicate that the code has been executed. Passing counters nil generates code which is a little smaller and faster, but does not count the number of times a piece of code has been executed. The default value of counters is t.

force, if true, forces generating counters in code that is marked not to generate counters by without-code-coverage or error-situation-forms. The default value of force is nil.

count-implicit-branch controls whether to generate counters for implicit branches. Implicit branches are generated by macros like cl:when, where the source only contains the "then" branch, and the "else" branch (which returns nil) is implicit. The other macros are cl:unless (when it is an implicit "then"), and the switch macros cl:cond, cl:case and cl:typecase when they do not have a t or otherwise clause. When count-implicit-branch is true, the compiler generates a counter for the implicit branch, which counts the number of times that the implicit branch was executed. In other words for cl:when this is the number of times that the condition returned nil; for cl:unless this is the number of times that the condition returned true, and for the switch macros it is the number of times that all the clauses returned nil.

When coloring with an implicit branch with counter 0 inside a form with a non-zero counter, there is nowhere to put the color for the uncovered code, so the form is colored as a hidden-partial form (see 10.7 Understanding the code coverage output).

The default value of count-implicit-branch is t.

Notes

If generate-code-coverage is called outside the body of with-code-coverage-generation, it switches the generation globally. Inside the body of with-code-coverage-generation it switches the generation within the scope of the surrounding with-code-coverage-generation, but has no effect once this with-code-coverage-generation exited.