Modifier and Type	Class and Description
private static record	AbstractLinker.LinkRequest
public static interface	AbstractLinker.UpcallStubFactory

Modifier and Type	Field and Description
private final Set<MemoryLayout>	CANONICAL_LAYOUTS_CACHE
private final SoftReferenceCache<AbstractLinker.LinkRequest, MethodHandle>	DOWNCALL_CACHE
private final SoftReferenceCache<AbstractLinker.LinkRequest, AbstractLinker.UpcallStubFactory>	UPCALL_CACHE

Access	Constructor and Description
public	AbstractLinker()

Method Summary

Modifier and Type	Method and Description
protected abstract MethodHandle	arrangeDowncall(MethodType inferredMethodType, FunctionDescriptor function, LinkerOptions options)
protected abstract AbstractLinker.UpcallStubFactory	arrangeUpcall(MethodType targetType, FunctionDescriptor function, LinkerOptions options)
private static void	checkGroup(GroupLayout gl, long maxUnpaddedOffset)
private void	checkHasNaturalAlignment(MemoryLayout layout)
private void	checkLayout(MemoryLayout layout)
private void	checkLayoutRecursive(MemoryLayout layout)
private void	checkLayouts(FunctionDescriptor descriptor)
private static void	checkMemberOffset(StructLayout parent, MemoryLayout memberLayout, long lastUnpaddedOffset, long offset)
private static void	checkNotAllPadding(StructLayout sl)
protected void	checkStructMember(MemoryLayout member, long offset)
private void	checkSupported(ValueLayout valueLayout)
public SystemLookup	defaultLookup() Implements java.lang.foreign.Linker.defaultLookup. Returns a symbol lookup for symbols in a set of commonly used libraries.
public final MethodHandle	downcallHandle(MemorySegment symbol, FunctionDescriptor function, Linker.Option... options) Implements java.lang.foreign.Linker.downcallHandle. Creates a method handle that is used to call a foreign function with the given signature and address.
public final MethodHandle	downcallHandle(FunctionDescriptor function, Linker.Option... options) Implements java.lang.foreign.Linker.downcallHandle. Creates a method handle that is used to call a foreign function with the given signature.
private MethodHandle	downcallHandle0(FunctionDescriptor function, Linker.Option... options)
private static String	inMessage(GroupLayout gl)
private static IllegalArgumentException	memberException(MemoryLayout parent, MemoryLayout member, String info)
private static MemoryLayout	stripNames(MemoryLayout ml)
private static MemoryLayout[]	stripNames(List<MemoryLayout> layouts)
private static FunctionDescriptor	stripNames(FunctionDescriptor function)
public final MemorySegment	upcallStub(MethodHandle target, FunctionDescriptor function, Arena arena, Linker.Option... options) Implements java.lang.foreign.Linker.upcallStub. Creates an upcall stub which can be passed to other foreign functions as a function pointer, associated with the given arena.
private void	validateVariadicLayouts(FunctionDescriptor function, LinkerOptions optionSet)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

CANONICAL_LAYOUTS_CACHE	back to summary
private final Set<MemoryLayout> CANONICAL_LAYOUTS_CACHE

DOWNCALL_CACHE	back to summary
private final SoftReferenceCache<AbstractLinker.LinkRequest, MethodHandle> DOWNCALL_CACHE

UPCALL_CACHE	back to summary
private final SoftReferenceCache<AbstractLinker.LinkRequest, AbstractLinker.UpcallStubFactory> UPCALL_CACHE

Constructor Detail

AbstractLinker	back to summary
public AbstractLinker()

Method Detail

arrangeDowncall	back to summary
protected abstract MethodHandle arrangeDowncall(MethodType inferredMethodType, FunctionDescriptor function, LinkerOptions options)

arrangeUpcall	back to summary
protected abstract AbstractLinker.UpcallStubFactory arrangeUpcall(MethodType targetType, FunctionDescriptor function, LinkerOptions options)

checkGroup	back to summary
private static void checkGroup(GroupLayout gl, long maxUnpaddedOffset)

checkHasNaturalAlignment	back to summary
private void checkHasNaturalAlignment(MemoryLayout layout)

checkLayout	back to summary
private void checkLayout(MemoryLayout layout)

checkLayoutRecursive	back to summary
private void checkLayoutRecursive(MemoryLayout layout)

checkLayouts	back to summary
private void checkLayouts(FunctionDescriptor descriptor)

checkMemberOffset	back to summary
private static void checkMemberOffset(StructLayout parent, MemoryLayout memberLayout, long lastUnpaddedOffset, long offset)

checkNotAllPadding	back to summary
private static void checkNotAllPadding(StructLayout sl)

checkStructMember	back to summary
protected void checkStructMember(MemoryLayout member, long offset)

checkSupported	back to summary
private void checkSupported(ValueLayout valueLayout)

