From ade7a4ec814c69c052ab7eaebaf7c9d26e5ae143 Mon Sep 17 00:00:00 2001
From: Nikolay Igotti <olonho@users.noreply.github.com>
Date: Thu, 5 Jul 2018 16:18:12 +0300
Subject: [PATCH] v0.8 preparations. (#1762)

---
 CHANGELOG.md                                   | 12 ++++++++++++
 FAQ.md                                         | 18 ++++++++++++++++++
 RELEASE_NOTES.md                               |  9 +++++----
 .../src/main/kotlin/konan/worker/Atomics.kt    |  5 +++++
 4 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e609af66fcf..b8aa1bc6d61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,15 @@
+## v0.8 (Jul 2018)
+  * Singleton objects are frozen after creation, and shared between threads
+  * String and primitives types are frozen by default
+  * Common stdlib with Kotlin/JVM and Kotlin/JS
+  * Implemented `kotlin.random.*` and `Collection.shuffle`
+  * Implemented atomic integers and atomic references
+  * Multiple bugfixes in compiler (coroutines, inliner)
+  * Support 32-bit iOS (target `ios_arm32`)
+  * New experimental Gradle plugin
+  * Support XCode 9.4.1
+  * Optimizations (switch by enum, memory management)
+
 ## v0.7.1 (Jun 2018)
   * Bugfixes in the runtime (indexOf, GC for kotlin.Array, enum equality) and the compiler
   * Fix NSBlock problem, preventing upload of binaries to the AppStore
diff --git a/FAQ.md b/FAQ.md
index 3ba1ed46d9b..808d3e62782 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -20,18 +20,21 @@ C language header, allowing to use all public APIs available in your Kotlin/Nati
 See `samples/python_extension` as an example of using such shared object to provide a bridge between Python and
 Kotlin/Native.
 
+
 Q: How do I create static library or an object file?
 
 A: Use `-produce static` compiler switch, or `konanArtifacts { static('foo') {} }` in Gradle.
 It will produce platform-specific static object (.a library format) and C language header, allowing to
 use all public APIs available in your Kotlin/Native program from C/C++ code.
 
+
 Q: How do I run Kotlin/Native behind corporate proxy?
 
 A: As Kotlin/Native need to download platform specific toolchain, you need to specify
 `-Dhttp.proxyHost=xxx -Dhttp.proxyPort=xxx` as compiler's or `gradlew` arguments,
 or set it via `JAVA_OPTS` environment variable.
 
+
 Q: How do I specify custom Objective-C prefix/name for my Kotlin framework?
 
 A: Use `-module_name` compiler option or matching Gradle DSL statement, i.e.
@@ -40,3 +43,18 @@ framework("MyCustomFramework") {
     extraOpts '-module_name', 'TheName'
 }
 ```
+
+
+Q: Why do I see `InvalidMutabilityException`?
+
+A: It likely happens, because you are trying to mutate a frozen object. Object could transfer to the
+frozen state either explicitly, as objects reachable from objects on which `konan.worker.freeze` is called,
+or implicitly (i.e. reachable from `enum` or global singleton object - see next question).
+
+
+Q: How do I make a singleton object mutable?
+
+A: Currently, singleton objects are immutable (i.e. frozen after creation), and it's generally considered
+a good practise to have global state immutable. If for some reasons you need mutable state inside such an
+object, use `@konan.ThreadLocal` annotation on the object. Also `konan.worker.AtomicReference` class could be
+used to store different pointers to frozen objects in a frozen object and atomically update those.
\ No newline at end of file
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 5c7e97f9880..db8d8fd847e 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -25,11 +25,12 @@ the following platforms:
    (`-target linux`, default on Linux hosts)
  * Microsoft Windows x86-64 (tested on Windows 7 and Windows 10), host and target (`-target mingw`,
    default on Windows hosts)
- * Apple iOS (armv7 and arm64 devices, x86 simulator), cross-compiled target (`-target ios_arm64`), hosted on macOS
+ * Apple iOS (armv7 and arm64 devices, x86 simulator), cross-compiled target
+   (`-target ios_arm32|ios_arm64|ios_x64`), hosted on macOS
  * Linux arm32 hardfp, Raspberry Pi, cross-compiled target (`-target raspberrypi`), hosted on Linux
- * Linux mips big endian, cross-compiled target (`-target mips`), hosted on Linux
- * Linux mips little endian, cross-compiled target (`-target mipsel`), hosted on Linux
- * Android arm32 and arm64 (`-target android_arm32` and `-target android_arm64`) target, hosted on Linux or macOS
+ * Linux MIPS big endian, cross-compiled target (`-target mips`), hosted on Linux
+ * Linux MIPS little endian, cross-compiled target (`-target mipsel`), hosted on Linux
+ * Android arm32 and arm64 (`-target android_arm32|android_arm64`) target, hosted on Linux or macOS
  * WebAssembly (`-target wasm32`) target, hosted on Linux, Windows or macOS
 
  Adding support for other target platforms shouldn't be too hard, if LLVM support is available.
diff --git a/runtime/src/main/kotlin/konan/worker/Atomics.kt b/runtime/src/main/kotlin/konan/worker/Atomics.kt
index 9584a6ddb37..313a1ce4ff7 100644
--- a/runtime/src/main/kotlin/konan/worker/Atomics.kt
+++ b/runtime/src/main/kotlin/konan/worker/Atomics.kt
@@ -117,6 +117,11 @@ class AtomicNativePtr(private var value: NativePtr) {
 @SymbolName("Kotlin_AtomicReference_checkIfFrozen")
 external private fun checkIfFrozen(ref: Any?)
 
+/**
+ * An atomic reference to a frozen Kotlin object. Can be used in concurrent scenarious
+ * and must be zeroed out (with `compareAndSwap(get(), null)`) once no longer needed.
+ * Otherwise memory leak could happen.
+ */
 @Frozen
 class AtomicReference<T>(private var value: T? = null) {
     // A spinlock to fix potential ARC race. Not an AtomicInt just for the effeciency sake.