Expose atomic updates on MutableStateFlow

[lowasser]

MutableStateFlow exposes compareAndSet, making it possible to do atomic updates on its value, but does not provide helpers to do so correctly. The StateFlow documentation even shows an example method

fun inc() {
  _counter.value++
}

which is not safe to be used concurrently.

Correct atomic update methods like those in atomicfu are not hard to build yourself if you know what you're doing, but providing them directly -- and showing their correct use in the documentation examples -- seems like a good idea.

(So, for example, I'd expect to see MutableStateFlow<T>.updateAndGet(updater: (T) -> T): T. Number-specific helpers like addAndGet or incrementAndGet would be nice to have, but the basics would suffice.)

[lowasser]

Looks closed to me!

[joffrey-bion]

Sorry to be late to the party, but I find it strange that this finally made it to the library given the explanations I got when I first asked for it in #2392.

I believe the drawbacks of the looping implementation should be noted in the doc of the new helpers, because for complex objects where equals is not trivial, it might not be desirable to perform repeated calls to compareAndSet (as pointed out in the initial discussion).

[elizarov]

Exposing the locking variant (without CAS) is extremely fragile. The resulting design would suffer from a host of hard-to-understand issues similar to issues Java's ConcurrentMap.computeIfAbsent suffers from. CAS-based approach seems to be a reasonably good compromise as it performs well as long as you don't have too many concurrent mutation attempts. If your particular application needs lock-based updates, then you can always build it on top of the StateFlow's API yourself using a separate Mutex. The converse is not true. If we don't provide you with CAS-based updates, then you cannot build your own.

[joffrey-bion]

Thanks a lot for the fast response. I agree with the problems you mentioned about the lock-based version, so yeah I should actually not be surprised that the CAS version was introduced (I'm actually happy about it).

I just believe it might be worth adding to the doc that this could repeatedly call compareAndSet (in addition to repeatedly call the transform function), because both of those could be expensive depending on the state's type.