Visitors

As the CodeSonar analysis runs, it invokes visitors on various elements of the intermediate representation. Decorators, such as project_visitor() declare functions (callables, really) to be visitors.

Project visitors are invoked exactly once per analysis, and are always passed the project as a parameter. You could issue all your warnings from a project_visitor(). However, this might entail traversing the intermediate representation yourself. If you implement many warning classes, then each one might end up traversing the IR itself.

CodeSonar provides additional visitors as a convenience and for efficiency. For instance, a point_visitor() will visit every program point. Visitors boost efficiency because they improve locality of reference. All point visitors will visit point1, then they will all visit point2, and so on. The need to traverse the representation multiple times is avoided. The bottom up variety of visitors run concurrently (in different processes), boosting efficiency even further.

The visitor decorator you use will depend on the type of the visited elements and the phase in which you want to apply the visitor, as shown in the following table.

visited element type visitor phase options
project project_drop_visitor(), project_drop_finish_visitor(), project_visitor(), project_finish_visitor(), project_parallel_visitor(), project_parallel_finish_visitor(), project_bottom_up_visitor(), cache_cleanup_visitor()
compunit compunit_drop_visitor(), compunit_visitor(), compunit_finish_visitor(), compunit_parallel_visitor(), compunit_parallel_finish_visitor()
sfileinst (used for both sfile and sfileinst visitors) sfile_visitor(), sfile_finish_visitor(), sfileinst_visitor() sfileinst_finish_visitor() sfile_parallel_visitor(), sfile_parallel_finish_visitor(), sfileinst_parallel_visitor(), sfileinst_parallel_finish_visitor()
procedure procedure_drop_visitor(), procedure_visitor(), procedure_finish_visitor(), procedure_parallel_finish_visitor(), procedure_parallel_visitor(), procedure_bottom_up_visitor(), procedure_bottom_up_finish_visitor()
point point_visitor(), point_parallel_visitor(), point_bottom_up_visitor()
symbol global_symbol_drop_visitor() (globals only), symbol_visitor(), symbol_parallel_visitor()
CFG edge: (point, edge_label) Special case that does not involve decorators: see Note on Step Visitors.

Note

The CodeSonar Plug-In API Tutorial and AST Tutorial provide annotated example plug-ins involving various visitor types, along with installation and testing instructions.

Note on Step Visitors

Step visitors are a special case. Instead of using decorators, step visitors are added by subclassing step_state, creating an object of the subclass, and passing that object to analysis.add_step_bottom_up_visitor().

See the step_state documentation for an annotated example.

Example

For a sample plug-in that inspects every program point, do the following.

  1. Save the following code as $INSTALL/codesonar/plugins/visitor_tutorial.plugin.py.

    import cs
tutorial_wc = cs.analysis.create_warningclass('visitor tutorial warning')

@cs.point_visitor
def check_assignments(pnt):
    if 'i = 1' in str(pnt):
        tutorial_wc.report(pnt, 'they assigned 1 to i!')

  2. Run the following command to analyze the foo.c program from the Exploring the Intermediate Representation section.

    codesonar analyze foo -foreground hub:port gcc -c foo.c

    The CodeSonar output will include the URL of the analysis results page.

  3. Open the analysis page. You will see that the plug-in has reported one warning in foo.c.

Plug-In API Tutorial Example

Shown below is the Python version of the sample plug-in from Part One of the Plug-In API Tutorial.

#      software is retained by CodeSecure, Inc.
# 

# UCvar_plugin.py
# 
#  a small example plugin that reports declarations for variables
#  whose names contain upper case characters

import cs

# The plug-in defines a new warning class to go with its new check. We
# do not associate any CodeSonar mnemonics or CWE identifiers with the
# new class, as none are appropriate.  The new warning class must be
# created in the top level scope.

upvar_wc = cs.analysis.create_warningclass(
    'Variable name has upper case characters',
    '',
    1.0,
    cs.warningclass_flags.PADDING,
    cs.warning_significance.STYLE
    )


# Visitors should be at the finest granularity that is appropriate
# for the check. This plug-in is checking a property of variable
# names, so we define a visitor that operates on symbols.

@cs.symbol_visitor        #  visitor decorator 
def check_var_case(sym):
    nm = sym.name()       # cs.symbol.name()

    # If there are one or more upper case characters and the variable
    # is declared in user code, issue a warning and return.
    if nm != nm.lower():        
        try:
            (symfi,symline) = sym.file_line()   # cs.symbol.file_line()
        except cs.result as r:
            # If no position, do not report warning. Raise any other errors.
            if r != cs.result.NO_POSITION:
                raise     
        else:
            if not symfi.is_system_include():   # cs.sfileinst.is_system_include()
                upvar_wc.report(symfi,          # cs.warningclass.report()
                                symline,
                                'Variable name %s has upper case character'%nm)

Visitor Decorators

