OpenJDK 1.23 · sun.jvm.hotspot.debugger.Address · APIdia, the JavaDoc alternative

This is the bottom-most interface which abstracts address access for both debugging and introspection. In the situation of debugging a target VM, these routines can throw the specified RuntimeExceptions to indicate failure and allow recovery of the debugging system. If these are used for introspecting the current VM and implementing functionality in it, however, it is expected that these kinds of failures will not occur and, in fact, a crash will occur if the situation arises where they would have been thrown.

Addresses are immutable. Further, it was decided not to expose the representation of the Address (and provide a corresponding factory method from, for example, long to Address). Unfortunately, because of the existence of C and "reuse" of low bits of pointers, it is occasionally necessary to perform logical operations like masking off the low bits of an "address". While these operations could be used to generate arbitrary Address objects, allowing this is not the intent of providing these operations.

This interface is able to fetch all Java primitive types, addresses, oops, and C integers of arbitrary size (see @see sun.jvm.hotspot.types.CIntegerType for further discussion). Note that the result of the latter is restricted to fitting into a 64-bit value and the high-order bytes will be silently discarded if too many bytes are requested.

Implementations may have restrictions, for example that the Java-related routines may not be called until a certain point in the bootstrapping process once the sizes of the Java primitive types are known. (The current implementation has that property.)

A note of warning: in C addresses, when represented as integers, are usually represented with unsigned types. Unfortunately, there are no unsigned primitive types in Java, so care will have to be taken in the implementation of this interface if using longs as the representation for 64-bit correctness. This is not so simple for the comparison operators.

Method Summary

Modifier and Type	Method and Description
public Address	addOffsetTo(long offset) This throws an UnsupportedOperationException if this address happens to actually be an OopHandle, because interior object pointers are not allowed.
public OopHandle	addOffsetToAsOopHandle(long offset) This method had to be added in order to support heap iteration in the debugging system, and is effectively the dangerous operation of allowing interior object pointers.
public Address	andWithMask(long mask) This throws an UnsupportedOperationException if this address happens to actually be an OopHandle.
public long	asLongValue()
public boolean	equals(Object arg) This is stated explicitly here because it is important for implementations to understand that equals() and hashCode() must absolutely, positively work properly -- i.e., two Address objects representing the same address are both equal (via equals()) and have the same hash code.
public Address	getAddressAt(long offset) This returns null if the address at the given offset is NULL.
public long	getCIntegerAt(long offset, long numBytes, boolean isUnsigned)
public Address	getCompKlassAddressAt(long offset)
public Address	getCompOopAddressAt(long offset) Returns the decoded address at the given offset
public OopHandle	getCompOopHandleAt(long offset)
public boolean	getJBooleanAt(long offset)
public byte	getJByteAt(long offset)
public char	getJCharAt(long offset)
public double	getJDoubleAt(long offset)
public float	getJFloatAt(long offset)
public int	getJIntAt(long offset)
public long	getJLongAt(long offset)
public short	getJShortAt(long offset)
public OopHandle	getOopHandleAt(long offset) This returns null if the address at the given offset is NULL.
public boolean	greaterThan(Address arg) Performs unsigned comparison "this > arg".
public boolean	greaterThanOrEqual(Address arg) Performs unsigned comparison "this >= arg".
public int	hashCode() This is stated explicitly here because it is important for implementations to understand that equals() and hashCode() must absolutely, positively work properly -- i.e., two Address objects representing the same address are both equal (via equals()) and have the same hash code.
public boolean	lessThan(Address arg) Performs unsigned comparison "this < arg".
public boolean	lessThanOrEqual(Address arg) Performs unsigned comparison "this <= arg".
public long	minus(Address arg) Performs the subtraction "this - arg", returning the resulting offset in bytes.
public Address	orWithMask(long mask) This throws an UnsupportedOperationException if this address happens to actually be an OopHandle.
public void	setAddressAt(long offset, Address value) Sets an Address at the specified location.
public void	setCIntegerAt(long offset, long numBytes, long value) Sets a C integer numBytes in size at the specified offset.
public void	setJBooleanAt(long offset, boolean value)
public void	setJByteAt(long offset, byte value)
public void	setJCharAt(long offset, char value)
public void	setJDoubleAt(long offset, double value)
public void	setJFloatAt(long offset, float value)
public void	setJIntAt(long offset, int value)
public void	setJLongAt(long offset, long value)
public void	setJShortAt(long offset, short value)
public void	setOopHandleAt(long offset, OopHandle value)
public Address	xorWithMask(long mask) This throws an UnsupportedOperationException if this address happens to actually be an OopHandle.

