Assign-Once Properties

[InversionSpaces]

Discussion for the Assign-Once Properties proposal. The full text is available here.

This proposal introduces assign-once properties to Kotlin.
They are a middle ground between lateinit var and val:

• Declared without an initializer. Reading before initialization throws.
• Can be assigned only once. Reassignment throws.
• Become stable after initialization.

Assign-once properties fit better where currently lateinit var is used:
fields for dependency injection or late setup initialization.

We discuss two possible ways to surface this feature in the language:
a new modifier for var declarations, or delegated properties.

class Example {
    // A new modifier for var declarations
    assignonce var service: Service
    // A standard AssignOnce property delegate
    // with builder: fun <T> assignOnce(): AssignOnce<T>
    var service: Service by assignOnce() 
}

We'd greatly appreciate input from the community, especially regarding the following questions:

• Should this be a new modifier, or "delegate-first"?
• Are smartcasts for assign-once properties a must-have?
• Is the requirement for explicit use-site targets (e.g. @set:) for annotations on assign-once properties acceptable?
• How critical is the allocation and performance overhead of assign-once properties?

[rnett]

To answer your questions:

• I'm majorly in favor of using delegates, rather adding modifier bloat.
• No, but it would certainly be very nice
• It's pretty awkward. I remember a while back there was discussion about making all the default target, would that solve this?
• Very important. Most of the time I find myself using this sort of variable, or lateinit, is for performance reasons already, or in performance sensitive code that is written in a way that can't be made more idiomatic for the performance reasons.

[InversionSpaces]

Thank you for your input!

Regarding @all: as the default target, I believe it is not a solution in this case.
In particular, @Inject annotation should be applied to the setter only:

• If it is applied to the getter, a DI framework will call the getter (possibly before setting the property)
• If it is applied to the property holding the delegate instance, a DI framework will try to inject to it (and fail because it is final)

Also, using @all: with delegated properties is prohibited because it is often ambiguous.

Could you please elaborate on using lateinit var in performance-sensitive contexts, possibly with an example? As stated in the document, we do not propose deprecating lateinit var, so it can always serve as a fallback when performance is critical. The question, then, is whether the overhead of the proposed assign-once property implementation is acceptable for the majority of assign-once use cases (dependency injection, late initialization).

[rnett]

Could you please elaborate on using lateinit var in performance-sensitive contexts, possibly with an example? As stated in the document, we do not propose deprecating lateinit var, so it can always serve as a fallback when performance is critical. The question, then, is whether the overhead of the proposed assign-once property implementation is acceptable for the majority of assign-once use cases (dependency injection, late initialization).

Sure. I don't consider using lateinit particularly idiomatic code (or var at all tbh), and avoid it when I can. There is typically a way to restructure code that would use it to use more idiomatic patterns instead. The cases when I end up using it are usually when the overhead of not using it is too high, which is typically in performance sensitive code (inner loops, large data processing, etc). Although there's also cases where it's just not possible due to the other APIs I'm working with. Some recent examples:

• A wrapper around Java IO streams for compression, where some fields need to be initialized on the first call. This is a perfect use-case for assign-once. It's very important here that the fast path (checking for init -> no update) is fast.
• Some graph processing algorithms. The lateinit vars are initialized from within the inner processing loops, and so are very performance sensitive.

I think the compromise of using lateinit var in particular performance code is fine, but not ideal, especially if lateinit val is used instead of delegates. I would expect most developers to assume that delegates have a performance penalty, but a modifier like lateinit val does not.

[InversionSpaces]

This is a perfect use-case for assign-once. It's very important here that the fast path (checking for init -> no update) is fast.

If I understood your examples correctly, our vision on use-cases for assign-once differs. As stated in the proposal, we expect assign-once properties to be used mostly where exactly one assignment is guaranteed through external means that compiler could not check statically, e.g., dependency injection. In a sense, it is an extension of allowing to defer the initialization of a val, see discussion below.

That said, the path (checking for init -> no update) should not matter much in such cases, because it is done only once. If you have a loop or a repeated call where initialization status of a property affects control flow, we suggest using a var. See the section on isInitialized check.

However, I believe that delegate-based implementation would still provide reasonably performant reads and writes (calls to getValue and setValue will be inlined on hot paths on the JVM). Most noticeable overhead is the allocation of the delegate and its memory footprint. Do you think this would be a big concern for your use-cases?

[rnett]

Ah yeah, that case would need to stick with var. If the only overhead is the delegate object, I think that's fine.

[rnett]

