1. SEP: advanced function/profiling in Scilab 6
2. Abstract
Scilab 6 introduced “coverage” functions and removed the legacy “profiling” functions, this SEP clarify the overall usage of such functionality and propose some extension to the Scilab 6.0.x functions: covStart, covMerge, covStop and covWrite. “coverage” did not aim to replace the “profiling” functionality but as both terms are related to the same “dynamic code analysis” area this led to some confusion; in this SEP, we will clarify the expected behaviors and describe a way to implement both “coverage” (the degree to which the source code is executed on a particular execution) and “profiling” (the frequency of each line of the source code) on top of the execution counters used to track execution time in Scilab 6.
3. Requirements
The initial idea is to have more information on a Scilab specific execution. Without any dedicated support, the user is left to guess where the code spent most of its time. “profiling” an execution should give insights on the execution by giving timing information back to the user as Scilab values and providing an easy way to visualize these timings. A specific analysis could also be written using Scilab to generate dedicated reports. “coverage” of an execution is such a dedicated report; it writes an HTML report of an execution in the form of a code line coverage.
The functions dedicated to the coverage are preserved as in 6.0.x and could be mixed with the profiling ones. The following functions are added or reserved for profiling:
profileEnable(function), profileEnable(macrolib), profileEnable(): setup execution counters on a specific Scilab function function (defined in macro files, in the console or in script files), Scilab library macrolib or all the loaded Scilab libraries.
profileDisable(function), profileDisable(macrolib), profileDisable(): disable execution counters on a specific Scilab function function (defined in macro files, in the console or in script files), Scilab library macrolib or all the loaded Scilab libraries.
prof = profileGetInfo(): Return a Scilab tlist containing execution counters information for all the enabled functions. The tlist ProfilerStatistics prof contains:
FunctionTable: a struct of profiled functions information containing:
FunctionName: the function name.
FileName: the macro .bin file used to defined the function.
FirstLine: the first executed line of the macro.
LibraryName: the library name (with its lib suffix) containing the function.
ParentIndex: index to the parent function for inner functions.
FunctionCoverage: a struct of profiled functions information containing:
NumCalls: the number of call to this function.
TotalTime: time spent in seconds within this function.
InstructionsCount: a vector 2xN of uint64, where N is the executed lines count, containing the number of executed instructions and the number of non-executed instructions.
BranchesCount: a vector 2xN of uint64, where N is the executed lines count, containing the number of executed branches and the number of non-executed branches.
PathsCount: a vector 1xN of uint64, where N is the executed lines count, containing the number of executed paths.
LineCoverage : a list of execution counters per functions with:
LineCoverage(i)(1,:) : a list containing the number of times the line i of the function has been executed or containing -1 if this is not an executable line.
LineCoverage(i)(2,:) : cumulated CPU time [in seconds] spent to execute the line i of the function
The following names are reserved for a future implementation:
profile: generic entry-point used to hide the multiple functions.
profileShow: display executed lines into the Scilab console (mixed with Scilab code).
profilePlot: display executed lines into a Figure and display the selected line within Scinotes on-click/
comparing to the Scilab 5 implementation, the functionalities are all prefixed with a profile name to clarify the topic.
Sub-functions (functions defined in the same macro file but private to the macro file) or inner-function (functions defined within another function) are handled as independe
3.1. Bugzilla links
The following bugs have been entered on Bugzilla to track similar or related problems/wishlist:
http://bugzilla.scilab.org/show_bug.cgi?id= 15012 covStart function crashes Scilab
3.2. Mailing list threads
http://mailinglists.scilab.org/New-profiling-module-code-coverage-td4034048.html reports usability issue on coverage functions.
http://mailinglists.scilab.org/SEP-advanced-function-profiling-in-Scilab-6-td4038865.html SEP thread.
3.3. Other software
4. Examples
1 // Function to be profiled
2 function x=foo(n)
3 if n > 0 then
4 x = 0;
5 for k = 1:n
6 s = svd(rand(n, n));
7 x = x + s(1);
8 end
9 else
10 x = [];
11 end
12 endfunction
13
14 // Enables the profiling of the function
15 profileEnable(foo)
16
17 // Executes the function
18 foo(200);
19
20 // Returns the function profiling results
21 prof = profileGetInfo();