@cs.project_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first program visitor for programs ( project ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to programs in these languages ( language ).

During analysis, the visitor (decorated function) will be applied to the project at the beginning of the serial depth-first analysis phase, before the serial depth-first traversal begins.

* [drop phase]              (incremental only)
* program setup visitors
* program visitors                                 <=======
*     [serial depth-first traversal]
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

>>> @project_visitor
... def visit_project(proj):
...     print('hello from', proj)
@cs.compunit_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase visitor for compilation units ( compunit ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to programs in these languages ( language ).

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to compilation units ( compunit ) whose language appears in langs.

  • In base analyses, it will be applied to every such compilation unit in the project.
  • In incremental analyses, it will be applied only to compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1                    <===========
*          [visitors applied to elements contained in cu1]
*      compunit finish visitors applied to cu1
*      compunit visitors applied to cu2                    <===========
*          [visitors applied to elements contained in cu2]
*      compunit finish visitors applied to cu2
*      [remaining compunits]                               <-----------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.procedure_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase visitor for procedures in compilation units ( compunit ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to procedures in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to procedures ( procedure ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such procedure in the project.
  • In incremental analyses, it will be applied only to procedures contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to compunit-level symbols in cu1]
*          [visitors applied to source files and file instances in cu1]
*          procedure visitors applied to cu1proc1                   <========
*              [visitors applied to elements contained in cu1proc1]
*          procedure finish visitors applied to cu1proc1
*          procedure visitors applied to cu1proc2                   <========
*              [visitors applied to elements contained in cu1proc2]
*          procedure finish visitors applied to cu1proc2
*          [remaining procedures in cu1]                            <--------
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                        <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.symbol_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase visitor for symbols ( symbol ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to symbols in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to symbols ( symbol ) in the project that are contained in a compilation unit whose language appears in langs.

  • In base analyses, it will be applied to every such symbol in the project.
  • In incremental analyses, it will be applied only to symbols contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          symbol visitor applied to symbol cu1proc1fsym (function symbol for cu1proc1) <========
*          [visitors applied to source files and file instances in cu1]
*          procedure visitors applied to cu1proc1
*              symbol visitor applied to cu1proc1vsym1                                  <========
*              symbol visitor applied to cu1proc1vsym2                                  <========
*              [remaining symbols in cu1proc1]                                          <--------
*              [visitors applied to points contained in cu1proc1
*          procedure finish visitors applied to cu1proc1
*          [remaining procedures in cu1]                                                <--------
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                                            <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.point_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase visitor for points ( point ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to points in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied points ( point ) in the project that are contained in a compilation unit whose language appears in langs.

  • In base analyses, it will be applied to every such point in the project.
  • In incremental analyses, it will be applied only to points contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to compunit-level symbols in cu1]
*          procedure visitors applied to cu1proc1
*              [visitors applied to symbols contained in cu1proc1]
*              point visitor applied to cu1proc1point1                                        <========
*              point visitor applied to cu1proc1point2                                        <========
*              [remaining points in cu1proc1]                                                 <--------
*          procedure finish visitors applied to cu1proc1
*          [remaining procedures in cu1]                                                      <--------
*          [visitors applied to source files and file instances in cu1]
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                                                  <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

>>> @point_visitor
... def visit_point(pnt):
...     print('visiting', pnt)
@cs.procedure_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase finish visitor for procedures ( procedure ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to procedures in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to procedures ( procedure ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such procedure in the project.
  • In incremental analyses, it will be applied only to procedures contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to compunit-level symbols in cu1]
*          [visitors applied to source files and file instances in cu1]
*          procedure visitors applied to cu1proc1
*              [visitors applied to elements contained in cu1proc1]
*          procedure finish visitors applied to cu1proc1            <========
*          procedure visitors applied to cu1proc2
*              [visitors applied to elements contained in cu1proc2]
*          procedure finish visitors applied to cu1proc2            <========
*          [remaining procedures in cu1]                            <--------
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                        <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfile_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase visitor for (representative instances of) files in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to files in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to the representative instances ( sfileinst ) of source files contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to the representative instance of every such source file in the project.
  • In incremental analyses, it will be applied only to representative instances of source files for which all remaining instances are contained in compilation units compiled in the increment.

Note that the visitor is applied to a sfileinst (not a sfile ).

* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to compunit-level symbols in cu1]
*          sfile visitors applied to representative instance of top-level source file f1 in cu1...             <========
*            ...IF AND ONLY IF this is first time f1 is encountered
*          sfileinst visitors applied to f1 instance (always)
*              sfile visitors applied to representative instance of file f1inc1 included in f1...              <========
*                ...IF AND ONLY IF this is first time f1inc1 is encountered
*              sfileinst visitors applied to f1inc1 instance (always)
*                  sfile visitors applied to representative instance of file f1inc1inc1 included in f1inc1...  <========
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  sfileinst visitors applied to f1inc1inc1 instance (always)
*                      [traverse f1inc1inc1 include tree]                                                      <--------
*                  sfileinst finish visitors applied to f1inc1inc1 instance (always)
*                  sfile finish visitors applied to representative instance of f1inc1inc1...
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  [traverse remainder of f1inc1 include tree]                                                 <--------
*              sfileinst finish visitors applied to f1inc1 instance (always)
*              sfile finish visitors applied to f1inc1
*                ...IF AND ONLY IF this is first time f1inc1 is encountered
*              [traverse remainder of f1 include tree]                                                         <--------
*          sfileinst finish visitors applied to f1 instance (always)
*          sfile finish visitors applied to representative instance of f1...
*            ...IF AND ONLY IF this is first time f1 is encountered
*          [visitors applied to procedures,points,symbols in cu1]
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                                                                    <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfileinst_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase finish visitor for file instances ( sfileinst ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to file instances in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to source file instances ( sfile ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such source file instance in the project.
  • In incremental analyses, it will be applied only to source file instances contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to compunit-level symbols in cu1]
*          sfile visitors applied to representative instance of top-level source file f1 in cu1...
*             ...IF AND ONLY IF this is first time f1 is encountered
*          sfileinst visitors applied to f1 instance (always)
*              sfile visitors applied to representative instance of file f1inc1 included in f1...
*                 ...IF AND ONLY IF this is first time f1inc1 is encountered
*              sfileinst visitors applied to f1inc1 instance (always)
*                  sfile visitors applied to representative instance of file f1inc1inc1 included in f1inc1...
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  sfileinst visitors applied to f1inc1inc1 instance (always)
*                      [traverse f1inc1inc1 include tree]                                     <--------
*                  sfileinst finish visitors applied to f1inc1inc1 instance (always)          <========
*                  sfile finish visitors applied to representative instance of f1inc1inc1
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  [traverse remainder of f1inc1 include tree]                                <--------
*              sfileinst finish visitors applied to f1inc1 instance (always)                  <========
*              sfile finish visitors applied to representative instance of f1inc1
*                ...IF AND ONLY IF this is first time f1inc1 is encountered
*              [traverse remainder of f1 include tree]                                        <--------
*          sfileinst finish visitors applied to f1 instance (always)                          <========
*          sfile finish visitors applied to representative instance of f1
*                  IF AND ONLY IF this is first time f1 is encountered
*          [visitors applied to procedures,points,symbols in cu1]
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                                                  <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfileinst_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase visitor for file instances ( sfileinst ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to file instances in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to source file instances ( sfile ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such source file instance in the project.
  • In incremental analyses, it will be applied only to source file instances contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to compunit-level symbols in cu1]
*          sfile visitors applied to representative instance of top-level source file f1 in cu1...
*            ...IF AND ONLY IF this is first time f1 is encountered
*          sfileinst visitors applied to f1 instance (always)                                          <========
*              sfile visitors applied to representative instance of file f1inc1 included in f1...
*                ...IF AND ONLY IF this is first time f1inc1 is encountered
*              sfileinst visitors applied to f1inc1 instance (always)                                  <========
*                  sfile visitors applied to representative instance of file f1inc1inc1 included in f1inc1...
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  sfileinst visitors applied to f1inc1inc1 instance (always)                          <========
*                      [traverse f1inc1inc1 include tree]                                              <--------
*                  sfileinst finish visitors applied to f1inc1inc1 instance (always)
*                  sfile finish visitors applied to representative instance of f1inc1inc1...
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  [traverse remainder of f1inc1 include tree]                                         <--------
*              sfileinst finish visitors applied to f1inc1 instance (always)
*              sfile finish visitors applied to representative instance of f1inc1...
*                ...IF AND ONLY IF this is first time f1inc1 is encountered
*              [traverse remainder of f1 include tree]                                                 <--------
*          sfileinst finish visitors applied to f1 instance (always)
*          sfile finish visitors applied to representative instance of f1...
*             ...IF AND ONLY IF this is first time f1 is encountered
*          [visitors applied to procedures,points,symbols in cu1]
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                                                           <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfile_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase finish visitor for (representative instances of) files in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to files in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to the representative instances ( sfileinst ) of source files contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to the representative instance of every such source file in the project.
  • In incremental analyses, it will be applied only to the representative instances of source files for which all remaining instances are contained in compilation units compiled in the increment.

Note that the visitor is applied to a sfileinst (not a sfile ).

* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to compunit-level symbols in cu1]
*          sfile visitors applied to representative instance of top-level source file f1 in cu1...
*            ...IF AND ONLY IF this is first time f1 is encountered
*          sfileinst visitors applied to f1 instance (always)
*              sfile visitors applied to representative instance of file f1inc1 included in f1...
*                ...IF AND ONLY IF this is first time f1inc1 is encountered
*              sfileinst visitors applied to f1inc1 instance (always)
*                  sfile visitors applied to representative instance of file f1inc1inc1 included in f1inc1...
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  sfileinst visitors applied to f1inc1inc1 instance (always)
*                      [traverse f1inc1inc1 include tree]                                    <--------
*                  sfileinst finish visitors applied to f1inc1inc1 instance (always)
*                  sfile finish visitors applied to representative instance of f1inc1inc1... <========
*                    ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*                  [traverse remainder of f1inc1 include tree]                               <--------
*              sfileinst finish visitors applied to f1inc1 instance (always)
*              sfile finish visitors applied to representative instance of f1inc1...         <========
*                ...IF AND ONLY IF this is first time f1inc1 is encountered
*              [traverse remainder of f1 include tree]                                       <--------
*          sfileinst finishvisitors applied to f1 instance (always)
*          sfile finish visitors applied to representative instance of f1...                 <========
*            ...IF AND ONLY IF this is first time f1 is encountered
*          [visitors applied to procedures,points,symbols in cu1]
*      compunit finish visitors applied to cu1
*      [remaining compunits]                                                                 <--------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.compunit_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first phase finish visitor for compilation units ( compunit ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to files in compilation units whose language is one of these.

During the serial depth-first analysis phase, the visitor (decorated function) will be applied to compilation units ( compunit ) whose language appears in langs.

  • In base analyses, it will be applied to every such compilation unit in the project.
  • In incremental analyses, it will be applied only to compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*   (serial depth-first traversal)
*      compunit visitors applied to cu1
*          [visitors applied to elements contained in cu1]
*      compunit finish visitors applied to cu1             <===========
*      compunit visitors applied to cu2
*          [visitors applied to elements contained in cu2]
*      compunit finish visitors applied to cu2             <===========
*      [remaining compunits]                               <-----------
* program finish visitors
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.project_parallel_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first program visitor for programs ( project ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to programs in these languages ( language ).

During analysis, the visitor (decorated function) will be applied to the project at the beginning of the parallel depth-first analysis phase, before the parallel depth-first traversal begins.

* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors                       <=======
*     [parallel depth-first traversal]
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.project_parallel_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first program finish visitor for programs ( project ) whose languages ( language ) appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to programs in these languages ( language ).

the decorated function will be applied to the project at the end of the parallel depth-first phase, after the parallel depth-first traversal has finished.

* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   [parallel depth-first traversal]
* program parallel finish visitors           <=======
* [pointer analysis]
* program bottom-up visitors
* [bottom-up phase]
* program bottom-up finish visitors
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.compunit_parallel_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase visitor for compilation units ( compunit ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to programs in these languages ( language ).

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to compilation units ( compunit ) whose language appears in langs.

  • In base analyses, it will be applied to every such compilation unit in the project.
  • In incremental analyses, it will be applied only to compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1           <===========
*     [sA]    [parallel visitors applied to elements contained in cu1]
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] compunit parallel visitors applied to cu2           <===========
*     [sB]    [parallel visitors applied to elements contained in cu2]
*     [sB] compunit parallel finish visitors applied to cu2
*     [remaining compunits]                                    <-----------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.compunit_parallel_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase finish visitor for compilation units ( compunit ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to files in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to compilation units ( compunit ) whose language appears in langs.

  • In base analyses, it will be applied to every such compilation unit in the project.
  • In incremental analyses, it will be applied only to compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     [parallel visitors applied to elements contained in cu1]
*     [sA] compunit parallel finish visitors applied to cu1    <===========
*     [sB] compunit parallel visitors applied to cu2
*     [sB]     [parallel visitors applied to elements contained in cu2]
*     [sB] compunit parallel finish visitors applied to cu2    <===========
*     [remaining compunits]                                    <-----------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.procedure_parallel_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase visitor for procedures in compilation units ( compunit ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to procedures in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to procedures ( procedure ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such procedure in the project.
  • In incremental analyses, it will be applied only to procedures contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]    [parallel visitors applied to compunit-level symbols in cu1]
*     [sA]    [parallel visitors applied to source files and file instances in cu1]
*     [sA]    procedure parallel visitors applied to cu1proc1            <========
*     [sA]         [parallel visitors applied to elements contained in cu1proc1]
*     [sA]    procedure parallel finish visitors applied to cu1proc1
*     [sA]    procedure parallel visitors applied to cu1proc2            <========
*     [sA]         [parallel visitors applied to elements contained in cu1proc2]
*     [sA]    procedure parallel finish visitors applied to cu1proc2
*     [sA]    [remaining procedures in cu1]                              <--------
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]           <--------
*     [remaining compunits]                                              <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.procedure_parallel_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase finish visitor for procedures ( procedure ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to procedures in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to procedures ( procedure ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such procedure in the project.
  • In incremental analyses, it will be applied only to procedures contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     [parallel visitors applied to compunit-level symbols in cu1]
*     [sA]     [parallel visitors applied to source files and file instances in cu1]
*     [sA]     procedure parallel visitors applied to cu1proc1
*     [sA]        [parallel visitors applied to elements contained in cu1proc1]
*     [sA]     procedure parallel finish visitors applied to cu1proc1   <========
*     [sA]     procedure parallel visitors applied to cu1proc2
*     [sA]        [parallel visitors applied to elements contained in cu1proc2]
*     [sA]     procedure parallel finish visitors applied to cu1proc2   <========
*     [sA]     [remaining procedures in cu1]                            <--------
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]          <--------
*     [remaining compunits]                                             <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.point_parallel_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase visitor for points ( point ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to points in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied points ( point ) in the project that are contained in a compilation unit whose language appears in langs.

  • In base analyses, it will be applied to every such point in the project.
  • In incremental analyses, it will be applied only to points contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     [parallel visitors applied to compunit-level symbols in cu1]
*     [sA]     procedure parallel visitors applied to cu1proc1
*     [sA]         [parallel visitors applied to symbols contained in cu1proc1]
*     [sA]         point parallel visitor applied to cu1proc1point1                 <========
*     [sA]         point parallel visitor applied to cu1proc1point2                 <========
*     [sA]         [remaining points in cu1proc1]                                   <--------
*     [sA]    procedure parallel finish visitors applied to cu1proc1
*     [sA]    [remaining procedures in cu1]                                         <--------
*     [sA]    [parallel visitors applied to source files and file instances in cu1]
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]                      <--------
*     [remaining compunits]                                                         <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.symbol_parallel_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase visitor for symbols ( symbol ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to symbols in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to symbols ( symbol ) in the project that are contained in a compilation unit whose language appears in langs.

  • In base analyses, it will be applied to every such symbol in the project.
  • In incremental analyses, it will be applied only to symbols contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     symbol parallel visitor applied to symbol cu1proc1fsym (function symbol for cu1proc1) <========
*     [sA]     [parallel visitors applied to source files and file instances in cu1]
*     [sA]     procedure parallel visitors applied to cu1proc1
*     [sA]         symbol parallel visitor applied to cu1proc1vsym1                                  <========
*     [sA]         symbol parallel visitor applied to cu1proc1vsym2                                  <========
*     [sA]         [remaining symbols in cu1proc1]                                                   <--------
*     [sA]         [parallel visitors applied to points contained in cu1proc1
*     [sA]     procedure parallel finish visitors applied to cu1proc1
*     [sA]     [remaining procedures in cu1]                                                         <--------
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]                                       <--------
*     [remaining compunits]                                                                          <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfile_parallel_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase visitor for (representative instances of) files in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to files in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to the representative instances ( sfileinst ) of source files contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to the representative instance of every such source file in the project.
  • In incremental analyses, it will be applied only to representative instances of source files for which all remaining instances are contained in compilation units compiled in the increment.

Note that the visitor is applied to a sfileinst (not a sfile ).

* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     [parallel visitors applied to compunit-level symbols in cu1]
*     [sA]     sfile parallel visitors applied to representative instance of top-level source file f1 in cu1...            <========
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     sfileinst parallel visitors applied to f1 instance (always)
*     [sA]         sfile parallel visitors applied to representative instance of file f1inc1 included in f1...             <========
*                    ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]         sfileinst parallel visitors applied to f1inc1 instance (always)
*     [sA]             sfile parallel visitors applied to representative instance of file f1inc1inc1 included in f1inc1... <========
*                        ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]             sfileinst parallel visitors applied to f1inc1inc1 instance (always)
*     [sA]                 [traverse f1inc1inc1 include tree]                                                              <--------
*     [sA]             sfileinst parallel finish visitors applied to f1inc1inc1 instance (always)
*     [sA]             sfile parallel finish visitors applied to representative instance of f1inc1inc1...
*                        ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]             [traverse remainder of f1inc1 include tree]                                                         <--------
*     [sA]         sfileinst parallel finish visitors applied to f1inc1 instance (always)
*     [sA]         sfile parallel finish visitors applied to f1inc1...
*                    ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]         [traverse remainder of f1 include tree]                                                                 <--------
*     [sA]     sfileinst parallel finish visitors applied to f1 instance (always)
*     [sA]     sfile parallel finish visitors applied to representative instance of f1...
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     [parallel visitors applied to procedures,points,symbols in cu1]
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]                                                             <--------
*     [remaining compunits]                                                                                                <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfile_parallel_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase finish visitor for (representative instances of) files in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to files in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to the representative instances ( sfileinst ) of source files contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to the representative instance of every such source file in the project.
  • In incremental analyses, it will be applied only to the representative instances of source files for which all remaining instances are contained in compilation units compiled in the increment.

Note that the visitor is applied to a sfileinst (not a sfile ).

* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     [parallel visitors applied to compunit-level symbols in cu1]
*     [sA]     sfile parallel visitors applied to representative instance of top-level source file f1 in cu1...
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     sfileinst parallel visitors applied to f1 instance (always)
*     [sA]         sfile parallel visitors applied to representative instance of file f1inc1 included in f1...
*                    ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]         sfileinst parallel visitors applied to f1inc1 instance (always)
*     [sA]             sfile parallel visitors applied to representative instance of file f1inc1inc1 included in f1inc1...
*                        ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]             sfileinst parallel visitors applied to f1inc1inc1 instance (always)
*     [sA]                 [traverse f1inc1inc1 include tree]                                             <--------
*     [sA]             sfileinst parallel finish visitors applied to f1inc1inc1 instance (always)
*     [sA]             sfile parallel finish visitors applied to representative instance of f1inc1inc1... <========
*                         ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]             [traverse remainder of f1inc1 include tree]                                        <--------
*     [sA]         sfileinst parallel finish visitors applied to f1inc1 instance (always)
*     [sA]         sfile parallel finish visitors applied to representative instance of f1inc1...         <========
*                    ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]         [traverse remainder of f1 include tree]                                                <--------
*     [sA]     sfileinst parallel finish visitors applied to f1 instance (always)
*     [sA]     sfile parallel finish visitors applied to representative instance of f1...                 <========
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     [parallel visitors applied to procedures,points,symbols in cu1]
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]                                            <--------
*     [remaining compunits]                                                                               <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfileinst_parallel_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase visitor for file instances ( sfileinst ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to file instances in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to source file instances ( sfile ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such source file instance in the project.
  • In incremental analyses, it will be applied only to source file instances contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     [parallel visitors applied to compunit-level symbols in cu1]
*     [sA]     sfile parallel visitors applied to representative instance of top-level source file f1 in cu1...
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     sfileinst parallel visitors applied to f1 instance (always)                                              <========
*     [sA]         sfile parallel visitors applied to representative instance of file f1inc1 included in f1...
*                    ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]         sfileinst parallel visitors applied to f1inc1 instance (always)                                      <========
*     [sA]             sfile parallel visitors applied to representative instance of file f1inc1inc1 included in f1inc1...
*                        ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]             sfileinst parallel visitors applied to f1inc1inc1 instance (always)                              <========
*     [sA]                 [traverse f1inc1inc1 include tree]                                                           <--------
*     [sA]             sfileinst parallel finish visitors applied to f1inc1inc1 instance (always)
*     [sA]             sfile parallel finish visitors applied to representative instance of f1inc1inc1...
*                        ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]             [traverse remainder of f1inc1 include tree]                                                      <--------
*     [sA]         sfileinst parallel finish visitors applied to f1inc1 instance (always)
*     [sA]         sfile parallel finish visitors applied to representative instance of f1inc1...
*                    ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]         [traverse remainder of f1 include tree]                                                              <--------
*     [sA]     sfileinst parallel finish visitors applied to f1 instance (always)
*     [sA]     sfile parallel finish visitors applied to representative instance of f1...
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     [parallel visitors applied to procedures,points,symbols in cu1]
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]                                                          <--------
*     [remaining compunits]                                                                                             <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.sfileinst_parallel_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a parallel depth-first phase visitor for file instances ( sfileinst ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to file instances in compilation units whose language is one of these.

During the parallel depth-first analysis phase, the visitor (decorated function) will be applied to source file instances ( sfile ) contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such source file instance in the project.
  • In incremental analyses, it will be applied only to source file instances contained in compilation units compiled in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* program parallel visitors
*   (parallel depth-first traversal: analysis slaves sA, sB,... may run in parallel)
*     [sA] compunit parallel visitors applied to cu1
*     [sA]     [parallel visitors applied to compunit-level symbols in cu1]
*     [sA]     sfile parallel visitors applied to representative instance of top-level source file f1 in cu1...
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     sfileinst parallel visitors applied to f1 instance (always)
*     [sA]         sfile parallel visitors applied to representative instance of file f1inc1 included in f1...
*                    ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]         sfileinst parallel visitors applied to f1inc1 instance (always)
*     [sA]             sfile parallel visitors applied to representative instance of file f1inc1inc1 included in f1inc1...
*                        ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]             sfileinst parallel visitors applied to f1inc1inc1 instance (always)
*     [sA]                 [traverse f1inc1inc1 include tree]                                                      <--------
*     [sA]             sfileinst parallel finish visitors applied to f1inc1inc1 instance (always)                  <========
*     [sA]             sfile parallel finish visitors applied to representative instance of f1inc1inc1...
*                        ...IF AND ONLY IF this is first time f1inc1inc1 is encountered
*     [sA]            [traverse remainder of f1inc1 include tree]                                                  <--------
*     [sA]        sfileinst parallel finish visitors applied to f1inc1 instance (always)                           <========
*     [sA]        sfile parallel finish visitors applied to representative instance of f1inc1...
*                   ...IF AND ONLY IF this is first time f1inc1 is encountered
*     [sA]        [traverse remainder of f1 include tree]                                                          <--------
*     [sA]     sfileinst parallel finish visitors applied to f1 instance (always)                                  <========
*     [sA]     sfile parallel finish visitors applied to representative instance of f1...
*                ...IF AND ONLY IF this is first time f1 is encountered
*     [sA]     [parallel visitors applied to procedures,points,symbols in cu1]
*     [sA] compunit parallel finish visitors applied to cu1
*     [sB] [traverse compunit cu2, applying parallel visitors]                                                     <--------
*     [remaining compunits]                                                                                        <--------
* program parallel finish visitors
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.project_bottom_up_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a bottom-up program visitor for programs ( project ) whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to programs in these languages ( language ).

