inline value class: a uniform spelling for value classes of the inline kind for all platforms

[ice-phoenix]

Kotlin currently infers that single-field value classes are inline on non-JVM platforms implicitly, by the single-field shape, while JVM requires an explicit @JvmInline annotation. With full value classes (MFVCs), the implicit inference on non-JVM platforms becomes ambiguous:

@Serializable
value class UserId(val value: String) // inline? full?

Adding a field could silently turn an inline value class into a full value class and change, for example, its serialized representation:

@Serializable
value class UserId(val value: String, val source: String)

KEEP-0468 introduces inline value class as a new unified spelling for this class kind while retaining @JvmInline as an equivalent spelling. After migration, when full value classes are enabled, marked classes remain inline, while an unmarked value class denotes a full value class, even if it has a single field.

We’d appreciate feedback on this idea, and the migration strategy, especially from multiplatform library and tooling authors.

[kyay10]

@BinaryInline could be a better name, analogous to @BinarySignatureName being the KMP equivalent of @JvmName

[CLOVIS-AI]

We could introduce inline value class as the common spelling.

inline value class Color(val rgb: Int)

This makes the declaration read as one coherent class kind, but it requires a boilerplate-y migration: most existing JVM and common declarations are already marked with @JvmInline, and they must eventually be rewritten even though its semantic kind does not change. It also marks inline value class as a full part of the Kotlin language, whereas we hope to reduce or even eliminate the need to think about inline value class kind once project Valhalla and other activities around value classes are complete.

I'm not convinced.

First,

it requires a boilerplate-y migration: most existing JVM and common declarations are already marked with @JvmInline, and they must eventually be rewritten even though its semantic kind does not change

It's the exact same migration as migrating from @JvmInline to @PlatformInline and can be solved the same way via IDE integration.

But more importantly, the same KEEP states:

To name a few concrete examples:

• Compose uses common value classes as lightweight type-safe wrappers, and it needs them to stay that way for performance purposes.
• Serialization tools, such as kotlinx.serialization and Ktor OpenAPI, use the inline shape to conventionally represent value classes as their underlying values rather than a full class-like structure.
• Export tools such as SKIE expose single-field value classes as their underlying properties.

In other words, "single-field value class" has become a cross-tool convention for the inline value class kind. With full value classes this is no longer automatically the case, and whether a value class is inline should not be inferred solely from the number of primary properties.

It sounds to me that this is behavior that is here to stay, and a meaningful semantic difference.

Unless you have plans for these three use-cases to not need @PlatformInline in the future, my vote is for a keyword.

[CLOVIS-AI]

(I do agree that inline class is bad idea, it's a value class that happens to be compiled in a specific way, not an entirely new kind of class)

[ice-phoenix]

Hi mates! After internal discussions and taking your feedback into consideration, we will be going with the inline value class spelling instead of @PlatformInline value class one! The mechanical updates to the KEEP will be done some time later, but nothing fundamental is changed w.r.t. the spirit of the proposal.

[ice-phoenix]

Update done!

[CLOVIS-AI]

I am personally in favor of deprecating @JvmInline value class if it's exactly the same as inline value class.

I don't particularly like that the annotation is called @JvmXXX but has behavior that impacts non-JVM platforms. It makes sense to me as a transitional state with at least soft-deprecation, but I'm not a fan long-term.

[quickstep24]

I assume that when Valhalla arrives, many code authors will like to use Valhalla value classes on the JVM (for Java compatibility, value-class arrays, etc.) and Kotlin inline value classes as a fallback solution on other platforms (for performance).
My understanding was, that the @JvmInline annotation provided just that choice:

• Old: @JvmInline value class = Kotlin inline class on all platforms including JVM
• Old: value class = JVM value class on JVM and Kotlin inline class on all other platforms

Can you describe if and how the new proposal supports this use-case.