concurrent-ruby 0.0.1 → 0.1.0

data/lib/concurrent/thread_pool.rb

@@ -0,0 +1,61 @@
+require 'functional/behavior'
+require 'concurrent/event'
+
+behavior_info(:thread_pool,
+              running?: 0,
+              shutdown?: 0,
+              killed?: 0,
+              shutdown: 0,
+              kill: 0,
+              size: 0,
+              wait_for_termination: -1,
+              post: -1,
+              :<< => 1,
+              status: 0)
+
+behavior_info(:global_thread_pool,
+              post: -1,
+              :<< => 1)
+
+module Concurrent
+
+  class ThreadPool
+
+    def initialize
+      @status = :running
+      @queue = Queue.new
+      @termination = Event.new
+      @pool = []
+    end
+
+    def running?
+      return @status == :running
+    end
+
+    def shutdown?
+      return ! running?
+    end
+
+    def killed?
+      return @status == :killed
+    end
+
+    def shutdown
+      @pool.size.times{ @queue << :stop }
+      @status = :shuttingdown
+    end
+
+    def wait_for_termination(timeout = nil)
+      if shutdown? || killed?
+        return true
+      else
+        return @termination.wait(timeout)
+      end
+    end
+
+    def <<(block)
+      self.post(&block)
+      return self
+    end
+  end
+end

data/lib/concurrent/version.rb

@@ -1,3 +1,3 @@
 module Concurrent
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/lib/concurrent_ruby.rb

@@ -0,0 +1 @@
+require 'concurrent'

data/md/agent.md