defaultLookup back to summary

defaultLookup	back to summary
public SystemLookup defaultLookup() Implements java.lang.foreign.Linker.defaultLookup. Doc from java.lang.foreign.Linker.defaultLookup. Returns a symbol lookup for symbols in a set of commonly used libraries. Each `Linker` is responsible for choosing libraries that are widely recognized as useful on the OS and processor combination supported by the `Linker`. Accordingly, the precise set of symbols exposed by the symbol lookup is unspecified; it varies from one `Linker` to another. Annotations @Override

public SystemLookup defaultLookup()

Implements java.lang.foreign.Linker.defaultLookup.

Doc from java.lang.foreign.Linker.defaultLookup.

Returns a symbol lookup for symbols in a set of commonly used libraries.

Each Linker is responsible for choosing libraries that are widely recognized as useful on the OS and processor combination supported by the Linker. Accordingly, the precise set of symbols exposed by the symbol lookup is unspecified; it varies from one Linker to another.

Annotations

@Override

downcallHandle back to summary

downcallHandle	back to summary
public final MethodHandle downcallHandle(MemorySegment symbol, FunctionDescriptor function, Linker.Option... options) Implements java.lang.foreign.Linker.downcallHandle. Doc from java.lang.foreign.Linker.downcallHandle. Creates a method handle that is used to call a foreign function with the given signature and address. Calling this method is equivalent to the following code: `linker.downcallHandle(function, options).bindTo(address);` linker.downcallHandle(function, options).bindTo(address); Annotations @Override @CallerSensitive

public final MethodHandle downcallHandle(MemorySegment symbol, FunctionDescriptor function, Linker.Option... options)

Implements java.lang.foreign.Linker.downcallHandle.

Doc from java.lang.foreign.Linker.downcallHandle.

Creates a method handle that is used to call a foreign function with the given signature and address.

Calling this method is equivalent to the following code:

linker.downcallHandle(function, options).bindTo(address);

Annotations

@Override
@CallerSensitive

downcallHandle back to summary

downcallHandle	back to summary
public final MethodHandle downcallHandle(FunctionDescriptor function, Linker.Option... options) Implements java.lang.foreign.Linker.downcallHandle. Doc from java.lang.foreign.Linker.downcallHandle. Creates a method handle that is used to call a foreign function with the given signature. The Java method type associated with the returned method handle is derived from the argument and return layouts in the function descriptor, but features an additional leading parameter of type `MemorySegment`, from which the address of the target foreign function is derived. Moreover, if the function descriptor's return layout is a group layout, the resulting downcall method handle accepts an additional leading parameter of type `SegmentAllocator`, which is used by the linker runtime to allocate the memory region associated with the struct returned by the downcall method handle. Upon invoking a downcall method handle, the linker provides the following guarantees for any argument `A` of type `MemorySegment` whose corresponding layout is an address layout: `A.scope().isAlive() == true`. Otherwise, the invocation throws `IllegalStateException`; The invocation occurs in a thread `T` such that `A.isAccessibleBy(T) == true`. Otherwise, the invocation throws `WrongThreadException`; and `A` is kept alive during the invocation. For instance, if `A` has been obtained using a shared arena, any attempt to close the arena while the downcall method handle is still executing will result in an `IllegalStateException`. Moreover, if the provided function descriptor's return layout is an address layout, invoking the returned method handle will return a native segment associated with the global scope. Under normal conditions, the size of the returned segment is `0`. However, if the function descriptor's return layout has a target layout `T`, then the size of the returned segment is set to `T.byteSize()`. The returned method handle will throw an `IllegalArgumentException` if the `MemorySegment` representing the target address of the foreign function is the `MemorySegment#NULL` address. If an argument is a `MemorySegment`, whose corresponding layout is a group layout, the linker might attempt to access the contents of the segment. As such, one of the exceptions specified by the `MemorySegment#get(ValueLayout.OfByte, long)` or the `MemorySegment#copy(MemorySegment, long, MemorySegment, long, long)` methods may be thrown. If an argument is a `MemorySegment` whose corresponding layout is an address layout, the linker will throw an `IllegalArgumentException` if the segment is a heap memory segment, unless heap memory segments are explicitly allowed through the `Linker.Option#critical(boolean)` linker option. The returned method handle will additionally throw `NullPointerException` if any argument passed to it is `null`. Annotations @Override @CallerSensitive

public final MethodHandle downcallHandle(FunctionDescriptor function, Linker.Option... options)

Implements java.lang.foreign.Linker.downcallHandle.

Doc from java.lang.foreign.Linker.downcallHandle.

Creates a method handle that is used to call a foreign function with the given signature.