About stability: I understand not wanting to open the can of worms that would be a general way to declare delegates stable here. However, having some way to declare things stable has came up multiple different times in different areas (i.e. here, the sharing keep), and I would hope that some solution that works for both delegates, custom getters, and external modules can be created. It seems like a good place for a new contract to me, if delegates could have property contracts. I have written a few stable delegates (e.g. getting from an immutable map, or env var on JVM) before and being able to smart cast them would be super nice.

[InversionSpaces]

I agree that declaring stability would be a prominent feature, and during our research we indeed encountered many user-defined delegates that are stable. However, we would prefer to refrain from introducing a new unchecked contract into the language.
In any case, this deserves a separate design discussion, and if we special case AssignOnce delegate now, it can be still incorporated into a more general approach later.

[kyay10]

As delegates implementing AssignOnce interface are considered stable by convention, it has to be made sealed to prohibit extensions that do not conform to stability.

I really dislike this.
My top preference would be to have a general stability marking mechanism (likely in the form of a contract), but I understand the need to refrain from that for now.

My next preference is to mark AssignOnce with @SubclassOptIn, and thus leave it to the user to implement it aptly. This would thus allow having Lazy implement it as well, which is a plus in my eyes (and Lazy absolutely should have had a SubclassOptIn already)

[InversionSpaces]

Thank you for your suggestion!

Marking AssignOnce with SubclassOptInRequired is indeed a good compromise, we should add this option to the proposal.

However, I am not sure that it is crucial to allow inheritance from AssignOnce. There are situations where it can prove useful, but I believe that most of intended use-cases would be covered by provided implementations.

[kyay10]

About the allocation of a delegate: I wonder what the future holds in this aspect w.r.t. value classes. If we had mutating operator fun setValue, then we can trivially have the non-thread-safe assign once delegate compile down to a normal field. Perhaps that's too far in the future to think about, but it feels like that'd be the ideal design here with even less compromises.

[InversionSpaces]

Thank you for the idea!

Although it is indeed still far in the future and requires stabilization of value classes, the idea seems appealing as a possible new property delegate definition convention. It might allow to define "inlinable" property delegates under some reasonable constraints.

But developing a consistent design for a new convention is certainly far beyond the scope of the current proposal.

[kyay10]

verifying the stability of arbitrary user-defined delegates would be hard in practice, and the compiler would have to treat it as a trusted assumption.

That's exactly what contracts are for! Contracts let you do way more dangerous things! Your analysis of how difficult it'd be to debug is already true of contracts, which is an incredible feature to have for libraries (including the stdlib)

You also say that it's not a property of the getValue, but I disagree. The fact that setValue might change it is irrelevant. I can just as well have no setValue, but still exposed a way to change what getValue may return. Hell, I could have getValue return a random number!
My point is, stability is absolutely a property of getValue. Declaring my getValue to be stable means that I guarantee the implementation will return the same value every time. For AssignOnce, it means that I guarantee that the field it holds will only change once. Thus, I have some Data type invariant, and based on it I surface a property about my getValue. Kotlin's philosophy on extensibility is really important here. It doesn't make much sense to mark my types with a marker interface when instead I can use a contract or similar to mark this method in a special way. Someone could even have 2 different getValue implementations for the same data type where one might be stable, and the other isn't (e.g. with type arguments)

[InversionSpaces]

That's exactly what contracts are for! Contracts let you do way more dangerous things!

I would argue that contracts are not a mechanism for enabling a “just trust me” mode in the compiler. Their purpose is to provide additional information to the function’s caller, enriching the function signature. From that perspective, you are right that contracts can be used to declare stability.

That said, there’s a separate question of whether contract conformance should be checked. At the moment, we believe we should focus on making contracts safer and avoid introducing additional unchecked ones.

My point is, stability is absolutely a property of getValue

I think the same dual nature of a contract (stability, in our case) is what’s causing confusion here. If we’re talking about promising the stability of getValue to an external caller, then a natural way to do so is indeed to put a contract on that method itself.

However, the proposal discusses checking that stability is actually guaranteed. From that perspective, one would need to consider the entire delegate to verify the contract, which is difficult in practice.

[kyay10]

Firstly, thank you so much for responding! I know this is out-of-scope, so I don't want to waste your time. Feel free to ignore this reply!

