Inline value classes
Sometimes it is useful to wrap a value in a class to create a more domain-specific type. However, it introduces runtime overhead due to additional heap allocations. Moreover, if the wrapped type is primitive, the performance hit is significant, because primitive types are usually heavily optimized by the runtime, while their wrappers don't get any special treatment.
To solve such issues, Kotlin introduces a special kind of class called an inline class. Inline classes are a subset of value-based classes. They don't have an identity and can only hold values.
To declare an inline class, use the
value modifier before the name of the class:
To declare an inline class for the JVM backend, use the
value modifier along with the
@JvmInline annotation before the class declaration:
An inline class must have a single property initialized in the primary constructor. At runtime, instances of the inline class will be represented using this single property (see details about runtime representation below):
This is the main feature of inline classes, which inspired the name inline: data of the class is inlined into its usages (similar to how content of inline functions is inlined to call sites).
Inline classes support some functionality of regular classes. In particular, they are allowed to declare properties and functions, have an
init block and secondary constructors:
Inline class properties cannot have backing fields. They can only have simple computable properties (no
Inline classes are allowed to inherit from interfaces:
It is forbidden for inline classes to participate in a class hierarchy. This means that inline classes cannot extend other classes and are always
In generated code, the Kotlin compiler keeps a wrapper for each inline class. Inline class instances can be represented at runtime either as wrappers or as the underlying type. This is similar to how
Int can be represented either as a primitive
int or as the wrapper
The Kotlin compiler will prefer using underlying types instead of wrappers to produce the most performant and optimized code. However, sometimes it is necessary to keep wrappers around. As a rule of thumb, inline classes are boxed whenever they are used as another type.
Because inline classes may be represented both as the underlying value and as a wrapper, referential equality is pointless for them and is therefore prohibited.
Inline classes can also have a generic type parameter as the underlying type. In this case, the compiler maps it to
Any? or, generally, to the upper bound of the type parameter.
Since inline classes are compiled to their underlying type, it may lead to various obscure errors, for example unexpected platform signature clashes:
To mitigate such issues, functions using inline classes are mangled by adding some stable hashcode to the function name. Therefore,
fun compute(x: UInt) will be represented as
public final void compute-<hashcode>(int x), which solves the clash problem.
Calling from Java code
You can call functions that accept inline classes from Java code. To do so, you should manually disable mangling: add the
@JvmName annotation before the function declaration:
Inline classes vs type aliases
At first sight, inline classes seem very similar to type aliases. Indeed, both seem to introduce a new type and both will be represented as the underlying type at runtime.
However, the crucial difference is that type aliases are assignment-compatible with their underlying type (and with other type aliases with the same underlying type), while inline classes are not.
In other words, inline classes introduce a truly new type, contrary to type aliases which only introduce an alternative name (alias) for an existing type:
Inline classes and delegation
Implementation by delegation to inlined value of inlined class is allowed with interfaces: