Renamed Lazy to LazyReference.

jdantonio · jdantonio · commit 390ac66baea9 · 2015-03-03T22:12:30.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -32,8 +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`
+* Added `LazyReference`, a simpler and faster varition of `Delay`
+  - Updated most internal uses of `Delay` with `LazyReference`
 
 ## Current Release v0.8.0 (25 January 2015)
 
diff --git a/README.md b/README.md
@@ -66,36 +66,29 @@ This library contains a variety of concurrency abstractions at high and low leve
 
 * See [ThreadPool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
 
-### Thread-safe Observers
-
-* [Concurrent::Observable](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Observable.html) mixin module
-* [CopyOnNotifyObserverSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CopyOnNotifyObserverSet.html)
-* [CopyOnWriteObserverSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CopyOnWriteObserverSet.html)
-
 ### Thread synchronization classes and algorithms
 
-Lower-level abstractions mainly used as building blocks. 
-
-* [condition](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Condition.html)
-* [countdown latch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html)
-* [cyclic barrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html)
-* [event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html)
-* [exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
-* [semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html)
-* [timeout](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timeout-class_method)
-* [timer](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timer-class_method)
+* [Condition](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Condition.html)
+* [CountdownLatch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html)
+* [CyclicBarrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html)
+* [Event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html)
+* [Exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
+* [Semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html)
+* [Timeout](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timeout-class_method)
+* [Timer](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timer-class_method)
 
 ### Thread-safe variables
 
-Lower-level abstractions mainly used as building blocks. 
-
 * [AtomicBoolean](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicBoolean.html)
 * [AtomicFixnum](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicFixnum.html)
-* AtomicReference (no docs currently available, check source)
+* [AtomicReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutexAtomic.html)
+* [Delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html)
+* [LazyReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyReference.html)
+* [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
 * [I-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html) (IVar)
 * [M-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html) (MVar)
-* [thread-local variables](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html)
-* [software transactional memory](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) (TVar)
+* [Thread-local variables](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html)
+* [Software transactional memory](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) (TVar)
 
 ## Usage
 
@@ -128,6 +121,8 @@ require 'concurrent/delay'          # Concurrent::Delay
 require 'concurrent/exchanger'      # Concurrent::Exchanger
 require 'concurrent/future'         # Concurrent::Future
 require 'concurrent/ivar'           # Concurrent::IVar
+require 'concurrent/lazy_register'  # Concurrent::LazyRegister
+require 'concurrent/lazy_reference' # Concurrent::LazyReference
 require 'concurrent/mvar'           # Concurrent::MVar
 require 'concurrent/promise'        # Concurrent::Promise
 require 'concurrent/scheduled_task' # Concurrent::ScheduledTask
diff --git a/examples/lazy_and_delay.rb b/examples/lazy_and_delay.rb
@@ -5,11 +5,12 @@
 require 'benchmark'
 
 require 'concurrent/delay'
+require 'concurrent/lazy_reference'
 
 n = 500_000
 
 delay = Concurrent::Delay.new{ nil }
-lazy = Concurrent::Lazy.new{ nil }
+lazy = Concurrent::LazyReference.new{ nil }
 
 delay.value
 lazy.value
diff --git a/lib/concurrent.rb b/lib/concurrent.rb
@@ -2,14 +2,14 @@
 
 require 'concurrent/configuration'
 
+require 'concurrent/actor'
 require 'concurrent/atomics'
 require 'concurrent/channels'
 require 'concurrent/collections'
 require 'concurrent/errors'
 require 'concurrent/executors'
 require 'concurrent/utilities'
 
-require 'concurrent/actor'
 require 'concurrent/atomic'
 require 'concurrent/agent'
 require 'concurrent/async'
@@ -19,7 +19,7 @@
 require 'concurrent/exchanger'
 require 'concurrent/future'
 require 'concurrent/ivar'
-require 'concurrent/lazy'
+require 'concurrent/lazy_reference'
 require 'concurrent/lazy_register'
 require 'concurrent/mvar'
 require 'concurrent/promise'
diff --git a/lib/concurrent/agent.rb b/lib/concurrent/agent.rb
@@ -24,7 +24,18 @@ class Agent
     #
     # @param [Object] initial the initial value
     #
-    # @!macro executor_and_deref_options
+    # @!macro [attach] executor_and_deref_options
+    #  
+    #   @param [Hash] opts the options used to define the behavior at update and deref
+    #     and to specify the executor on which to perform actions
+    #   @option opts [Executor] :executor when set use the given `Executor` instance.
+    #     Three special values are also supported: `:task` returns the global task pool,
+    #     `:operation` returns the global operation pool, and `:immediate` returns a new
+    #     `ImmediateExecutor` object.
+    #   @option opts [Boolean] :dup_on_deref (false) call `#dup` before returning the data
+    #   @option opts [Boolean] :freeze_on_deref (false) call `#freeze` before returning the data
+    #   @option opts [Proc] :copy_on_deref (nil) call the given `Proc` passing
+    #     the internal value and returning the value returned from the proc
     def initialize(initial, opts = {})
       @value                = initial
       @rescuers             = []
