I noticed that the M3 `ColorScheme` is annotated with ` Stab

Question

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 gt 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 · Answer

gt 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 amp cid=CJLTWPH7S>

MR3Y · Answer

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 · Answer

Ah okay that makes sense Thanks

Andrew Hughes · Answer

What about annotating a function with ` Stable` The documentation states gt 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 · Answer

As long as those 2 instances don t violate ` Stable` contract then the function can be stable

Andrew Hughes · Answer

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 · Answer

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 · Answer

gt 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 gt 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` amp `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 · Answer

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 · Answer

gt 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 gt It is normal The compose compiler would recompose that to read the updated value

MR3Y · Answer

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 · Answer

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 amp 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 · Answer

gt 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 gt You re right any function that takes stable amp returns stable can be marked as stable

Andrew Hughes · Answer

thumbsup 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 · Answer

gt You re right any function that takes stable amp 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 · Answer

gt 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 · Answer

gt 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 · Answer

here are some examples of functions that are doing that

MR3Y · Answer

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

Grégory Lureau · Answer

gt You re right any function that takes stable amp 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 · Answer

generally changing reading global or static variables amp 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 · Answer

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 · Answer

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 <https cs android com androidx platform frameworks support + androidx main compose foundation foundation src commonMain kotlin androidx compose foundation Clickable kt l=80 q=clickable amp ss=androidx 2Fplatform 2Fframeworks 2Fsupport compose 2F|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 · Answer

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