I noticed that the M3 `ColorScheme` is annotated with `@Stable`, however, it does not override `equa...

# compose

[Andrew Hughes]

I noticed that the M3 ColorScheme is annotated with @Stable, however, it does not override equals. The @Stable annotation mentions that the following must be true:

1. The result of equals will always return the same result for the same two instances.

I assume this means that two instances of a class with the same internal values should evaluate to true using equals. However, this is not the case for ColorScheme. Am I misunderstanding what this means?

[MR3Y]

I assume this means that two instances of a class with the same internal values should evaluate to true using equals.

No, this is not what the documentation of @Stable is meaning. what it actually means is that calling equals on the same two instances should always return the same result even if that result was false, that doesn't violate stable contract.
Also, see: https://kotlinlang.slack.com/archives/CJLTWPH7S/p1660409798793859?thread_ts=1660409095.230819&cid=CJLTWPH7S

[MR3Y]

So, here ColorScheme isn't overriding equals , so, it will fallback to the default equals that is always returning false. That being said, ColorScheme complies with @Stable contract

[Andrew Hughes]

Ah, okay that makes sense. Thanks!

[Andrew Hughes]

What about annotating a function with @Stable? The documentation states:

When applied to a function or a property, the Stable annotation indicates that the function will return the same result if the same parameters are passed in. This is only meaningful if the parameters and results are themselves Stable, Immutable, or primitive.

If I have a function that returns an instance of a class that is marked @Stable, does that function need to return the exact same instance if the same parameters are passed in? Or can it return a different instance that is functionally equivalent?

[MR3Y]

As long as those 2 instances don't violate @Stable contract, then the function can be stable.

[Andrew Hughes]

I guess I'm still not following what they mean by "the function will return the same result if the same parameters are passed in".

If I pass in an @Stable instance A as a parameter to a function and it returns an @Stable instance B. Does annotating the function with @Stable require that the instance B be returned every time A is passed in? Or could it return a different instance (C, D, ...) each time it is called with A, as long as the the returned value is "the same" (not necessarily equal or the same instance)?

[Andrew Hughes]

And what if A is mutated (while complying with the @Stable contract)? In my scenario, this could change the output of the function. The question is, how does that affect the stability of the function?

[MR3Y]

If I pass in an @Stable instance A as a parameter to a function and it returns an @Stable instance B. Does annotating the function with @Stable require that the instance B be returned every time A is passed in? Or could it return a different instance (C, D, ...) each time it is called with A, as long as the the returned value is "the same" (not necessarily equal or the same instance)?

it doesn't have to be the same instance, just make sure that calling B.equals(C or D...)
will always return the same result whether it is false or true, this is what @Stable cares about , if B & C or D have the same values but for some reason or another their equals call isn't deterministc, then they shouldn't be marked as @Stable because compose compiler can recompose those incorrectly based on your assumption.

[Andrew Hughes]

Oh, "the same result" is referring to the equals? It sounds like it's referring to the result of the function.

If I'm understanding you correctly, that would mean any function that returns an @Stable value can be marked as @Stable. But I don't think that's the case. Maybe I'm misunderstanding.

[MR3Y]

And what if A is mutated (while complying with the @Stable contract)? In my scenario, this could change the output of the function. The question is, how does that affect the stability of the function?

It is normal, The compose compiler would recompose that to read the updated value

[MR3Y]

the whole idea behind @Stable annotation is to aid the compiler in making smart optimizations for you for things that aren't optimized by default

[MR3Y]

But it does a good job optimizing many things for you under the hood, you should use @Stable if you are SURE that something isn't optimized by default & it should be optimized, otherwise you shouldn't care about anything because compiler is doing some optimizations under the hood, and if you annotated an API with Stable while it shouldn't be, the compiler would actually incorrectly recompose your code when it shouldn't be

[MR3Y]

If I'm understanding you correctly, that would mean any function that returns an @Stable value can be marked as @Stable. But I don't think that's the case. Maybe I'm misunderstanding.

You're right, any function that takes stable & returns stable can be marked as stable

[Andrew Hughes]

👍 Yea, I'm not trying to put @Stable on a bunch of things. I just thought it might make sense for this once scenario, but I'm still not wrapping my head around it for functions.

Here's what I'm doing:
I've created a TonalPalette class that's basically a copy of the implementation of ColorScheme, but with all the base tonal values for each tonal range. This is annotated with @Stable, just like ColorScheme. Then I have a fun TonalPalette.lightColorScheme(): ColorScheme that creates a ColorScheme from the appropriate values from the TonalPalette (as well as a corresponding TonalPalette.darkColorScheme() function). Initially, it made sense to me that these functions could be annotated with @Stable as well, but now I'm not so sure. Does that make sense?

The functions are used in our AppTheme composable, which wraps MaterialTheme, and determine the appropriate ColorScheme based on the current TonalPalette and darkTheme parameter. I assume it'd be helpful if the functions generating the ColorScheme only were called and/or created new ColorScheme whenever TonalPalette or darkTheme changes. Does that sound like an appropriate use of @Stable on these functions? Or should I just not worry about it?

[Andrew Hughes]

You're right, any function that takes stable & returns stable can be marked as stable

Okay, then if a function takes a stable and returns a stable, does the compiler already implicitly mark it as stable? Or is it still necessary to manually annotate it?

[MR3Y]

I've created a TonalPalette class that's basically a copy of the implementation of ColorScheme, but with all the base tonal values for each tonal range. This is annotated with @Stable, just like ColorScheme. Then I have a fun TonalPalette.lightColorScheme(): ColorScheme that creates a ColorScheme from the appropriate values from the TonalPalette (as well as a corresponding TonalPalette.darkColorScheme() function). Initially, it made sense to me that these functions could be annotated with @Stable as well, but now I'm not so sure. Does that make sense?

Yes, it perfectly makes sense

[MR3Y]

Okay, then if a function takes a stable and returns a stable, does the compiler already implicitly mark it as stable? Or is it still necessary to manually annotate it?

honestly, I'm not sure if the compiler would implicitly mark it or not, I would need to check the underlying code for that. But, I think the most common approach is to annotate that manually since there are many functions in compose UI, material, and foundation are already doing that

[MR3Y]

here are some examples of functions that are doing that: RowScope.weight ColumnScope.weight BoxScope.align

[MR3Y]

you can also refer to the declaration & the implementation of those functions if you still have some doubts about when to mark a function as a @Stable

[Grégory Lureau]

You're right, any function that takes stable & returns stable can be marked as stable

What if there is side effects (or even local random)?
I think about a function using the system time or a static variable/function where the result can change depending of the timing of the call, and it impacts the output (let's say a stable data class that contain the result). If I get the goal of @Stable right, it should not be marked as stable because we want the compiler to call it again even if the parameters haven't changed. Am I right?

[MR3Y]

generally, changing/reading global or static variables & changing the result based on that would be a bad practice because:
• testing this function would be difficult
• the behavior of the function wouldn't be easily known/deterministic for the caller of the function which might lead to obscure bugs
That being said, the correct thing to do here IMO is to take that variable as a function parameter, and that would bring us back to ensuring that function parameters are stable to mark it as a @Stable.
On a side note, I wanted to ask you one question, do you have a usecase for when a function that should be stable depends on some global variables? because I can't think of a usecase for it or haven't seen one like that yet. Or is it just a contrived example to better understand @Stable?

[Grégory Lureau]

Contrived example tbh, and not pushing for this usage neither, but I can think of using Android applicationContext to get a resource for example. Given the access to context could be made static (applicationContext), or maybe coming directly from Compose via stuff like LocalContext.current because it's a @Composable method.

[MR3Y]

probably you're taking about stateful modifiers here that are created with composed and allows you to access composable functions/getters inside factory lambda body. For example: Modifier.clickable is a stateful modifier. if you're talking about those, as far as I've seen, no, those aren't marked as @Stable

[MR3Y]

most or all stateful modifiers from the official compose libraries aren't marked @Stable