OpenJDK 27 · jdk.dynalink.support.ChainedCallSite · APIdia, the JavaDoc alternative

A relinkable call site that implements a polymorphic inline caching strategy. It remembers up to 8 GuardedInvocations it was linked with, and on each relink request builds a cascading chain of method handles of one invocation falling back to the next one. The number of remembered invocations can be customized by overriding getMaxChainLength() in a subclass. When this call site is relinked with a new invocation and the length of the chain is already at the maximum, it will throw away the oldest invocation. Invocations with invalidated switch points and ones for which their invalidating exception triggered are removed eagerly from the chain. The invocations are never reordered; the most recently linked method handle is always at the start of the chain and the least recently linked at its end. The call site can be safely relinked on more than one thread concurrently. Race conditions in linking are resolved by throwing away the GuardedInvocation produced on the losing thread without incorporating it into the chain, so it can lead to repeated linking for the same arguments.

Field Summary

Modifier and Type	Field and Description
private Object	invocations Contains the invocations currently linked into this call site's target.
private static final MethodHandle	PRUNE_CATCHES
private static final MethodHandle	PRUNE_SWITCHPOINTS

Constructor Summary

Access	Constructor and Description
public	ChainedCallSite(final CallSiteDescriptor the descriptor for the call site. descriptor) Creates a new chained call site.

Method Summary

Modifier and Type	Method and Description
private static int	checkMaxChainLength(final int maxChainLength)
protected int	Returns: the maximum number of method handles in the chain. The return value is checked, and if your override returns a value less than 1, a `RuntimeException` will be thrown. getMaxChainLength() The maximum number of method handles in the chain.
private MethodHandle	Returns: a method handle for prune-and-invoke makePruneAndInvokeMethod(final MethodHandle the ultimate fallback for the chain passed from the dynamic linker. relinkAndInvoke, final MethodHandle prune) Creates a method that rebuilds our call chain, pruning it of any invalidated switchpoints, and then invokes that chain.
private MethodHandle	prune(final MethodHandle relink, final boolean catches)
public void	relink(final GuardedInvocation guardedInvocation, final MethodHandle relinkAndInvoke) Implements jdk.dynalink.RelinkableCallSite.relink. This method will be called by the dynamic linker every time the call site is relinked (but see `resetAndRelink(GuardedInvocation, MethodHandle)` for an exception).
private MethodHandle	relinkInternal(final GuardedInvocation invocation, final MethodHandle relink, final boolean reset, final boolean removeCatches)
public void	resetAndRelink(final GuardedInvocation guardedInvocation, final MethodHandle relinkAndInvoke) Implements jdk.dynalink.RelinkableCallSite.resetAndRelink. This method will be called by the dynamic linker every time the call site is relinked and the linker wishes the call site to throw away any prior linkage state (that is how it differs from `relink(GuardedInvocation, MethodHandle)`).

Inherited from jdk.dynalink.support.AbstractRelinkableCallSite:: getDescriptor initialize

Field Detail

invocations back to summary

invocations	back to summary
private Object invocations Contains the invocations currently linked into this call site's target. They are used when we are relinking to rebuild the guardWithTest chain. Valid values for this field are: `null` if there's no linked invocations, or an instance of `GuardedInvocation` if there is exactly one previous invocation, or an instance of `GuardedInvocation[]` if there is more than one previous invocation.

private Object invocations

Contains the invocations currently linked into this call site's target. They are used when we are relinking to rebuild the guardWithTest chain. Valid values for this field are: null if there's no linked invocations, or an instance of GuardedInvocation if there is exactly one previous invocation, or an instance of GuardedInvocation[] if there is more than one previous invocation.

PRUNE_CATCHES	back to summary
private static final MethodHandle PRUNE_CATCHES

PRUNE_SWITCHPOINTS	back to summary
private static final MethodHandle PRUNE_SWITCHPOINTS

Constructor Detail

ChainedCallSite	back to summary
public ChainedCallSite(final CallSiteDescriptor descriptor) Creates a new chained call site. Parameters descriptor:CallSiteDescriptor the descriptor for the call site.

ChainedCallSite

back to summary

public ChainedCallSite(final CallSiteDescriptor descriptor)

Creates a new chained call site.

Parameters

descriptor:CallSiteDescriptor: the descriptor for the call site.

Method Detail

checkMaxChainLength	back to summary
private static int checkMaxChainLength(final int maxChainLength)