diff --git a/lib/concurrent/async.rb b/lib/concurrent/async.rb
@@ -1,7 +1,7 @@
 require 'thread'
 require 'concurrent/configuration'
 require 'concurrent/delay'
-require 'concurrent/lazy'
+require 'concurrent/lazy_reference'
 require 'concurrent/errors'
 require 'concurrent/ivar'
 require 'concurrent/executor/immediate_executor'
@@ -202,7 +202,7 @@ def init_mutex
       }
 
       @__await_delegator__ = Delay.new(executor: :immediate) {
-        AsyncDelegator.new(self, Lazy.new{ Concurrent::ImmediateExecutor.new }, serializer, true)
+        AsyncDelegator.new(self, LazyReference.new{ Concurrent::ImmediateExecutor.new }, serializer, true)
       }
 
       @__async_delegator__ = Delay.new(executor: :immediate) {
diff --git a/lib/concurrent/configuration.rb b/lib/concurrent/configuration.rb
@@ -1,5 +1,5 @@
 require 'thread'
-require 'concurrent/lazy'
+require 'concurrent/lazy_reference'
 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 = Lazy.new do
+    @@global_fast_executor = LazyReference.new do
       Concurrent.new_fast_executor(
         stop_on_exit: @@auto_terminate_global_executors.value)
     end
 
-    @@global_io_executor = Lazy.new do
+    @@global_io_executor = LazyReference.new do
       Concurrent.new_io_executor(
         stop_on_exit: @@auto_terminate_global_executors.value)
     end
 
-    @@global_timer_set = Lazy.new do
+    @@global_timer_set = LazyReference.new do
       Concurrent::TimerSet.new(
         stop_on_exit: @@auto_terminate_global_executors.value)
     end
diff --git a/lib/concurrent/delay.rb b/lib/concurrent/delay.rb
@@ -7,7 +7,7 @@ module Concurrent
 
   # 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,
+  # complex and feature-rich version of `LazyReference`. 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.
@@ -28,16 +28,16 @@ module Concurrent
   # `Delay` includes the `Concurrent::Dereferenceable` mixin to support thread
   # safety of the reference returned by `#value`.
   #
-  # Because of its simplicity `Lazy` is much faster than `Delay`:
+  # Because of its simplicity `LazyReference` is much faster than `Delay`:
   #
   #            user     system      total        real
   #     Benchmarking Delay...
   #        0.730000   0.000000   0.730000 (  0.738434)
-  #     Benchmarking Lazy...
+  #     Benchmarking LazyReference...
   #        0.040000   0.000000   0.040000 (  0.042322)
   #
   # @see Concurrent::Dereferenceable
-  # @see Concurrent::Lazy
+  # @see Concurrent::LazyReference
   class Delay
     include Obligation
     include ExecutorOptions
@@ -46,18 +46,7 @@ class Delay
     #
     # @yield the delayed operation to perform
     #
-    # @!macro [attach] executor_and_deref_options
-    #  
-    #   @param [Hash] opts the options used to define the behavior at update and deref
-    #     and to specify the executor on which to perform actions
-    #   @option opts [Executor] :executor when set use the given `Executor` instance.
-    #     Three special values are also supported: `:task` returns the global task pool,
-    #     `:operation` returns the global operation pool, and `:immediate` returns a new
-    #     `ImmediateExecutor` object.
-    #   @option opts [Boolean] :dup_on_deref (false) call `#dup` before returning the data
-    #   @option opts [Boolean] :freeze_on_deref (false) call `#freeze` before returning the data
-    #   @option opts [Proc] :copy_on_deref (nil) call the given `Proc` passing
-    #     the internal value and returning the value returned from the proc
+    # @!macro executor_and_deref_options
     #
     # @raise [ArgumentError] if no block is given
     def initialize(opts = {}, &block)
diff --git a/lib/concurrent/lazy_reference.rb b/lib/concurrent/lazy_reference.rb
@@ -1,23 +1,23 @@
 module Concurrent
 
   # Lazy evaluation of a block yielding an immutable result. Useful for
-  # expensive operations that may never be needed. `Lazy` is a simpler,
+  # expensive operations that may never be needed. `LazyReference` 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`:
+  # Because of its simplicity `LazyReference` is much faster than `Delay`:
   #
   #            user     system      total        real
   #     Benchmarking Delay...
   #        0.730000   0.000000   0.730000 (  0.738434)
-  #     Benchmarking Lazy...
+  #     Benchmarking LazyReference...
   #        0.040000   0.000000   0.040000 (  0.042322)
   #
   # @see Concurrent::Delay
-  class Lazy
+  class LazyReference
 
     # Creates anew unfulfilled object.
     #
diff --git a/lib/concurrent/utility/processor_count.rb b/lib/concurrent/utility/processor_count.rb
@@ -1,12 +1,12 @@
 require 'rbconfig'
-require 'concurrent/lazy'
+require 'concurrent/lazy_reference'
 
 module Concurrent
 
   class ProcessorCounter
     def initialize
-      @processor_count          = Lazy.new { compute_processor_count }
-      @physical_processor_count = Lazy.new { compute_physical_processor_count }
+      @processor_count          = LazyReference.new { compute_processor_count }
+      @physical_processor_count = LazyReference.new { compute_physical_processor_count }
     end
 
     # Number of processors seen by the OS and used for process scheduling. For
diff --git a/spec/concurrent/lazy_reference_spec.rb b/spec/concurrent/lazy_reference_spec.rb
@@ -1,12 +1,12 @@
 module Concurrent
 
-  describe Lazy do
+  describe LazyReference do
 
     context '#initialize' do
 
       it 'raises an exception when no block given' do
         expect {
-          Lazy.new
+          LazyReference.new
         }.to raise_error(ArgumentError)
       end
     end
@@ -17,25 +17,25 @@ module Concurrent
 
       it 'does not call the block before #value is called' do
         expect(task).to_not receive(:call).with(any_args)
-        Lazy.new(&task)
+        LazyReference.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
+        LazyReference.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)
+        lazy = LazyReference.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 = LazyReference.new(&task)
         lazy.value
 
         expect(mutex).to_not receive(:synchronize).with(any_args)
@@ -49,25 +49,25 @@ module Concurrent
 
         it 'suppresses the error' do
           expect {
-            Lazy.new{ raise StandardError }
+            LazyReference.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 }
+          lazy = LazyReference.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 }
+          lazy = LazyReference.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 = LazyReference.new{ raise StandardError }
           lazy.value
 
           expect(mutex).to_not receive(:synchronize).with(any_args)
