Class Subroutines

java.lang.Object
org.apache.bcel.verifier.structurals.Subroutines

public class Subroutines extends Object
Instances of this class contain information about the subroutines found in a code array of a method. This implementation considers the top-level (the instructions reachable without a JSR or JSR_W starting off from the first instruction in a code array of a method) being a special subroutine; see getTopLevel() for that. Please note that the definition of subroutines in the Java Virtual Machine Specification, Second Edition is somewhat incomplete. Therefore, JustIce uses an own, more rigid notion. Basically, a subroutine is a piece of code that starts at the target of a JSR of JSR_W instruction and ends at a corresponding RET instruction. Note also that the control flow of a subroutine may be complex and non-linear; and that subroutines may be nested. JustIce also mandates subroutines not to be protected by exception handling code (for the sake of control flow predictability). To understand JustIce's notion of subroutines, please read TODO: refer to the paper.
See Also:
  • Field Details

    • subroutines

      private final Map<InstructionHandle,Subroutine> subroutines
      The map containing the subroutines found. Key: InstructionHandle of the leader of the subroutine. Elements: SubroutineImpl objects.
    • TOPLEVEL

      public final Subroutine TOPLEVEL
      This is referring to a special subroutine, namely the top level. This is not really a subroutine but we use it to distinguish between top level instructions and unreachable instructions.
  • Constructor Details

    • Subroutines

      public Subroutines(MethodGen mg)
      Constructs a new instance.
      Parameters:
      mg - A MethodGen object representing method to create the Subroutine objects of. Assumes that JustIce strict checks are needed.
    • Subroutines

      public Subroutines(MethodGen mg, boolean enableJustIceCheck)
      Constructs a new instance.
      Parameters:
      mg - A MethodGen object representing method to create the Subroutine objects of.
      enableJustIceCheck - whether to enable additional JustIce checks.
      Since:
      6.0
  • Method Details

    • getSuccessors

      private static InstructionHandle[] getSuccessors(InstructionHandle instruction)
      A utility method that calculates the successors of a given InstructionHandle in the same subroutine. That means, a RET does not have any successors as defined here. A JsrInstruction has its physical successor as its successor (opposed to its target) as defined here.
    • recursiveCallException

      private static StructuralCodeConstraintException recursiveCallException(Subroutine sub2)
    • getSubroutine

      public Subroutine getSubroutine(InstructionHandle leader)
      Returns the Subroutine object associated with the given leader (that is, the first instruction of the subroutine). You must not use this to get the top-level instructions modeled as a Subroutine object.
      Parameters:
      leader - The leader instruction handle.
      Returns:
      The Subroutine object.
      See Also:
    • getTopLevel

      public Subroutine getTopLevel()
      For easy handling, the piece of code that is not a subroutine, the top-level, is also modeled as a Subroutine object. It is a special Subroutine object where you must not invoke getEnteringJsrInstructions() or getLeavingRET().
      Returns:
      The top-level Subroutine.
      See Also:
    • noRecursiveCalls

      private void noRecursiveCalls(Subroutine sub)
      This utility method makes sure that no subroutine is calling a subroutine that uses the same local variable for the RET as themselves (recursively). This includes that subroutines may not call themselves recursively, even not through intermediate calls to other subroutines. Every subroutine is fully validated exactly once, memoizing the RET local variable indices used anywhere in its call subtree. The former implementation re-explored a subroutine once per call path, which is exponential in the number of subroutines for a layered JSR call graph.
      Throws:
      StructuralCodeConstraintException - Thrown if the above constraint is not satisfied.
    • noRecursiveCalls

      private BitSet noRecursiveCalls(Subroutine sub, BitSet pathLocals, Map<Subroutine,BitSet> validated, Map<Integer,Integer> localIds)
      The recursive helper for noRecursiveCalls(Subroutine).
      Parameters:
      sub - the subroutine whose callees are validated.
      pathLocals - compact ids (see localIds) of the RET local variables used by the subroutines on the current call path.
      validated - maps every fully validated subroutine to the compact ids of the RET local variables used by it and its entire call subtree.
      localIds - maps a RET local variable index to a compact id so the bit sets stay small.
      Returns:
      the compact ids of the RET local variables used by sub's callees and their call subtrees.
      Throws:
      StructuralCodeConstraintException - Thrown if a subroutine calls a subroutine using the same RET local variable.
    • subroutineOf

      public Subroutine subroutineOf(InstructionHandle any)
      Returns the subroutine object associated with the given instruction. This is a costly operation, you should consider using getSubroutine(InstructionHandle). Returns 'null' if the given InstructionHandle lies in so-called 'dead code', for example code that can never be executed.
      Parameters:
      any - The instruction handle.
      Returns:
      The Subroutine object or null.
      See Also:
    • toString

      public String toString()
      Returns a String representation of this object; merely for debugging puposes.
      Overrides:
      toString in class Object