toInsert - the instrumentation to be added in the Chain
point_src - the source point of an edge in CFG
point_tgt - the target point of an edge in CFG
The insertOnEdge API correctly adds instructions (toInsert) to the target program (Body) on an edge. In a Control Flow Graph, such a directed edge would be represented by a source point (point_src) and a target unit (point_tgt).
Without this API, instrumenting certain edges can prove difficult and time consuming to the user.
Consider the following if condition:
The control flow graph for the above code is as follows:
Assume that the user wishes to instrument all three edges with a statement toInsert.
Edge 1: Can be instrumented using body.getUnits().insertAfter(toInsert, Unit1)
Edge 2: Can be instrumented using body.getUnits().insertBeforeNoRedirect(toInsert, Unit3)
Edge 3: ????
None of the APIs previously available enables a user to easily instrument only the false branch (Edge 3). Neither insertBefore unit3 nor insertAfter unit1 will work. Using insertBefore unit3 will cause the instrumentation to be executed no matter which branch the program takes.
insertOnEdge(toInsert, null, target) Doing this is same as performing insertBefore(toInsert, target). All jumps to target is redirected to toInsert
insertOnEdge(toInsert, source, null) Doing this is same as performing insertAfter(toInsert, source)
insertOnEdge(toInsert, source, target) This adds an instrumentation in a manner such that the resulting CFG of the program will contain toInsert on an edge that is defined by source and target. insertOnEdge will throw RuntimeException if such an edge does not exist in the program’s CFG.
insertOnEdge(toInsert, null, null) Just don’t do this. insertOnEdge will throw a RuntimeException.