More details on Lazy Vals

Author: allanrenucci

docs/docs/reference/changed/lazy-vals-spec.md

@@ -0,0 +1,76 @@
+---
+layout: doc-page
+title: Changed: Lazy Vals - More Details
+---
+
+Dotty implements [Version 6](https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html#version-6---no-synchronization-on-this-and-concurrent-initialization-of-fields)
+of the [SIP-20] improved lazy vals initialization proposal.
+
+## Motivation
+
+The newly proposed lazy val initialization mechanism aims to eliminate the acquisition of resources
+during the execution of the lazy val initializer block, thus reducing the possibility of a deadlock.
+The concrete deadlock scenarios that the new lazy val initialization scheme eliminates are
+summarized in the [SIP-20] document.
+
+## Implementation
+
+Given a lazy field of the form:
+
+```scala
+class Foo {
+  @volatile lazy val bar = <RHS>
+}
+```
+
+The Dotty compiler will generate code equivalent to:
+
+```scala
+class Foo {
+  import dotty.runtime.LazyVals
+  var value_0: Int = _
+  var bitmap = 0
+  val bitmap_offset = LazyVals.getOffset(classOf[LazyCell], "bitmap")
+
+  def bar(): Int = {
+    var result: Int = 0
+    var retry: Boolean = true
+    var flag: Long = 0L
+    while (retry) {
+      flag = LazyVals.get(this, bitmap_offset)
+      LazyVals.STATE(flag, <field-id>) match {
+        case <state-0> =>
+          if (LazyVals.CAS(this, bitmap_offset, flag, <state-1>)) {
+            try result = <RHS>
+            catch {
+              case ex =>
+                LazyVals.setFlag(this, bitmap_offset, <state-0>, <field-id>)
+                throw ex
+            }
+            value_0 = result
+            LazyVals.setFlag(this, bitmap_offset, <state-3>, <field-id>)
+            retry = false
+          }
+        case <state-1> | <state-2> =>
+          LazyVals.wait4Notification(this, bitmap_offset, flag, <field-id>)
+        case <state-3> =>
+          retry = false
+          result = $target
+        }
+      }
+    result
+  }
+}
+```
+
+The state of the lazy val `<state-i>` is represented with 4 values: 0, 1, 2 and 3. The state 0
+represents a non-initialized lazy val. The state 1 represents a lazy val that is currently being
+initialized by some thread. The state 2 denotes that there are concurrent readers of the lazy val.
+The state 3 represents a lazy val that has been initialized. `<field-id>` is the id of the lazy
+val. This id grows with the number of volatile lazy vals defined in the class.
+
+## Reference
+
+* [SIP-20]
+
+[SIP-20]: https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html

docs/docs/reference/changed/lazy-vals.md

@@ -1,19 +1,27 @@
 ---
 layout: doc-page
-title: Changed: Lazy Vals and @volatile
+title: Changed: Lazy Vals
 ---
 
-Lazy val initialization no longer guarantees safe publishing. This change was done
-to avoid the performance overhead of thread synchonization because many lazy vals are only used in a single-threaded context.
+Lazy field initialization no longer guarantees safe publishing. This change was done
+to avoid the performance overhead of thread synchonization because most lazy vals are only used in
+a single-threaded context.
 
-To get back safe publishing you need to annotate a lazy val with `@volatile`. In
+## Compatibility considerations
 
-    @volatile lazy val x = expr
+To get back safe publishing (Scala 2's default) you need to annotate a lazy val with `@volatile`. In
 
-it is guaranteed that readers of a lazy val will see the value of `x`
-once it is assigned.
+```scala
+@volatile lazy val x = expr
+```
+
+it is guaranteed that readers of a lazy val will see the value of `x` once it is assigned.
+
+Local lazy vals (i.e. defined inside methods) are left unchanged.
 
 The [ScalaFix](https://scalacenter.github.io/scalafix/) rewrite tool
 as well as Dotty's own `-language:Scala2 -rewrite` option will rewrite all normal
 lazy vals to volatile ones in order to keep their semantics compatible
 with current Scala's.
+
+[More details](./lazy-vals-spec.html)