From 524dd6794a3c01fc41209b3a91f3654f75a2fc73 Mon Sep 17 00:00:00 2001 From: Sergej Jaskiewicz Date: Fri, 2 Feb 2024 16:55:26 +0100 Subject: [PATCH] [JVM IR] Use KDoc in JvmSymbols i/o regular comments when possible --- .../kotlin/backend/jvm/JvmSymbols.kt | 124 +++++++++++------- 1 file changed, 74 insertions(+), 50 deletions(-) diff --git a/compiler/ir/backend.jvm/src/org/jetbrains/kotlin/backend/jvm/JvmSymbols.kt b/compiler/ir/backend.jvm/src/org/jetbrains/kotlin/backend/jvm/JvmSymbols.kt index aa019163647..53c09569ada 100644 --- a/compiler/ir/backend.jvm/src/org/jetbrains/kotlin/backend/jvm/JvmSymbols.kt +++ b/compiler/ir/backend.jvm/src/org/jetbrains/kotlin/backend/jvm/JvmSymbols.kt @@ -24,6 +24,7 @@ import org.jetbrains.kotlin.ir.UNDEFINED_OFFSET import org.jetbrains.kotlin.ir.builders.declarations.* import org.jetbrains.kotlin.ir.declarations.* import org.jetbrains.kotlin.ir.declarations.impl.IrExternalPackageFragmentImpl +import org.jetbrains.kotlin.ir.expressions.IrRawFunctionReference import org.jetbrains.kotlin.ir.expressions.impl.IrConstImpl import org.jetbrains.kotlin.ir.expressions.impl.IrConstructorCallImpl import org.jetbrains.kotlin.ir.symbols.* @@ -39,6 +40,7 @@ import org.jetbrains.kotlin.resolve.JVM_INLINE_ANNOTATION_FQ_NAME import org.jetbrains.kotlin.resolve.jvm.JvmClassName import org.jetbrains.kotlin.storage.LockBasedStorageManager import org.jetbrains.kotlin.types.Variance +import java.lang.invoke.MethodType class JvmSymbols( private val context: JvmBackendContext, @@ -62,15 +64,19 @@ class JvmSymbols( private val kotlinInternalPackage: IrPackageFragment = createPackage(FqName("kotlin.internal")) - // Special package for functions representing dynamic symbols referenced by 'INVOKEDYNAMIC' instruction - e.g., - // 'get(Ljava/lang/String;)Ljava/util/function/Supplier;' - // in - // INVOKEDYNAMIC get(Ljava/lang/String;)Ljava/util/function/Supplier; [ - // H_INVOKESTATIC java/lang/invoke/LambdaMetafactory.metafactory(...)Ljava/lang/invoke/CallSite; - // ... - // ] - // Such functions don't exist as methods in the actual bytecode - // (they are expected to be provided at run-time by the corresponding bootstrap method). + /** + * A special package for functions representing dynamic symbols referenced by the `INVOKEDYNAMIC` instruction — e.g., + * `get(Ljava/lang/String;)Ljava/util/function/Supplier;` + * in + * ``` + * INVOKEDYNAMIC get(Ljava/lang/String;)Ljava/util/function/Supplier; [ + * H_INVOKESTATIC java/lang/invoke/LambdaMetafactory.metafactory(...)Ljava/lang/invoke/CallSite; + * ... + * ] + * ``` + * Such functions don't exist as methods in the actual bytecode + * (they are expected to be provided at run-time by the corresponding bootstrap method). + */ val kotlinJvmInternalInvokeDynamicPackage: IrPackageFragment = createPackage(FqName("kotlin.jvm.internal.invokeDynamic")) private val generateOptimizedCallableReferenceSuperClasses = context.config.generateOptimizedCallableReferenceSuperClasses @@ -161,8 +167,10 @@ class JvmSymbols( }) } - // This function is used only with ir inliner. It is needed to ensure that all local declarations inside lambda will be generated, - // because after inline these lambdas can be dropped. + /** + * This function is used only with the IR inliner. It is needed to ensure that all local declarations inside lambda will be generated, + * because after inline these lambdas can be dropped. + */ val singleArgumentInlineFunction: IrSimpleFunctionSymbol = intrinsicsClass.functions.single { it.owner.name.asString() == "singleArgumentInlineFunction" } @@ -648,35 +656,41 @@ class JvmSymbols( val arrayOfAnyType = irBuiltIns.arrayClass.typeWith(irBuiltIns.anyType) val arrayOfAnyNType = irBuiltIns.arrayClass.typeWith(irBuiltIns.anyNType) - // Intrinsic to represent closure creation using INVOKEDYNAMIC with LambdaMetafactory.{metafactory, altMetafactory} - // as a bootstrap method. - // fun ``( - // samMethodType, - // implMethodReference, - // instantiatedMethodType, - // vararg extraOverriddenMethodTypes, - // shouldBeSerializable - // ): SAM_TYPE - // where: - // `SAM_TYPE` is a single abstract method interface, which is implemented by a resulting closure; - // `samMethodType` is a method type (signature and return type) of a method to be implemented by a closure; - // `implMethodReference` is an actual implementation method (e.g., method for a lambda function); - // `instantiatedMethodType` is a specialized implementation method type; - // `extraOverriddenMethodTypes` is a possibly empty vararg of additional methods to be implemented by a closure; - // `shouldBeSerializable` is true if the class of the resulting object should implement `java.io.Serializable`. - // - // At this stage, "method types" are represented as IrRawFunctionReference nodes for the functions with corresponding signature. - // `` call rewriting selects a particular bootstrap method (`metafactory` or `altMetafactory`) - // and takes care about low-level detains of bootstrap method arguments representation. - // Note that `instantiatedMethodType` is a raw function reference to a "fake" specialized function (belonging to a "fake" specialized - // class) that doesn't exist in the bytecode and serves only the purpose of representing a corresponding method signature. - // - // Resulting closure produced by INVOKEDYNAMIC instruction has (approximately) the following shape: - // object : ${SAM_TYPE} { - // override fun ${samMethodName}(${instantiatedMethodType}) = ${implMethod}(...) - // // bridge fun ${samMethodName}(${bridgeMethodType}) = ${instantiatedMethod}(...) - // // for each 'bridgeMethodType' in [ ${samMethodType}, *${extraOverriddenMethodTypes} ] - // } + /** + * An intrinsic to represent closure creation using `INVOKEDYNAMIC` with `LambdaMetafactory.{metafactory, altMetafactory}` + * as a bootstrap method. + * ```kotlin + * fun ``( + * samMethodType: Any?, + * implMethodReference: Any?, + * instantiatedMethodType: Any?, + * vararg extraOverriddenMethodTypes: Any, + * shouldBeSerializable: Boolean, + * ): SAM_TYPE + * ``` + * where: + * - `SAM_TYPE` is a single abstract method interface, which is implemented by a resulting closure; + * - `samMethodType` is a method type (signature and return type) of a method to be implemented by a closure; + * - `implMethodReference` is an actual implementation method (e.g., method for a lambda function); + * - `instantiatedMethodType` is a specialized implementation method type; + * - `extraOverriddenMethodTypes` is a possibly empty vararg of additional methods to be implemented by a closure; + * - `shouldBeSerializable` is true if the class of the resulting object should implement `java.io.Serializable`. + * + * At this stage, "method types" are represented as [IrRawFunctionReference] nodes for the functions with corresponding signature. + * `` call rewriting selects a particular bootstrap method (`metafactory` or `altMetafactory`) + * and takes care about low-level detains of bootstrap method arguments representation. + * Note that `instantiatedMethodType` is a raw function reference to a "fake" specialized function (belonging to a "fake" specialized + * class) that doesn't exist in the bytecode and serves only the purpose of representing a corresponding method signature. + * + * Resulting closure produced by INVOKEDYNAMIC instruction has (approximately) the following shape: + * ```kotlin + * object : ${SAM_TYPE} { + * override fun ${samMethodName}(${instantiatedMethodType}) = ${implMethod}(...) + * // bridge fun ${samMethodName}(${bridgeMethodType}) = ${instantiatedMethod}(...) + * // for each 'bridgeMethodType' in [ ${samMethodType}, *${extraOverriddenMethodTypes} ] + * } + * ``` + */ val indyLambdaMetafactoryIntrinsic: IrSimpleFunctionSymbol = irFactory.buildFun { name = Name.special("") @@ -753,13 +767,18 @@ class JvmSymbols( addValueParameter("isInterface", irBuiltIns.booleanType) }.symbol - // Intrinsic to represent INVOKEDYNAMIC calls in IR. - // fun ``( - // dynamicCall: T, - // bootstrapMethodHandle: Any, - // vararg bootstrapMethodArgs: Any - // ): T - // Bootstrap method handle is represented as a `` call. + /** + * An intrinsic to represent `INVOKEDYNAMIC` calls in IR. + * + * ```kotlin + * fun ``( + * dynamicCall: T, + * bootstrapMethodHandle: Any, + * vararg bootstrapMethodArgs: Any + * ): T + * ``` + * Bootstrap method handle is represented as a `` call. + */ val jvmIndyIntrinsic: IrSimpleFunctionSymbol = irFactory.buildFun { name = Name.special("") @@ -777,9 +796,14 @@ class JvmSymbols( returnType = t.defaultType }.symbol - // Intrinsic used to represent MethodType objects in bootstrap method arguments (see jvmInvokeDynamicIntrinsic above). - // Value argument is a raw function reference to a corresponding method (e.g., 'java.lang.function.Supplier#get'). - // Resulting method type is unsubstituted. + /** + * An intrinsic used to represent [MethodType] objects in bootstrap method arguments (see [jvmIndyIntrinsic] above). + * The value argument is a raw function reference to the corresponding method (e.g., `java.lang.function.Supplier#get`). + * The resulting method type is unsubstituted. + * ```kotlin + * fun ``(method: Any): Any + * ``` + */ val jvmOriginalMethodTypeIntrinsic: IrSimpleFunctionSymbol = irFactory.buildFun { name = Name.special("")