Add documentation

* to volatile read/write methods
* Float assignment may not be atomic

Author: pitr-ch

doc/synchronization.md

@@ -139,13 +139,14 @@ We are interested in following behaviors:
 
 ### Variables
 
--   **Local variables** - atomic assignment, non-volatile. 
+-   **Local variables** - atomic assignment (only Integer and Object), 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. 
+-   **Instance variables** - atomic assignment (only Integer and Object), 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.
+-   **Assignments of Float** may not be atomic (some implementations (e.g. Truffle) may use native double).
 
 Other:
 

ext/com/concurrent_ruby/ext/SynchronizationLibrary.java

@@ -121,10 +121,12 @@ public IRubyObject ensureIvarVisibilityBang(ThreadContext context) {
         @JRubyMethod(name = "instance_variable_get_volatile", visibility = Visibility.PROTECTED)
         public IRubyObject instanceVariableGetVolatile(ThreadContext context, IRubyObject name) {
             if (UnsafeHolder.U == null) {
+                // TODO: Possibly dangerous, there may be a deadlock on the this
                 synchronized (this) {
                     return instance_variable_get(context, name);
                 }
             } else if (UnsafeHolder.SUPPORTS_FENCES) {
+                // ensure we see latest value
                 UnsafeHolder.loadFence();
                 return instance_variable_get(context, name);
             } else {
@@ -136,11 +138,13 @@ public IRubyObject instanceVariableGetVolatile(ThreadContext context, IRubyObjec
         @JRubyMethod(name = "instance_variable_set_volatile", visibility = Visibility.PROTECTED)
         public IRubyObject InstanceVariableSetVolatile(ThreadContext context, IRubyObject name, IRubyObject value) {
             if (UnsafeHolder.U == null) {
+                // TODO: Possibly dangerous, there may be a deadlock on the this
                 synchronized (this) {
                     return instance_variable_set(name, value);
                 }
             } else if (UnsafeHolder.SUPPORTS_FENCES) {
-                IRubyObject result = instance_variable_set(name, value);
+                final IRubyObject result = instance_variable_set(name, value);
+                // ensure we make latest value visible
                 UnsafeHolder.storeFence();
                 return result;
             } else {