遷移至新的記憶體管理器

NOTE

自 Kotlin 1.9.20 起，已完全移除對舊版記憶體管理器 (legacy memory manager) 的支援。請將您的專案遷移至目前的記憶體模型，該模型自 Kotlin 1.7.20 起已預設啟用。

本指南比較了新的 Kotlin/Native 記憶體管理器與舊版記憶體管理器，並說明如何遷移您的專案。

新的記憶體管理器最顯著的變化是解除了物件共享的限制。您不再需要凍結 (freeze) 物件即可在執行緒 (thread) 之間共享它們，具體來說：

頂層屬性 (top-level properties) 可以由任何執行緒存取和修改，而無需使用 @SharedImmutable。
透過互通 (interop) 傳遞的物件可以由任何執行緒存取和修改，而無需凍結它們。
Worker.executeAfter 不再要求操作 (operations) 必須被凍結。
Worker.execute 不再要求生產者 (producers) 返回一個隔離的物件子圖 (isolated object subgraph)。
包含 AtomicReference 和 FreezableAtomicReference 的參考循環 (reference cycles) 不會導致記憶體洩漏 (memory leaks)。

除了輕鬆共享物件之外，新的記憶體管理器還帶來了其他重大變化：

全域屬性 (global properties) 在首次存取定義它們的檔案時才進行延遲初始化 (lazily initialized)。以前，全域屬性是在程式啟動時初始化的。作為替代方案，您可以將必須在程式啟動時初始化的屬性標記為 @EagerInitialization 註解。在使用前，請查閱其文件。
by lazy {} 屬性支援執行緒安全模式，但不處理無界遞歸 (unbounded recursion)。
從 Worker.executeAfter 中的 operation 逃逸的例外 (exceptions) 會像其他執行時 (runtime) 部分一樣處理，即嘗試執行使用者定義的未處理例外掛鉤 (unhandled exception hook)，如果找不到掛鉤或掛鉤本身執行失敗，則終止程式。
凍結 (Freezing) 功能已棄用且始終禁用。

請遵循以下指南將您的專案從舊版記憶體管理器遷移：

更新 Kotlin

新的 Kotlin/Native 記憶體管理器自 Kotlin 1.7.20 起已預設啟用。請檢查 Kotlin 版本並在必要時更新至最新版本。

為了支援新的記憶體管理器，請移除受影響 API 的使用方式：

舊版 API	應對方式
`@SharedImmutable`	您可以移除所有用法，儘管在新記憶體管理器中使用此 API 不會產生警告。
The `FreezableAtomicReference` class	改用 `AtomicReference`。
The `FreezingException` class	移除所有用法。
The `InvalidMutabilityException` class	移除所有用法。
The `IncorrectDereferenceException` class	移除所有用法。
The `freeze()` function	移除所有用法。
The `isFrozen` property	您可以移除所有用法。由於凍結 (freezing) 功能已棄用，該屬性始終返回 `false`。
The `ensureNeverFrozen()` function	移除所有用法。
The `atomicLazy()` function	改用 `lazy()`。
The `MutableData` class	改用任何常規集合 (regular collection)。
The `WorkerBoundReference<out T : Any>` class	直接使用 `T`。
The `DetachedObjectGraph<T>` class	直接使用 `T`。若要透過 C 語言互通 (interop) 傳遞值，請使用 StableRef 類別。