Package: org.codehaus.groovy.vmplugin.v8

## [Java] Class CacheableCallSite

- org.codehaus.groovy.vmplugin.v8.CacheableCallSite

-     public class CacheableCallSite
      extends MutableCallSite

  Represents a cacheable call site, which can reduce the cost of resolving methods

  Since:
    3.0.0

- - ### Constructor Summary

    Constructors
    Constructor and description
    `CacheableCallSite(MethodType type, Lookup lookup)` Creates a cacheable call site for the supplied type and lookup context.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public MethodHandleWrapper` | `getAndPut(String className, org.codehaus.groovy.runtime.memoize.MemoizeCache.ValueProvider<? super String, ? extends MethodHandleWrapper> valueProvider)` Returns a cached method-handle wrapper for the receiver class, computing and storing it if needed.
    `` | `public MethodHandle` | `getDefaultTarget()` Returns the default target currently installed on this call site.
    `` | `public AtomicLong` | `getFallbackRound()` Returns the fallback round counter.
    `` | `public MethodHandle` | `getFallbackTarget()` Returns the fallback target used when guards fail.
    `` | `public MethodHandleWrapper` | `getIfPresent(String className)` Read-only PIC lookup: the cached wrapper for the receiver class, or `null` when absent or its soft reference has been cleared.
    `` | `public Lookup` | `getLookup()` Returns the lookup associated with this call site.
    `` | `public long` | `incrementFallbackCount()` Increments the number of fallback executions for this call site.
    `` | `public boolean` | `isAotLinked()` Whether this site was linked in AOT mode (GraalVM native image, or the `groovy.indy.aot.link` diagnostic knob): the site is wrapped in a `ConstantCallSite` over the cache-consulting default path, is never retargeted, and cache freshness is carried by the `AotDispatch` stamp instead of SwitchPoints.
    `` | `public MethodHandleWrapper` | `put(String name, MethodHandleWrapper mhw)` Stores a method-handle wrapper under the supplied cache key.
    `` | `public void` | `resetFallbackCount()` Resets the fallback count and advances the fallback round marker.
    `` | `public void` | `setDefaultTarget(MethodHandle defaultTarget)` Stores the default target for this call site.
    `` | `public void` | `setFallbackTarget(MethodHandle fallbackTarget)` Stores the fallback target used when guards fail.
    `` | `public void` | `setTarget(MethodHandle newTarget)` Fails fast on any retarget attempt in AOT mode.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class MutableCallSite` | `dynamicInvoker, equals, getClass, getTarget, hashCode, notify, notifyAll, setTarget, syncAll, toString, type, wait, wait, wait`

- - ### Constructor Detail

    - #### public CacheableCallSite(MethodType type, Lookup lookup)

      Creates a cacheable call site for the supplied type and lookup context.

      Parameters:
        `type` - the call-site type
        `lookup` - the lookup used to unreflect targets

  - ### Method Detail

    - #### public MethodHandleWrapper getAndPut(String className, org.codehaus.groovy.runtime.memoize.MemoizeCache.ValueProvider<? super String, ? extends MethodHandleWrapper> valueProvider)

      Returns a cached method-handle wrapper for the receiver class, computing and storing it if needed.

      Parameters:
        `className` - the receiver cache key
        `valueProvider` - the provider used to compute a missing entry
      Returns:
        the cached or newly created wrapper

    - #### public MethodHandle getDefaultTarget()

      Returns the default target currently installed on this call site.

      Returns:
        the default target

    - #### public AtomicLong getFallbackRound()

      Returns the fallback round counter.

      Returns:
        the fallback round counter

    - #### public MethodHandle getFallbackTarget()

      Returns the fallback target used when guards fail.

      Returns:
        the fallback target

    - #### public MethodHandleWrapper getIfPresent(String className)

      Read-only PIC lookup: the cached wrapper for the receiver class, or `null` when absent or its soft reference has been cleared. Used by the AOT dispatch path, which resolves misses itself and must not pay for a value-provider allocation per call.

      Parameters:
        `className` - the receiver cache key
      Returns:
        the cached wrapper or `null`

    - #### public Lookup getLookup()

      Returns the lookup associated with this call site.

      Returns:
        the call-site lookup

    - #### public long incrementFallbackCount()

      Increments the number of fallback executions for this call site.

      Returns:
        the updated fallback count

    - #### public boolean isAotLinked()

      Whether this site was linked in AOT mode (GraalVM native image, or the `groovy.indy.aot.link` diagnostic knob): the site is wrapped in a `ConstantCallSite` over the cache-consulting default path, is never retargeted, and cache freshness is carried by the `AotDispatch` stamp instead of SwitchPoints.

    - #### public MethodHandleWrapper put(String name, MethodHandleWrapper mhw)

      Stores a method-handle wrapper under the supplied cache key.

      Parameters:
        `name` - the receiver cache key
        `mhw` - the wrapper to cache
      Returns:
        the previously cached wrapper, or `null` if none existed

    - #### public void resetFallbackCount()

      Resets the fallback count and advances the fallback round marker.

    - #### public void setDefaultTarget(MethodHandle defaultTarget)

      Stores the default target for this call site.

      Parameters:
        `defaultTarget` - the default target handle

    - #### public void setFallbackTarget(MethodHandle fallbackTarget)

      Stores the fallback target used when guards fail.

      Parameters:
        `fallbackTarget` - the fallback target handle

    - #### public void setTarget(MethodHandle newTarget)

      Fails fast on any retarget attempt in AOT mode. Under a real native image `setTarget` throws `UnsupportedFeatureError` anyway — and worse, execution would continue with the stale target if that error were swallowed — so a missed gate is a bug on every platform; this surfaces it on the JVM, where tests run with the diagnostic knob.