concurrent-ruby 0.8.0 → 0.9.0.pre2

data/lib/concurrent/synchronization/monitor_object.rb

@@ -0,0 +1,24 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    class MonitorObject < MutexObject
+      def initialize
+        @__lock__      = ::Monitor.new
+        @__condition__ = @__lock__.new_cond
+      end
+
+      protected
+
+      def synchronize
+        @__lock__.synchronize { yield }
+      end
+
+      def ns_wait(timeout = nil)
+        @__condition__.wait timeout
+        self
+      end
+    end
+  end
+end

data/lib/concurrent/synchronization/mutex_object.rb

@@ -0,0 +1,43 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    class MutexObject < AbstractObject
+      def initialize
+        @__lock__      = ::Mutex.new
+        @__condition__ = ::ConditionVariable.new
+      end
+
+      protected
+
+      def synchronize
+        if @__lock__.owned?
+          yield
+        else
+          @__lock__.synchronize { yield }
+        end
+      end
+
+      def ns_signal
+        @__condition__.signal
+        self
+      end
+
+      def ns_broadcast
+        @__condition__.broadcast
+        self
+      end
+
+      def ns_wait(timeout = nil)
+        @__condition__.wait @__lock__, timeout
+        self
+      end
+
+      def ensure_ivar_visibility!
+        # relying on undocumented behavior of CRuby, GVL acquire has lock which ensures visibility of ivars
+        # https://github.com/ruby/ruby/blob/ruby_2_2/thread_pthread.c#L204-L211
+      end
+    end
+  end
+end

data/lib/concurrent/synchronization/object.rb

@@ -0,0 +1,78 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    Implementation = case
+                     when Concurrent.on_jruby?
+                       JavaObject
+                     when Concurrent.on_cruby? && Concurrent.ruby_version(:<=, 1, 9, 3)
+                       MonitorObject
+                     when Concurrent.on_cruby? && Concurrent.ruby_version(:>, 1, 9, 3)
+                       MutexObject
+                     when Concurrent.on_rbx?
+                       RbxObject
+                     else
+                       warn 'Possibly unsupported Ruby implementation'
+                       MutexObject
+                     end
+    private_constant :Implementation
+
+    # @!macro [attach] synchronization_object
+    #  
+    #   Safe synchronization under any Ruby implementation.
+    #   It provides methods like {#synchronize}, {#wait}, {#signal} and {#broadcast}.
+    #   Provides a single layer which can improve its implementation over time without changes needed to
+    #   the classes using it. Use {Synchronization::Object} not this abstract class.
+    #  
+    #   @note this object does not support usage together with
+    #     [`Thread#wakeup`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-wakeup)
+    #     and [`Thread#raise`](http://ruby-doc.org/core-2.2.0/Thread.html#method-i-raise).
+    #     `Thread#sleep` and `Thread#wakeup` will work as expected but mixing `Synchronization::Object#wait` and
+    #     `Thread#wakeup` will not work on all platforms.
+    #  
+    #   @see {Event} implementation as an example of this class use
+    #  
+    #   @example simple
+    #     class AnClass < Synchronization::Object
+    #       def initialize
+    #         super
+    #         synchronize { @value = 'asd' }
+    #       end
+    #  
+    #       def value
+    #         synchronize { @value }
+    #       end
+    #     end
+    #
+    class Object < Implementation
+
+      # @!method initialize(*args, &block)
+      #   @!macro synchronization_object_method_initialize
+
+      # @!method synchronize
+      #   @!macro synchronization_object_method_synchronize
+
+      # @!method initialize(*args, &block)
+      #   @!macro synchronization_object_method_ns_initialize
+
+      # @!method wait_until(timeout = nil, &condition)
+      #   @!macro synchronization_object_method_ns_wait_until
+
+      # @!method wait(timeout = nil)
+      #   @!macro synchronization_object_method_ns_wait
+
+      # @!method signal
+      #   @!macro synchronization_object_method_ns_signal
+
+      # @!method broadcast
+      #   @!macro synchronization_object_method_ns_broadcast
+
+      # @!method ensure_ivar_visibility!
+      #   @!macro synchronization_object_method_ensure_ivar_visibility
+
+      # @!method self.attr_volatile(*names)
+      #   @!macro synchronization_object_method_self_attr_volatile
+    end
+  end
+end

data/lib/concurrent/synchronization/rbx_object.rb