The Java method type associated with the returned method handle is derived from the argument and return layouts in the function descriptor, but features an additional leading parameter of type MemorySegment, from which the address of the target foreign function is derived. Moreover, if the function descriptor's return layout is a group layout, the resulting downcall method handle accepts an additional leading parameter of type SegmentAllocator, which is used by the linker runtime to allocate the memory region associated with the struct returned by the downcall method handle.

Upon invoking a downcall method handle, the linker provides the following guarantees for any argument A of type MemorySegment whose corresponding layout is an address layout:

A.scope().isAlive() == true. Otherwise, the invocation throws IllegalStateException;
The invocation occurs in a thread T such that A.isAccessibleBy(T) == true. Otherwise, the invocation throws WrongThreadException; and
A is kept alive during the invocation. For instance, if A has been obtained using a shared arena, any attempt to close the arena while the downcall method handle is still executing will result in an IllegalStateException.

Moreover, if the provided function descriptor's return layout is an address layout, invoking the returned method handle will return a native segment associated with the global scope. Under normal conditions, the size of the returned segment is 0. However, if the function descriptor's return layout has a target layout T, then the size of the returned segment is set to T.byteSize().

The returned method handle will throw an IllegalArgumentException if the MemorySegment representing the target address of the foreign function is the MemorySegment#NULL address. If an argument is a MemorySegment, whose corresponding layout is a group layout, the linker might attempt to access the contents of the segment. As such, one of the exceptions specified by the MemorySegment#get(ValueLayout.OfByte, long) or the MemorySegment#copy(MemorySegment, long, MemorySegment, long, long) methods may be thrown. If an argument is a MemorySegment whose corresponding layout is an address layout, the linker will throw an IllegalArgumentException if the segment is a heap memory segment, unless heap memory segments are explicitly allowed through the Linker.Option#critical(boolean) linker option. The returned method handle will additionally throw NullPointerException if any argument passed to it is null.

Annotations

@Override
@CallerSensitive

downcallHandle0	back to summary
private MethodHandle downcallHandle0(FunctionDescriptor function, Linker.Option... options)

inMessage	back to summary
private static String inMessage(GroupLayout gl)

memberException	back to summary
private static IllegalArgumentException memberException(MemoryLayout parent, MemoryLayout member, String info)

stripNames	back to summary
private static MemoryLayout stripNames(MemoryLayout ml) Annotations @SuppressWarnings:restricted

stripNames	back to summary
private static MemoryLayout[] stripNames(List<MemoryLayout> layouts)

stripNames	back to summary
private static FunctionDescriptor stripNames(FunctionDescriptor function)

upcallStub back to summary

upcallStub	back to summary
public final MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function, Arena arena, Linker.Option... options) Implements java.lang.foreign.Linker.upcallStub. Doc from java.lang.foreign.Linker.upcallStub. Creates an upcall stub which can be passed to other foreign functions as a function pointer, associated with the given arena. Calling such a function pointer from foreign code will result in the execution of the provided method handle. The returned memory segment's address points to the newly allocated upcall stub, and is associated with the provided arena. As such, the lifetime of the returned upcall stub segment is controlled by the provided arena. For instance, if the provided arena is a confined arena, the returned upcall stub segment will be deallocated when the provided confined arena is closed. An upcall stub argument whose corresponding layout is an address layout is a native segment associated with the global scope. Under normal conditions, the size of this segment argument is `0`. However, if the address layout has a target layout `T`, then the size of the segment argument is set to `T.byteSize()`. The target method handle should not throw any exceptions. If the target method handle does throw an exception, the JVM will terminate abruptly. To avoid this, clients should wrap the code in the target method handle in a try/catch block to catch any unexpected exceptions. This can be done using the `java.lang.invoke.MethodHandles#catchException(MethodHandle, Class, MethodHandle)` method handle combinator, and handle exceptions as desired in the corresponding catch block. Annotations @Override @CallerSensitive

public final MemorySegment upcallStub(MethodHandle target, FunctionDescriptor function, Arena arena, Linker.Option... options)

Implements java.lang.foreign.Linker.upcallStub.

Doc from java.lang.foreign.Linker.upcallStub.

Creates an upcall stub which can be passed to other foreign functions as a function pointer, associated with the given arena. Calling such a function pointer from foreign code will result in the execution of the provided method handle.

The returned memory segment's address points to the newly allocated upcall stub, and is associated with the provided arena. As such, the lifetime of the returned upcall stub segment is controlled by the provided arena. For instance, if the provided arena is a confined arena, the returned upcall stub segment will be deallocated when the provided confined arena is closed.

An upcall stub argument whose corresponding layout is an address layout is a native segment associated with the global scope. Under normal conditions, the size of this segment argument is 0. However, if the address layout has a target layout T, then the size of the segment argument is set to T.byteSize().