@@ -0,0 +1,123 @@
+# Secret Agent Man
+
+Agents are inspired by [Clojure's](http://clojure.org/) [agent](http://clojure.org/agents) keyword.
+An agent is a single atomic value that represents an identity. The current value
+of the agent can be requested at any time (`deref`). Each agent has a work queue and operates on
+the global thread pool (see below). Consumers can `post` code blocks to the
+agent. The code block (function) will receive the current value of the agent as its sole
+parameter. The return value of the block will become the new value of the agent. Agents support
+two error handling modes: fail and continue. A good example of an agent is a shared incrementing
+counter, such as the score in a video game.
+
+An agent must be initialize with an initial value. This value is always accessible via the `value`
+(or `deref`) methods. Code blocks sent to the agent will be processed in the order received. As
+each block is processed the current value is updated with the result from the block. This update
+is an atomic operation so a `deref` will never block and will always return the current value.
+
+When an agent is created it may be given an optional `validate` block and zero or more `rescue`
+blocks. When a new value is calculated the value will be checked against the validator, if present.
+If the validator returns `true` the new value will be accepted. If it returns `false` it will be
+rejected. If a block raises an exception during execution the list of `rescue` blocks will be
+seacrhed in order until one matching the current exception is found. That `rescue` block will
+then be called an passed the exception object. If no matching `rescue` block is found, or none
+were configured, then the exception will be suppressed.
+
+Agents also implement Ruby's [Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html).
+Code that observes an agent will receive a callback with the new value any time the value
+is changed.
+
+## Examples
+
+A simple example:
+
+```ruby
+require 'concurrent'
+
+score = Concurrent::Agent.new(10)
+score.value #=> 10
+
+score << proc{|current| current + 100 }
+sleep(0.1)
+score.value #=> 110
+
+score << proc{|current| current * 2 }
+sleep(0.1)
+deref score #=> 220
+
+score << proc{|current| current - 50 }
+sleep(0.1)
+score.value #=> 170
+```
+
+With validation and error handling:
+
+```ruby
+score = agent(0).validate{|value| value <= 1024 }.
+          rescue(NoMethodError){|ex| puts "Bam!" }.
+          rescue(ArgumentError){|ex| puts "Pow!" }.
+          rescue{|ex| puts "Boom!" }
+score.value #=> 0
+
+score << proc{|current| current + 2048 }
+sleep(0.1)
+score.value #=> 0
+
+score << proc{|current| raise ArgumentError }
+sleep(0.1)
+#=> puts "Pow!"
+score.value #=> 0
+
+score << proc{|current| current + 100 }
+sleep(0.1)
+score.value #=> 100
+```
+
+With observation:
+
+```ruby
+bingo = Class.new{
+  def update(time, score)
+    puts "Bingo! [score: #{score}, time: #{time}]" if score >= 100
+  end
+}.new
+
+score = agent(0)
+score.add_observer(bingo)
+
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+
+sleep(1)
+#=> Bingo! [score: 120, time: 2013-07-22 21:26:08 -0400]
+```
+
+## 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/defer.md

@@ -0,0 +1,174 @@
+# I Can't Think of a Movie or Music Reference for Defer
+
+In the pantheon of concurrency objects a `Defer` sits somewhere between `Future` and `Promise`.
+Inspired by [EventMachine's *defer* method](https://github.com/eventmachine/eventmachine/wiki/EM::Deferrable-and-EM.defer),
+a `Defer` can be considered a non-blocking `Future` or a simplified, non-blocking `Promise`.
+
+Unlike `Future` and `Promise` a defer is non-blocking. The deferred *operation* is performed on another
+thread. If the *operation* is successful an optional *callback* is called on the same thread as the *operation*.
+The result of the *operation* is passed to the *callbacl*. If the *operation* fails (by raising an exception)
+then an optional *errorback* (error callback) is called on
+the same thread as the *operation*. The raised exception is passed to the *errorback*. The calling thread is
+never aware of the result of the *operation*. This approach fits much more cleanly within an
+[event-driven](http://en.wikipedia.org/wiki/Event-driven_programming) application.
+
+The operation of a `Defer` can easily be simulated using either `Future` or `Promise` and traditional branching
+(if/then/else) logic. This approach works but it is more verbose and partitions the work across two threads.
+Whenever you find yourself checking the result of a `Future` or a `Promise` then branching based on the result,
+consider a `Defer` instead.
+
+For programmer convenience there are two syntaxes for creating and running a `Defer`. One is idiomatic of Ruby
+and uses chained method calls. The other is more isiomatic of [functional programming](http://en.wikipedia.org/wiki/Concurrentprogramming)
+and passes one or more `proc` objects as arguments. Do not mix syntaxes on a single `Defer` invocation.
+
+## Examples
+
+A simple `Defer` using idiomatic Ruby syntax:
+
+```ruby
+require 'concurrent'
+
+deferred = Concurrent::Defer.new{ puts 'w00t!' }
+# when using idiomatic syntax the #go method must be called
+deferred.go
+sleep(0.1)
+
+#=> 'w00t!'
+```
+
+A simple `Defer` using functional programming syntax:
+
+```ruby
+operation = proc{ puts 'w00t!' }
+Concurrent::Defer.new(operation) # NOTE: a call to #go is unnecessary
+sleep(0.1)
+
+#=> 'w00t!'
+
+defer(operation)
+sleep(0.1)
+
+#=> 'w00t!'
+```
+
+Adding a *callback*:
+
+```ruby
+Concurrent::Defer.new{ "Jerry D'Antonio" }.
+                  then{|result| puts "Hello, #{result}!" }.
+                  go
+
+#=> Hello, Jerry D'Antonio!
+
+operation = proc{ "Jerry D'Antonio" }
+callback = proc{|result| puts "Hello, #{result}!" }
+defer(operation, callback, nil)
+sleep(0.1)
+
+#=> Hello, Jerry D'Antonio!
+```
+
+Adding an *errorback*:
+
+```ruby
+Concurrent::Defer.new{ raise StandardError.new('Boom!') }.
+                  rescue{|ex| puts ex.message }.
+                  go
+sleep(0.1)
+
+#=> "Boom!"
+
+operation = proc{ raise StandardError.new('Boom!') }
+errorback = proc{|ex| puts ex.message }
+defer(operation, nil, errorback)
+
+#=> "Boom!"
+```
+
+Putting it all together:
+
+```ruby
+Concurrent::Defer.new{ "Jerry D'Antonio" }.
+                  then{|result| puts "Hello, #{result}!" }.
+                  rescue{|ex| puts ex.message }.
+                  go
+
+#=> Hello, Jerry D'Antonio!
+
+operation = proc{ raise StandardError.new('Boom!') }
+callback  = proc{|result| puts result }
+errorback = proc{|ex| puts ex.message }
+defer(operation, callback, errorback)
+sleep(0.1)
+
+#=> "Boom!"
+```
+
+Crossing the streams:
+
+```ruby
+operation = proc{ true }
+callback = proc{|result| puts result }
+errorback = proc{|ex| puts ex.message }
+
+Concurrent::Defer.new(operation, nil, nil){ false }
+#=> ArgumentError: two operations given
+
+defer(nil, callback, errorback)
+# => ArgumentError: no operation given
+
+Concurrent::Defer.new.go
+# => ArgumentError: no operation given
+
+defer(nil, nil, nil)
+# => ArgumentError: no operation given
+
+Concurrent::Defer.new(operation, nil, nil).
+                  then{|result| puts result }.
+                  go
+#=> Concurrent::IllegalMethodCallError: the defer is already running
+
+defer(callback, nil, nil).then{|result| puts result }
+#=> Concurrent::IllegalMethodCallError: the defer is already running
+
+Concurrent::Defer.new{ true }.
+                  then{|result| puts "Boom!" }.
+                  then{|result| puts "Bam!" }.
+                  go
+#=> Concurrent::IllegalMethodCallError: a callback has already been provided
+
+Concurrent::Defer.new{ raise StandardError }.
+                  rescue{|ex| puts "Boom!" }.
+                  rescue{|ex| puts "Bam!" }.
+                  go
+#=> Concurrent::IllegalMethodCallError: a errorback has already been provided
+```
+
+## Copyright
+
+*Concurrent Ruby* is Copyright © 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/event.md

@@ -0,0 +1,32 @@
+# Event
+
+TBD...
+
+## Copyright
+
+*Concurrent Ruby* is Copyright © 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/future.md

@@ -0,0 +1,83 @@
+# We're Sending You Back to the Future!
+
+Futures are inspired by [Clojure's](http://clojure.org/) [future](http://clojuredocs.org/clojure_core/clojure.core/future) keyword.
+A future represents a promise to complete an action at some time in the future. The action is atomic and permanent.
+The idea behind a future is to send an action off for asynchronous operation, do other stuff, then return and
+retrieve the result of the async operation at a later time. Futures run on the global thread pool (see below).
+
+Futures have three possible states: *pending*, *rejected*, and *fulfilled*. When a future is created it is set
+to *pending* and will remain in that state until processing is complete. A completed future is either *rejected*,
+indicating that an exception was thrown during processing, or *fulfilled*, indicating succedd. If a future is
+*fulfilled* its `value` will be updated to reflect the result of the operation. If *rejected* the `reason` will
+be updated with a reference to the thrown exception. The predicate methods `pending?`, `rejected`, and `fulfilled?`
+can be called at any time to obtain the state of the future, as can the `state` method, which returns a symbol.
+
+Retrieving the value of a future is done through the `value` (alias: `deref`) method. Obtaining the value of
+a future is a potentially blocking operation. When a future is *rejected* a call to `value` will return `nil`
+immediately. When a future is *fulfilled* a call to `value` will immediately return the current value.
+When a future is *pending* a call to `value` will block until the future is either *rejected* or *fulfilled*.
+A *timeout* value can be passed to `value` to limit how long the call will block. If `nil` the call will
+block indefinitely. If `0` the call will not block. Any other integer or float value will indicate the
+maximum number of seconds to block.
+
+## Examples
+
+A fulfilled example:
+
+```ruby
+require 'concurrent'
+
+count = Concurrent::Future{ sleep(10); 10 }
+count.state #=> :pending
+count.pending? #=> true
+
+# do stuff...
+
+count.value(0) #=> nil (does not block)
+
+count.value #=> 10 (after blocking)
+count.state #=> :fulfilled
+count.fulfilled? #=> true
+deref count #=> 10
+```
+
+A rejected example:
+
+```ruby
+count = future{ sleep(10); raise StandardError.new("Boom!") }
+count.state #=> :pending
+pending?(count) #=> true
+
+deref(count) #=> nil (after blocking)
+rejected?(count) #=> true
+count.reason #=> #<StandardError: Boom!> 
+```
+
+## 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.