@@ -0,0 +1,75 @@
+module Concurrent
+  module Synchronization
+
+    if Concurrent.on_rbx?
+      
+      # @!visibility private
+      # @!macro internal_implementation_note
+      class RbxObject < AbstractObject
+        def initialize
+          @Waiters = []
+          ensure_ivar_visibility!
+        end
+
+        protected
+
+        def synchronize(&block)
+          Rubinius.synchronize(self, &block)
+        end
+
+        def ns_wait(timeout = nil)
+          wchan = Rubinius::Channel.new
+
+          begin
+            @Waiters.push wchan
+            Rubinius.unlock(self)
+            signaled = wchan.receive_timeout timeout
+          ensure
+            Rubinius.lock(self)
+
+            if !signaled && !@Waiters.delete(wchan)
+              # we timed out, but got signaled afterwards,
+              # so pass that signal on to the next waiter
+              @Waiters.shift << true unless @Waiters.empty?
+            end
+          end
+
+          self
+        end
+
+        def ns_signal
+          @Waiters.shift << true unless @Waiters.empty?
+          self
+        end
+
+        def ns_broadcast
+          @Waiters.shift << true until @Waiters.empty?
+          self
+        end
+
+        def ensure_ivar_visibility!
+          # Rubinius instance variables are not volatile so we need to insert barrier
+          Rubinius.memory_barrier
+        end
+
+        def self.attr_volatile *names
+          names.each do |name|
+            ivar = :"@volatile_#{name}"
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}
+              Rubinius.memory_barrier
+              #{ivar}
+            end
+
+            def #{name}=(value)
+              #{ivar} = value
+              Rubinius.memory_barrier
+            end
+            RUBY
+          end
+          names.map { |n| [n, :"#{n}="] }.flatten
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/timer_task.rb

@@ -1,72 +1,81 @@
-require 'concurrent/dereferenceable'
-require 'concurrent/observable'
+require 'concurrent/collection/copy_on_notify_observer_set'
+require 'concurrent/concern/dereferenceable'
+require 'concurrent/concern/observable'
 require 'concurrent/atomic/atomic_boolean'
-require 'concurrent/executor/executor'
+require 'concurrent/executor/executor_service'
 require 'concurrent/executor/safe_task_executor'
 
 module Concurrent
 
-  # A very common currency pattern is to run a thread that performs a task at regular
-  # intervals. The thread that performs the task sleeps for the given interval then
-  # wakes up and performs the task. Lather, rinse, repeat... This pattern causes two
-  # problems. First, it is difficult to test the business logic of the task because the
-  # task itself is tightly coupled with the concurrency logic. Second, an exception
-  # raised while performing the task can cause the entire thread to abend. In a
-  # long-running application where the task thread is intended to run for days/weeks/years
-  # a crashed task thread can pose a significant problem. `TimerTask` alleviates both problems.
-  # 
-  # When a `TimerTask` is launched it starts a thread for monitoring the execution interval.
-  # The `TimerTask` thread does not perform the task, however. Instead, the TimerTask
-  # launches the task on a separate thread. Should the task experience an unrecoverable
-  # crash only the task thread will crash. This makes the `TimerTask` very fault tolerant
-  # Additionally, the `TimerTask` thread can respond to the success or failure of the task,
-  # performing logging or ancillary operations. `TimerTask` can also be configured with a
-  # timeout value allowing it to kill a task that runs too long.
-  # 
-  # One other advantage of `TimerTask` is that it forces the business logic to be completely decoupled
-  # from the concurrency logic. The business logic can be tested separately then passed to the
-  # `TimerTask` for scheduling and running.
-  # 
-  # In some cases it may be necessary for a `TimerTask` to affect its own execution cycle.
-  # To facilitate this, a reference to the TimerTask instance is passed as an argument
-  # to the provided block every time the task is executed.
-  # 
-  # The `TimerTask` class includes the `Dereferenceable` mixin module so the result of
-  # the last execution is always available via the `#value` method. Derefencing options
-  # can be passed to the `TimerTask` during construction or at any later time using the
-  # `#set_deref_options` method.
-  # 
+  # A very common currency pattern is to run a thread that performs a task at
+  # regular intervals. The thread that performs the task sleeps for the given
+  # interval then wakes up and performs the task. Lather, rinse, repeat... This
+  # pattern causes two problems. First, it is difficult to test the business
+  # logic of the task because the task itself is tightly coupled with the
+  # concurrency logic. Second, an exception raised while performing the task can
+  # cause the entire thread to abend. In a long-running application where the
+  # task thread is intended to run for days/weeks/years a crashed task thread
+  # can pose a significant problem. `TimerTask` alleviates both problems.
+  #
+  # When a `TimerTask` is launched it starts a thread for monitoring the
+  # execution interval. The `TimerTask` thread does not perform the task,
+  # however. Instead, the TimerTask launches the task on a separate thread.
+  # Should the task experience an unrecoverable crash only the task thread will
+  # crash. This makes the `TimerTask` very fault tolerant Additionally, the
+  # `TimerTask` thread can respond to the success or failure of the task,
+  # performing logging or ancillary operations. `TimerTask` can also be
+  # configured with a timeout value allowing it to kill a task that runs too
+  # long.
+  #
+  # One other advantage of `TimerTask` is that it forces the business logic to
+  # be completely decoupled from the concurrency logic. The business logic can
+  # be tested separately then passed to the `TimerTask` for scheduling and
+  # running.
+  #
+  # In some cases it may be necessary for a `TimerTask` to affect its own
+  # execution cycle. To facilitate this, a reference to the TimerTask instance
+  # is passed as an argument to the provided block every time the task is
+  # executed.
+  #
+  # The `TimerTask` class includes the `Dereferenceable` mixin module so the
+  # result of the last execution is always available via the `#value` method.
+  # Derefencing options can be passed to the `TimerTask` during construction or
+  # at any later time using the `#set_deref_options` method.
+  #
   # `TimerTask` supports notification through the Ruby standard library
