public interface MemoryAddress
A memory address models a reference into a memory location. Memory addresses are typically obtained using the
MemorySegment.baseAddress()
method; such addresses are said to be checked, and can be expressed
as offsets into some underlying memory segment (see segment()
and segmentOffset()
).
Since checked memory addresses feature both spatial and temporal bounds, these addresses can safely be
dereferenced using a memory access var handle (see MemoryHandles
).
If an address does not have any associated segment, it is said to be unchecked. Unchecked memory
addresses do not feature known spatial or temporal bounds; as such, attempting a memory dereference operation
using an unchecked memory address will result in a runtime exception. Unchecked addresses can be obtained
e.g. by calling the ofLong(long)
method.
All implementations of this interface must be value-based;
use of identity-sensitive operations (including reference equality (==
), identity hash code, or synchronization) on
instances of MemoryAddress
may have unpredictable results and should be avoided. The equals
method should
be used for comparisons.
Non-platform classes should not implement MemoryAddress directly.
- API Note:
- In the future, if the Java language permits,
MemoryAddress
may become asealed
interface, which would prohibit subclassing except by explicitly permitted types. - Implementation Requirements:
- Implementations of this interface are immutable, thread-safe and value-based.
-
Field Summary
Fields Modifier and Type Field Description static MemoryAddress
NULL
The unchecked memory address instance modelling theNULL
address. -
Method Summary
Modifier and Type Method Description MemoryAddress
addOffset(long offset)
Creates a new memory address with given offset (in bytes), which might be negative, from current one.boolean
equals(Object that)
Compares the specified object with this address for equality.int
hashCode()
Returns the hash code value for this address.static MemoryAddress
ofLong(long value)
Obtain a new unchecked memory address instance from given long address.MemoryAddress
rebase(MemorySegment segment)
Reinterpret this address as an offset into the provided segment.MemorySegment
segment()
Returns the memory segment (if any) this address belongs to.long
segmentOffset()
Returns the offset of this memory address into the underlying segment (if any).long
toRawLongValue()
Returns the raw long value associated to this memory address.
-
Field Details
-
NULL
The unchecked memory address instance modelling theNULL
address. This address is not backed by a memory segment and hence it cannot be dereferenced.
-
-
Method Details
-
addOffset
Creates a new memory address with given offset (in bytes), which might be negative, from current one.- Parameters:
offset
- specified offset (in bytes), relative to this address, which should be used to create the new address.- Returns:
- a new memory address with given offset from current one.
-
segmentOffset
long segmentOffset()Returns the offset of this memory address into the underlying segment (if any).- Returns:
- the offset of this memory address into the underlying segment (if any).
- Throws:
UnsupportedOperationException
- if no segment is associated with this memory address, e.g. ifsegment() == null
.
-
toRawLongValue
long toRawLongValue()Returns the raw long value associated to this memory address.- Returns:
- The raw long value associated to this memory address.
- Throws:
UnsupportedOperationException
- if this memory address is associated with an heap segment.
-
segment
MemorySegment segment()Returns the memory segment (if any) this address belongs to.- Returns:
- The memory segment this address belongs to, or
null
if no such segment exists.
-
rebase
Reinterpret this address as an offset into the provided segment.- Parameters:
segment
- the segment to be rebased- Returns:
- a new address pointing to the same memory location through the provided segment
- Throws:
IllegalArgumentException
- if the provided segment is not a valid rebase target for this address. This can happen, for instance, if an heap-based addressed is rebased to an off-heap memory segment.
-
equals
Compares the specified object with this address for equality. Returnstrue
if and only if the specified object is also an address, and it refers to the same memory location as this address.- Overrides:
equals
in classObject
- API Note:
- two addresses might be considered equal despite their associated segments differ. This
can happen, for instance, if the segment associated with one address is a slice
(see
MemorySegment.asSlice(long, long)
) of the segment associated with the other address. Moreover, two addresses might be considered equals despite differences in the temporal bounds associated with their corresponding segments. - Parameters:
that
- the object to be compared for equality with this address.- Returns:
true
if the specified object is equal to this address.- See Also:
Object.hashCode()
,HashMap
-
hashCode
int hashCode()Returns the hash code value for this address.- Overrides:
hashCode
in classObject
- Returns:
- the hash code value for this address.
- See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
ofLong
Obtain a new unchecked memory address instance from given long address. The returned address is not backed by a memory segment and hence it cannot be dereferenced.- Parameters:
value
- the long address.- Returns:
- the new memory address instance.
-