Added Lazy, a simpler and faster variation of Delay.

Author: jdantonio

CHANGELOG.md

@@ -32,6 +32,8 @@
 * All high-level abstractions default to the "io executor"
 * Added shutdown/kill/wait_for_termination variants for global executors
 * Fixed bug in `Actor` causing it to prematurely warm global thread pools on gem load
+* Added `Lazy`, a simpler and faster varition of `Delay`
+  - Updated most internal uses of `Delay` with `Lazy`
 
 ## Current Release v0.8.0 (25 January 2015)
 

examples/lazy_and_delay.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+$: << File.expand_path('../../lib', __FILE__)
+
+require 'benchmark'
+
+require 'concurrent/delay'
+
+n = 500_000
+
+delay = Concurrent::Delay.new{ nil }
+lazy = Concurrent::Lazy.new{ nil }
+
+delay.value
+lazy.value
+
+Benchmark.bm do |x|
+  puts 'Benchmarking Delay...'
+  x.report { n.times{ delay.value } }
+  puts 'Benchmarking Lazy...'
+  x.report { n.times{ lazy.value } }
+end

lib/concurrent/actor.rb

@@ -1,4 +1,5 @@
 require 'concurrent/configuration'
+require 'concurrent/delay'
 require 'concurrent/executor/serialized_execution'
 require 'concurrent/ivar'
 require 'concurrent/logging'

lib/concurrent/async.rb

@@ -1,6 +1,7 @@
 require 'thread'
 require 'concurrent/configuration'
 require 'concurrent/delay'
+require 'concurrent/lazy'
 require 'concurrent/errors'
 require 'concurrent/ivar'
 require 'concurrent/executor/immediate_executor'
