☰

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).

Global compilation options of incremental analysis are available in incanal_options. Edit this file to activate tracing or run-time checks.

Incremental analysis only works with fixpoint dd, one abstract domain and multivariance on success off. The assertions of the predicates of this module reflect this.

Usage

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

?- set_pp_flag(fixpoint, dd),
   set_pp_flag(incremental, on),
   set_pp_flag(del_strategy, top_down). %% select strategy for incremental deletion

  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.

Documentation on exports

PREDICATEincremental_module/1

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.
  • The following properties should hold globally:
    (not_fails/1)All the calls of the form incremental_module(Files) do not fail.

PREDICATEincremental_module/2

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.
  • The following properties should hold globally:
    (not_fails/1)All the calls of the form incremental_module(Files,Stats) do not fail.

PREDICATEincremental_analyze/1

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 and assertions after.

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

PREDICATEincremental_analyze/2

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.
  • The following properties should hold globally:
    (not_fails/1)All the calls of the form incremental_analyze(AbsInt,Stats) do not fail.

PREDICATEreset_incremental_analysis_info/0

Usage:

Resets incremental and regular ciaopp internal data structures.

    PREDICATEconfig_incremental_load/1

    Usage:config_incremental_load(X)

    PREDICATEall_assertions_pred/4
    No further documentation available for this predicate.

    Generated with LPdoc using Ciao