Visitors

• Overview
• Available Visitor Types
• Additional Notes
• Example
• Adding Visitors
• More on Plug-Ins

Overview

Visitors specify actions to be carried out on elements of the CodeSonar internal representation (IR) at various stages of the analysis.

Most visitors consist of a function and a list of languages, except for step visitors (which consist of a set of four functions and a list of languages). Visitors can be attached to any of a number of visitor lists, which determine when and to which IR element types the function will be applied. The list of languages in the visitor provides an additional level of control: the function will only be applied to IR elements whose language appears on the list.

Each visitor list is associated with an element type, a traversal phase, and a visit time.

Available Visitor Types

The following table shows the available visitor types.

• [*] See the additional notes on program visitors.
• [**] Global symbols only.

Note that there are no finish visitors for source file instances, points (PDG_VERTEX) or variable symbols (ABS_LOC). This is because they are leaves of the traversal trees: no traversal takes place below them, so there is no distinction between starting and finishing.

Additional Notes

• Program-level Visitors
• Step Visitors
• Drop Visitors
• Parallel Analyses
• Incremental Analyses

Program-level Visitors

Program-level visitors are not actually applied during the analysis traversals, but immediately before and after them.

• Drop visitors are applied during the drop phase, before the analysis traversals begin.
  • Program drop visitors are applied before the beginning of the drop traversal.
  • Program drop finish visitors are applied after the end of the drop traversal.
• Setup visitors are applied after the drop traversal (if any) but before anything else. New warning classes and new metric classes can only be created in program setup visitors.
• Serial depth-first visitors are applied during the serial depth-first analysis phase.
  • Program visitors are applied at the beginning of the serial depth-first analysis phase, before the serial depth-first traversal begins.
  • Program finish visitors are applied at the end of the serial depth-first analysis phase, after the serial depth-first traversal has finished.
• Parallel depth-first visitors are applied during the parallel depth-first analysis phase.
  • Program parallel visitors are applied at the beginning of the parallel depth-first analysis phase, before the parallel depth-first traversal begins.
  • Program finish visitors are applied at the end of the parallel depth-first analysis phase, after the parallel depth-first traversal has finished.
• Bottom-up visitors are applied during the bottom-up analysis phase.
  • Program bottom-up visitors are applied at the beginning of the bottom-up phase, before the bottom-up traversal begins.
  • Program bottom-up finish visitors are applied at the end of the bottom-up phase, after the bottom-up traversal has finished. Since the bottom-up phase is the last one, these are the last visitors to be applied to the program.

Step Visitors

There are several differences between step visitors and the other kinds of visitor:

• Step visitors can include operations on a user-defined type (referred to here as USER_STATE), that keeps track of program state as CodeSonar explores the program procedures.
• CodeSonar will do bookkeeping for USER_STATE values, including making copies (with the specified copy() operation) when there are branches in the CFG and destroying them (with the specified close() operation) when they are no longer needed.
• While other kinds of visitor are expressed in terms of a single function, a step visitor involves four different operations:

  open()	() -> USER_STATE Create a new USER_STATE: will be called by CodeSonar every time the step traversal enters a function.
  copy()	USER_STATE -> USER_STATE Copy a USER_STATE: will be called by CodeSonar every time the step traversal encounters a branch in the CFG.
  close()	USER_STATE -> () Close a USER_STATE and perform any necessary cleanup: will be called by CodeSonar when a USER_STATE is no longer needed.
  transition()	(USER_STATE, POINT, CFG_EDGE_LABEL, POINT, TRANSFORM, TRANSFORM, STEP_PATH) -> USER_STATE Perform any operations associated with a specified transition in the CFG, and return the resulting USER_STATE. Called by CodeSonar every time the step traversal moves across a CFG edge. If the state is stored in USER_STATE, the transition function will not need to depend on the traversal order. However, for the sake of completeness, we note that the step traversal is currently breadth first. This may change in future releases.

  The mechanism used to associate these operations with the visitor depends on the API language. See Adding: Step Visitors, below, for details.

Step visitors have the following limitations.

