93  * Interface for relinkable call sites. Language runtimes wishing to use this framework must use subclasses of

    91  * Interface for call sites managed by a {@link DynamicLinker}. Users of

    94  * {@link CallSite} that also implement this interface as their call sites. There is a readily usable

    92  * Dynalink must use subclasses of {@link CallSite} that also implement this

    95  * {@link MonomorphicCallSite} subclass that implements monomorphic inline caching strategy as well as a

    93  * interface as their call site implementations. There is a readily usable

    96  * {@link ChainedCallSite} that retains a chain of already linked method handles. The reason this is defined as an

    94  * {@link MonomorphicCallSite} subclass that implements monomorphic inline

    97  * interface instead of a concrete, albeit abstract class is that it allows independent implementations to choose

    95  * caching strategy as well as {@link ChainedCallSite} that implements a

    98  * between {@link MutableCallSite} and {@link VolatileCallSite} as they see fit.

    96  * polymorphic inline caching strategy and retains a chain of previously linked

    97  * method handles. A relinkable call site will be managed by a

    98  * {@link DynamicLinker} object after being associated with it using its

    99  * {@link DynamicLinker#link(RelinkableCallSite)} method.

   102      * Initializes the relinkable call site by setting a relink-and-invoke method handle. The call site

   103      * Invoked by dynamic linker to initialize the relinkable call site by

   103      * implementation is supposed to set this method handle as its target.

   104      * setting a relink-and-invoke method handle. The call site implementation

   104      * @param relinkAndInvoke a relink-and-invoke method handle supplied by the {@link DynamicLinker}.

   105      * is supposed to set this method handle as its target using

   106      * {@link CallSite#setTarget(MethodHandle)}. Relink-and-invoke is the

   107      * initial method handle set by

   108      * {@link DynamicLinker#link(RelinkableCallSite)} that will cause the call

   109      * site to be relinked to an appropriate target on its first invocation

   110      * based on its arguments, and that linked target will then be invoked

   111      * (hence the name). This linking protocol effectively delays linking until

   112      * the call site is invoked with actual arguments and thus ensures that

   113      * linkers can make nuanced linking decisions based on those arguments and

   114      * not just on the static method type of the call site.

   115      * @param relinkAndInvoke a relink-and-invoke method handle supplied by

   116      * Dynalink.

   116      * This method will be called by the dynamic linker every time the call site is normally relinked. It will be passed

   128      * This method will be called by the dynamic linker every time the call site

   117      * a {@code GuardedInvocation} that the call site should incorporate into its target method handle. When this method

   129      * is relinked (but see

   118      * is called, the call site is allowed to keep other non-invalidated invocations around for implementation of

   130      * {@link #resetAndRelink(GuardedInvocation, MethodHandle)} for an

   119      * polymorphic inline caches and compose them with this invocation to form its final target.

   131      * exception). It will be passed a {@code GuardedInvocation} that the call

   132      * site should incorporate into its target method handle. When this method

   133      * is called, the call site is allowed to keep other non-invalidated

   134      * invocations around for implementation of polymorphic inline caches and

   135      * compose them with this invocation to form its final target.

   121      * @param guardedInvocation the guarded invocation that the call site should incorporate into its target method

   137      * @param guardedInvocation the guarded invocation that the call site should

   122      * handle.

   138      * incorporate into its target method handle.

   123      * @param fallback the fallback method. This is a method matching the method type of the call site that is supplied

   139      * @param relinkAndInvoke a relink-and-invoke method handle. This is a

   124      * by the {@link DynamicLinker} to be used by this call site as a fallback when it can't invoke its target with the

   140      * method handle matching the method type of the call site that is supplied

   125      * passed arguments. The fallback method is such that when it's invoked, it'll try to discover the adequate target

   141      * by the {@link DynamicLinker} as a callback. It should be used by this

   126      * for the invocation, subsequently invoke {@link #relink(GuardedInvocation, MethodHandle)} or

   142      * call site as the ultimate fallback when it can't invoke its target with

   127      * {@link #resetAndRelink(GuardedInvocation, MethodHandle)}, and finally invoke the target.

   143      * the passed arguments. The fallback method is such that when it's invoked,

   144      * it'll try to obtain an adequate target {@link GuardedInvocation} for the

   145      * invocation, and subsequently invoke

   146      * {@link #relink(GuardedInvocation, MethodHandle)} or

   147      * {@link #resetAndRelink(GuardedInvocation, MethodHandle)}, and finally

   148      * invoke the target.

   129     public void relink(GuardedInvocation guardedInvocation, MethodHandle fallback);

   150     public void relink(GuardedInvocation guardedInvocation, MethodHandle relinkAndInvoke);

   132      * This method will be called by the dynamic linker every time the call site is relinked and the linker wishes the

   153      * This method will be called by the dynamic linker every time the call site

   133      * call site to throw away any prior linkage state. It will be passed a {@code GuardedInvocation} that the call site

   154      * is relinked <b>and</b> the linker wishes the call site to throw away any

   134      * should use to build its target method handle. When this method is called, the call site is discouraged from

   155      * prior linkage state (that is how it differs from

   135      * keeping previous state around, and is supposed to only link the current invocation.

   156      * {@link #relink(GuardedInvocation, MethodHandle)}). It will be passed a

   157      * {@code GuardedInvocation} that the call site should use to build its new

   158      * target method handle. When this method is called, the call site is

   159      * discouraged from keeping any previous state, and is supposed to only

   160      * link the current invocation.

   137      * @param guardedInvocation the guarded invocation that the call site should use to build its target method handle.

   162      * @param guardedInvocation the guarded invocation that the call site should

   138      * @param fallback the fallback method. This is a method matching the method type of the call site that is supplied

   163      * use to build its target method handle.

   139      * by the {@link DynamicLinker} to be used by this call site as a fallback when it can't invoke its target with the

   164      * @param relinkAndInvoke a relink-and-invoke method handle. This is a

   140      * passed arguments. The fallback method is such that when it's invoked, it'll try to discover the adequate target

   165      * method handle matching the method type of the call site that is supplied

   141      * for the invocation, subsequently invoke {@link #relink(GuardedInvocation, MethodHandle)} or

   166      * by the {@link DynamicLinker} as a callback. It should be used by this

   142      * {@link #resetAndRelink(GuardedInvocation, MethodHandle)}, and finally invoke the target.

   167      * call site as the ultimate fallback when it can't invoke its target with

   168      * the passed arguments. The fallback method is such that when it's invoked,

   169      * it'll try to obtain an adequate target {@link GuardedInvocation} for the

   170      * invocation, and subsequently invoke

   171      * {@link #relink(GuardedInvocation, MethodHandle)} or

   172      * {@link #resetAndRelink(GuardedInvocation, MethodHandle)}, and finally

   173      * invoke the target.

   144     public void resetAndRelink(GuardedInvocation guardedInvocation, MethodHandle fallback);

   175     public void resetAndRelink(GuardedInvocation guardedInvocation, MethodHandle relinkAndInvoke);