Method Detail

addOffsetTo	back to summary
public Address addOffsetTo(long offset) throws UnsupportedOperationException This throws an UnsupportedOperationException if this address happens to actually be an OopHandle, because interior object pointers are not allowed. Negative offsets are allowed and handle the subtraction case.

addOffsetToAsOopHandle	back to summary
public OopHandle addOffsetToAsOopHandle(long offset) throws UnsupportedOperationException This method had to be added in order to support heap iteration in the debugging system, and is effectively the dangerous operation of allowing interior object pointers. For this reason it was kept as a separate API and its use is forbidden in the non-debugging (i.e., reflective system) case. It is strongly recommended that this not be called by clients: it is currently wrapped up in the Space's iteration mechanism.

addOffsetToAsOopHandle

back to summary

public OopHandle addOffsetToAsOopHandle(long offset) throws UnsupportedOperationException

This method had to be added in order to support heap iteration in the debugging system, and is effectively the dangerous operation of allowing interior object pointers. For this reason it was kept as a separate API and its use is forbidden in the non-debugging (i.e., reflective system) case. It is strongly recommended that this not be called by clients: it is currently wrapped up in the Space's iteration mechanism.

andWithMask	back to summary
public Address andWithMask(long mask) throws UnsupportedOperationException This throws an UnsupportedOperationException if this address happens to actually be an OopHandle. Performs a logical "and" operation of the bits of the address and the mask (least significant bits of the Address and the mask are aligned) and returns the result as an Address. Returns null if the result was zero.

asLongValue	back to summary
public long asLongValue()

equals	back to summary
public boolean equals(Object arg) This is stated explicitly here because it is important for implementations to understand that equals() and hashCode() must absolutely, positively work properly -- i.e., two Address objects representing the same address are both equal (via equals()) and have the same hash code.

getAddressAt	back to summary
public Address getAddressAt(long offset) throws UnmappedAddressException, UnalignedAddressException This returns null if the address at the given offset is NULL.

getCIntegerAt	back to summary
public long getCIntegerAt(long offset, long numBytes, boolean isUnsigned) throws UnmappedAddressException, UnalignedAddressException

getCompKlassAddressAt	back to summary
public Address getCompKlassAddressAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getCompOopAddressAt	back to summary
public Address getCompOopAddressAt(long offset) throws UnmappedAddressException, UnalignedAddressException Returns the decoded address at the given offset

getCompOopHandleAt	back to summary
public OopHandle getCompOopHandleAt(long offset) throws UnmappedAddressException, UnalignedAddressException, NotInHeapException

getJBooleanAt	back to summary
public boolean getJBooleanAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getJByteAt	back to summary
public byte getJByteAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getJCharAt	back to summary
public char getJCharAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getJDoubleAt	back to summary
public double getJDoubleAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getJFloatAt	back to summary
public float getJFloatAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getJIntAt	back to summary
public int getJIntAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getJLongAt	back to summary
public long getJLongAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getJShortAt	back to summary
public short getJShortAt(long offset) throws UnmappedAddressException, UnalignedAddressException

getOopHandleAt	back to summary
public OopHandle getOopHandleAt(long offset) throws UnmappedAddressException, UnalignedAddressException, NotInHeapException This returns null if the address at the given offset is NULL.