Here's my library-developer perspective:
Most property delegates are declared by library/DSL developers (i.e. the actual operator fun Foo.getValue is in a library). In fact, I'd argue that it's specifically libraries, and not just multi-module projects where one may have an internal "library".
I think contract checking would be incredible to have (with opt-outs through suppression of course), but I think the average user is way more likely to write a callsInPlace or returns or even a holdsIn contract, than to write a stability contract for a property delegate.
Thus, I think having this contract would be helpful, and it's okay to burden the writer with verifying their implementation manually.
I'm also personally opposed to "magic" being added to the language that only the stdlib has access to, but we don't. I feel somewhat similarly about internal annotations like OnlyInputTypes, but at least there's workarounds for those.
I think putting a new contract, and keeping it some OptIn to emphasize that "you better know what you're doing", is way better.
My opinion is that stability is an incredibly important contract to have because of its interaction with smart casts. Thus, I think it's inevitable that some mechanism is added for it, so I'd rather have it sooner than later (and any checker and guarantees can always come later)
I completely understand if the direction the team wants to go in is "guaranteed safety". It's a valid direction to have. I think this case is niche enough, though, that having a guarantee isn't as necessary, compared to having the feature in the first place.

[kyay10]

I like the delegate approach more, but for the language approach, lateinit val feels natural. You mention that assigning to a val is strange, but that's actually already possible in Kotlin (and is a really nice feature of it IMO):

val foo: String
foo = ""

So there's precedent for assigning to an uninitialised val.

I'd also love a delegate version of lateinit that doesn't have its limitations.

[xvbcfj]

+1 to lateinit val. Right now, a lot of times I type this in and then realize that this is not supported.

[InversionSpaces]

