update: new FAQ answer (#4789)

Author: danil-pavlov

docs/topics/native/native-faq.md

@@ -109,28 +109,22 @@ The Kotlin/Native compiler does not support bitcode embedding since Kotlin 2.0.2
 If you're using earlier versions of Xcode but want to upgrade to Kotlin 2.0.20 or later versions, disable bitcode
 embedding in your Xcode projects.
 
-## Why do I see InvalidMutabilityException?
+## How do I reference objects safely from different coroutines?
 
-> This issue is relevant for the legacy memory manager only. Check out [Kotlin/Native memory management](native-memory-manager.md)
-> to learn about the new memory manager, which has been enabled by default since Kotlin 1.7.20.
->
-{style="note"}
+To safely access or update an object across multiple coroutines in Kotlin/Native, consider using concurrency-safe
+constructs, such as `@Volatile` and `AtomicReference`.
 
-It likely happens, because you are trying to mutate a frozen object. An object can transfer to the
-frozen state either explicitly, as objects reachable from objects on which the `kotlin.native.concurrent.freeze` is called,
-or implicitly (i.e. reachable from `enum` or global singleton object - see the next question).
+Use [`@Volatile`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.concurrent/-volatile/) to annotate a `var` property.
+This makes all reads and writes to the property's backing field atomic. In addition, writes become immediately visible
+to other threads. When another thread accesses this property, it observes not only the updated value but also the changes
+that happened before the update.
 
-## How do I make a singleton object mutable?
+Alternatively, use [AtomicReference](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.concurrent.atomics/-atomic-reference/),
+which supports atomic reads and updates. On Kotlin/Native, it wraps a volatile variable and performs atomic operations.
+Kotlin also provides a set of types for atomic operations tailored to specific data types. You can use `AtomicInt`,
+`AtomicLong`, `AtomicBoolean`, `AtomicArray`, as well as `AtomicIntArray` and `AtomicLongArray`.
 
-> This issue is relevant for the legacy memory manager only. Check out [Kotlin/Native memory management](native-memory-manager.md)
-> to learn about the new memory manager, which has been enabled by default since Kotlin 1.7.20.
->
-{style="note"}
-
-Currently, singleton objects are immutable (i.e. frozen after creation), and it's generally considered
-good practise to have the global state immutable. If for some reason you need a mutable state inside such an
-object, use the `@konan.ThreadLocal` annotation on the object. Also, the `kotlin.native.concurrent.AtomicReference` class could be
-used to store different pointers to frozen objects in a frozen object and automatically update them.
+For more information about access to shared mutable state, see the [Coroutines documentation](shared-mutable-state-and-concurrency.md).
 
 ## How can I compile my project with unreleased versions of Kotlin/Native?
 

docs/topics/native/native-migration-guide.md

@@ -67,7 +67,7 @@ To support the new memory manager, remove usages of the affected API:
 |-------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [`@SharedImmutable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native.concurrent/-shared-immutable/)                                  | You can remove all usages, though there are no warnings for using this API in the new memory manager.                                                             |
 | [The `FreezableAtomicReference` class](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native.concurrent/-freezable-atomic-reference/)      | Use [`AtomicReference`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native.concurrent/-atomic-reference/) instead.                                        |
-| [The `FreezingException` class](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native.concurrent/-freezing-exception/)                     | Remove all usages.                                                                                                                                                |                                                                                                      |
+| [The `FreezingException` class](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native.concurrent/-freezing-exception/)                     | Remove all usages.                                                                                                                                                |
 | [The `InvalidMutabilityException` class](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native.concurrent/-invalid-mutability-exception/)  | Remove all usages.                                                                                                                                                |
 | [The `IncorrectDereferenceException` class](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native/-incorrect-dereference-exception/)       | Remove all usages.                                                                                                                                                |
 | [The `freeze()` function](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.native.concurrent/freeze.html)                                    | Remove all usages.                                                                                                                                                |
@@ -81,4 +81,5 @@ To support the new memory manager, remove usages of the affected API:
 ## What's next
 
 * [Learn more about the new memory manager](native-memory-manager.md)
-* [Check the specifics of integration with Swift/Objective-C ARC](native-arc-integration.md)
+* [Check the specifics of integration with Swift/Objective-C ARC](native-arc-integration.md)
+* [Learn how to reference objects safely from different coroutines](native-faq.md#how-do-i-reference-objects-safely-from-different-coroutines)