concurrent-ruby 0.4.1 → 0.5.0.pre.1

data/md/scheduled_task.md

@@ -1,156 +0,0 @@
-# I'm late! For a very important date!
-
-`ScheduledTask` is a close relative of `Concurrent::Future` but with one
-important difference. A `Future` is set to execute as soon as possible
-whereas a `ScheduledTask` is set to execute at a specific time. This implementation
-is loosely based on Java's
-[ScheduledExecutorService](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ScheduledExecutorService.html).
-
-## Scheduling
-
-The scheduled time of task execution is set on object construction. The first
-parameter to `#new` is the task execution time. The time can be a numeric (floating
-point or integer) representing a number of seconds in the future or it can ba a
-`Time` object representing the approximate time of execution. Any other value,
-a numeric equal to or less than zero, or a time in the past will result in
-an `ArgumentError` being raised.
-
-The constructor can also be given zero or more processing options. Currently the
-only supported options are those recognized by the
-[Dereferenceable](https://github.com/jdantonio/concurrent-ruby/blob/master/md/dereferenceable.md)
-module.
-
-The final constructor argument is a block representing the task to be performed
-at the scheduled time. If no block is given an `ArgumentError` will be raised.
-
-### States
-
-`ScheduledTask` mixes in the 
-[Obligation](https://github.com/jdantonio/concurrent-ruby/blob/master/md/obligation.md)
-module thus giving it "future" behavior. This includes the expected lifecycle states.
-`ScheduledTask` has one additional state, however. While the task (block) is being
-executed the state of the object will be `:in_progress`. This additional state is 
-necessary because it has implications for task cancellation.
-
-### Cancellation
-
-A `:pending` task can be cancelled using the `#cancel` method. A task in any other
-state, including `:in_progress`, cannot be cancelled. The `#cancel` method returns
-a boolean indicating the success of the cancellation attempt. A cancelled `ScheduledTask`
-cannot be restarted. It is immutable.
-
-## Obligation and Observation
-
-The result of a `ScheduledTask` can be obtained either synchronously or asynchronously.
-`ScheduledTask` mixes in both the
-[Obligation](https://github.com/jdantonio/concurrent-ruby/blob/master/md/obligation.md)
-module and the
-[Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html)
-module from the Ruby standard library. With one exception `ScheduledTask` behaves
-identically to
-[Concurrent::Future](https://github.com/jdantonio/concurrent-ruby/blob/master/md/future.md)
-with regard to these modules.
-
-Unlike `Future`, however, an observer added to a `ScheduledTask` *after* the task
-operation has completed will *not* receive notification. The reason for this is the
-subtle but important difference in intent between the two abstractions. With a
-`Future` there is no way to know when the operation will complete. Therefore the
-*expected* behavior of an observer is to be notified. With a `ScheduledTask` however,
-the approximate time of execution is known. It is often explicitly set as a constructor
-argument. It is always available via the `#schedule_time` attribute reader. Therefore
-it is always possible for calling code to know whether the observer is being added
-prior to task execution. It is also easy to add an observer long before task
-execution begins (since there is never a reason to create a scheduled task that starts
-immediately). Subsequently, the *expectation* is that the caller of `#add_observer`
-is making the call within an appropriate time.
-
-## Examples
-
-Successful task execution using seconds for scheduling:
-
-```ruby
-require 'concurrent'
-
-task = Concurrent::ScheduledTask.new(2){ 'What does the fox say?' }
-task.pending?      #=> true
-task.schedule_time #=> 2013-11-07 12:20:07 -0500
-
-# wait for it...
-sleep(3)
-
-task.pending?   #=> false
-task.fulfilled? #=> true
-task.rejected?  #=> false
-task.value      #=> 'What does the fox say?'
-```
-
-Failed task execution using a `Time` object for scheduling:
-
-```ruby
-require 'concurrent'
-
-t = Time.now + 2
-task = Concurrent::ScheduledTask.new(t){ raise StandardError.new('Call me maybe?') }
-task.pending?      #=> true
-task.schedule_time #=> 2013-11-07 12:22:01 -0500
-
-# wait for it...
-sleep(3)
-
-task.pending?   #=> false
-task.fulfilled? #=> false
-task.rejected?  #=> true
-task.value      #=> nil
-task.reason     #=> #<StandardError: Call me maybe?> 
-```
-
-Task execution with observation:
-
-```ruby
-require 'concurrent'
-
-observer = Class.new{
-  def update(time, value, reason)
-    puts "The task completed at #{time} with value '#{value}'"
-  end
-}.new
-
-task = Concurrent::ScheduledTask.new(2){ 'What does the fox say?' }
-task.add_observer(observer)
-task.pending?      #=> true
-task.schedule_time #=> 2013-11-07 12:20:07 -0500
-
-# wait for it...
-sleep(3)
-
-#>> The task completed at 2013-11-07 12:26:09 -0500 with value 'What does the fox say?'
-```
-
-## Copyright
-
-*Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
-It is free software and may be redistributed under the terms specified in the LICENSE file.
-
-## License
-
-Released under the MIT license.
-
-http://www.opensource.org/licenses/mit-license.php  
-
-> Permission is hereby granted, free of charge, to any person obtaining a copy  
-> of this software and associated documentation files (the "Software"), to deal  
-> in the Software without restriction, including without limitation the rights  
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
-> copies of the Software, and to permit persons to whom the Software is  
-> furnished to do so, subject to the following conditions:  
-> 
-> The above copyright notice and this permission notice shall be included in  
-> all copies or substantial portions of the Software.  
-> 
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
-> THE SOFTWARE.  

data/md/supervisor.md

@@ -1,246 +0,0 @@
-# You don't need to get no supervisor! You the supervisor today!
-
-One of Erlang's claim to fame is its fault tolerance. Erlang systems have been known
-to exhibit near-mythical levels of uptime. One of the main reasons is the pervaisve
-design philosophy of "let it fail." When errors occur most Erlang systems simply let
-the failing component fail completely. The system then restarts the failed component.
-This "let it fail" resilience isn't an intrinsic capability of either the language
-or the virtual machine. It's a deliberate design philosophy. One of the key enablers
-of this philosophy is the [Supervisor](http://www.erlang.org/doc/man/supervisor.html)
-of the OTP (standard library).
-
-The Supervisor module answers the question "Who watches the watchmen?" A single
-Supervisor can manage any number of workers (children). The Supervisor assumes
-responsibility for starting the children, stopping them, and restarting them if
-they fail. Several classes in this library, including `Actor` and `TimerTask` are
-designed to work with `Supervisor`. Additionally, `Supervisor`s can supervise others
-`Supervisor`s (see *Supervision Trees* below).
-
-The `Concurrent::Supervisor` class is a faithful and nearly complete implementaion
-of Erlang's Supervisor module. 
-
-## Basic Supervisor Behavior
-
-At the core a `Supervisor` instance is a very simple object. Simply create a `Supervisor`,
-add at least one worker using the `#add_worker` method, and start the `Supervisor` using
-either `#run` (blocking) or `#run!` (non-blocking). The `Supervisor` will spawn a new thread
-for each child and start the chid on its thread. The `Supervisor` will then continuously
-monitor all its child threads. If any of the children crash the `Supervisor` will restart
-them in accordance with its *restart strategy* (see below). Later, stop the `Supervisor`
-with its `#stop` method and it will gracefully stop all its children.
-
-A `Supervisor` will also track the number of times it must restart children withing a
-defined, sliding window of time. If the onfigured threshholds are exceeded (see *Intervals*
-below) then the `Supervisor` will assume there is a catastrophic failure (possibly within
-the `Supervisor` itself) and it will shut itself down. If the `Supervisor` is part of a
-*supervision tree* (see below) then its `Supervisor` will likely restart it.
-
-```ruby
-task = Concurrent::TimerTask.new{ print "[#{Time.now}] Hello world!\n" }
-
-supervisor = Concurrent::Supervisor.new
-supervisor.add_worker(task)
-
-supervisor.run! # the #run method blocks, #run! does not
-```
-
-## Workers
-
-Any object can be managed by a `Supervisor` so long as the class to be supervised supports
-the required API. A supervised object needs only support three methods:
-
-* `#run` is a blocking call that starts the child then blocks until the child is stopped
-* `#running?` is a predicate method indicating whether or not the child is running
-* `#stop` gracefully stops the child if it is running
-
-### Runnable
-
-To facilitate the creation of supervisorable classes, the `Runnable` module is provided.
-Simple include `Runnable` in the class and the required API methods will be provided.
-`Runnable` also provides several lifecycle methods that may be overridden by the including
-class. At a minimum the `#on_task` method *must* be overridden. `Runnable` will provide an
-infinite loop that will start when either the `#run` or `#run!` method is called. The subclass
-`#on_task` method will be called once in every iteration. The overridden method should provide
-some sort of blocking behavior otherwise the run loop may monopolize the processor and spike
-the processor utilization.
-
-The following optional lifecycle methods are also provided:
-
-* `#on_run` is called once when the object is started via the `#run` or `#run!` method but before the `#on_task` method is first called
-* `#on_stop` is called once when the `#stop` method is called, after the last call to `#on_task`
-
-```ruby
-class Echo
-  include Concurrent::Runnable
-
-  def initialize
-    @queue = Queue.new
-  end
-
-  def post(message)
-    @queue.push(message)
-  end
-
-  protected
-
-  def on_task
-    message = @queue.pop
-    print "#{message}\n"
-  end
-end
-
-echo = Echo.new
-supervisor = Concurrent::Supervisor.new
-supervisor.add_worker(echo)
-supervisor.run!
-```
-
-##  Supervisor Configuration
-
-A newly-created `Supervisor` will be configured with a reasonable set of options that should
-suffice for most purposes. In many cases no additional configuration will be required. When
-more granular control is required a `Supervisor` may be given several configuration options
-during initialization. Additionally, a few per-worker configuration options may be passed
-during the call to `#add_worker`. Once a `Supervisor` is created and the workers are added
-no additional configuration is possible.
-
-### Intervals
-
-A `Supervisor` monitors its children and conducts triage operations based on several configurable
-intervals:
-
-* `:monitor_interval` specifies the number of seconds between health checks of the workers. The
-  higher the interval the longer a particular worker may be dead before being restarted. The
-  default is 1 second.
-* `:max_restart` specifies the number of times (in total) the `Supevisor` may restart children
-  before it assumes there is a catastrophic failure and it shuts itself down. The default is 5
-  restarts.
-* `:max_time` if the time interval over which `#max_restart` is tracked. Since `Supervisor` is
-  intended to be used in applications that may run forever the `#max_restart` count must be
-  timeboxed to prevent erroneous `Supervisor shutdown`. The default is 60 seconds.
-
-### Restart Strategy
-
-When a child thread dies the `Supervisor` will restart it, and possibly other children,
-with the expectation that the workers are capable of cleaning themselves up and running
-again. The `Supervisor` will call each targetted worker's `#stop` method, kill the
-worker's thread, spawn a new thread, and call the worker's `#run` method.
-
-* `:one_for_one` When this restart strategy is set the `Supervisor` will only restart
-  the worker thread that has died. It will not restart any of the other children.
-  This is the default restart strategy.
-* `:one_for_all` When this restart strategy is set the `Supervisor` will restart all
-  children when any one child dies. All workers will be stopped in the order they were
-  originally added to the `Supervisor`. Once all childrean have been stopped they will
-  all be started again in the same order.
-* `:rest_for_one` This restart strategy assumes that the order the workers were added
-  to the `Supervisor` is meaningful. When one child dies all the downstream children
-  (children added to the `Supervisor` after the dead worker) will be restarted. The
-  `Supervisor` will begin by calling the `#stop` method on the dead worker and all
-  downstream workers. The `Supervisor` will then iterate over all dead workers and
-  restart each by creating a new thread then calling the worker's `#run` method.
-
-When a restart is initiated under any strategy other than `:one_for_one` the
-`:max_restart` value will only be incremented by one, regardless of how many children
-are restarted.
-
-### Worker Restart Option
-
-When a worker dies the default behavior of the `Supervisor` is to restart one or more
-workers according to the restart strategy defined when the `Supervisor` is created
-(see above). This behavior can be modified on a per-worker basis using the `:restart`
-option when calling `#add_worker`. Three worker `:restart` options are supported:
-
-* `:permanent` means the worker is intended to run forever and will always be restarted
-  (this is the default)
-* `:temporary` workers are expected to stop on their own as a normal part of their operation
-  and will only be restarted on an abnormal exit
-* `:transient` workers will never be restarted
-
-### Worker Type
-
-Every worker added to a `Supervisor` is of either type `:worker` or `:supervisor`. The defauly
-value is `:worker`. Currently this type makes no functional difference. It is purely informational.
-
-## Supervision Trees
-
-One of the most powerful aspects of Erlang's supervisor module is its ability to supervise
-other supervisors. This allows for the creation of deep, robust *supervision trees*.
-Workers can be gouped under multiple bottom-level `Supervisor`s. Each of these `Supervisor`s
-can be configured according to the needs of its workers. These multiple `Supervisor`s can
-be added as children to another `Supervisor`. The root `Supervisor` can then start the
-entire tree via trickel-down (start its children which start their children and so on).
-The root `Supervisor` then monitor its child `Supervisor`s, and so on.
-
-Supervision trees are the main reason that a `Supervisor` will shut itself down if its
-`:max_restart`/`:max_time` threshhold is exceeded. An isolated `Supervisor` will simply
-shut down forever. A `Supervisor` that is part of a supervision tree will shut itself
-down and let its parent `Supervisor` manage the restart.
-
-## Examples
-
-```ruby
-QUERIES = %w[YAHOO Microsoft google]
-
-class FinanceActor < Concurrent::Actor
-  def act(query)
-    finance = Finance.new(query)
-    print "[#{Time.now}] RECEIVED '#{query}' to #{self} returned #{finance.update.suggested_symbols}\n\n"
-  end
-end
-
-financial, pool = FinanceActor.pool(5)
-
-timer_proc = proc do
-  query = QUERIES[rand(QUERIES.length)]
-  financial.post(query)
-  print "[#{Time.now}] SENT '#{query}' from #{self} to worker pool\n\n"
-end
-
-t1 = Concurrent::TimerTask.new(execution_interval: rand(5)+1, &timer_proc)
-t2 = Concurrent::TimerTask.new(execution_interval: rand(5)+1, &timer_proc)
-
-overlord = Concurrent::Supervisor.new
-
-overlord.add_worker(t1)
-overlord.add_worker(t2)
-pool.each{|actor| overlord.add_worker(actor)}
-
-overlord.run!
-```
-
-## Additional Reading
-
-* [Supervisor Module](http://www.erlang.org/doc/man/supervisor.html)
-* [Supervisor Behaviour](http://www.erlang.org/doc/design_principles/sup_princ.html)
-* [Who Supervises The Supervisors?](http://learnyousomeerlang.com/supervisors)
-* [OTP Design Principles](http://www.erlang.org/doc/design_principles/des_princ.html)
-
-## Copyright
-
-*Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
-It is free software and may be redistributed under the terms specified in the LICENSE file.
-
-## License
-
-Released under the MIT license.
-
-http://www.opensource.org/licenses/mit-license.php  
-
-> Permission is hereby granted, free of charge, to any person obtaining a copy  
-> of this software and associated documentation files (the "Software"), to deal  
-> in the Software without restriction, including without limitation the rights  
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
-> copies of the Software, and to permit persons to whom the Software is  
-> furnished to do so, subject to the following conditions:  
-> 
-> The above copyright notice and this permission notice shall be included in  
-> all copies or substantial portions of the Software.  
-> 
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
-> THE SOFTWARE.  

data/md/thread_pool.md

@@ -1,225 +0,0 @@
-# We're Going to Need a Bigger Boat
-
-Thread pools are neither a new idea nor an implementation of the actor pattern. Nevertheless, thread
-pools are still an extremely relevant concurrency tool. Every time a thread is created then
-subsequently destroyed there is overhead. Creating a pool of reusable worker threads then repeatedly'
-dipping into the pool can have huge performace benefits for a long-running application like a service.
-Ruby's blocks provide an excellent mechanism for passing a generic work request to a thread, making
-Ruby an excellent candidate language for thread pools.
-
-The inspiration for thread pools in this library is Java's `java.util.concurrent` implementation of
-[thread pools](java.util.concurrent). The `java.util.concurrent` library is a well-designed, stable,
-scalable, and battle-tested concurrency library. It provides three different implementations of thread
-pools. One of those implementations is simply a special case of the first and doesn't offer much
-advantage in Ruby, so only the first two (`FixedThreadPool` and `CachedThreadPool`) are implemented here.
-
-Thread pools share common `behavior` defined by `:thread_pool`. The most imortant method is `post`
-(aliased with the left-shift operator `<<`). The `post` method sends a block to the pool for future
-processing.
-
-A running thread pool can be shutdown in an orderly or disruptive manner. Once a thread pool has been
-shutdown in cannot be started again. The `shutdown` method can be used to initiate an orderly shutdown
-of the thread pool. All new `post` calls will reject the given block and immediately return `false`.
-Threads in the pool will continue to process all in-progress work and will process all tasks still in
-the queue. The `kill` method can be used to immediately shutdown the pool. All new `post` calls will
-reject the given block and immediately return `false`. Ruby's `Thread.kill` will be called on all threads
-in the pool, aborting all in-progress work. Tasks in the queue will be discarded.
-
-A client thread can choose to block and wait for pool shutdown to complete. This is useful when shutting
-down an application and ensuring the app doesn't exit before pool processing is complete. The method
-`wait_for_termination` will block for a maximum of the given number of seconds then return `true` if
-shutdown completed successfully or `false`. When the timeout value is `nil` the call will block
-indefinitely. Calling `wait_for_termination` on a stopped thread pool will immediately return `true`.
-
-Predicate methods are provided to describe the current state of the thread pool. Provided methods are
-`running?`, `shutdown?`, and `killed?`. The `shutdown` method will return true regardless of whether
-the pool was shutdown wil `shutdown` or `kill`.
-
-## FixedThreadPool
-
-From the docs:
-
-> Creates a thread pool that reuses a fixed number of threads operating off a shared unbounded queue.
-> At any point, at most `nThreads` threads will be active processing tasks. If additional tasks are submitted
-> when all threads are active, they will wait in the queue until a thread is available. If any thread terminates
-> due to a failure during execution prior to shutdown, a new one will take its place if needed to execute
-> subsequent tasks. The threads in the pool will exist until it is explicitly `shutdown`.
-
-### Examples
-
-```ruby
-require 'concurrent'
-
-pool = Concurrent::FixedThreadPool.new(5)
-
-pool.size     #=> 5
-pool.running? #=> true
-pool.status   #=> ["sleep", "sleep", "sleep", "sleep", "sleep"]
-
-pool.post(1,2,3){|*args| sleep(10) }
-pool << proc{ sleep(10) }
-pool.size     #=> 5
-
-sleep(11)
-pool.status   #=> ["sleep", "sleep", "sleep", "sleep", "sleep"]
-
-pool.shutdown #=> :shuttingdown
-pool.status   #=> []
-pool.wait_for_termination
-
-pool.size      #=> 0
-pool.status    #=> []
-pool.shutdown? #=> true
-```
-
-## CachedThreadPool
-
-From the docs:
-
-> Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when
-> they are available. These pools will typically improve the performance of programs that execute many short-lived
-> asynchronous tasks. Calls to [`post`] will reuse previously constructed threads if available. If no existing
-> thread is available, a new thread will be created and added to the pool. Threads that have not been used for
-> sixty seconds are terminated and removed from the cache. Thus, a pool that remains idle for long enough will
-> not consume any resources. Note that pools with similar properties but different details (for example,
-> timeout parameters) may be created using [`CachedThreadPool`] constructors.
-
-### Examples
-
-```ruby
-require 'concurrent'
-
-pool = Concurrent::CachedThreadPool.new
-
-pool.size     #=> 0
-pool.running? #=> true
-pool.status   #=> []
-
-pool.post(1,2,3){|*args| sleep(10) }
-pool << proc{ sleep(10) }
-pool.size     #=> 2
-pool.status   #=> [[:working, nil, "sleep"], [:working, nil, "sleep"]]
-
-sleep(11)
-pool.status   #=> [[:idle, 23, "sleep"], [:idle, 23, "sleep"]]
-
-sleep(60)
-pool.size     #=> 0
-pool.status   #=> []
-
-pool.shutdown #=> :shuttingdown
-pool.status   #=> []
-pool.wait_for_termination
-
-pool.size      #=> 0
-pool.status    #=> []
-pool.shutdown? #=> true
-```
-
-## Global Thread Pool
-
-For efficiency, of the aforementioned concurrency methods (agents, futures, promises, and
-goroutines) run against a global thread pool. This pool can be directly accessed through the
-`$GLOBAL_THREAD_POOL` global variable. Generally, this pool should not be directly accessed.
-Use the other concurrency features instead.
-
-By default the global thread pool is a `NullThreadPool`. This isn't a real thread pool at all.
-It's simply a proxy for creating new threads on every post to the pool. I couldn't decide which
-of the other threads pools and what configuration would be the most universally appropriate so
-I punted. If you understand thread pools then you know enough to make your own choice. That's
-why the global thread pool can be changed.
-
-### Changing the Global Thread Pool
-
-It is possible to change the global thread pool. Simply assign a new pool to the `$GLOBAL_THREAD_POOL`
-variable:
-
-```ruby
-$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
-```
-
-Ideally this should be done at application startup, before any concurrency functions are called.
-If the circumstances warrant the global thread pool can be changed at runtime. Just make sure to
-shutdown the old global thread pool so that no tasks are lost:
-
-```ruby
-$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
-
-# do stuff...
-
-old_global_pool = $GLOBAL_THREAD_POOL
-$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
-old_global_pool.shutdown
-```
-
-### NullThreadPool
-
-If for some reason an appliction would be better served by *not* having a global thread pool, the
-`NullThreadPool` is provided. The `NullThreadPool` is compatible with the global thread pool but
-it is not an actual thread pool. Instead it spawns a new thread on every call to the `post` method.
-
-### EventMachine
-
-The [EventMachine](http://rubyeventmachine.com/) library (source [online](https://github.com/eventmachine/eventmachine))
-is an awesome library for creating evented applications. EventMachine provides its own thread pool
-and the authors recommend using their pool rather than using Ruby's `Thread`. No sweat,
-`concurrent-ruby` is fully compatible with EventMachine. Simple require `eventmachine`
-*before* requiring `concurrent-ruby` then replace the global thread pool with an instance
-of `EventMachineDeferProxy`:
-
-```ruby
-require 'eventmachine' # do this FIRST
-require 'concurrent'
-
-$GLOBAL_THREAD_POOL = EventMachineDeferProxy.new
-```
-
-## Per-class Thread Pools
-
-Many of the classes in this library use the global thread pool rather than creating new threads.
-Classes such as `Agent`, `Defer`, and others follow this pattern. There may be cases where a
-program would be better suited for one or more of these classes used a different thread pool.
-All classes that use the global thread pool support a class-level `thread_pool` attribute accessor.
-This property defaults to the global thread pool but can be changed at any time. Once changed, all
-new instances of that class will use the new thread pool.
-
-```ruby
-Concurrent::Agent.thread_pool == $GLOBAL_THREAD_POOL #=> true
-
-$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10) #=> #<Concurrent::FixedThreadPool:0x007fe31130f1f0 ...
-
-Concurrent::Agent.thread_pool == $GLOBAL_THREAD_POOL #=> false
-
-Concurrent::Defer.thread_pool = Concurrent::CachedThreadPool.new #=> #<Concurrent::CachedThreadPool:0x007fef1c6b6b48 ...
-Concurrent::Defer.thread_pool == Concurrent::Agent.thread_pool #=> false
-Concurrent::Defer.thread_pool == $GLOBAL_THREAD_POOL #=> false
-```
-
-## Copyright
-
-*Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
-It is free software and may be redistributed under the terms specified in the LICENSE file.
-
-## License
-
-Released under the MIT license.
-
-http://www.opensource.org/licenses/mit-license.php  
-
-> Permission is hereby granted, free of charge, to any person obtaining a copy  
-> of this software and associated documentation files (the "Software"), to deal  
-> in the Software without restriction, including without limitation the rights  
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
-> copies of the Software, and to permit persons to whom the Software is  
-> furnished to do so, subject to the following conditions:  
-> 
-> The above copyright notice and this permission notice shall be included in  
-> all copies or substantial portions of the Software.  
-> 
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  
-> THE SOFTWARE.