The target method handle should not throw any exceptions. If the target method handle does throw an exception, the JVM will terminate abruptly. To avoid this, clients should wrap the code in the target method handle in a try/catch block to catch any unexpected exceptions. This can be done using the java.lang.invoke.MethodHandles#catchException(MethodHandle, Class, MethodHandle) method handle combinator, and handle exceptions as desired in the corresponding catch block.

Annotations

@Override
@CallerSensitive

validateVariadicLayouts	back to summary
private void validateVariadicLayouts(FunctionDescriptor function, LinkerOptions optionSet)

jdk.internal.foreign.abi back to summary

private final Record AbstractLinker.LinkRequest

Class Inheritance

extends Record

java.lang.Object
java.lang.Record
jdk.internal.foreign.abi.AbstractLinker.LinkRequest

Record Components

descriptor:FunctionDescriptor
options:LinkerOptions

Field Summary

Modifier and Type	Field and Description
private final FunctionDescriptor	descriptor Record Component accessed by descriptor().
private final LinkerOptions	options Record Component accessed by options().

Constructor Summary

Access	Constructor and Description
private	LinkRequest(FunctionDescriptor descriptor, LinkerOptions options)

Method Summary

Modifier and Type	Method and Description
public FunctionDescriptor	descriptor() Record Component getter of descriptor.
public boolean	equals(Object obj) Implements abstract java.lang.Record.equals. Indicates whether some other object is "equal to" this one.
public int	hashCode() Implements abstract java.lang.Record.hashCode. Returns a hash code value for the record.
public LinkerOptions	options() Record Component getter of options.
public final String	toString() Implements abstract java.lang.Record.toString. Returns a string representation of the record.

Field Detail

descriptor	back to summary
private final FunctionDescriptor descriptor Record Component accessed by descriptor().

options	back to summary
private final LinkerOptions options Record Component accessed by options().

Constructor Detail

LinkRequest	back to summary
private LinkRequest(FunctionDescriptor descriptor, LinkerOptions options)

Method Detail

descriptor	back to summary
public FunctionDescriptor descriptor() Record Component getter of descriptor.

equals back to summary

equals	back to summary
public boolean equals(Object obj) Implements abstract java.lang.Record.equals. Doc from java.lang.Record.equals. Indicates whether some other object is "equal to" this one. In addition to the general contract of `Object.equals`, record classes must further obey the invariant that when a record instance is "copied" by passing the result of the record component accessor methods to the canonical constructor, as follows: R copy = new R(r.c1(), r.c2(), ..., r.cn()); then it must be the case that `r.equals(copy)`. Annotations @Override

public boolean equals(Object obj)

Implements abstract java.lang.Record.equals.

Doc from java.lang.Record.equals.

Indicates whether some other object is "equal to" this one. In addition to the general contract of Object.equals, record classes must further obey the invariant that when a record instance is "copied" by passing the result of the record component accessor methods to the canonical constructor, as follows:

    R copy = new R(r.c1(), r.c2(), ..., r.cn());

then it must be the case that r.equals(copy).

Annotations

@Override

hashCode back to summary

hashCode	back to summary
public int hashCode() Implements abstract java.lang.Record.hashCode. Doc from java.lang.Record.hashCode. Returns a hash code value for the record. Obeys the general contract of `Object.hashCode`. For records, hashing behavior is constrained by the refined contract of `Record.equals`, so that any two records created from the same components must have the same hash code. Annotations @Override

public int hashCode()

Implements abstract java.lang.Record.hashCode.

Doc from java.lang.Record.hashCode.

Returns a hash code value for the record. Obeys the general contract of Object.hashCode. For records, hashing behavior is constrained by the refined contract of Record.equals, so that any two records created from the same components must have the same hash code.

Annotations

@Override

options	back to summary
public LinkerOptions options() Record Component getter of options.

toString back to summary

toString	back to summary
public final String toString() Implements abstract java.lang.Record.toString. Doc from java.lang.Record.toString. Returns a string representation of the record. In accordance with the general contract of `Object#toString()`, the `toString` method returns a string that "textually represents" this record. The result should be a concise but informative representation that is easy for a person to read. In addition to this general contract, record classes must further participate in the invariant that any two records which are equal must produce equal strings. This invariant is necessarily relaxed in the rare case where corresponding equal component values might fail to produce equal strings for themselves.

public final String toString()

Implements abstract java.lang.Record.toString.

Doc from java.lang.Record.toString.

Returns a string representation of the record. In accordance with the general contract of Object#toString(), the toString method returns a string that "textually represents" this record. The result should be a concise but informative representation that is easy for a person to read.

In addition to this general contract, record classes must further participate in the invariant that any two records which are equal must produce equal strings. This invariant is necessarily relaxed in the rare case where corresponding equal component values might fail to produce equal strings for themselves.

public abstract sealed Class AbstractLinker

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Record AbstractLinker.LinkRequest

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Interface AbstractLinker.UpcallStubFactory

Method Summary

Method Detail