Class Label
- java.lang.Object
-
- org.datanucleus.enhancer.asm.Label
-
public class Label extends java.lang.Object
A position in the bytecode of a method. Labels are used for jump, goto, and switch instructions, and for try catch blocks. A label designates the instruction that is just after. Note however that there can be other elements between a label and the instruction it designates (such as other labels, stack map frames, line numbers, etc.).
-
-
Field Summary
Fields Modifier and Type Field Description (package private) int
bytecodeOffset
The offset of this label in the bytecode of its method, in bytes.(package private) static Label
EMPTY_LIST
A sentinel element used to indicate the end of a list of labels.(package private) static int
FLAG_DEBUG_ONLY
A flag indicating that a label is only used for debug attributes.(package private) static int
FLAG_JUMP_TARGET
A flag indicating that a label is the target of a jump instruction, or the start of an exception handler.(package private) static int
FLAG_REACHABLE
A flag indicating that a label corresponds to a reachable basic block.(package private) static int
FLAG_RESOLVED
A flag indicating that the bytecode offset of a label is known.(package private) static int
FLAG_SUBROUTINE_CALLER
A flag indicating that the basic block corresponding to a label ends with a subroutine call.(package private) static int
FLAG_SUBROUTINE_END
A flag indicating that the basic block corresponding to a label is the end of a subroutine.(package private) static int
FLAG_SUBROUTINE_START
A flag indicating that the basic block corresponding to a label is the start of a subroutine.(package private) short
flags
The type and status of this label or its corresponding basic block.(package private) static int
FORWARD_REFERENCE_HANDLE_MASK
The bit mask to extract the 'handle' of a forward reference to this label.(package private) static int
FORWARD_REFERENCE_TYPE_MASK
The bit mask to extract the type of a forward reference to this label.(package private) static int
FORWARD_REFERENCE_TYPE_SHORT
The type of forward references stored with two bytes in the bytecode.(package private) static int
FORWARD_REFERENCE_TYPE_WIDE
The type of forward references stored in four bytes in the bytecode.(package private) static int
FORWARD_REFERENCES_CAPACITY_INCREMENT
The number of elements to add to theforwardReferences
array when it needs to be resized to store a new forward reference.private int[]
forwardReferences
The forward references to this label.(package private) Frame
frame
The input and output stack map frames of the basic block corresponding to this label.java.lang.Object
info
A user managed state associated with this label.(package private) short
inputStackSize
The number of elements in the input stack of the basic block corresponding to this label.(package private) static int
LINE_NUMBERS_CAPACITY_INCREMENT
The number of elements to add to theotherLineNumbers
array when it needs to be resized to store a new source line number.private short
lineNumber
The source line number corresponding to this label, or 0.(package private) Label
nextBasicBlock
The successor of this label, in the order they are visited inMethodVisitor.visitLabel(org.datanucleus.enhancer.asm.Label)
.(package private) Label
nextListElement
The next element in the list of labels to which this label belongs, or null if it does not belong to any list.private int[]
otherLineNumbers
The source line numbers corresponding to this label, in addition tolineNumber
, or null.(package private) Edge
outgoingEdges
The outgoing edges of the basic block corresponding to this label, in the control flow graph of its method.(package private) short
outputStackMax
The maximum height reached by the output stack, relatively to the top of the input stack, in the basic block corresponding to this label.(package private) short
outputStackSize
The number of elements in the output stack, at the end of the basic block corresponding to this label.(package private) short
subroutineId
The id of the subroutine to which this basic block belongs, or 0.
-
Constructor Summary
Constructors Constructor Description Label()
Constructs a new label.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description (package private) void
accept(MethodVisitor methodVisitor, boolean visitLineNumbers)
Makes the given visitor visit this label and its source line numbers, if applicable.private void
addForwardReference(int sourceInsnBytecodeOffset, int referenceType, int referenceHandle)
Adds a forward reference to this label.(package private) void
addLineNumber(int lineNumber)
Adds a source line number corresponding to this label.(package private) void
addSubroutineRetSuccessors(Label subroutineCaller)
Finds the basic blocks that end a subroutine starting with the basic block corresponding to this label and, for each one of them, adds an outgoing edge to the basic block following the given subroutine call.(package private) Label
getCanonicalInstance()
Returns the "canonical"Label
instance corresponding to this label's bytecode offset, if known, otherwise the label itself.int
getOffset()
Returns the bytecode offset corresponding to this label.(package private) void
markSubroutine(short subroutineId)
Finds the basic blocks that belong to the subroutine starting with the basic block corresponding to this label, and marks these blocks as belonging to this subroutine.private Label
pushSuccessors(Label listOfLabelsToProcess)
Adds the successors of this label in the method's control flow graph (except those corresponding to a jsr target, and those already in a list of labels) to the given list of blocks to process, and returns the new list.(package private) void
put(ByteVector code, int sourceInsnBytecodeOffset, boolean wideReference)
Puts a reference to this label in the bytecode of a method.(package private) boolean
resolve(byte[] code, int bytecodeOffset)
Sets the bytecode offset of this label to the given value and resolves the forward references to this label, if any.java.lang.String
toString()
Returns a string representation of this label.
-
-
-
Field Detail
-
FLAG_DEBUG_ONLY
static final int FLAG_DEBUG_ONLY
A flag indicating that a label is only used for debug attributes. Such a label is not the start of a basic block, the target of a jump instruction, or an exception handler. It can be safely ignored in control flow graph analysis algorithms (for optimization purposes).- See Also:
- Constant Field Values
-
FLAG_JUMP_TARGET
static final int FLAG_JUMP_TARGET
A flag indicating that a label is the target of a jump instruction, or the start of an exception handler.- See Also:
- Constant Field Values
-
FLAG_RESOLVED
static final int FLAG_RESOLVED
A flag indicating that the bytecode offset of a label is known.- See Also:
- Constant Field Values
-
FLAG_REACHABLE
static final int FLAG_REACHABLE
A flag indicating that a label corresponds to a reachable basic block.- See Also:
- Constant Field Values
-
FLAG_SUBROUTINE_CALLER
static final int FLAG_SUBROUTINE_CALLER
A flag indicating that the basic block corresponding to a label ends with a subroutine call. By construction inMethodWriter.visitJumpInsn(int, org.datanucleus.enhancer.asm.Label)
, labels with this flag set have at least two outgoing edges:- the first one corresponds to the instruction that follows the jsr instruction in the
bytecode, i.e. where execution continues when it returns from the jsr call. This is a
virtual control flow edge, since execution never goes directly from the jsr to the next
instruction. Instead, it goes to the subroutine and eventually returns to the instruction
following the jsr. This virtual edge is used to compute the real outgoing edges of the
basic blocks ending with a ret instruction, in
addSubroutineRetSuccessors(org.datanucleus.enhancer.asm.Label)
. - the second one corresponds to the target of the jsr instruction,
- See Also:
- Constant Field Values
- the first one corresponds to the instruction that follows the jsr instruction in the
bytecode, i.e. where execution continues when it returns from the jsr call. This is a
virtual control flow edge, since execution never goes directly from the jsr to the next
instruction. Instead, it goes to the subroutine and eventually returns to the instruction
following the jsr. This virtual edge is used to compute the real outgoing edges of the
basic blocks ending with a ret instruction, in
-
FLAG_SUBROUTINE_START
static final int FLAG_SUBROUTINE_START
A flag indicating that the basic block corresponding to a label is the start of a subroutine.- See Also:
- Constant Field Values
-
FLAG_SUBROUTINE_END
static final int FLAG_SUBROUTINE_END
A flag indicating that the basic block corresponding to a label is the end of a subroutine.- See Also:
- Constant Field Values
-
LINE_NUMBERS_CAPACITY_INCREMENT
static final int LINE_NUMBERS_CAPACITY_INCREMENT
The number of elements to add to theotherLineNumbers
array when it needs to be resized to store a new source line number.- See Also:
- Constant Field Values
-
FORWARD_REFERENCES_CAPACITY_INCREMENT
static final int FORWARD_REFERENCES_CAPACITY_INCREMENT
The number of elements to add to theforwardReferences
array when it needs to be resized to store a new forward reference.- See Also:
- Constant Field Values
-
FORWARD_REFERENCE_TYPE_MASK
static final int FORWARD_REFERENCE_TYPE_MASK
The bit mask to extract the type of a forward reference to this label. The extracted type is eitherFORWARD_REFERENCE_TYPE_SHORT
orFORWARD_REFERENCE_TYPE_WIDE
.- See Also:
forwardReferences
, Constant Field Values
-
FORWARD_REFERENCE_TYPE_SHORT
static final int FORWARD_REFERENCE_TYPE_SHORT
The type of forward references stored with two bytes in the bytecode. This is the case, for instance, of a forward reference from an ifnull instruction.- See Also:
- Constant Field Values
-
FORWARD_REFERENCE_TYPE_WIDE
static final int FORWARD_REFERENCE_TYPE_WIDE
The type of forward references stored in four bytes in the bytecode. This is the case, for instance, of a forward reference from a lookupswitch instruction.- See Also:
- Constant Field Values
-
FORWARD_REFERENCE_HANDLE_MASK
static final int FORWARD_REFERENCE_HANDLE_MASK
The bit mask to extract the 'handle' of a forward reference to this label. The extracted handle is the bytecode offset where the forward reference value is stored (using either 2 or 4 bytes, as indicated by theFORWARD_REFERENCE_TYPE_MASK
).- See Also:
forwardReferences
, Constant Field Values
-
EMPTY_LIST
static final Label EMPTY_LIST
A sentinel element used to indicate the end of a list of labels.- See Also:
nextListElement
-
info
public java.lang.Object info
A user managed state associated with this label. Warning: this field is used by the ASM tree package. In order to use it with the ASM tree package you must override the getLabelNode method in MethodNode.
-
flags
short flags
The type and status of this label or its corresponding basic block. Must be zero or more ofFLAG_DEBUG_ONLY
,FLAG_JUMP_TARGET
,FLAG_RESOLVED
,FLAG_REACHABLE
,FLAG_SUBROUTINE_CALLER
,FLAG_SUBROUTINE_START
,FLAG_SUBROUTINE_END
.
-
lineNumber
private short lineNumber
The source line number corresponding to this label, or 0. If there are several source line numbers corresponding to this label, the first one is stored in this field, and the remaining ones are stored inotherLineNumbers
.
-
otherLineNumbers
private int[] otherLineNumbers
The source line numbers corresponding to this label, in addition tolineNumber
, or null. The first element of this array is the number n of source line numbers it contains, which are stored between indices 1 and n (inclusive).
-
bytecodeOffset
int bytecodeOffset
The offset of this label in the bytecode of its method, in bytes. This value is set if and only if theFLAG_RESOLVED
flag is set.
-
forwardReferences
private int[] forwardReferences
The forward references to this label. The first element is the number of forward references, times 2 (this corresponds to the index of the last element actually used in this array). Then, each forward reference is described with two consecutive integers noted 'sourceInsnBytecodeOffset' and 'reference':- 'sourceInsnBytecodeOffset' is the bytecode offset of the instruction that contains the forward reference,
- 'reference' contains the type and the offset in the bytecode where the forward reference
value must be stored, which can be extracted with
FORWARD_REFERENCE_TYPE_MASK
andFORWARD_REFERENCE_HANDLE_MASK
.
For instance, for an ifnull instruction at bytecode offset x, 'sourceInsnBytecodeOffset' is equal to x, and 'reference' is of type
FORWARD_REFERENCE_TYPE_SHORT
with value x + 1 (because the ifnull instruction uses a 2 bytes bytecode offset operand stored one byte after the start of the instruction itself). For the default case of a lookupswitch instruction at bytecode offset x, 'sourceInsnBytecodeOffset' is equal to x, and 'reference' is of typeFORWARD_REFERENCE_TYPE_WIDE
with value between x + 1 and x + 4 (because the lookupswitch instruction uses a 4 bytes bytecode offset operand stored one to four bytes after the start of the instruction itself).
-
inputStackSize
short inputStackSize
The number of elements in the input stack of the basic block corresponding to this label. This field is computed inMethodWriter.computeMaxStackAndLocal()
.
-
outputStackSize
short outputStackSize
The number of elements in the output stack, at the end of the basic block corresponding to this label. This field is only computed for basic blocks that end with a RET instruction.
-
outputStackMax
short outputStackMax
The maximum height reached by the output stack, relatively to the top of the input stack, in the basic block corresponding to this label. This maximum is always positive or null.
-
subroutineId
short subroutineId
The id of the subroutine to which this basic block belongs, or 0. If the basic block belongs to several subroutines, this is the id of the "oldest" subroutine that contains it (with the convention that a subroutine calling another one is "older" than the callee). This field is computed inMethodWriter.computeMaxStackAndLocal()
, if the method contains JSR instructions.
-
frame
Frame frame
The input and output stack map frames of the basic block corresponding to this label. This field is only used when theMethodWriter.COMPUTE_ALL_FRAMES
orMethodWriter.COMPUTE_INSERTED_FRAMES
option is used.
-
nextBasicBlock
Label nextBasicBlock
The successor of this label, in the order they are visited inMethodVisitor.visitLabel(org.datanucleus.enhancer.asm.Label)
. This linked list does not include labels used for debug info only. If theMethodWriter.COMPUTE_ALL_FRAMES
orMethodWriter.COMPUTE_INSERTED_FRAMES
option is used then it does not contain either successive labels that denote the same bytecode offset (in this case only the first label appears in this list).
-
outgoingEdges
Edge outgoingEdges
The outgoing edges of the basic block corresponding to this label, in the control flow graph of its method. These edges are stored in a linked list ofEdge
objects, linked to each other by theirEdge.nextEdge
field.
-
nextListElement
Label nextListElement
The next element in the list of labels to which this label belongs, or null if it does not belong to any list. All lists of labels must end with theEMPTY_LIST
sentinel, in order to ensure that this field is null if and only if this label does not belong to a list of labels. Note that there can be several lists of labels at the same time, but that a label can belong to at most one list at a time (unless some lists share a common tail, but this is not used in practice).List of labels are used in
MethodWriter.computeAllFrames()
andMethodWriter.computeMaxStackAndLocal()
to compute stack map frames and the maximum stack size, respectively, as well as inmarkSubroutine(short)
andaddSubroutineRetSuccessors(org.datanucleus.enhancer.asm.Label)
to compute the basic blocks belonging to subroutines and their outgoing edges. Outside of these methods, this field should be null (this property is a precondition and a postcondition of these methods).
-
-
Method Detail
-
getOffset
public int getOffset()
Returns the bytecode offset corresponding to this label. This offset is computed from the start of the method's bytecode. This method is intended forAttribute
sub classes, and is normally not needed by class generators or adapters.- Returns:
- the bytecode offset corresponding to this label.
- Throws:
java.lang.IllegalStateException
- if this label is not resolved yet.
-
getCanonicalInstance
final Label getCanonicalInstance()
Returns the "canonical"Label
instance corresponding to this label's bytecode offset, if known, otherwise the label itself. The canonical instance is the first label (in the order of their visit byMethodVisitor.visitLabel(org.datanucleus.enhancer.asm.Label)
) corresponding to this bytecode offset. It cannot be known for labels which have not been visited yet.This method should only be used when the
MethodWriter.COMPUTE_ALL_FRAMES
option is used.- Returns:
- the label itself if
frame
is null, otherwise the Label's frame owner. This corresponds to the "canonical" label instance described above thanks to the way the label frame is set inMethodWriter.visitLabel(org.datanucleus.enhancer.asm.Label)
.
-
addLineNumber
final void addLineNumber(int lineNumber)
Adds a source line number corresponding to this label.- Parameters:
lineNumber
- a source line number (which should be strictly positive).
-
accept
final void accept(MethodVisitor methodVisitor, boolean visitLineNumbers)
Makes the given visitor visit this label and its source line numbers, if applicable.- Parameters:
methodVisitor
- a method visitor.visitLineNumbers
- whether to visit of the label's source line numbers, if any.
-
put
final void put(ByteVector code, int sourceInsnBytecodeOffset, boolean wideReference)
Puts a reference to this label in the bytecode of a method. If the bytecode offset of the label is known, the relative bytecode offset between the label and the instruction referencing it is computed and written directly. Otherwise, a null relative offset is written and a new forward reference is declared for this label.- Parameters:
code
- the bytecode of the method. This is where the reference is appended.sourceInsnBytecodeOffset
- the bytecode offset of the instruction that contains the reference to be appended.wideReference
- whether the reference must be stored in 4 bytes (instead of 2 bytes).
-
addForwardReference
private void addForwardReference(int sourceInsnBytecodeOffset, int referenceType, int referenceHandle)
Adds a forward reference to this label. This method must be called only for a true forward reference, i.e. only if this label is not resolved yet. For backward references, the relative bytecode offset of the reference can be, and must be, computed and stored directly.- Parameters:
sourceInsnBytecodeOffset
- the bytecode offset of the instruction that contains the reference stored at referenceHandle.referenceType
- eitherFORWARD_REFERENCE_TYPE_SHORT
orFORWARD_REFERENCE_TYPE_WIDE
.referenceHandle
- the offset in the bytecode where the forward reference value must be stored.
-
resolve
final boolean resolve(byte[] code, int bytecodeOffset)
Sets the bytecode offset of this label to the given value and resolves the forward references to this label, if any. This method must be called when this label is added to the bytecode of the method, i.e. when its bytecode offset becomes known. This method fills in the blanks that where left in the bytecode by each forward reference previously added to this label.- Parameters:
code
- the bytecode of the method.bytecodeOffset
- the bytecode offset of this label.- Returns:
- true if a blank that was left for this label was too small to store the offset. In such a case the corresponding jump instruction is replaced with an equivalent ASM specific instruction using an unsigned two bytes offset. These ASM specific instructions are later replaced with standard bytecode instructions with wider offsets (4 bytes instead of 2), in ClassReader.
-
markSubroutine
final void markSubroutine(short subroutineId)
Finds the basic blocks that belong to the subroutine starting with the basic block corresponding to this label, and marks these blocks as belonging to this subroutine. This method follows the control flow graph to find all the blocks that are reachable from the current basic block WITHOUT following any jsr target.Note: a precondition and postcondition of this method is that all labels must have a null
nextListElement
.- Parameters:
subroutineId
- the id of the subroutine starting with the basic block corresponding to this label.
-
addSubroutineRetSuccessors
final void addSubroutineRetSuccessors(Label subroutineCaller)
Finds the basic blocks that end a subroutine starting with the basic block corresponding to this label and, for each one of them, adds an outgoing edge to the basic block following the given subroutine call. In other words, completes the control flow graph by adding the edges corresponding to the return from this subroutine, when called from the given caller basic block.Note: a precondition and postcondition of this method is that all labels must have a null
nextListElement
.- Parameters:
subroutineCaller
- a basic block that ends with a jsr to the basic block corresponding to this label. This label is supposed to correspond to the start of a subroutine.
-
pushSuccessors
private Label pushSuccessors(Label listOfLabelsToProcess)
Adds the successors of this label in the method's control flow graph (except those corresponding to a jsr target, and those already in a list of labels) to the given list of blocks to process, and returns the new list.- Parameters:
listOfLabelsToProcess
- a list of basic blocks to process, linked together with theirnextListElement
field.- Returns:
- the new list of blocks to process.
-
toString
public java.lang.String toString()
Returns a string representation of this label.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a string representation of this label.
-
-