Incremental analysis (high level)

Author(s): Isabel Garcia-Contreras.

Stability: [devel] Currently the subject of active development and/or research. Functionality may be limited and API and/or functionality may change without warning or deprecation period. Not recommended yet for use in production.


This module implements a high level interface of incremental analysis (see incanal_driver for the low level interface).

Usage

Important: For using incremental analysis some ciaopp flags have to be set:

?- set_pp_flag(fixpoint, dd),
   set_pp_flag(incremental, on).

  1. (Re)Load a list of modules to be analyzed with incremental_module/1 (or incremental_module/2 to get statistics). It can be done several times before reanalyzing.

  2. (Re)Analyze the code with incremental_analyze/1 (or incremental_analyze/2 to get statistics). Internally, the changes will be automatically incrementally applied.

    This predicate depends on the ciaopp flag del_strategy for incremental deletion.

Note: If a module is not present in the reloading list, it is assumed that it has been removed from analysis so all modules must be in the input list although they may have not changed.

Tip (under construction!!): If you want to quickly display the information inferred by the analyzer between analyses you can:

?- use_module(ciaopp(raw_printer)).
?- show_analysis.

Example

Example of incremental analysis for file foo.pl

:- module(foo, [p/1], []).

p(1).
p(3).

Incremental analysis from Ciao toplevel:

?- use_module(ciaopp(plai/incanal)), use_module(ciaopp(preprocess_flags)).

yes
?- % incremental flags
   set_pp_flag(fixpoint, dd),
   set_pp_flag(incremental, on).

yes
?- incremental_module(foo, T).

T = [time(317.96,[])] ?

yes
?- incremental_analyze(eterms, T).

T = [proc_diff(0.244),add(2.281),delete(0.001)] ?

yes
% reload changes:
?- incremental_module(foo, T).

T = [time(299.822,[])] ?

yes
?- incremental_analyze(eterms, T).
{Incrementally analyzed with dd for eterms }

T = [proc_diff(0.314),add(2.148),delete(2.797)] ?

yes

Side effects

As a result of the incremental analysis, auxiliary files are generated for each analyzed module:

  • When loaded a module: File.itf.
  • When analyzed a module: File.dump.

They are used to detect if changes were made in a module. To reset the incremental analysis these files have to be removed.

WARNING: There might be problems with clause locators because Ids generated when transforming the code can be modified.


Usage and interface

Documentation on exports

Usage:incremental_module(Files)

Loads and transforms the code of Files to the ciaopp code database, computing the differences with the code previously present

  • The following properties should hold at call time:
    (list/1)Files is a list.

Usage:incremental_module(Files,Stats)

Same as incremental_module/1 but returns runtime statistics in Stats.

  • The following properties should hold at call time:
    (list/1)Files is a list.
  • The following properties should hold upon exit:
    (list/1)Stats is a list.

Usage:incremental_analyze(AbsInt)

Applies Diff to the current analysis by performing all deletions according to the deletion strategy set the ciaopp flag (top_down or bottom_up), reanalyzing and adding all clauses after.

  • The following properties should hold at call time:
    (atm/1)AbsInt is an atom.

Usage:incremental_analyze(AbsInt,Stats)

Same as incremental_analyze/1 but returns runtime statistics in Stats. Statistics are divided in:

  • proc_diff: Time needed to apply the differences to the incremental database.
  • add: Time needed for performing the addition of clauses.
  • delete: Time needed for performing the deletion of clauses according to the selected deletion strategy.

  • The following properties should hold at call time:
    (atm/1)AbsInt is an atom.
  • The following properties should hold upon exit:
    (list/1)Stats is a list.

Usage:

Resets incremental and regular ciaopp internal data structures.

    Usage:config_incremental_load(X)

    PREDICATEsame_clause/2

    Usage:same_clause(+Cl1,+Cl2)

    This predicate succeeds if Cl1 and Cl2 are the same clause, if a variable is renamed, the clauses are considered the same.