the decorated function will be applied to the project at the beginning of the bottom-up phase, before the bottom-up traversal begins.

* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* program bottom-up visitors                          <=======
*     [bottom-up traversal]
* program bottom-up finish visitors
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.procedure_bottom_up_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a bottom-up phase visitor for procedures ( procedure ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to procedures in compilation units whose language is one of these.

During the bottom-up analysis phase, the visitor (decorated function) will be applied to procedures ( procedure ) that are contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such procedure in the project.
  • In incremental analyses, it will be applied only to procedures F for which at least one of the following is true.
    • F is contained in a compilation unit that was compiled in the increment.
    • F’s summary is needed for incremental analysis and had to be recomputed because it relied on elements that were deleted or modified by changes in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* program bottom-up visitors
*   (bottom-up traversal)
*     procedure bottom up visitors applied to proc1             <========
*         point bottom up visitors applied to points in proc1
*         step visitors applied to CFG edges in proc1
*     procedure bottom up finish visitors applied to proc1
*     procedure bottom up visitors applied to proc2             <========
*         point bottom up visitors applied to points in proc2
*         step visitors applied to CFG edges in proc2
*     procedure bottom up finish visitors applied to proc2
*     [remaining procedures]                                    <--------
* program bottom-up finish visitors
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.point_bottom_up_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a bottom-up phase visitor for points ( point ) in compilation units whose languages appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to points in compilation units whose language is one of these.

During the bottom-up analysis phase, the visitor (decorated function) will be applied to procedures ( procedure ) that are contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such procedure in the project.
  • In incremental analyses, it will be applied only to procedures F for which at least one of the following is true.
    • F is contained in a compilation unit that was compiled in the increment.
    • F's summary is needed for incremental analysis and had to be recomputed because it relied on elements that were deleted or modified by changes in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* program bottom-up visitors
*   (bottom-up traversal)
*     procedure bottom up visitors applied to proc1
*         point bottom up visitors applied to proc1point1   <========
*         point bottom up visitors applied to proc1point2   <========
*         [remaining points in proc1]
*         [step visitors applied to CFG edges in proc1]
*     procedure bottom up finish visitors applied to proc1
*     [remaining procedures]                                <--------
* program bottom-up finish visitors
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.procedure_bottom_up_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a bottom-up phase finish visitor for procedures ( procedure ) in compilation units whose languages ( language ) appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to procedures in compilation units whose language is one of these.

During the bottom-up analysis phase, the visitor (decorated function) will be applied to procedures ( procedure ) that are contained in compilation units whose language appears in langs.

  • In base analyses, it will be applied to every such procedure in the project.
  • In incremental analyses, it will be applied only to procedures F for which at least one of the following is true.
    • F is contained in a compilation unit that was compiled in the increment.
    • F's summary is needed for incremental analysis and had to be recomputed because it relied on elements that were deleted or modified by changes in the increment.
* [drop phase]              (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* program bottom-up visitors
*   (bottom-up traversal)
*     procedure bottom up visitors applied to proc1
*         [point bottom up visitors applied to points in proc1]
*         [step visitors applied to CFG edges in proc1]
*     procedure bottom up finish visitors applied to proc1      <========
*     procedure bottom up visitors applied to proc2
*         [point bottom up visitors applied to points in proc2]
*         [step visitors applied to CFG edges in proc2]
*     procedure bottom up finish visitors applied to proc2      <========
*     [remaining procedures]                                    <--------
* program bottom-up finish visitors
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.project_finish_visitor([langs = ( language.WILDCARD, )])

Add the decorated function as a serial depth-first program finish visitor for programs ( project ) whose languages ( language ) appear in langs.

Parameters:langs (iterable of language) – (optional) The visitor will only be applied to programs in these languages ( language ).

v will be applied to the project at the end of the serial depth-first phase, after the serial depth-first traversal has finished.

* [drop phase]              (incremental only)
* program setup visitors
* program visitors
*     [serial depth-first traversal]
* program finish visitors                             <=======
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.project_drop_visitor

Add v to the list of program drop visitors, which are invoked at the beginning of the drop phase.

For incremental analyses, v will be applied to the project at the beginning of the drop phase if anything in the project has been dropped. (No drop visitors are applied in base analyses, which do not have a drop phase.)

* program drop visitors         (incremental only)  <=======
*     [drop traversal]          (incremental only)
* program drop finish visitors  (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Use a program drop visitor when you need to clean up state that you have saved for dropped project components and cannot handle the cleanup with one of the smaller-scope drop visitors. You do not need to handle cleanup for the project itself: CodeSonar will do that.

Restriction: the visitor (decorated function) must not call any API functions other than the following: procedure.__eq__(), procedure.__hash__(), compunit.__eq__(), compunit.__hash__(), symbol.__eq__(), symbol.__hash__().

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.compunit_drop_visitor

Add the decorated function as a drop phase compilation unit ( compunit ) visitor.

For incremental analyses, v will be applied during the drop phase to every compilation unit ( compunit ) U for which at least one of the following is true.

  • U has been dropped
  • a file static in U has been dropped
  • the include tree for U has changed

(No drop visitors are applied in base analyses, which do not have a drop phase.)

* program drop visitors         (incremental only)
*     [drop traversal]          (incremental only)  <=======
* program drop finish visitors  (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Use a compilation unit drop visitor to clean up any state you have saved for:

  • the compilation unit
  • any file instances in the compilation unit
  • any ASTs in the compilation unit
  • any component you can clean up with a procedure drop visitor: see procedure_drop_visitor().

You do not need to handle cleanup for the compunit object itself: CodeSonar will do that.

Restriction: the visitor (decorated function) must not call any API functions other than the following: procedure.__eq__(), procedure.__hash__(), compunit.__eq__(), compunit.__hash__(), symbol.__eq__(), symbol.__hash__().

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.procedure_drop_visitor

Add the decorated function as a drop phase procedure visitor.

For incremental analyses, v will be applied during the drop phase to every procedure F for which at least one of the following is true.

  • F has been dropped
  • a function static variable in F has been dropped
  • a point in F has been dropped

(No drop visitors are applied in base analyses, which do not have a drop phase.)

* program drop visitors         (incremental only)
*     [drop traversal]          (incremental only)  <=======
* program drop finish visitors  (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Use a procedure drop visitor to clean up any state that you have saved for:

  • the procedure
  • any ( point , edge_label ) whose target is in the procedure
  • any point in the procedure
  • any symbol whose scope is restricted to the procedure

You do not need to handle cleanup for the procedure object itself: CodeSonar will do that.

Restriction: the visitor (decorated function) must not call any API functions other than the following: procedure.__eq__(), procedure.__hash__(), compunit.__eq__(), compunit.__hash__(), symbol.__eq__(), symbol.__hash__().

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.global_symbol_drop_visitor

Add the decorated function as a drop phase visitor for global symbols ( symbol ).

For incremental analyses, v will be applied during the drop phase to every global symbol that has been dropped. (No drop visitors are applied in base analyses, which do not have a drop phase.)

* program drop visitors         (incremental only)
*     [drop traversal]          (incremental only)  <=======
* program drop finish visitors  (incremental only)
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Use a global symbol drop visitor to clean up any state that you have saved for:

  • the symbol

You do not need to handle cleanup for the symbol object itself: CodeSonar will do that.

Restriction: the visitor (decorated function) must not call any API functions other than the following: procedure.__eq__(), procedure.__hash__(), compunit.__eq__(), compunit.__hash__(), symbol.__eq__(), symbol.__hash__().

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.project_drop_finish_visitor

Add v to the list of program drop finish visitors, which are invoked at the end of the drop phase.

For incremental analyses, the visitor (decorated function) will be applied to the project at the end of the drop phase if anything in the project has been dropped. (No drop visitors are applied in base analyses, which do not have a drop phase.)

* program drop visitors         (incremental only)
*     [drop traversal]              (incremental only)
* program drop finish visitors  (incremental only)  <=======
* program setup visitors
* [serial depth-first phase]
* [parallel depth-first phase]
* [pointer analysis]
* [bottom-up phase]
*

Use a program drop finish visitor when you need to clean up state that you have saved for dropped project components and cannot handle the cleanup with one of the smaller-scope drop visitors.

Restriction: the visitor (decorated function) must not call any API functions other than the following: procedure.__eq__(), procedure.__hash__(), compunit.__eq__(), compunit.__hash__(), symbol.__eq__(), symbol.__hash__().

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.

@cs.cache_cleanup_visitor

Add the decorated function as a cache-cleanup visitor.

Cache-cleanup visitors are invoked periodically as the analysis progresses.

Only suitable for use in your plug-in’s top-level scope. Do not use it inside visitors.