Introduce experimental kotlin.concurrent.Volatile annotation KT-55268, KT-55609

Use this annotation in tests to ensure it works the same at least on JVM

libraries/stdlib/common/src/kotlin/JvmAnnotationsH.kt

@@ -122,8 +122,16 @@ public expect annotation class JvmInline()
 public expect annotation class JvmRecord()
 
 /**
- * Marks the JVM backing field of the annotated property as `volatile`, meaning that writes to this field
- * are immediately made visible to other threads.
+ * Marks the JVM backing field of the annotated `var` property as `volatile`, meaning that reads and writes to this field
+ * are atomic and writes are always made visible to other threads. If another thread reads the value of this field (e.g. through its accessor),
+ * it sees not only that value, but all side effects that led to writing that value.
+ *
+ * This annotation has effect only in Kotlin/JVM. It's recommended to use [kotlin.concurrent.Volatile] annotation instead
+ * in multiplatform projects.
+ *
+ * Note that only _backing field_ operations are atomic when the field is annotated with `Volatile`.
+ * For example, if the property getter or setter make several operations with the backing field,
+ * a _property_ operation, i.e. reading or setting it through these accessors, is not guaranteed to be atomic.
  */
 @Target(FIELD)
 @MustBeDocumented

libraries/stdlib/jvm/runtime/kotlin/jvm/annotations/JvmFlagAnnotations.kt

@@ -8,8 +8,13 @@ package kotlin.jvm
 import kotlin.annotation.AnnotationTarget.*
 
 /**
- * Marks the JVM backing field of the annotated property as `volatile`, meaning that writes to this field
- * are immediately made visible to other threads.
+ * Marks the JVM backing field of the annotated `var` property as `volatile`, meaning that reads and writes to this field
+ * are atomic and writes are always made visible to other threads. If another thread reads the value of this field (e.g. through its accessor),
+ * it sees not only that value, but all side effects that led to writing that value.
+ *
+ * Note that only _backing field_ operations are atomic when the field is annotated with `Volatile`.
+ * For example, if the property getter or setter make several operations with the backing field,
+ * a _property_ operation, i.e. reading or setting it through these accessors, is not guaranteed to be atomic.
  */
 @Target(FIELD)
 @Retention(AnnotationRetention.SOURCE)

libraries/stdlib/jvm/src/kotlin/concurrent/Volatile.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.concurrent
+
+/**
+ * Marks the JVM backing field of the annotated `var` property as `volatile`, meaning that reads and writes to this field
+ * are atomic and writes are always made visible to other threads. If another thread reads the value of this field (e.g. through its accessor),
+ * it sees not only that value, but all side effects that led to writing that value.
+ *
+ * Note that only _backing field_ operations are atomic when the field is annotated with `Volatile`.
+ * For example, if the property getter or setter make several operations with the backing field,
+ * a _property_ operation, i.e. reading or setting it through these accessors, is not guaranteed to be atomic.
+ */
+@SinceKotlin("1.8")
+@ExperimentalStdlibApi
+public actual typealias Volatile = kotlin.jvm.Volatile

libraries/stdlib/src/kotlin/concurrent/Volatile.kt

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.concurrent
+
+import kotlin.internal.RequireKotlin
+import kotlin.internal.RequireKotlinVersionKind
+
+
+/**
+ * Marks the backing field of the annotated `var` property as `volatile`, meaning that reads and writes to this field
+ * are atomic and writes are always made visible to other threads. If another thread reads the value of this field (e.g. through its accessor),
+ * it sees not only that value, but all side effects that led to writing that value.
+ *
+ * This annotation has effect in Kotlin/JVM and Kotlin/Native.
+ *
+ * Note that only _backing field_ operations are atomic when the field is annotated with `Volatile`.
+ * For example, if the property getter or setter make several operations with the backing field,
+ * a _property_ operation, i.e. reading or setting it through these accessors, is not guaranteed to be atomic.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.SOURCE)
+@MustBeDocumented
+@OptionalExpectation
+@SinceKotlin("1.8")
+@RequireKotlin(version = "1.8.20", versionKind = RequireKotlinVersionKind.COMPILER_VERSION)
+@ExperimentalStdlibApi
+public expect annotation class Volatile()