Merge pull request #421 from ruby-concurrency/synchronization

Documentation and few updates and class conversions

Author: Petr Chalupa

doc/synchronization-notes.md

@@ -0,0 +1,64 @@
+# Concurrent Ruby Notes
+
+## Locks
+
+Concurrent Ruby also has an internal extension of `Object` called
+`LockableObject`, which provides same synchronization primitives as Java's
+Object: `synchronize(&block)`, `wait(timeout = nil)`,
+`wait_until(timeout = nil, &condition)`, `signal`, `broadcast`. This class is
+intended for internal use in `concurrent-ruby` only and it does not support
+subclassing (since it cannot protect its lock from its children, for more
+details see [this article](http://wiki.apidesign.org/wiki/Java_Monitor)). It has
+minimal interface to be able to use directly locking available on given
+platforms.
+
+For non-internal use there is `Lock` and `Condition` implementation in
+`Synchronization` namespace, a condition can be obtained with `new_condition`
+method on `Lock`. So far their implementation is naive and requires more work.
+API is not expected to change.
+
+## Method names conventions
+
+Methods starting with `ns_` are marking methods that are not using
+synchronization by themselves, they have to be used inside synchronize block.
+They are usually used in pairs to separate the synchronization from behavior and
+to allow to call methods in the same object without double locking.
+
+``` ruby
+class Node
+  # ...
+  def left
+    synchronize { ns_left }
+  end  
+
+  def right
+    synchronize { ns_right }
+  end  
+
+  def to_a
+    # avoids double locking
+    synchronize { [ns_left, ns_right] }
+  end    
+
+  private
+
+  def ns_left
+    @left
+  end
+
+  def ns_right
+    @right
+  end
+  # ...
+end
+```
+## Piggybacking
+
+Any write executed before volatile write based on program-order is visible to
+the volatile read as well, which allows
+[piggybacking](http://stackoverflow.com/questions/8769570/volatile-piggyback-is-this-enough-for-visiblity).
+Because it creates synchronizes-with (JMM term) order between volatile write
+and read, which participates in creating happens-before order.
+
+This trick is used in some of the abstractions, to avoid unnecessary
+synchronization or volatile declarations.

doc/synchronization.md

@@ -1,176 +1,5 @@
-`Synchronization` module provides common layer for synchronization. It provides same guaranties independent of any particular Ruby implementation.
+# Synchronization
 
-*This is a new module, it is expected to fully stabilize for 1.0 release.*
-
-## Synchronization::Object
-
-Provides common parent for all objects which need to be synchronized or be using other synchronization tools. It provides:
-
--   Synchronized block
--   Methods for waiting and signaling
--   Volatile fields
--   Ensure visibility of final fields
--   Fields with CAS operations
-
-## Synchronized block
-
-`Synchronization::Object` provides private method `#synchronize(&block)`. For a given object only one Thread can enter one of the blocks synchronized against this object. Object is locked when a thread enters one of the synchronized blocks.
-
-Example of a simple counter which can be used by multiple threads:
-
-```ruby
-class SafeCounter < Concurrent::Synchronization::Object
-  def initialize
-    super
-    synchronize { @count = 0 }
-  end
-
-  def increment
-    synchronize { @count += 1 }
-  end
-
-  def count
-    synchronize { @count }
-  end
-end
-```
-
-### Naming conventions
-
-Methods starting with `ns_` are marking methods that are not using synchronization by themselves, they have to be used inside synchronize block. They are usually used in pairs to separate the synchronization from behavior:
-
-```ruby
-def compute
-  service.report synchronize { ns_compute }
-end
-
-private
-
-def ns_compute
-  ns_compute_reduce ns_compute_map
-end
-```
-where `compute` defines how is it synchronized and `ns_compute` handles the behavior (in this case the computation). `ns_` methods should only call other `ns_` methods or `pr_` methods. They can call normal methods on other objects, but that should be done with care (better to avoid) because the thread escapes this object while the lock is still held, which can lead to deadlock. That's why the `report` method is called in `compute` and not in `ns_compute`.
-
-`pr_` methods are pure functions they can be used in and outside of synchronized blocks.
-
-## Methods for waiting and signaling
-
-Sometimes while already inside the synchronized block some condition is not met. Then the thread needs to wait (releasing the lock) until the condition is met. The waiting thread is then signaled that it can continue.
-
-To fulfill these needs there are private methods:
-
--   `ns_wait` {include:Concurrent::Synchronization::AbstractLockableObject#ns_wait}
--   `ns_wait_until` {include:Concurrent::Synchronization::AbstractLockableObject#ns_wait_until}
--   `ns_signal` {include:Concurrent::Synchronization::AbstractLockableObject#ns_signal}
--   `ns_broadcast` {include:Concurrent::Synchronization::AbstractLockableObject#ns_broadcast}
-
-All methods have to be called inside synchronized block.
-
-## Volatile fields
-
-`Synchronization::Object` can have volatile fields (Java semantic). They are defined by `attr_volatile :field_name`. `attr_volatile` defines reader and writer with the `field_name`. Any write is always immediately visible for any subsequent reads of the same field.
-
-## Ensure visibility of final fields
-
-Instance variables assigned only once in `initialize` method are not guaranteed to be visible to all threads. For that user can call `ensure_ivar_visibility!` method, like in following example taken from `Edge::AbstractPromise` implementation:
-
-```ruby
-class AbstractPromise < Synchronization::Object
-  def initialize(future, *args, &block)
-    super(*args, &block)
-    @Future = future
-    ensure_ivar_visibility!
-  end
-  # ...
-end
-```
-
-###  Naming conventions
-
-Instance variables with camel case names are final and never reassigned, e.g. `@FinalVariable`.
-
-## Fields with CAS operations
-
-They are not supported directly, but AtomicReference can be stored in final field and then CAS operations can be done on it, like in following example taken from `Edge::Event` implementation:
-
-```ruby
-class Event < Synchronization::Object
-  extend FutureShortcuts
-
-  def initialize(promise, default_executor = :io)
-    @Promise         = promise
-    @DefaultExecutor = default_executor
-    @Touched         = AtomicBoolean.new(false)
-    super()
-    ensure_ivar_visibility!
-  end
-  # ...
-  def touch
-    # distribute touch to promise only once
-    @Promise.touch if @Touched.make_true
-    self
-  end
-  # ...
-end
-```
-
-Operations on `@Touched` field have volatile semantic.
-
-## Memory model
-
-*Intended for further revision, and extension.*
-
-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 takes in account following implementations:
-
--   CRuby 1.9 - 2.2 (no differences found)
--   JRuby 1.7
--   JRuby 9 *not examined yet, same behavior as in 1.7 assumed*
--   Rubinius 2.5
-
-We are interested in following behaviors:
-
--   **volatility** - in Java's sense. Any written value is immediately visible to any subsequent reads including all writes leading to this value.
--   **atomicity** - operation is either done or not as a whole.
-
-### Variables
-
--   **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 (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:
-
--   **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
-
-Following operations are **assumed** thread-safe, volatile and atomic on all implementations:
-
--   Class definition
--   Method definition
--   Library requirement
-
-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 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
-
--   [JRuby wiki page on concurrency](https://github.com/jruby/jruby/wiki/Concurrency-in-jruby)
--   [Rubinius page on concurrency](http://rubini.us/doc/en/systems/concurrency/)
--   CRuby has GVL. Any GVL release and acquire uses lock which means that all writes done by a releasing thread will be visible to the second acquiring thread. See: <https://github.com/ruby/ruby/blob/ruby_2_2/thread_pthread.c#L101-L107>
+[This document](https://docs.google.com/document/d/1pVzU8w_QF44YzUCCab990Q_WZOdhpKolCIHaiXG-sPw/edit?usp=sharing) 
+is moved to Google documents. It will be moved here once final and stabilized.
 

ext/com/concurrent_ruby/ext/SynchronizationLibrary.java

@@ -6,6 +6,7 @@
 import org.jruby.RubyClass;
 import org.jruby.RubyModule;
 import org.jruby.RubyObject;
+import org.jruby.RubyBasicObject;
 import org.jruby.anno.JRubyClass;
 import org.jruby.anno.JRubyMethod;
 import org.jruby.runtime.ObjectAllocator;
@@ -47,6 +48,9 @@ public void load(Ruby runtime, boolean wrap) throws IOException {
                 defineModule("Concurrent").
                 defineModuleUnder("Synchronization");
 
+        RubyModule jrubyAttrVolatileModule = synchronizationModule.defineModuleUnder("JRubyAttrVolatile");
+        jrubyAttrVolatileModule.defineAnnotatedMethods(JRubyAttrVolatile.class);
+
         defineClass(runtime, synchronizationModule, "AbstractObject", "JRubyObject",
                 JRubyObject.class, JRUBY_OBJECT_ALLOCATOR);
 
@@ -81,21 +85,16 @@ private RubyClass defineClass(Ruby runtime, RubyModule namespace, String parentN
     //   SynchronizedVariableAccessor wraps with synchronized block, StampedVariableAccessor uses fullFence or
     //   volatilePut
 
-    @JRubyClass(name = "JRubyObject", parent = "AbstractObject")
-    public static class JRubyObject extends RubyObject {
-        private static volatile ThreadContext threadContext = null;
-
-        public JRubyObject(Ruby runtime, RubyClass metaClass) {
-            super(runtime, metaClass);
-        }
+    // module JRubyAttrVolatile
+    public static class JRubyAttrVolatile {
 
-        @JRubyMethod
-        public IRubyObject initialize(ThreadContext context) {
-            return this;
-        }
+        // volatile threadContext is used as a memory barrier per the JVM memory model happens-before semantic
+        // on volatile fields. any volatile field could have been used but using the thread context is an
+        // attempt to avoid code elimination.
+        private static volatile ThreadContext threadContext = null;
 
         @JRubyMethod(name = "full_memory_barrier", visibility = Visibility.PRIVATE)
-        public IRubyObject fullMemoryBarrier(ThreadContext context) {
+        public static IRubyObject fullMemoryBarrier(ThreadContext context, IRubyObject self) {
             // Prevent reordering of ivar writes with publication of this instance
             if (UnsafeHolder.U == null || !UnsafeHolder.SUPPORTS_FENCES) {
                 // Assuming that following volatile read and write is not eliminated it simulates fullFence.
@@ -109,35 +108,43 @@ public IRubyObject fullMemoryBarrier(ThreadContext context) {
         }
 
         @JRubyMethod(name = "instance_variable_get_volatile", visibility = Visibility.PROTECTED)
-        public IRubyObject instanceVariableGetVolatile(ThreadContext context, IRubyObject name) {
+        public static IRubyObject instanceVariableGetVolatile(ThreadContext context, IRubyObject self, IRubyObject name) {
             // Ensure we ses latest value with loadFence
             if (UnsafeHolder.U == null || !UnsafeHolder.SUPPORTS_FENCES) {
                 // piggybacking on volatile read, simulating loadFence
                 final ThreadContext oldContext = threadContext;
-                return instance_variable_get(context, name);
+                return ((RubyBasicObject)self).instance_variable_get(context, name);
             } else {
                 UnsafeHolder.loadFence();
-                return instance_variable_get(context, name);
+                return ((RubyBasicObject)self).instance_variable_get(context, name);
             }
         }
 
         @JRubyMethod(name = "instance_variable_set_volatile", visibility = Visibility.PROTECTED)
-        public IRubyObject InstanceVariableSetVolatile(ThreadContext context, IRubyObject name, IRubyObject value) {
+        public static IRubyObject InstanceVariableSetVolatile(ThreadContext context, IRubyObject self, IRubyObject name, IRubyObject value) {
             // Ensure we make last update visible
             if (UnsafeHolder.U == null || !UnsafeHolder.SUPPORTS_FENCES) {
                 // piggybacking on volatile write, simulating storeFence
-                final IRubyObject result = instance_variable_set(name, value);
+                final IRubyObject result = ((RubyBasicObject)self).instance_variable_set(name, value);
                 threadContext = context;
                 return result;
             } else {
                 // JRuby uses StampedVariableAccessor which calls fullFence
                 // so no additional steps needed.
                 // See https://github.com/jruby/jruby/blob/master/core/src/main/java/org/jruby/runtime/ivars/StampedVariableAccessor.java#L151-L159
-                return instance_variable_set(name, value);
+                return ((RubyBasicObject)self).instance_variable_set(name, value);
             }
         }
     }
 
+    @JRubyClass(name = "JRubyObject", parent = "AbstractObject")
+    public static class JRubyObject extends RubyObject {
+
+        public JRubyObject(Ruby runtime, RubyClass metaClass) {
+            super(runtime, metaClass);
+        }
+    }
+
     @JRubyClass(name = "Object", parent = "JRubyObject")
     public static class Object extends JRubyObject {
 

lib/concurrent/async.rb

@@ -299,6 +299,7 @@ def new(*args, &block)
     #
     # @!visibility private
     class AsyncDelegator < Synchronization::LockableObject
+      safe_initialization!
 
       # Create a new delegator object wrapping the given delegate.
       #
@@ -308,7 +309,6 @@ def initialize(delegate)
         @delegate = delegate
         @queue = []
         @executor = Concurrent.global_io_executor
-        ensure_ivar_visibility!
       end
 
       # Delegates method calls to the wrapped object.

lib/concurrent/atom.rb

@@ -111,9 +111,10 @@ class Atom < Synchronization::Object
     #
     # @raise [ArgumentError] if the validator is not a `Proc` (when given)
     def initialize(value, opts = {})
+      super()
       @Validator     = opts.fetch(:validator, -> v { true })
       self.observers = Collection::CopyOnNotifyObserverSet.new
-      super(value)
+      self.value     = value
     end
 
     # @!method value

lib/concurrent/atomic/atomic_boolean.rb

@@ -1,5 +1,5 @@
 require 'concurrent/atomic/mutex_atomic_boolean'
-require 'concurrent/utility/native_extension_loader'
+require 'concurrent/synchronization'
 
 module Concurrent
 

lib/concurrent/atomic/atomic_fixnum.rb

@@ -1,5 +1,5 @@
 require 'concurrent/atomic/mutex_atomic_fixnum'
-require 'concurrent/utility/native_extension_loader'
+require 'concurrent/synchronization'
 
 module Concurrent
 

lib/concurrent/atomic/atomic_reference.rb

@@ -1,4 +1,4 @@
-require 'concurrent/utility/native_extension_loader'
+require 'concurrent/synchronization'
 require 'concurrent/utility/engine'
 require 'concurrent/atomic_reference/concurrent_update_error'
 require 'concurrent/atomic_reference/mutex_atomic'

lib/concurrent/atomic/semaphore.rb

@@ -1,5 +1,5 @@
 require 'concurrent/atomic/mutex_semaphore'
-require 'concurrent/utility/native_extension_loader'
+require 'concurrent/synchronization'
 
 module Concurrent
 

lib/concurrent/atomic_reference/jruby+truffle.rb

@@ -0,0 +1 @@
+require 'concurrent/atomic_reference/rbx'