@@ -201,7 +202,7 @@ def init_mutex
       }
 
       @__await_delegator__ = Delay.new(executor: :immediate) {
-        AsyncDelegator.new(self, Delay.new{ Concurrent::ImmediateExecutor.new }, serializer, true)
+        AsyncDelegator.new(self, Lazy.new{ Concurrent::ImmediateExecutor.new }, serializer, true)
       }
 
       @__async_delegator__ = Delay.new(executor: :immediate) {

lib/concurrent/configuration.rb

@@ -1,5 +1,5 @@
 require 'thread'
-require 'concurrent/delay'
+require 'concurrent/lazy'
 require 'concurrent/atomics'
 require 'concurrent/errors'
 require 'concurrent/executors'
@@ -12,17 +12,17 @@ module Concurrent
   class << self
     @@auto_terminate_global_executors = Concurrent::AtomicBoolean.new(true)
 
-    @@global_fast_executor = Delay.new(executor: :immediate) do
+    @@global_fast_executor = Lazy.new do
       Concurrent.new_fast_executor(
         stop_on_exit: @@auto_terminate_global_executors.value)
     end
 
-    @@global_io_executor = Delay.new(executor: :immediate) do
+    @@global_io_executor = Lazy.new do
       Concurrent.new_io_executor(
         stop_on_exit: @@auto_terminate_global_executors.value)
     end
 
-    @@global_timer_set = Delay.new(executor: :immediate) do
+    @@global_timer_set = Lazy.new do
       Concurrent::TimerSet.new(
         stop_on_exit: @@auto_terminate_global_executors.value)
     end

lib/concurrent/delay.rb

@@ -5,13 +5,15 @@
 
 module Concurrent
 
-  # Lazy evaluation of a block yielding an immutable result. Useful for expensive
-  # operations that may never be needed.
-  #
-  # A `Delay` is similar to `Future` but solves a different problem.
-  # Where a `Future` schedules an operation for immediate execution and
-  # performs the operation asynchronously, a `Delay` (as the name implies)
-  # delays execution of the operation until the result is actually needed.
+  # Lazy evaluation of a block yielding an immutable result. Useful for
+  # expensive operations that may never be needed. `Delay` is a more
+  # complex and feature-rich version of `Lazy`. It is non-blocking,
+  # supports the `Obligation` interface, and accepts the injection of
+  # custom executor upon which to execute the block. Processing of
+  # block will be deferred until the first time `#value` is called.
+  # At that time the caller can choose to return immediately and let
+  # the block execute asynchronously, block indefinitely, or block
+  # with a timeout.
   #
   # When a `Delay` is created its state is set to `pending`. The value and
   # reason are both `nil`. The first time the `#value` method is called the
@@ -26,10 +28,16 @@ module Concurrent
   # `Delay` includes the `Concurrent::Dereferenceable` mixin to support thread
   # safety of the reference returned by `#value`.
   #
-  # @see Concurrent::Dereferenceable
+  # Because of its simplicity `Lazy` is much faster than `Delay`:
   #
-  # @see http://clojuredocs.org/clojure_core/clojure.core/delay
-  # @see http://aphyr.com/posts/306-clojure-from-the-ground-up-state
+  #            user     system      total        real
+  #     Benchmarking Delay...
+  #        0.730000   0.000000   0.730000 (  0.738434)
+  #     Benchmarking Lazy...
+  #        0.040000   0.000000   0.040000 (  0.042322)
+  #
+  # @see Concurrent::Dereferenceable
+  # @see Concurrent::Lazy
   class Delay
     include Obligation
     include ExecutorOptions
@@ -63,12 +71,20 @@ def initialize(opts = {}, &block)
       @computing     = false
     end
 
-    def wait(timeout)
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method.
+    #
+    # @param [Integer] timeout (nil) the maximum number of seconds to wait for
+    #   the value to be computed. When `nil` the caller will block indefinitely.
+    #
+    # @return [Object] the current value of the object
+    def wait(timeout = nil)
       execute_task_once
-      super timeout
+      super(timeout)
     end
 
-    # reconfigures the block returning the value if still #incomplete?
+    # Reconfigures the block returning the value if still `#incomplete?`
+    #
     # @yield the delayed operation to perform
     # @return [true, false] if success
     def reconfigure(&block)
@@ -86,7 +102,8 @@ def reconfigure(&block)
 
     private
 
-    def execute_task_once
+    # @!visibility private
+    def execute_task_once # :nodoc:
       mutex.lock
       execute = @computing = true unless @computing
       task    = @task

lib/concurrent/lazy.rb

@@ -0,0 +1,62 @@
+module Concurrent
+
+  # Lazy evaluation of a block yielding an immutable result. Useful for
+  # expensive operations that may never be needed. `Lazy` is a simpler,
+  # blocking version of `Delay` and has an API similar to `AtomicReference`.
+  # The first time `#value` is called the caller will block until the
+  # block given at construction is executed. Once the result has been
+  # computed the value will be immutably set. Any exceptions thrown during
+  # computation will be suppressed.
+  #
+  # Because of its simplicity `Lazy` is much faster than `Delay`:
+  #
+  #            user     system      total        real
+  #     Benchmarking Delay...
+  #        0.730000   0.000000   0.730000 (  0.738434)
+  #     Benchmarking Lazy...
+  #        0.040000   0.000000   0.040000 (  0.042322)
+  #
+  # @see Concurrent::Delay
+  class Lazy
+
+    # Creates anew unfulfilled object.
+    #
+    # @yield the delayed operation to perform
+    # @param [Object] default (nil) the default value for the object when
+    #   the block raises an exception
+    #
+    # @raise [ArgumentError] if no block is given
+    def initialize(default = nil, &block)
+      raise ArgumentError.new('no block given') unless block_given?
+      @default = default
+      @task = block
+      @mutex = Mutex.new
+      @value = nil
+      @fulfilled = false
+    end
+
+    # The calculated value of the object or the default value if one
+    # was given at construction. This first time this method is called
+    # it will block indefinitely while the block is processed.
+    # Subsequent calls will not block.
+    #
+    # @return [Object] the calculated value
+    def value
+      # double-checked locking is safe because we only update once
+      return @value if @fulfilled
+
+      @mutex.synchronize do
+        unless @fulfilled
+          begin
+            @value = @task.call
+          rescue
+            @value = @default
+          ensure
+            @fulfilled = true
+          end
+        end
+        return @value
+      end
+    end
+  end
+end

lib/concurrent/utility/processor_count.rb

@@ -1,13 +1,12 @@
 require 'rbconfig'
-require 'concurrent/delay'
-require 'concurrent/executor/immediate_executor'
+require 'concurrent/lazy'
 
 module Concurrent
 
   class ProcessorCounter
     def initialize
-      @processor_count          = Delay.new(executor: :immediate) { compute_processor_count }
-      @physical_processor_count = Delay.new(executor: :immediate) { compute_physical_processor_count }
+      @processor_count          = Lazy.new { compute_processor_count }
+      @physical_processor_count = Lazy.new { compute_physical_processor_count }
     end
 
     # Number of processors seen by the OS and used for process scheduling. For
@@ -79,7 +78,7 @@ def compute_processor_count
         if os_name =~ /mingw|mswin/
           require 'win32ole'
           result = WIN32OLE.connect("winmgmts://").ExecQuery(
-              "select NumberOfLogicalProcessors from Win32_Processor")
+            "select NumberOfLogicalProcessors from Win32_Processor")
           result.to_enum.collect(&:NumberOfLogicalProcessors).reduce(:+)
         elsif File.readable?("/proc/cpuinfo")
           IO.read("/proc/cpuinfo").scan(/^processor/).size
