Coverage Recorders

This page explains few details how Clover code instrumentation works and how the coverage data is being collected at runtime.

This article might be helpful for you in case you have significant performance problems or your application runs in a restricted environment.

Instrumenting code

Every time Clover instruments the code (via <clover-instr/> or <clover-setup/> - both Java and Groovy) it records information about the code structure (packages, files, classes, method, statements, branches, test methods etc) into the Clover database. Because of fact that the same database can be used multiple times (for instance in case of incremental compilation; or when project has several modules compiled separately), it maintains history of changes in blocks named 'instrumentation session'.

Every instrumented class is enhanced by adding code which requests a Clover's coverage recorder instance. Such coverage recorder getter is called with some arguments, which allows to determine which Clover database file and which instrumentation session in this file contains information about the class structure (like indexes of statements, methods, branches etc).

As project contains many classes, Clover has an optimization so that some of these classes will share the same coverage recorder instance - exact strategy depends on selected recorder type - see below.

Diagram: code instrumentation process

Information about code structured is stored in Clover database. Every instrumented class contains information about database (initstring) and the instrumentation session time stamp. Thanks to this it's possible to map compiled class file to a corresponding source file (also in correct version - see C.java).

Executing code

Fixed Coverage Recorder

It's using an in-memory fixed-size long[] array for recording hit counts for methods, statements and branches. Calculation of the long[] array size requires access to the Clover Database (clover.db) at runtime, however. All classes which were compiled in the same instrumentation session (i.e. within the same <clover-instr> or javac or groovyc call) will share the same instance of the coverage recorder.

Growable Coverage Recorder

It's using a dynamically resizeable two-dimensional long[][1000000] array for recording hit counts for methods. Thanks to this it does not require access to the Clover Database at runtime and this is its main advantage. It's performance is slightly lower than the Fixed Coverage Recorder due to memory allocation and two-level indexing. All classes which were compiled in the same instrumentation session (i.e. within the same <clover-instr> or javac or groovyc call) will share the same instance of the coverage recorder.

Shared Coverage Recorder

It's a modification of the Growable Coverage Recorder designed specially for Grails-based projects. It shares the same coverage recorder instance for every instrumented class which was compiled with the same database initstring and configuration settings (like flush policy). It means that it ignores instrumentation session timestamps.

Grails build system works in such way that it compiles every domain class and service class separately. As a consequence, Clover "sees" this as a separate instrumentation session. It means that in case of the fixed or growable coverage recorder it creates a separate instance of the recorder for every domain or service class.

It might become a performance problem if you have many such classes and you execute test methods, because end of every test method will force creation of the per-test coverage file (clover.db*.s) from all coverage recorder instances. For example:

• 500 domain classes * 1000 unit tests = 500 coverage recorders * 1000 snapshots = 500'000 files on disk

Note that the performance problem does not occur during normal application run or when test code is not instrumented. For example:

• 500 domain classes (normal app execution) = 500 coverage recorders * 1-2 snapshots (depends on flush policy) = 500-1000 files on disk

If you decide to use a Shared Coverage Recorder, you must keep in mind that:

• you cannot have multiple modules which have the same initstring value, but they actually point to different files (it's a typical case if you have a multi-module Maven project and you use the same relative initstring for each module)
  • TIP: use an absolute path for initstrings or share a same database among modules
• you cannot deploy outdated class files, for which information in the Clover database is not longer valid (as instrumentation timestamp is ignored);
  
  • TIP: perform a full project build, deleting all old classes as well as Clover database and coverage recording files (see "Using shared coverage recorder" example for Grails)