[Scilab-Dev] SEP advanced function/profiling in Scilab 6

[Clément David]

Hello Samuel and happy new year,

I will try to answer your question in-line to clarify the current description (and implementation).
I also updated the wiki page with the latest information (mainly a split I will detail below).

 
> => Will it be possible to target a user-defined function out of libraries (defined with deff,
> function (in console), exec, jdeff..)?

Yes of course, from the interpreter point of view, a Scilab function (in whatever way we use to
define it) is a specific value we instrument or retrieve the value from.

> sel = prof.FunctionTable.ModuleName=="myModule";
> prof.FunctionTable(sel).FunctionName
> prof.FunctionTable(sel).TotalTime

Yep, that's almost it :

 sel = prof.FunctionTable.ModuleName == "myModule";
 prof.FunctionCoverage(sel).FunctionName
 prof.FunctionCoverage(sel).TotalTime


> I do not catch why there are 2 distinct 1st level fields FunctionTable and FunctionCoverage,
> instead of having a tenth field FunctionCoverage directly at the first level. This first level
> FunctionTable/FunctionCoverage complicates the addressing, and its motivation is unclear.
> 
> To me, the most handy first level addressing should be directly through <functionName>:
> prof.myFun.TotalTime
> prof.myFun.Coverage
> etc. This is much simpler and straightforward than with the syntaxes presented hereabove.

I described a way to store functions descriptions, functions statistics and line coverage in
separate fields as this is really different information. For exemple, to store function description
or statistics I used a struct which is the most easy way to select (as in the above snippet) a
module or a specific function whereas to store line coverage (per function) in a compact way I used
a list containing information for each function and *per line*. So really the final indexing is not
the same for this line coverage.

At the end and after some interaction with our current customer, we ended up with three different
information : static per function (file names, module, etc..), dynamic per function (number of
calls, total time, etc...), dynamic per function per line (time and counter). So a tlist with three
fields : FunctionTable, FunctionCoverage and LineCoverage. 

> About fields names
> "ModuleName" might be abbreviated into Module or Library without loss of meaning and clarity. If
> the expected value is the name of the library (e.g. corelib), then the field name should be
> Library instead of Module or ModuleName. Otherwise, ModuleName will refer to core, not to corelib.
> This would prevent securely addressing information from the library (the name of a module is not
> clearly defined. Is it the name of its SCI/<module> directory, or the name of its gateway, or...?

I agree with the "core" vs "corelib" however this value is stored as a string so this is really a
name. I will switch to "LibraryName" to ease understanding and be coherent with the libraryinfo
documentation [1].

[1]: https://help.scilab.org/docs/6.0.1/en_US/libraryinfo.html

> "FirstLine" : is it the "Prototype"?

This field is the first line of the function (the one with the `function` keyword) and is the same
as:
 * used on error (in Scilab 5 or 6)
 * within Scinotes

This is also used to avoid generating header lines on LineCoverage.

> InstructionsCount, BranchesCount, PathsCount : 
> these fields would be new results, not available in Scilab 5. For the time being, I do not
> understand what they represent nor what they can be used to.
> Does "executed lines count" stand for only lines that are actually executed, or does it stand for
> all lines, with a count 0 for not executed ones?

This is basically counters for coverage, the executed instruction/branches/path and non executed
instruction/branches counts for a specific function are reported. This is not really "lines count"
but expression count (executable statement in the code) thus is more precise than lines based
coverage but harder to visualize.

> The case of nested functions (a function defined in a function, etc) is not presented. There were
> some issues in Scilab 5 about them. See for instance the bug 12104 or the bug 12105.
> 
> The case of internal functions defined in the same .sci file after the main function is not
> presented. This is a new topic, since the Scilab 6 processing is new with respect           to
> these local dependencies. Will profiling these internal dependencies be possible?

Yes this is handled and was an important remark from our customer. Both the sub function (in the
same macro file) or inner functions (within another function) are handled as independent functions
and could be retrieved by FunctionTable.FileName and a specific FunctionTable.ParentIndex (index to
its parent function).

Inner functions are also reported as non executable lines on the parent function LineCoverage.

> "The main issue with switching API is the associated effort to port existing Scilab 5 toolset to
> the new API. As you propose, a Matlab-like `profile`  might be a later extension."
> I am sorry, i do not clearly understand this point. Anyway, the API is changed, since functions
> are renamed, and the format of results is completely changed.
> Writting a profile() macro routing to the internal profileEnable() etc would be somehow let's say
> ~3% of the time, by far the easiest part of the forge, compared to the implementation/rewritting
> of hard code. But it would ease usages and maintenance and documentation. Skipping it looks like a
> bit self censorship, self limiting impact of a great work.
> At least, not splitting the documentation in N separated pages, but building a single help page
> presenting all profiling functions and usages would be better.

Well, each Scilab function is supposed to have its own associated help page furthermore having the
full description. However I agree that having a single `profile` page will ease overall
understanding, its usage and its maintenance. 

Thanks for your remarks,

--
Clément