-  # {http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html Observable}
-  # module. On execution the `TimerTask` will notify the observers
-  # with three arguments: time of execution, the result of the block (or nil on failure),
-  # and any raised exceptions (or nil on success). If the timeout interval is exceeded
-  # the observer will receive a `Concurrent::TimeoutError` object as the third argument.
+  # {http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
+  # Observable} module. On execution the `TimerTask` will notify the observers
+  # with three arguments: time of execution, the result of the block (or nil on
+  # failure), and any raised exceptions (or nil on success). If the timeout
+  # interval is exceeded the observer will receive a `Concurrent::TimeoutError`
+  # object as the third argument.
+  #
+  # @!macro copy_options
   #
   # @example Basic usage
   #   task = Concurrent::TimerTask.new{ puts 'Boom!' }
   #   task.execute
-  #   
+  #
   #   task.execution_interval #=> 60 (default)
   #   task.timeout_interval   #=> 30 (default)
-  #   
+  #
   #   # wait 60 seconds...
   #   #=> 'Boom!'
-  #   
+  #
   #   task.shutdown #=> true
   #
   # @example Configuring `:execution_interval` and `:timeout_interval`
   #   task = Concurrent::TimerTask.new(execution_interval: 5, timeout_interval: 5) do
   #          puts 'Boom!'
   #        end
-  #   
+  #
   #   task.execution_interval #=> 5
   #   task.timeout_interval   #=> 5
   #
   # @example Immediate execution with `:run_now`
   #   task = Concurrent::TimerTask.new(run_now: true){ puts 'Boom!' }
   #   task.execute
-  #   
+  #
   #   #=> 'Boom!'
   #
   # @example Last `#value` and `Dereferenceable` mixin
@@ -74,7 +83,7 @@ module Concurrent
   #     dup_on_deref: true,
   #     execution_interval: 5
   #   ){ Time.now }
-  #   
+  #
   #   task.execute
   #   Time.now   #=> 2013-11-07 18:06:50 -0500
   #   sleep(10)
@@ -90,7 +99,7 @@ module Concurrent
   #       task.shutdown
   #     end
   #   end
-  #   
+  #
   #   timer_task.execute # blocking call - this task will stop itself
   #   #=> Boom!
   #   #=> Boom! Boom!
@@ -111,29 +120,29 @@ module Concurrent
   #       end
   #     end
   #   end
-  #   
+  #
   #   task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ 42 }
   #   task.add_observer(TaskObserver.new)
   #   task.execute
-  #   
+  #
   #   #=> (2013-10-13 19:08:58 -0400) Execution successfully returned 42
   #   #=> (2013-10-13 19:08:59 -0400) Execution successfully returned 42
   #   #=> (2013-10-13 19:09:00 -0400) Execution successfully returned 42
   #   task.shutdown
-  #   
+  #
   #   task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ sleep }
   #   task.add_observer(TaskObserver.new)
   #   task.execute
-  #   
+  #
   #   #=> (2013-10-13 19:07:25 -0400) Execution timed out
   #   #=> (2013-10-13 19:07:27 -0400) Execution timed out
   #   #=> (2013-10-13 19:07:29 -0400) Execution timed out
   #   task.shutdown
-  #   
+  #
   #   task = Concurrent::TimerTask.new(execution_interval: 1){ raise StandardError }
   #   task.add_observer(TaskObserver.new)
   #   task.execute
-  #   
+  #
   #   #=> (2013-10-13 19:09:37 -0400) Execution failed with error StandardError
   #   #=> (2013-10-13 19:09:38 -0400) Execution failed with error StandardError
   #   #=> (2013-10-13 19:09:39 -0400) Execution failed with error StandardError
@@ -141,10 +150,9 @@ module Concurrent
   #
   # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
   # @see http://docs.oracle.com/javase/7/docs/api/java/util/TimerTask.html