@@ -128,7 +127,7 @@ def compute_physical_processor_count
             when /mswin|mingw/
               require 'win32ole'
               result_set = WIN32OLE.connect("winmgmts://").ExecQuery(
-                  "select NumberOfCores from Win32_Processor")
+                "select NumberOfCores from Win32_Processor")
               result_set.to_enum.collect(&:NumberOfCores).reduce(:+)
             else
               processor_count

spec/concurrent/lazy_spec.rb

@@ -0,0 +1,82 @@
+module Concurrent
+
+  describe Lazy do
+
+    context '#initialize' do
+
+      it 'raises an exception when no block given' do
+        expect {
+          Lazy.new
+        }.to raise_error(ArgumentError)
+      end
+    end
+
+    context '#value' do
+
+      let(:task){ proc{ nil } }
+
+      it 'does not call the block before #value is called' do
+        expect(task).to_not receive(:call).with(any_args)
+        Lazy.new(&task)
+      end
+
+      it 'calls the block when #value is called' do
+        expect(task).to receive(:call).once.with(any_args).and_return(nil)
+        Lazy.new(&task).value
+      end
+
+      it 'only calls the block once no matter how often #value is called' do
+        expect(task).to receive(:call).once.with(any_args).and_return(nil)
+        lazy = Lazy.new(&task)
+        5.times{ lazy.value }
+      end
+
+      it 'does not lock the mutex once the block has been called' do
+        mutex = Mutex.new
+        allow(Mutex).to receive(:new).and_return(mutex)
+
+        lazy = Lazy.new(&task)
+        lazy.value
+
+        expect(mutex).to_not receive(:synchronize).with(any_args)
+        expect(mutex).to_not receive(:lock).with(any_args)
+        expect(mutex).to_not receive(:try_lock).with(any_args)
+
+        5.times{ lazy.value }
+      end
+
+      context 'on exception' do
+
+        it 'suppresses the error' do
+          expect {
+            Lazy.new{ raise StandardError }
+          }.to_not raise_exception
+        end
+
+        it 'sets the value to nil when no default is given' do
+          lazy = Lazy.new{ raise StandardError }
+          expect(lazy.value).to be_nil
+        end
+
+        it 'sets the value appropriately when given a default' do
+          lazy = Lazy.new(100){ raise StandardError }
+          expect(lazy.value).to eq 100
+        end
+
+        it 'does not try to call the block again' do
+          mutex = Mutex.new
+          allow(Mutex).to receive(:new).and_return(mutex)
+
+          lazy = Lazy.new{ raise StandardError }
+          lazy.value
+
+          expect(mutex).to_not receive(:synchronize).with(any_args)
+          expect(mutex).to_not receive(:lock).with(any_args)
+          expect(mutex).to_not receive(:try_lock).with(any_args)
+
+          5.times{ lazy.value }
+        end
+      end
+    end
+  end
+end