org.dynalang.dynalink.linker

Class GuardedInvocation

java.lang.Object

org.dynalang.dynalink.linker.GuardedInvocation

public class GuardedInvocation
extends Object

Represents a conditionally valid method handle. It is an immutable triple of an invocation method handle, a guard method handle that defines the applicability of the invocation handle, and a switch point that can be used for external invalidation of the invocation handle. The invocation handle is suitable for invocation if the guard handle returns true for its arguments, and as long as the switch point is not invalidated. Both the guard and the switch point are optional; neither, one, or both can be present.

Author:

Attila Szegedi

Constructor Summary

Constructors

Constructor and Description
GuardedInvocation(MethodHandle invocation, MethodHandle guard) Creates a new guarded invocation.
GuardedInvocation(MethodHandle invocation, MethodHandle guard, SwitchPoint switchPoint) Creates a new guarded invocation.
GuardedInvocation(MethodHandle invocation, SwitchPoint switchPoint, MethodHandle guard) Creates a new guarded invocation.

Method Summary

Methods

Modifier and Type	Method and Description
void	assertType(MethodType type) Asserts that the invocation is of the specified type, and the guard (if present) is of the specified type with a boolean return type.
GuardedInvocation	asType(CallSiteDescriptor desc) Changes the type of the invocation, as if MethodHandle.asType(MethodType) was applied to its invocation and its guard, if it has one (with return type changed to boolean for guard).
GuardedInvocation	asType(MethodType newType) Changes the type of the invocation, as if MethodHandle.asType(MethodType) was applied to its invocation and its guard, if it has one (with return type changed to boolean for guard).
MethodHandle	compose(MethodHandle fallback) Composes the invocation, switchpoint, and the guard into a composite method handle that knows how to fall back.
MethodHandle	compose(MethodHandle switchpointFallback, MethodHandle guardFallback) Composes the invocation, switchpoint, and the guard into a composite method handle that knows how to fall back.
GuardedInvocation	dropArguments(int pos, Class<?>... valueTypes) Makes an invocation that drops arguments in both the invocation and the guard (if there is one).
GuardedInvocation	dropArguments(int pos, List<Class<?>> valueTypes) Makes an invocation that drops arguments in both the invocation and the guard (if there is one).
GuardedInvocation	filterArguments(int pos, MethodHandle... filters) Applies argument filters to both the invocation and the guard (if there is one).
MethodHandle	getGuard() Returns the guard method handle.
MethodHandle	getInvocation() Returns the invocation method handle.
SwitchPoint	getSwitchPoint() Returns the switch point that can be used to invalidate the invocation handle.
boolean	hasBeenInvalidated() Returns true if and only if this guarded invocation has a switchpoint, and that switchpoint has been invalidated.
GuardedInvocation	replaceMethods(MethodHandle newInvocation, MethodHandle newGuard) Creates a new guarded invocation with different methods, preserving the switch point.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GuardedInvocation

public GuardedInvocation(MethodHandle invocation,
                 MethodHandle guard)

Creates a new guarded invocation.

Parameters:

invocation - the method handle representing the invocation. Must not be null.

guard - the method handle representing the guard. Must have the same method type as the invocation, except it must return boolean. For some useful guards, check out the Guards class. It can be null to represent an unconditional invocation, although that is unusual.

Throws:

NullPointerException - if invocation is null.

GuardedInvocation

public GuardedInvocation(MethodHandle invocation,
                 MethodHandle guard,
                 SwitchPoint switchPoint)

Creates a new guarded invocation.

Parameters:

invocation - the method handle representing the invocation. Must not be null.

guard - the method handle representing the guard. Must have the same method type as the invocation, except it must return boolean. For some useful guards, check out the Guards class. It can be null. If both it and the switch point are null, this represents an unconditional invocation, which is legal but unusual.

switchPoint - the optional switch point that can be used to invalidate this linkage.

Throws:

NullPointerException - if invocation is null.

GuardedInvocation

public GuardedInvocation(MethodHandle invocation,
                 SwitchPoint switchPoint,
                 MethodHandle guard)

