Annotation Interface Yield

@Retention(SOURCE)
@Target(TYPE)
public @interface Yield

Declares a custom yield operation. A custom yield operation has the same control flow behaviour as the built-in yield, but allows to customize the result produced. For example, a custom yield can create a guest generator object instead of a ContinuationResult, or it can perform custom logic before creating the continuation result.

Below is an example of a custom yield that returns a guest language generator object:

@Yield
public static final class CustomYield {
    @Specialization
    public static Object doYield(Object value, @Bind ContinuationRootNode root, @Bind MaterializedFrame frame) {
        return new MyGeneratorObject(root, frame, value);
    }
}

A custom yield operation has many of the same restrictions and capabilities of a regular Operation, with a few differences:

• It can take zero or more dynamic operands.
• It yields a value to the caller, so it must have a return value. The result should be a valid interop type. Typically, the result should encapsulate the continuation state so that the callee can resume execution at a later time.
• It can Bind a ContinuationRootNode operand, which can be used to resume execution at a later time. (Custom yields will typically also Bind the MaterializedFrame to capture the interpreter state, but this is possible in regular operations.)

If a custom yield takes multiple dynamic operands, resultOperandIndex() specifies which operand represents the logical "result" of the yield before the custom yield executes. This result is used by tag instrumentation.

Note that GenerateBytecode.enableYield() does not need to be true to use custom yields; it is only necessary if you need the built-in yield operation. The built-in yield operation is semantically equivalent to the following custom yield operation:

@Yield
public static final class BuiltinYield {
    @Specialization
    public static Object doYield(Object result, @Bind ContinuationRootNode root, @Bind MaterializedFrame frame) {
        return ContinuationResult.create(root, frame, result);
    }
}

Since:

25.1

See Also:

• GenerateBytecode.enableYield()

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	forceCached	Whether executing this operation should force the uncached interpreter (if enabled) to transition to cached.
String	javadoc	Optional documentation for the instrumentation.
int	resultOperandIndex	Index of the dynamic operand that represents the logical "result" of the yield before the custom yield executes.
Class<? extends Tag>[]	tags	The instrumentation tags that should be implicitly associated with this operation.

Element Details

forceCached

boolean forceCached

Whether executing this operation should force the uncached interpreter (if enabled) to transition to cached.

Since:

25.1

See Also:

• Operation.forceCached()

Default:

false

tags

Class<? extends Tag>[] tags

The instrumentation tags that should be implicitly associated with this operation.

Since:

25.1

See Also:

• GenerateBytecode.enableTagInstrumentation()

Default:

{}

javadoc

String javadoc

Optional documentation for the instrumentation. This documentation is included in the javadoc for the generated interpreter.

Since:

25.1

Default:

""

resultOperandIndex

int resultOperandIndex

Index of the dynamic operand that represents the logical "result" of the yield before the custom yield executes. This result is used by tag instrumentation.

This field must be specified for custom yields with multiple dynamic operands; it should not be specified for custom yields with no dynamic operands.

Since:

25.2

Default:

0