greaterThan	back to summary
public boolean greaterThan(Address arg) Performs unsigned comparison "this > arg". (FIXME: should this work for OopHandles?)

greaterThanOrEqual	back to summary
public boolean greaterThanOrEqual(Address arg) Performs unsigned comparison "this >= arg". (FIXME: should this work for OopHandles?)

hashCode	back to summary
public int hashCode() This is stated explicitly here because it is important for implementations to understand that equals() and hashCode() must absolutely, positively work properly -- i.e., two Address objects representing the same address are both equal (via equals()) and have the same hash code.

lessThan	back to summary
public boolean lessThan(Address arg) Performs unsigned comparison "this < arg". (FIXME: should this work for OopHandles?)

lessThanOrEqual	back to summary
public boolean lessThanOrEqual(Address arg) Performs unsigned comparison "this <= arg". (FIXME: should this work for OopHandles?)

minus	back to summary
public long minus(Address arg) Performs the subtraction "this - arg", returning the resulting offset in bytes. Note that this must handle a null argument properly, and can be used to convert an Address into a long for further manipulation, but that the reverse conversion is not possible. (FIXME: any signed/unsigned issues? Should this work for OopHandles?)

orWithMask	back to summary
public Address orWithMask(long mask) throws UnsupportedOperationException This throws an UnsupportedOperationException if this address happens to actually be an OopHandle. Performs a logical "or" operation of the bits of the address and the mask (least significant bits of the Address and the mask are aligned) and returns the result as an Address. Returns null if the result was zero.

setAddressAt	back to summary
public void setAddressAt(long offset, Address value) Sets an Address at the specified location.

setCIntegerAt	back to summary
public void setCIntegerAt(long offset, long numBytes, long value) Sets a C integer numBytes in size at the specified offset. Note that there is no "unsigned" flag for the accessor since the value will not be sign-extended; the number of bytes are simply copied from the value into the target address space.

setJBooleanAt	back to summary
public void setJBooleanAt(long offset, boolean value) throws UnmappedAddressException, UnalignedAddressException

setJByteAt	back to summary
public void setJByteAt(long offset, byte value) throws UnmappedAddressException, UnalignedAddressException

setJCharAt	back to summary
public void setJCharAt(long offset, char value) throws UnmappedAddressException, UnalignedAddressException

setJDoubleAt	back to summary
public void setJDoubleAt(long offset, double value) throws UnmappedAddressException, UnalignedAddressException

setJFloatAt	back to summary
public void setJFloatAt(long offset, float value) throws UnmappedAddressException, UnalignedAddressException

setJIntAt	back to summary
public void setJIntAt(long offset, int value) throws UnmappedAddressException, UnalignedAddressException

setJLongAt	back to summary
public void setJLongAt(long offset, long value) throws UnmappedAddressException, UnalignedAddressException

setJShortAt	back to summary
public void setJShortAt(long offset, short value) throws UnmappedAddressException, UnalignedAddressException

setOopHandleAt	back to summary
public void setOopHandleAt(long offset, OopHandle value) throws UnmappedAddressException, UnalignedAddressException

xorWithMask	back to summary
public Address xorWithMask(long mask) throws UnsupportedOperationException This throws an UnsupportedOperationException if this address happens to actually be an OopHandle. Performs a logical "exclusive or" operation of the bits of the address and the mask (least significant bits of the Address and the mask are aligned) and returns the result as an Address. Returns null if the result was zero.

xorWithMask

back to summary

public Address xorWithMask(long mask) throws UnsupportedOperationException

This throws an UnsupportedOperationException if this address happens to actually be an OopHandle. Performs a logical "exclusive or" operation of the bits of the address and the mask (least significant bits of the Address and the mask are aligned) and returns the result as an Address. Returns null if the result was zero.

public Interface Address

Method Summary

Method Detail