Update synchronization

Author: pitr-ch

doc/synchronization.md

@@ -115,13 +115,17 @@ class Event < Synchronization::Object
 end  
 ```
 
-## Memory model (incomplete)
+Operations on `@Touched` field have volatile semantic. 
+
+## Memory model
 
 *Intended for further revision, and extension.*
 
-`Synchronization::Object` provides an unified behavior for different Ruby implementations on top of this memory model. This part provides a summary of how Ruby (any implementation) behaves in parallel environment. It is built using the weakest behavior provided by any of the implementations for a particular language element. (E.g. local variable updates are always visible in CRuby but not in JRuby, so in this case JRuby behavior is picked.). If some Ruby behavior is omitted here it is considered unsafe foe use in parallel environment (Reasons may be lack of information, or difficulty of verification). 
+When writing libraries in `concurrent-ruby` we are reasoning based on following memory model which is further extended by features provided in `Synchronization::Object` (described above).
+
+The memory model is constructed based on our best effort and knowledge of the 3 main Ruby implementations (CRuby, JRuby, Rubinius). When considering certain aspect we always choose the weakest guarantee (e.g. local variable updates are always visible in CRuby but not in JRuby, so in this case JRuby behavior is picked). If some Ruby behavior is omitted here it is considered unsafe for use in parallel environment (Reasons may be lack of information, or difficulty of verification).
 
-This part takes in account following implementations: 
+This takes in account following implementations: 
 
 -   CRuby 1.9 - 2.2 (no differences found)
 -   JRuby 1.7
@@ -135,13 +139,18 @@ We are interested in following behaviors:
 
 ### Variables
 
--   **Local variables** - atomic, non-volatile. 
-    Consequence: a lambda defined on `thread1` executing on `thread2` may not see updated values in local variables captured in its closure. 
--   **Instance variables** - atomic, non-volatile. 
-    Consequence: Different thread may see old values; different thread may see not fully-initialized object.
--   **Constants** - atomic, volatile.
--   **Global variables** - omitted (atomic and volatile on JRuby and CRuby)
--   **Class variables** - omitted (atomic and volatile on JRuby and CRuby)
+-   **Local variables** - atomic assignment, non-volatile. 
+    -   Consequence: a lambda defined on `thread1` executing on `thread2` may not see updated values in local variables captured in its closure.
+    -   Reason: local variables are non-volatile on Jruby and Rubinius.
+-   **Instance variables** - atomic assignment, non-volatile. 
+    -   Consequence: Different thread may see old values; different thread may see not fully-initialized object.
+    -   Reason: local variables are non-volatile on Jruby and Rubinius.
+-   **Constants** - atomic assignment, volatile.
+
+Other:
+
+-   **Global variables** - we don't use them, omitted (atomic and volatile on JRuby and CRuby, Rubinius unknown)
+-   **Class variables** - we don't use them, omitted (atomic and volatile on JRuby and CRuby, Rubinius unknown)
 
 ### Assumptions
 
@@ -151,11 +160,11 @@ Following operations are **assumed** thread-safe, volatile and atomic on all imp
 -   Method definition
 -   Library requirement
 
-It's best practice thought to eager load before going into parallel part of an application.
+It's best practice though to eager load before going into parallel part of an application.
 
 ### Issues to be aware of
 
--   **Initialization** - Since instance variables are not volatile and a particular implementation may preinitialize values with nils, based on shapes it already saw, a second thread obtaining reference to newly constructed may still se old preinitialized values instead of values set in `initialize` method. To fix this `ensure_ivar_visibility!` can be used or the object can be safely published in a volatile field.
+-   **Initialization** - Since instance variables are not volatile and a particular implementation may preinitialize values with nils, based on shapes it already saw, a second thread obtaining reference to newly constructed may still see old preinitialized values instead of values set in `initialize` method. To fix this `ensure_ivar_visibility!` can be used or the object can be safely published in a volatile field.
 -   **`||=`, `+=` and similar** - are not atomic.
 
 ### Notes/Sources on implementations