Creates a new guarded invocation.

Parameters:

invocation - the method handle representing the invocation. Must not be null.

switchPoint - the optional switch point that can be used to invalidate this linkage.

guard - the method handle representing the guard. Must have the same method type as the invocation, except it must return boolean. For some useful guards, check out the Guards class. It can be null. If both it and the switch point are null, this represents an unconditional invocation, which is legal but unusual.

Throws:

NullPointerException - if invocation is null.

Method Detail

getInvocation

public MethodHandle getInvocation()

Returns the invocation method handle.

Returns:

the invocation method handle. It will never be null.

getGuard

public MethodHandle getGuard()

Returns the guard method handle.

Returns:

the guard method handle. Can be null.

getSwitchPoint

public SwitchPoint getSwitchPoint()

Returns the switch point that can be used to invalidate the invocation handle.

Returns:

the switch point that can be used to invalidate the invocation handle. Can be null.

hasBeenInvalidated

public boolean hasBeenInvalidated()

Returns true if and only if this guarded invocation has a switchpoint, and that switchpoint has been invalidated.

Returns:

true if and only if this guarded invocation has a switchpoint, and that switchpoint has been invalidated.

assertType

public void assertType(MethodType type)

Asserts that the invocation is of the specified type, and the guard (if present) is of the specified type with a boolean return type.

Parameters:

type - the asserted type

Throws:

WrongMethodTypeException - if the invocation and the guard are not of the expected method type.

replaceMethods

public GuardedInvocation replaceMethods(MethodHandle newInvocation,
                               MethodHandle newGuard)

Creates a new guarded invocation with different methods, preserving the switch point.

Parameters:

newInvocation - the new invocation

newGuard - the new guard

Returns:

a new guarded invocation with the replaced methods and the same switch point as this invocation.

asType

public GuardedInvocation asType(MethodType newType)

Changes the type of the invocation, as if MethodHandle.asType(MethodType) was applied to its invocation and its guard, if it has one (with return type changed to boolean for guard). If the invocation already is of the required type, returns this object.

Parameters:

newType - the new type of the invocation.

Returns:

a guarded invocation with the new type applied to it.

asType

public GuardedInvocation asType(CallSiteDescriptor desc)

Changes the type of the invocation, as if MethodHandle.asType(MethodType) was applied to its invocation and its guard, if it has one (with return type changed to boolean for guard). If the invocation already is of the required type, returns this object.

Parameters:

desc - a call descriptor whose method type is adapted.

Returns:

a guarded invocation with the new type applied to it.

filterArguments

public GuardedInvocation filterArguments(int pos,
                                MethodHandle... filters)

Applies argument filters to both the invocation and the guard (if there is one).

Parameters:

pos - the position of the first argumen being filtered

filters - the argument filters

Returns:

a filtered invocation

dropArguments

public GuardedInvocation dropArguments(int pos,
                              List<Class<?>> valueTypes)

Makes an invocation that drops arguments in both the invocation and the guard (if there is one).

Parameters:

pos - the position of the first argument being dropped

valueTypes - the types of the values being dropped

Returns:

an invocation that drops arguments

dropArguments

public GuardedInvocation dropArguments(int pos,
                              Class<?>... valueTypes)

Makes an invocation that drops arguments in both the invocation and the guard (if there is one).

Parameters:

pos - the position of the first argument being dropped

valueTypes - the types of the values being dropped

Returns:

an invocation that drops arguments

compose

public MethodHandle compose(MethodHandle fallback)

Composes the invocation, switchpoint, and the guard into a composite method handle that knows how to fall back.

Parameters:

fallback - the fallback method handle in case switchpoint is invalidated or guard returns false.

Returns:

a composite method handle.

compose

public MethodHandle compose(MethodHandle switchpointFallback,
                   MethodHandle guardFallback)

Composes the invocation, switchpoint, and the guard into a composite method handle that knows how to fall back.

Parameters:

switchpointFallback - the fallback method handle in case switchpoint is invalidated.

guardFallback - the fallback method handle in case guard returns false.

Returns:

a composite method handle.