• When the CFG involves loops, the step traversal will model a finite number of iterations. This can cause loss of precision and false negatives.
• It is possible to create programs that contain more branches than the step traversal can track. In such cases some parts of the traversal may be dropped, which can in turn lead to false negatives.

Note: Step visitors will generally not produce useful information when applied to C# and Java analyses, because internal representation for points is not generated for those analyses .

Drop Visitors

When CodeSonar runs in incremental mode, drop visitors are applied during the drop phase to IR elements that existed in the previous analysis of the project but will not exist in the current analysis.

Use drop visitors to clean up any additional information that your plug-in has associated with these elements. Drop visitors are not responsible for cleaning up the elements themselves: CodeSonar will do that.

Because the IR elements no longer exist, drop visitors should not access their contents. The only API functions that can be called by drop visitors are:

• warning retraction functions, and
• equality tests and hash functions on the procedure (PDG), compilation unit, and symbol (ABS_LOC) types.

Visitors in Parallel Analyses

If the analysis runs in serial mode, all visitors are called by the analysis process. In parallel analyses, responsibility for applying visitors is divided between the analysis master and the analysis slaves as shown in the following table.

An example trace is provided below.

Visitors in Incremental Analyses

In incremental analyses, visitors are applied as follows.

Example

Here is an example trace of calls that CodeSonar might make to the various visitors for a program with two compilation units, each including foo.h and defining two procedures, each with two points, two CFG edges, and two local symbols. All procedures have no arguments and return void. Assume pdg4 calls pdg1 which calls pdg3 which calls pdg2. The order in which visitors registered with the same function are called is undefined. Assume there is exactly one visitor of each kind.

In this example, the analysis is running in parallel mode (see Visitors in Parallel Analyses above for more information). For the sake of clarity we refer to slaves A, B, C and D in the trace that follows; note that:

• the degree to which slaves can run in parallel is limited by the ANALYSIS_SLAVES and MAX_ANALYSIS_SLAVES settings, and
• a single slave may be assigned more than one procedure analysis task (in series), for example the names "slave A" and "slave D" may represent the same process.