Kotlin has great support for deferring initialization of local vals. However, we expect assign-once properties to be used mainly for class properties. For class properties, a val must be initialized either at the declaration site or in an init block. That means reading a val property is always valid, and assigning to it outside the constructor is always invalid (it won't compile). Neither statement is strictly true for a lateinit val, so the concept may be confusing.

On the other hand, introducing lateinit val would create a consistent model for properties:

	var	lateinit var	lateinit val	val
read	anytime	after first write	after first write	anytime
write	anytime	anytime	once	once (on initialization)

[kyay10]

EDIT: I realize now that you mean "outside of the init block", so my points aren't as strong. Still, I think the fact that it also expands the scope of writes isn't too strange.

reading a val property is always valid

Runtime-valid? Yes. At compile-time, you'll get errors if you try to read a val that wasn't initialized yet. In fact, the same exact thing happens with var:
I view lateinit as turning compile-time errors into runtime errors. The fact that this code errors at compile time:

var foo: String
println(foo)

while this errors at runtime:

lateinit var foo: String
println(foo)

is where my mental model comes from. If lateinit only moves compile time errors to runtime errors, then it also makes sense that it prevents reassignment. This code gives a compile error in the last line:

val foo: String
foo = ""
foo = "world"

and thus lateinit val foo would give a runtime error in the last line!

[kyay10]

Here's my version of your table, but taking into account compile time errors:

	var	lateinit var	lateinit val	val
read	after first write (compile-time error)	after first write (runtime error)	after first write (runtime error)	after first write (compile-time error)
write	anytime	anytime	once (runtime error)	once (compile-time error)

The behaviour match! The only difference is whether it's caught at compile-time or runtime

[adam-enko]

Maybe it's just a placeholder name, but I don't find assignonce easy to read because it contains many overlapping words. I keep skimming over it and reading some weird variation.

• assing once?
• as sign once?
• asign nonce? 😨
• ass ignonce?

I'd find a simpler phrase, something like setonce, easier to read. But lateinit val would make more sense to me.

(I don't have an opinion on a modifier vs delegate)

[OliverO2]

I agree that assignonce is not very readable. It also adds unnecessary complexity, as it introduces a new keyword for a concept that already exists in the language, as has been pointed out above.

So where the KEEP argues against lateinit val

However, lateinit vals would become vals that can be assigned after the declaration, which is conceptually confusing as vals are expected to be immutable.

it appears unconvincing, since val is already present in the language for "assign once" semantics.

lateinit val seems like an excellent choice to me.

[InversionSpaces]

Thank you for your feedback!

since val is already present in the language for "assign once" semantics.

While this is true for local vals, val class properties can not be assigned to, only initialized, see the comment above.

[OliverO2]

Thanks for pointing out the differences in class initialization:

For class properties, a val must be initialized either at the declaration site or in an init block.

If lateinit val would relax that constraint to allow initialization after init, it would still appeal to me, combining the familiar concepts of val and lateinit. I'd interpret it as a pure val guaranteeing the initialization at compile time (which requires a local control flow or an init block for classes), while lateinit val guarantees (one-time) initialization at run time (only available in classes for now, but in principle it could be extended to local vals where the compiler can't determine the control flow).

[adam-enko]

I just want to restate my feedback because I think it was missed in the general discussion about the implementation of the feature (a new keyword vs delegate). I don't have a strong opinion about either mechanism. I do have a strong dislike of the proposed keyword, assignonce, because it's not easy to read. Another, simpler keyword (e.g. setonce) would be much appreciated.

A delegate called assignOnce is okay - the camelcase makes it easier to read.

[InversionSpaces]

Thanks everyone for the feedback!

We see that people are mostly in favor of introducing lateinit val. Indeed, it contributes to a consistent property model where lateinit modifier allows late initialization while transferring guarantees to the runtime:

	var	lateinit var	lateinit val	val
read	after first write (ensured statically)	after first write (ensured at the runtime)	after first write (ensured at the runtime)	after first write (ensured statically)
write	anytime	anytime	once (ensured at the runtime)	once (ensured statically)

To continue the discussion, we would like to draw your attention to the problems with the lateinit val design.

Customization

The lateinit val design does not allow customizing semantics compared to the delegate-first design.
This does not allow opting out from thread-safety to avoid unnecessary synchronization, for example:

// Delegate-first approach allows customization:
var property: String by assignOnce(mode = AssignOnceThreadSafetyMode.NONE)

// lateinit val provides no way to opt out of thread-safety:
lateinit val property: String

Compilation Scheme

We believe that lateinit val has to be compiled to a delegated property to provide consistent semantics.
See the corresponding section of the proposal. This compilation scheme is much more complex than those of var, val and lateinit var. Not only might it cause confusion, it also causes problems described in the following sections.

Performance

While reads and writes are expected to be fairly performant on the JVM, compiling lateinit val requires allocating a delegate object for each assign-once property, adding memory overhead compared to lateinit var.

lateinit val property: String

// What the compiler generates:
private val property$delegate = AssignOnce<String>() // extra allocation
var property: String
    get() = property$delegate.getValue(...)
    set(value) = property$delegate.setValue(...)

This mismatch between the lightweight syntax and the heavier underlying mechanism could be a source of confusion, especially when migrating from lateinit var.

Annotations

Compilation scheme of lateinit val creates no backing field, so DI annotations like @Inject require an explicit @set: use-site target to reach the generated setter:

// @Inject targets the backing field, this works:
@Inject lateinit var service: Service

// No backing field, explicit target is required:
@set:Inject lateinit val service: Service

The two declarations look almost identical, but behave fundamentally differently with respect to annotations. This is especially problematic given that dependency injection is one of the primary use cases motivating the proposal.

Serialization

In kotlinx.serialization, delegated properties are treated as transient by default. Since lateinit val is compiled to a delegated property, it would not be serializable out of the box. This is unlike lateinit var, which is usually supported.

@Serializable
class Model {
    // Works with kotlinx.serialization:
    lateinit var field: String

    // Treated as transient by default:
    lateinit val field: String
}

While most intended use cases for assign-once properties involve non-serializable values, this is another case where lateinit val looks like lateinit var but behaves differently.

Conclusion

Introducing lateinit val is syntactically appealing and contributes to a consistent property model. However, due to the compilation scheme, it introduces ergonomic friction and unexpected performance overhead that one might not anticipate from the combination of familiar lateinit and val keywords.

We'd love to hear what you think about these trade-offs.

[OliverO2]

It can be done relatively cheap, using CAS operations.

To clarify: Cheap in terms of CPU operation count. Might be less cheap in cache line invalidations.

Other language constructs like val, var and lateinit var could not produce such [data race] situations.

To clarify: Data races in these cases exist, but they are not under language control.

Those annotations and their semantics are under third-party control, we should not assume something about them.

Makes sense, I agree.

[kyay10]

Data races in these cases exist, but they are not under language control.

It's not about language control, I don't think. This proposal includes smart casts, which would be invalid if a data race happens. The other language features mentioned do not suffer from this issue (data races causing invalid smart casts). The compiler providing smart casts is a strong guarantee, so it's important to have a way to make that guarantee robust in the face of data races. vars don't let you do smart casts in this way (unless it's a local var that's not captured in any non-calls-in-place closures)

[OliverO2]

I agree. The term might be a bit imprecise, but this would fall under the umbrella I was calling "language control" for lack of coming up with a better term.

[kyay10]

Also, a basic val cannot produce data races. In fact, val foo = ... cannot ever produce a data race, while val foo: SomeType (i.e. an uninitialised val) technically can (if you lie in a contract), and even thus have invalid smart casts (but again, it only happens if you lie in a contract)

[rnett]

I'm just concerned about losing consistency in the model with respect to lateinit var. I wonder if we should rethink lateinit var as well?

+1 for eventually moving it to a delegate. I believe I've seen this discussed by the Kotlin team somewhere (maybe even here), but forget where. IMO the less "privileged" language features, the better - this makes the language easier to learn, easier to read, and easier to extend (as the keep mentions).

[InversionSpaces]

Thank you everyone for the discussion!

It informed the design decisions captured in the successor proposal, KEEP-0455.
Comments are welcome in its discussion.