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 must take zero or one dynamic operand.
• 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.)

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.
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:

""