CALLING  | VISITOR
PROCESS  |
---------+--------
master   |  setup_visitor
master   |   program_visitor
master   |     uid_visitor(uid1)
master   |         pdg_visitor(pdg1 in uid1)
master   |         abs_loc_visitor(function abs_loc alf1 corresponding to pdg1)
master   |             abs_loc_visitor(al1 referenced in pdg1)
master   |             abs_loc_visitor(al2 referenced in pdg1)
master   |             pdg_vertex_visitor(v1 in pdg1)
master   |             pdg_vertex_visitor(v2 in pdg1)
master   |         pdg_finish_visitor(pdg1 in uid1)
master   |         pdg_visitor(pdg2 in uid1)
master   |         abs_loc_visitor(function abs_loc alf2 corresponding to pdg2)
master   |             abs_loc_visitor(al3 referenced in pdg2)
master   |             abs_loc_visitor(al4 referenced in pdg2)
master   |             pdg_vertex_visitor(v3 in pdg2)
master   |             pdg_vertex_visitor(v4 in pdg2)
master   |         pdg_finish_visitor(pdg2 in uid1)
master   |         sf_visitor(sfid1 (=comp1.c) )
master   |             sfi_visitor(sfid1 (=comp1.c) )
master   |                 sf_visitor(sfid2 (=foo.h) )
master   |                     sfi_visitor(sfid2 (=foo.h) )
master   |                     sfi_finish_visitor(sfid2 (=foo.h) )
master   |                 sf_finish_visitor(sfid2 (=foo.h) )
master   |             sfi_finish_visitor(sfid1 (=comp1.c) )
master   |         sf_finish_visitor(sfid1 (=comp1.c) )
master   |     uid_finish_visitor(uid1)
master   |     uid_visitor(uid2)
master   |         pdg_visitor(pdg3 in uid2)
master   |         abs_loc_visitor(function abs_loc alf3 corresponding to pdg3)
master   |             abs_loc_visitor(al5 referenced in pdg3)
master   |             abs_loc_visitor(al6 referenced in pdg3)
master   |             pdg_vertex_visitor(v5 in pdg3)
master   |             pdg_vertex_visitor(v6 in pdg3)
master   |         pdg_finish_visitor(pdg3 in uid2)
master   |         pdg_visitor(pdg4 in uid2)
master   |         abs_loc_visitor(function abs_loc alf4 corresponding to pdg4)
master   |             abs_loc_visitor(al7 referenced in pdg4)
master   |             abs_loc_visitor(al8 referenced in pdg4)
master   |             pdg_vertex_visitor(v7 in pdg4)
master   |             pdg_vertex_visitor(v8 in pdg4)
master   |         pdg_finish_visitor(pdg4 in uid2)
master   |         sf_visitor(sfid3 (=comp2.c) )
master   |             sfi_visitor(sfid3 (=comp2.c) )
master   |                 sfi_visitor(sfid4 (=foo.h) )
master   |                 sfi_finish_visitor(sfid4 (=foo.h) )
master   |             sfi_finish_visitor(sfid3 (=comp2.c) )
master   |         sf_finish_visitor(sfid3 (=comp2.c) )
master   |     uid_finish_visitor(uid2)
master   |   program_finish_visitor
master   |   program_parallel_visitor
slave A  |     uid_parallel_visitor(uid1)
slave A  |         pdg_parallel_visitor(pdg1 in uid1)
slave A  |         abs_loc_parallel_visitor(function abs_loc alf1 corresponding to pdg1)
slave A  |             abs_loc_parallel_visitor(al1 referenced in pdg1)
slave A  |             abs_loc_parallel_visitor(al2 referenced in pdg1)
slave A  |             pdg_vertex_parallel_visitor(v1 in pdg1)
slave A  |             pdg_vertex_parallel_visitor(v2 in pdg1)
slave A  |         pdg_parallel_finish_visitor(pdg1 in uid1)
slave A  |         pdg_parallel_visitor(pdg2 in uid1)
slave A  |         abs_loc_parallel_visitor(function abs_loc alf2 corresponding to pdg2)
slave A  |             abs_loc_parallel_visitor(al3 referenced in pdg2)
slave A  |             abs_loc_parallel_visitor(al4 referenced in pdg2)
slave A  |             pdg_vertex_parallel_visitor(v3 in pdg2)
slave A  |             pdg_vertex_parallel_visitor(v4 in pdg2)
slave A  |         pdg_parallel_finish_visitor(pdg2 in uid1)
slave A  |         sf_parallel_visitor(sfid1 (=comp1.c) )
slave A  |             sfi_parallel_visitor(sfid1 (=comp1.c) )
slave A  |                 sf_parallel_visitor(sfid2 (=foo.h) )
slave A  |                     sfi_parallel_visitor(sfid2 (=foo.h) )
slave A  |                     sfi_parallel_finish_visitor(sfid2 (=foo.h) )
slave A  |                 sf_parallel_finish_visitor(sfid2 (=foo.h) )
slave A  |             sfi_parallel_finish_visitor(sfid1 (=comp1.c) )
slave A  |         sf_parallel_finish_visitor(sfid1 (=comp1.c) )
slave A  |     uid_parallel_finish_visitor(uid1)
slave B  |     uid_parallel_visitor(uid2)
slave B  |         pdg_parallel_visitor(pdg3 in uid2)
slave B  |         abs_loc_parallel_visitor(function abs_loc alf3 corresponding to pdg3)
slave B  |             abs_loc_parallel_visitor(al5 referenced in pdg3)
slave B  |             abs_loc_parallel_visitor(al6 referenced in pdg3)
slave B  |             pdg_vertex_parallel_visitor(v5 in pdg3)
slave B  |             pdg_vertex_parallel_visitor(v6 in pdg3)
slave B  |         pdg_parallel_finish_visitor(pdg3 in uid2)
slave B  |         pdg_parallel_visitor(pdg4 in uid2)
slave B  |         abs_loc_parallel_visitor(function abs_loc alf4 corresponding to pdg4)
slave B  |             abs_loc_parallel_visitor(al7 referenced in pdg4)
slave B  |             abs_loc_parallel_visitor(al8 referenced in pdg4)
slave B  |             pdg_vertex_parallel_visitor(v7 in pdg4)
slave B  |             pdg_vertex_parallel_visitor(v8 in pdg4)
slave B  |         pdg_parallel_finish_visitor(pdg4 in uid2)
slave B  |         sf_parallel_visitor(sfid3 (=comp2.c) )
slave B  |             sfi_parallel_visitor(sfid3 (=comp2.c) )
slave B  |                 sfi_parallel_visitor(sfid4 (=foo.h) )
slave B  |                 sfi_parallel_finish_visitor(sfid4 (=foo.h) )
slave B  |             sfi_parallel_finish_visitor(sfid3 (=comp2.c) )
slave B  |         sf_parallel_finish_visitor(sfid3 (=comp2.c) )
slave B  |     uid_parallel_finish_visitor(uid2)
master   |   program_parallel_finish_visitor
master   |   program_bottom_up_visitor
slave A  |     pdg_bottom_up_visitor(pdg2)
slave A  |        pdg_vertex_bottom_up_visitor(v3 in pdg2)
slave A  |        pdg_vertex_bottom_up_visitor(v4 in pdg2)
slave A  |        step_visitor(cfg edge e3 in pdg2)
slave A  |        step_visitor(cfg edge e4 in pdg2)
slave A  |     pdg_bottom_up_finish_visitor(pdg2)
slave B  |     pdg_bottom_up_visitor(pdg3)
slave B  |        pdg_vertex_bottom_up_visitor(v5 in pdg3)
slave B  |        pdg_vertex_bottom_up_visitor(v6 in pdg3)
slave B  |        step_visitor(cfg edge e5 in pdg3)
slave B  |        step_visitor(cfg edge e6 in pdg3)       
slave B  |     pdg_bottom_up_finish_visitor(pdg3)
slave C  |     pdg_bottom_up_visitor(pdg1)
slave C  |        pdg_vertex_bottom_up_visitor(v1 in pdg1)
slave C  |        pdg_vertex_bottom_up_visitor(v2 in pdg1)
slave C  |        step_visitor(cfg edge e1 in pdg1)
slave C  |        step_visitor(cfg edge e2 in pdg2)
slave C  |     pdg_bottom_up_finish_visitor(pdg1)
slave D  |     pdg_bottom_up_visitor(pdg4)
slave D  |        pdg_vertex_bottom_up_visitor(v7 in pdg4)
slave D  |        pdg_vertex_bottom_up_visitor(v8 in pdg4)
slave D  |        step_visitor(cfg edge e7 in pdg4)
slave D  |        step_visitor(cfg edge e8 in pdg4)
slave D  |     pdg_bottom_up_finish_visitor(pdg4)
master   |   program_bottom_up_finish_visitor

Defining and Adding Visitors

Visitors other than step visitors are added by defining a visitor function and then instructing CodeSonar to add it as a particular kind of visitor. Step visitors involve a slightly different mechanism.

In both cases, the adding operation must take place in a specific location.

Adding: All visitor types except step visitors

There are two stages involved in adding a visitor.

1. Implement the function that will carry out the work of the visitor.
2. Instruct CodeSonar to add the function to the appropriate visitor list.

Adding: Step visitors

There are three stages involved in adding a step visitor.

1. Identify the state information that the visitor will need to track (this will be the USER_STATE described above).

   API language	USER_STATE corresponds to
   C++	an instance of a concrete cs::step_state subclass
   Python	an instance of a concrete cs.step_state subclass
   C	data of type cs_step_user_state_t (treated as opaque by CodeSonar)

2. Implement the step visitor operations open (where required), copy, transition, close with respect to USER_STATE and the goals of the step visitor.
3. Instruct CodeSonar to add the step visitor.

Visitor-Adding Functionality, by Phase.

The following table shows the API functions for adding visitors at the various build/analysis phases.

More on Plug-Ins

General Information:

Specific API Language: