concurrent-ruby 0.3.0 → 0.3.1.pre.1

data/lib/concurrent/obligation.rb

@@ -1,11 +1,13 @@
 require 'thread'
 require 'timeout'
 
+require 'concurrent/dereferenceable'
 require 'concurrent/event'
 
 module Concurrent
 
   module Obligation
+    include Dereferenceable
 
     attr_reader :state
     attr_reader :reason
@@ -15,7 +17,7 @@ module Concurrent
     def fulfilled?() return(@state == :fulfilled); end
     alias_method :realized?, :fulfilled?
 
-    # Has the promise been rejected?
+    # Has the obligation been rejected?
     # @return [Boolean]
     def rejected?() return(@state == :rejected); end
 
@@ -25,9 +27,8 @@ module Concurrent
 
     def value(timeout = nil)
       event.wait(timeout) unless timeout == 0 || @state != :pending
-      return @value
+      super()
     end
-    alias_method :deref, :value
 
     protected
 

data/lib/concurrent/promise.rb

@@ -115,13 +115,13 @@ module Concurrent
     end
 
     # @private
-    def on_fulfill(value) # :nodoc:
+    def on_fulfill(result) # :nodoc:
       @lock.synchronize do
-        @value = @handler.call(value)
+        @value = @handler.call(result)
         @state = :fulfilled
         @reason = nil
       end
-      return @value
+      return self.value
     end
 
     # @private

data/lib/concurrent/scheduled_task.rb

@@ -0,0 +1,94 @@
+require 'observer'
+
+require 'concurrent/obligation'
+require 'concurrent/runnable'
+
+module Concurrent
+
+  class ScheduledTask
+    include Obligation
+    include Observable
+    include Runnable
+
+    attr_reader :schedule_time
+
+    def initialize(schedule_time, opts = {}, &block)
+      now = Time.now
+
+      if ! block_given?
+        raise ArgumentError.new('no block given')
+      elsif schedule_time.is_a?(Time)
+        if schedule_time <= now
+          raise ArgumentError.new('schedule time must be in the future') 
+        else
+          @schedule_time = schedule_time.dup
+        end
+      elsif schedule_time.to_f <= 0.0
+        raise ArgumentError.new('seconds must be greater than zero')
+      else
+        @schedule_time = now + schedule_time.to_f
+      end
+
+      @state = :pending
+      @task = block
+      @schedule_time.freeze
+      set_deref_options(opts)
+    end
+
+    def cancelled?
+      return @state == :cancelled
+    end
+
+    def in_progress?
+      return @state == :in_progress
+    end
+
+    def cancel
+      return false if mutex.locked?
+      return mutex.synchronize do
+        if @state == :pending
+          @state = :cancelled
+          event.set
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def add_observer(observer, func = :update)
+      return false unless @state == :pending || @state == :in_progress
+      super
+    end
+
+    protected
+
+    def on_task
+      while (diff = @schedule_time.to_f - Time.now.to_f) > 0
+        sleep( diff > 60 ? 60 : diff )
+      end
+      
+      if @state == :pending
+        mutex.synchronize do
+          @state = :in_progress
+          begin
+            @value = @task.call
+            @state = :fulfilled
+          rescue => ex
+            @reason = ex
+            @state = :rejected
+          ensure
+            changed
+          end
+        end
+      end
+
+      if self.changed?
+        notify_observers(Time.now, self.value, @reason)
+        delete_observers
+      end
+      event.set
+      self.stop
+    end
+  end
+end

data/lib/concurrent/version.rb

@@ -1,3 +1,3 @@
 module Concurrent
-  VERSION = '0.3.0'
+  VERSION = '0.3.1.pre.1'
 end

data/md/actor.md

@@ -0,0 +1,209 @@
+# All the world's a stage
+
+Actor-based concurrency is all the rage in some circles. Originally described in
+1973, the actor model is a paradigm for creating asynchronous, concurrent objects
+that is becoming increasingly popular. Much has changed since actors were first
+written about four decades ago, which has led to a serious fragmentation within
+the actor community. There is *no* universally accepted, strict definition of
+"actor" and actor implementations differ widely between languages and libraries.
+
+A good definition of "actor" is:
+
+> An independent, concurrent, single-purpose, computational entity that
+> communicates exclusively via message passing.
+
+The `Concurrent::Actor` class in this library is based solely on the
+[Actor](http://www.scala-lang.org/api/current/index.html#scala.actors.Actor) task
+defined in the Scala standard library. It does not implement all the features of
+Scala's `Actor` but its behavior for what *has* been implemented is nearly identical
+
+## Definition
+
+Actors are defined by subclassing the `Concurrent::Actor` class and overriding the
+`#act` method. The `#act` method can have any signature/arity but
+
+> def act(*args, &block)
+
+is the most flexible and least error-prone signature. The `#act` method is called in
+response to a message being `#post` to the `Actor` instance (see *Behavior* below).
+
+## Behavior
+
+The `Concurrent::Actor` class includes the `Concurrent::Runnable` module. This provides
+an `Actor` instance with the necessary methods for running and graceful stopping.
+This also means that an `Actor` can be managed by a `Concurrent::Supervisor` for
+fault tolerance.
+
+Messages from any thread can be sent to an `Actor` using either the `#post` method. Calling
+this method causes all arguments and a block (if given) to be passed to the subclass `#act`
+method. Messages are processed one at a time in the order received. Each `Actor` subclass
+must detemine how it will interact with the rest of the system. A common practice is for
+one `Actor` to send messages to another `Actor` though this is hardly the only approach.
+
+## Pools
+
+Every `Actor` instance operates on its own thread. When one thread isn't enough capacity
+to manage all the messages being sent to an `Actor` a *pool* can be used instead. A pool
+is a collection of `Actor` instances, all of the same type, that shate a message queue.
+Messages from other threads are all sent to a single queue against which all `Actor`s
+load balance.
+
+## Additional Reading
+
+* [API documentation](http://www.scala-lang.org/api/current/index.html#scala.actors.Actor)
+  for the original (now deprecated) Scala Actor
+* [Scala Actors: A Short Tutorial](http://www.scala-lang.org/old/node/242)
+* [Scala Actors 101](http://java.dzone.com/articles/scala-threadless-concurrent)
+
+## Examples
+
+Two `Actor`s playing a back and forth game of Ping Pong, adapted from the Scala example
+[here](http://www.somewhere.com/find/the/blog/post):
+
+```ruby
+class Ping < Concurrent::Actor
+
+  def initialize(count, pong)
+    super()
+    @pong = pong
+    @remaining = count
+  end
+  
+  def act(msg)
+
+    if msg == :pong
+      print "Ping: pong\n" if @remaining % 1000 == 0
+      @pong.post(:ping)
+
+      if @remaining > 0
+        @pong << :ping
+        @remaining -= 1
+      else
+        print "Ping :stop\n"
+        @pong << :stop
+        self.stop
+      end
+    end
+  end
+end
+
+class Pong < Concurrent::Actor
+
+  attr_writer :ping
+
+  def initialize
+    super()
+    @count = 0
+  end
+
+  def act(msg)
+
+    if msg == :ping
+      print "Pong: ping\n" if @count % 1000 == 0
+      @ping << :pong
+      @count += 1
+
+    elsif msg == :stop
+      print "Pong :stop\n"
+      self.stop
+    end
+  end
+end
+
+pong = Pong.new
+ping = Ping.new(10000, pong)
+pong.ping = ping
+
+t1 = ping.run!
+t2 = pong.run!
+sleep(0.1)
+
+ping << :pong
+```
+
+A pool of `Actor`s and a `Supervisor`
+
+```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)
+
+overlord = Concurrent::Supervisor.new
+pool.each{|actor| overlord.add_worker(actor)}
+
+overlord.run! 
+
+pool.post('YAHOO')
+
+#>> [2013-10-18 09:35:28 -0400] SENT 'YAHOO' from main to worker pool
+#>> [2013-10-18 09:35:28 -0400] RECEIVED 'YAHOO' to #<FinanceActor:0x0000010331af70>...
+```
+
+The `#post!` method returns an `Obligation` (same API as `Future`) which can be queried
+for value/reason on fulfillment/rejection.
+
+```ruby
+class EverythingActor < Concurrent::Actor
+  def act(message)
+    sleep(1)
+    return 42
+  end
+end
+
+life = EverythingActor.new
+life.run!
+universe = life.post!('What do you get when you multiply six by nine?')
+universe.pending? #=> true
+
+# wait for it...
+
+universe.fulfilled? #=> true
+universe.value      #=> 42
+```
+
+The `#post?` method is a blocking call. It takes a number of seconds to wait as the
+first parameter and any number of additional parameters as the message. If the message
+is processed within the given number of seconds the call returns the result of the
+operation. If message processing raises an exception the exception is raised again
+by the `#post?` method. If the call to `#post?` times out a `Concurrent::Timeout`
+exception is raised.
+
+```ruby
+# needs code examples...
+```
+
+## 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/agent.md

@@ -1,20 +1,20 @@
 # 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
+`Agent`s are inspired by [Clojure's](http://clojure.org/) [agent](http://clojure.org/agents) function.
+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
+`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`. `Agent`s 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
+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`
+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
@@ -22,10 +22,29 @@ seacrhed in order until one matching the current exception is found. That `rescu
 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
+`Agent`s 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.
 
+## Copy Options
+
+Object references in Ruby are mutable. This can lead to serious problems when
+the value of an `Agent` is a mutable reference. Which is always the case unless
+the value is a `Fixnum`, `Symbol`, or similar "primative" data type. Each
+`Agent` instance can be configured with a few options that can help protect the
+program from potentially dangerous operations. Each of these options can be
+optionally set when the `Agent` is created:
+
+* `:dup_on_deref` when true the `Agent` will call the `#dup` method on the
+  `value` object every time the `#value` methid is called (default: false)
+* `:freeze_on_deref` when true the `Agent` will call the `#freeze` method on the
+  `value` object every time the `#value` method is called (default: false)
+* `:copy_on_deref` when given a `Proc` object the `Proc` will be run every time
+  the `#value` method is called. The `Proc` will be given the current `value` as
+  its only parameter and the result returned by the block will be the return
+  value of the `#value` call. When `nil` this option will be ignored (default:
+  nil)
+
 ## Examples
 
 A simple example:

data/md/future.md

@@ -1,25 +1,33 @@
 # 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
+`Future`s are inspired by [Clojure's](http://clojure.org/) [future](http://clojuredocs.org/clojure_core/clojure.core/future)
+function. 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 operation for
+asynchronous completion, do other stuff, then return and retrieve the result of the async
+operation at a later time. `Future`s run on the global thread pool (see below).
+
+`Future`s 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.
+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*.
+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.
 
+The `Future` class also includes the Ruby standard library
+[Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html) module. On fulfillment
+or rejection all observers will be notified according to the normal `Observable` behavior. The observer
+callback function will be called with three parameters: the `Time` of fulfillment/rejection, the
+final `value`, and the final `reason`. Observers added after fulfillment/rejection will still be
+notified as normal. The notification will occur on the global thread pool.
+
 ## Examples
 
 A fulfilled example:
@@ -53,6 +61,40 @@ count.rejected? #=> true
 count.reason #=> #<StandardError: Boom!> 
 ```
 
+An example with observation:
+
+```ruby
+class Ticker
+  Stock = Struct.new(:symbol, :name, :exchange)
+
+  def update(time, value, reason)
+    ticker = value.collect do |symbol|
+      Stock.new(symbol['symbol'], symbol['name'], symbol['exch'])
+    end
+
+    output = ticker.join("\n")
+    print "#{output}\n"
+  end
+end
+
+yahoo = Finance.new('YAHOO')
+future = Concurrent::Future.new { yahoo.update.suggested_symbols }
+future.add_observer(Ticker.new)
+
+# do important stuff...
+
+#>> #<struct Ticker::Stock symbol="YHOO", name="Yahoo! Inc.", exchange="NMS">
+#>> #<struct Ticker::Stock symbol="YHO.DE", name="Yahoo! Inc.", exchange="GER">
+#>> #<struct Ticker::Stock symbol="YAHOY", name="Yahoo Japan Corporation", exchange="PNK">
+#>> #<struct Ticker::Stock symbol="YAHOF", name="YAHOO JAPAN CORP", exchange="PNK">
+#>> #<struct Ticker::Stock symbol="YOJ.SG", name="YAHOO JAPAN", exchange="STU">
+#>> #<struct Ticker::Stock symbol="YHO.SG", name="YAHOO", exchange="STU">
+#>> #<struct Ticker::Stock symbol="YHOO.BA", name="Yahoo! Inc.", exchange="BUE">
+#>> #<struct Ticker::Stock symbol="YHO.DU", name="YAHOO", exchange="DUS">
+#>> #<struct Ticker::Stock symbol="YHO.HM", name="YAHOO", exchange="HAM">
+#>> #<struct Ticker::Stock symbol="YHO.BE", name="YAHOO", exchange="BER">
+```
+
 ## Copyright
 
 *Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).