-  class TimerTask
-    include Dereferenceable
-    include RubyExecutor
-    include Concurrent::Observable
+  class TimerTask < RubyExecutorService
+    include Concern::Dereferenceable
+    include Concern::Observable
 
     # Default `:execution_interval` in seconds.
     EXECUTION_INTERVAL = 60
@@ -163,36 +171,22 @@ module Concurrent
     #   @option opts [Boolean] :run_now Whether to run the task immediately
     #     upon instantiation or to wait until the first #  execution_interval
     #     has passed (default: false)
-    #  
+    #
+    #   @!macro deref_options
+    #
     #   @raise ArgumentError when no block is given.
-    #  
+    #
     #   @yield to the block after :execution_interval seconds have passed since
     #     the last yield
     #   @yieldparam task a reference to the `TimerTask` instance so that the
     #     block can control its own lifecycle. Necessary since `self` will
     #     refer to the execution context of the block rather than the running
     #     `TimerTask`.
-    #  
-    #   @note Calls Concurrent::Dereferenceable#  set_deref_options passing `opts`.
-    #     All options supported by Concurrent::Dereferenceable can be set
-    #     during object initialization.
     #
     #   @return [TimerTask] the new `TimerTask`
-    #  
-    #   @see Concurrent::Dereferenceable#  set_deref_options
     def initialize(opts = {}, &task)
       raise ArgumentError.new('no block given') unless block_given?
-
-      init_executor
-      set_deref_options(opts)
-
-      self.execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL
-      self.timeout_interval = opts[:timeout] || opts[:timeout_interval] || TIMEOUT_INTERVAL
-      @run_now = opts[:now] || opts[:run_now]
-      @executor = Concurrent::SafeTaskExecutor.new(task)
-      @running = Concurrent::AtomicBoolean.new(false)
-
-      self.observers = CopyOnNotifyObserverSet.new
+      super
     end
 
     # Is the executor running?
@@ -215,10 +209,8 @@ module Concurrent
     # @example Instance and execute in one line
     #   task = Concurrent::TimerTask.new(execution_interval: 10){ print "Hello World\n" }.execute
     #   task.running? #=> true
-    #
-    # @since 0.6.0
     def execute
-      mutex.synchronize do
+      synchronize do
         if @running.false?
           @running.make_true
           schedule_next_task(@run_now ? 0 : @execution_interval)
@@ -231,11 +223,9 @@ module Concurrent
     #
     # @!macro timer_task_initialize
     #
-    # @example 
+    # @example
     #   task = Concurrent::TimerTask.execute(execution_interval: 10){ print "Hello World\n" }
     #   task.running? #=> true
-    #
-    # @since 0.6.0
     def self.execute(opts = {}, &task)
       TimerTask.new(opts, &task).execute
     end
@@ -244,10 +234,7 @@ module Concurrent
     # @return [Fixnum] Number of seconds after the task completes before the
     #   task is performed again.
     def execution_interval
-      mutex.lock
-      @execution_interval
-    ensure
-      mutex.unlock
+      synchronize { @execution_interval }
     end
 
     # @!attribute [rw] execution_interval
@@ -257,12 +244,7 @@ module Concurrent
       if (value = value.to_f) <= 0.0
         raise ArgumentError.new('must be greater than zero')
       else
-        begin
-          mutex.lock
-          @execution_interval = value
-        ensure
-          mutex.unlock
-        end
+        synchronize { @execution_interval = value }
       end
     end
 
@@ -270,10 +252,7 @@ module Concurrent
     # @return [Fixnum] Number of seconds the task can run before it is
     #   considered to have failed.
     def timeout_interval
-      mutex.lock
-      @timeout_interval
-    ensure
-      mutex.unlock
+      synchronize { @timeout_interval }
     end
 
     # @!attribute [rw] timeout_interval
@@ -283,12 +262,7 @@ module Concurrent
       if (value = value.to_f) <= 0.0
         raise ArgumentError.new('must be greater than zero')
       else
-        begin
-          mutex.lock
-          @timeout_interval = value
-        ensure
-          mutex.unlock
-        end
+        synchronize { @timeout_interval = value }
       end
     end
 
@@ -296,6 +270,19 @@ module Concurrent
 
     protected
 
+    def ns_initialize(opts, &task)
+      init_mutex(self)
+      set_deref_options(opts)
+
+      self.execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL
+      self.timeout_interval = opts[:timeout] || opts[:timeout_interval] || TIMEOUT_INTERVAL
+      @run_now = opts[:now] || opts[:run_now]
+      @executor = Concurrent::SafeTaskExecutor.new(task)
+      @running = Concurrent::AtomicBoolean.new(false)
+
+      self.observers = Collection::CopyOnNotifyObserverSet.new
+    end
+
     # @!visibility private
     def shutdown_execution
       @running.make_false