getMaxChainLength back to summary

getMaxChainLength	back to summary
protected int getMaxChainLength() The maximum number of method handles in the chain. Defaults to 8. You can override it in a subclass if you need to change the value. Returns:int the maximum number of method handles in the chain. The return value is checked, and if your override returns a value less than 1, a `RuntimeException` will be thrown.

protected int getMaxChainLength()

The maximum number of method handles in the chain. Defaults to 8. You can override it in a subclass if you need to change the value.

Returns:int: the maximum number of method handles in the chain. The return value is checked, and if your override returns a value less than 1, a RuntimeException will be thrown.

makePruneAndInvokeMethod	back to summary
private MethodHandle makePruneAndInvokeMethod(final MethodHandle relinkAndInvoke, final MethodHandle prune) Creates a method that rebuilds our call chain, pruning it of any invalidated switchpoints, and then invokes that chain. Parameters relinkAndInvoke:MethodHandle the ultimate fallback for the chain passed from the dynamic linker. Returns:MethodHandle a method handle for prune-and-invoke

makePruneAndInvokeMethod

back to summary

private MethodHandle makePruneAndInvokeMethod(final MethodHandle relinkAndInvoke, final MethodHandle prune)

Creates a method that rebuilds our call chain, pruning it of any invalidated switchpoints, and then invokes that chain.

Parameters

relinkAndInvoke:MethodHandle: the ultimate fallback for the chain passed from the dynamic linker.

Returns:MethodHandle

a method handle for prune-and-invoke

prune	back to summary
private MethodHandle prune(final MethodHandle relink, final boolean catches) Annotations @SuppressWarnings:unused

relink back to summary

relink	back to summary
public void relink(final GuardedInvocation guardedInvocation, final MethodHandle relinkAndInvoke) Implements jdk.dynalink.RelinkableCallSite.relink. Doc from jdk.dynalink.RelinkableCallSite.relink. This method will be called by the dynamic linker every time the call site is relinked (but see `resetAndRelink(GuardedInvocation, MethodHandle)` for an exception). It will be passed a `GuardedInvocation` that the call site should incorporate into its target method handle. When this method is called, the call site is allowed to keep other non-invalidated invocations around for implementation of polymorphic inline caches and compose them with this invocation to form its final target. Annotations @Override

public void relink(final GuardedInvocation guardedInvocation, final MethodHandle relinkAndInvoke)

Implements jdk.dynalink.RelinkableCallSite.relink.

Doc from jdk.dynalink.RelinkableCallSite.relink.

This method will be called by the dynamic linker every time the call site is relinked (but see resetAndRelink(GuardedInvocation, MethodHandle) for an exception). It will be passed a GuardedInvocation that the call site should incorporate into its target method handle. When this method is called, the call site is allowed to keep other non-invalidated invocations around for implementation of polymorphic inline caches and compose them with this invocation to form its final target.

Annotations

@Override

relinkInternal	back to summary
private MethodHandle relinkInternal(final GuardedInvocation invocation, final MethodHandle relink, final boolean reset, final boolean removeCatches)

resetAndRelink back to summary

resetAndRelink	back to summary
public void resetAndRelink(final GuardedInvocation guardedInvocation, final MethodHandle relinkAndInvoke) Implements jdk.dynalink.RelinkableCallSite.resetAndRelink. Doc from jdk.dynalink.RelinkableCallSite.resetAndRelink. This method will be called by the dynamic linker every time the call site is relinked and the linker wishes the call site to throw away any prior linkage state (that is how it differs from `relink(GuardedInvocation, MethodHandle)`). It will be passed a `GuardedInvocation` that the call site should use to build its new target method handle. When this method is called, the call site is discouraged from keeping any previous state, and is supposed to only link the current invocation. Annotations @Override

public void resetAndRelink(final GuardedInvocation guardedInvocation, final MethodHandle relinkAndInvoke)

Implements jdk.dynalink.RelinkableCallSite.resetAndRelink.

Doc from jdk.dynalink.RelinkableCallSite.resetAndRelink.

This method will be called by the dynamic linker every time the call site is relinked and the linker wishes the call site to throw away any prior linkage state (that is how it differs from relink(GuardedInvocation, MethodHandle)). It will be passed a GuardedInvocation that the call site should use to build its new target method handle. When this method is called, the call site is discouraged from keeping any previous state, and is supposed to only link the current invocation.