concurrent-ruby 0.4.1 → 0.5.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a2299d64fb78b008f9f686ac6f72b87e92f54b5
-  data.tar.gz: b76068bdde155ed1e3f0572dca60b34cb9e7f952
+  metadata.gz: 75d1509eb5bc369de5272cdaf90447e357c45c6a
+  data.tar.gz: c2ae01438d9848893ab00a08880368bf82662f75
 SHA512:
-  metadata.gz: cc3346484a3fce841b6e10ee5406bb938a8d16f48295b08fd71014187cf7adb24c398b6856aef6ad62ef74e6d13d5a4a5adc9b1a57102b5175eaf269256850fd
-  data.tar.gz: 8c30bbcfde894063c3c466dd7a66b13c30827674d13446dc0a9f95b46509c326913ca927303047bf7537971a49905c0286cd90a4e45788e89504277034ea5834
+  metadata.gz: 95702184ad897fd9874ae2f8bcaddcf0501a166f1dfad0fa37fc5be2a6c7b0d133bf74cd843753880135c3b4d8b63c8d515b08cf2b9d692fdfaf629533502fe2
+  data.tar.gz: dba5b747f74d44cf63475eb7a1dc081b3fea7fc7218ef016773c37a4f19db0af410ed6e8cb621d0dcdc363406ef3b63afe430bf8ae54916b2eab7374c7e887fc

data/README.md

@@ -1,4 +1,7 @@
-# Concurrent Ruby [![Build Status](https://secure.travis-ci.org/jdantonio/concurrent-ruby.png)](https://travis-ci.org/jdantonio/concurrent-ruby?branch=master) [![Coverage Status](https://coveralls.io/repos/jdantonio/concurrent-ruby/badge.png)](https://coveralls.io/r/jdantonio/concurrent-ruby) [![Dependency Status](https://gemnasium.com/jdantonio/concurrent-ruby.png)](https://gemnasium.com/jdantonio/concurrent-ruby)
+# Concurrent Ruby
+[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.png)](http://badge.fury.io/rb/concurrent-ruby) [![Build Status](https://secure.travis-ci.org/jdantonio/concurrent-ruby.png)](https://travis-ci.org/jdantonio/concurrent-ruby?branch=master) [![Coverage Status](https://coveralls.io/repos/jdantonio/concurrent-ruby/badge.png)](https://coveralls.io/r/jdantonio/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/jdantonio/concurrent-ruby.png)](https://codeclimate.com/github/jdantonio/concurrent-ruby) [![Dependency Status](https://gemnasium.com/jdantonio/concurrent-ruby.png)](https://gemnasium.com/jdantonio/concurrent-ruby)
+
+***NOTE:*** *A few API updates in v0.5.0 are not backward-compatible. Please see the [release notes](https://github.com/jdantonio/concurrent-ruby/wiki/API-Updates-in-v0.5.0).*
 
 Modern concurrency tools for Ruby. Inspired by
 [Erlang](http://www.erlang.org/doc/reference_manual/processes.html),
@@ -21,26 +24,36 @@ The design goals of this gem are:
 
 ## Features & Documentation
 
-* Clojure-inspired [Agent](https://github.com/jdantonio/concurrent-ruby/blob/master/md/agent.md)
-* Clojure-inspired [Future](https://github.com/jdantonio/concurrent-ruby/blob/master/md/future.md)
-* Scala-inspired [Actor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/actor.md)
-* JavaScript-inspired [Promise](https://github.com/jdantonio/concurrent-ruby/blob/master/md/promise.md)
-* Java-inspired [Thread Pools](https://github.com/jdantonio/concurrent-ruby/blob/master/md/thread_pool.md)
-* Old school [events](http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655.aspx) from back in my Visual C++ days
-* Repeated task execution with Java-inspired [TimerTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/timer_task.md) service
-* Scheduled task execution with Java-inspired [ScheduledTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/scheduled_task.md) service
-* Erlang-inspired [Supervisor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md) for managing long-running threads
-* Actor variant [Channel](https://github.com/jdantonio/concurrent-ruby/blob/master/md/channel.md)
-  loosely based on the [MailboxProcessor](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx)
-  agent in [F#](http://msdn.microsoft.com/en-us/library/ee370357.aspx)
+Please see the [Concurrent Ruby Wiki](https://github.com/jdantonio/concurrent-ruby/wiki)
+or the [API documentation](http://rubydoc.info/github/jdantonio/concurrent-ruby/master/frames)
+for more information or join our [mailing list](http://groups.google.com/group/concurrent-ruby).
+
+There are many concurrency abstractions in this library. These abstractions can be broadly categorized
+into several general categories:
+
+* Asynchronous concurrency abstractions including [Actor](https://github.com/jdantonio/concurrent-ruby/wiki/Actor),
+  [Agent](https://github.com/jdantonio/concurrent-ruby/wiki/Agent), [Channel](https://github.com/jdantonio/concurrent-ruby/wiki/Channel),
+  [Future](https://github.com/jdantonio/concurrent-ruby/wiki/Future), [Promise](https://github.com/jdantonio/concurrent-ruby/wiki/Promise),
+  [ScheculedTask](https://github.com/jdantonio/concurrent-ruby/wiki/ScheduledTask),
+  and [TimerTask](https://github.com/jdantonio/concurrent-ruby/wiki/TimerTask) 
+* Erlang-inspired [Supervisor](https://github.com/jdantonio/concurrent-ruby/wiki/Supervisor) and other lifecycle classes/mixins
+  for managing long-running threads
+* Thread-safe variables including [M-Structures](https://github.com/jdantonio/concurrent-ruby/wiki/MVar-(M-Structure)),
+  [I-Structures](https://github.com/jdantonio/concurrent-ruby/wiki/IVar-(I-Structure)),
+  [thread-local variables](https://github.com/jdantonio/concurrent-ruby/wiki/ThreadLocalVar),
+  and atomic counters
+* Thread synchronization classes and algorithms including [dataflow](https://github.com/jdantonio/concurrent-ruby/wiki/Dataflow), 
+  timeout, condition, countdown latch, dependency counter, and event
+* Java-inspired [thread pools](https://github.com/jdantonio/concurrent-ruby/wiki/Thread%20Pools)
+* And many more...
 
 ### Semantic Versioning
 
-*Beginning with v0.4.0 this gem will strictly adhere to the rules of semantic versioning.*
+This gem adheres to the rules of [semantic versioning](http://semver.org/).
 
 ### Supported Ruby versions
 
-MRI 1.9.2, 1.9.3, 2.0, 2.1, and JRuby (1.9 mode). This library is pure Ruby and has no gem dependencies.
+MRI 1.9.2, 1.9.3, 2.0, 2.1, JRuby (1.9 mode), and Rubinius 2.x. This library is pure Ruby and has no gem dependencies.
 It should be fully compatible with any Ruby interpreter that is 1.9.x compliant.
 
 ### Example
@@ -106,6 +119,9 @@ These tools will help ease the burden, but at the end of the day it is essential
 ## Contributors
 
 * [Michele Della Torre](https://github.com/mighe)
+* [Chris Seaton](https://github.com/chrisseaton)
+* [Giuseppe Capizzi](https://github.com/gcapizzi)
+* [Brian Shirai](https://github.com/brixen)
 * [Chip Miller](https://github.com/chip-miller)
 * [Jamie Hodge](https://github.com/jamiehodge)
 * [Zander Hill](https://github.com/zph)
@@ -118,24 +134,6 @@ These tools will help ease the burden, but at the end of the day it is essential
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
-### Conference Presentations
-
-I've given several conference presentations on concurrent programming with this gem.
-Check them out:
-
-* ["Advanced Concurrent Programming in Ruby"](http://rubyconf.org/program#jerry-dantonio)
-  at [RubyConf 2013](http://rubyconf.org/)
-  used [this](https://github.com/jdantonio/concurrent-ruby-presentation) version of the presentation
-  and is available for viewing on [Confreaks](http://www.confreaks.com/videos/2872-rubyconf2013-advanced-concurrent-programming-in-ruby)
-* ["Advanced Multithreading in Ruby"](http://cascadiaruby.com/#advanced-multithreading-in-ruby)
-  at [Cascadia Ruby 2013](http://cascadiaruby.com/)
-  used [this](https://github.com/jdantonio/concurrent-ruby-presentation/tree/cascadia-ruby-2013) version of the presentation
-  and is available for viewing on [Confreaks](http://www.confreaks.com/videos/2790-cascadiaruby2013-advanced-multithreading-in-ruby)
-* [Cleveland Ruby Brigade](http://www.meetup.com/ClevelandRuby/events/149981942/) meetup in December of 2013
-  used [this](https://github.com/jdantonio/concurrent-ruby-presentation/releases/tag/clerb-dec-2013) version of the presentation
-* I'll be giving ["Advanced Concurrent Programming in Ruby"](http://codemash.org/sessions)
-  at [CodeMash 2014](http://codemash.org/)
-
 ## License and Copyright
 
 *Concurrent Ruby* is Copyright © 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).

data/lib/concurrent.rb

@@ -1,12 +1,21 @@
 require 'concurrent/version'
 
+require 'concurrent/atomic'
+require 'concurrent/count_down_latch'
+require 'concurrent/condition'
+require 'concurrent/copy_on_notify_observer_set'
+require 'concurrent/copy_on_write_observer_set'
+require 'concurrent/safe_task_executor'
+require 'concurrent/ivar'
+
 require 'concurrent/actor'
 require 'concurrent/agent'
-require 'concurrent/contract'
 require 'concurrent/channel'
+require 'concurrent/dataflow'
 require 'concurrent/dereferenceable'
 require 'concurrent/event'
 require 'concurrent/future'
+require 'concurrent/mvar'
 require 'concurrent/obligation'
 require 'concurrent/postable'
 require 'concurrent/promise'
@@ -14,6 +23,7 @@ require 'concurrent/runnable'
 require 'concurrent/scheduled_task'
 require 'concurrent/stoppable'
 require 'concurrent/supervisor'
+require 'concurrent/thread_local_var'
 require 'concurrent/timer_task'
 require 'concurrent/utilities'
 
@@ -23,8 +33,6 @@ require 'concurrent/cached_thread_pool'
 require 'concurrent/fixed_thread_pool'
 require 'concurrent/immediate_executor'
 
-require 'concurrent/event_machine_defer_proxy' if defined?(EventMachine)
-
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.
 # 

data/lib/concurrent/actor.rb

@@ -19,36 +19,36 @@ module Concurrent
   # 
   #   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
+  # The +Concurrent::Actor+ class in this library is based solely on the
   # {http://www.scala-lang.org/api/current/index.html#scala.actors.Actor Actor} trait
   # 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.
+  # Scala's +Actor+ but its behavior for what *has* been implemented is nearly identical.
   # The excluded features mostly deal with Scala's message semantics, strong typing,
   # and other characteristics of Scala that don't really apply to Ruby.
   # 
-  # Unlike most of the abstractions in this library, `Actor` takes an *object-oriented*
+  # Unlike many of the abstractions in this library, +Actor+ takes an *object-oriented*
   # approach to asynchronous concurrency, rather than a *functional programming*
   # approach.
   #   
-  # Because `Actor` mixes in the `Concurrent::Runnable` module subclasses have access to
-  # the `#on_error` method and can override it to implement custom error handling. The
-  # `Actor` base class does not use `#on_error` so as to avoid conflit with subclasses
-  # which override it. Generally speaking, `#on_error` should not be used. The `Actor`
+  # Because +Actor+ mixes in the +Concurrent::Runnable+ module subclasses have access to
+  # the +#on_error+ method and can override it to implement custom error handling. The
+  # +Actor+ base class does not use +#on_error+ so as to avoid conflit with subclasses
+  # which override it. Generally speaking, +#on_error+ should not be used. The +Actor+
   # base class provides concictent, reliable, and robust error handling already, and
   # error handling specifics are tied to the message posting method. Incorrect behavior
-  # in an `#on_error` override can lead to inconsistent `Actor` behavior that may lead
+  # in an +#on_error+ override can lead to inconsistent +Actor+ behavior that may lead
   # to confusion and difficult debugging.
   #   
-  # The `Actor` superclass mixes in the Ruby standard library
+  # The +Actor+ superclass mixes in the Ruby standard library
   # {http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html Observable}
   # module to provide consistent callbacks upon message processing completion. The normal
-  # `Observable` methods, including `#add_observer` behave normally. Once an observer
-  # is added to an `Actor` it will be notified of all messages processed *after*
+  # +Observable+ methods, including +#add_observer+ behave normally. Once an observer
+  # is added to an +Actor+ it will be notified of all messages processed *after*
   # addition. Notification will *not* occur for any messages that have already been
   # processed.
   #   
   # Observers will be notified regardless of whether the message processing is successful
-  # or not. The `#update` method of the observer will receive four arguments. The
+  # or not. The +#update+ method of the observer will receive four arguments. The
   # appropriate method signature is:
   #   
   #   def update(time, message, result, reason)
@@ -57,8 +57,8 @@ module Concurrent
   #   
   # * The time that message processing was completed
   # * An array containing all elements of the original message, in order
-  # * The result of the call to `#act` (will be `nil` if an exception was raised)
-  # * Any exception raised by `#act` (or `nil` if message processing was successful)
+  # * The result of the call to +#act+ (will be +nil+ if an exception was raised)
+  # * Any exception raised by +#act+ (or +nil+ if message processing was successful)
   #
   # @example Actor Ping Pong
   #   class Ping < Concurrent::Actor
@@ -140,10 +140,10 @@ module Concurrent
 
     # Create a pool of actors that share a common mailbox.
     #   
-    # 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
+    # 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.
     #
     # @param [Integer] count the number of actors in the pool
@@ -152,7 +152,7 @@ module Concurrent
     # @return [Array] two-element array with the shared mailbox as the first element
     #   and an array of actors as the second element
     #
-    # @raise ArgumentError if `count` is zero or less
+    # @raise ArgumentError if +count+ is zero or less
     #
     # @example
     #   class EchoActor < Concurrent::Actor
@@ -191,35 +191,35 @@ module Concurrent
 
     protected
 
-    # 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)`
+    # 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)+
     # 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).
+    # response to a message being post to the +Actor+ instance (see *Behavior* below).
     #
     # @param [Array] message one or more arguments representing the message sent to the
     #   actor via one of the Concurrent::Postable methods
     #
     # @return [Object] the result obtained when the message is successfully processed
     #
-    # @raise NotImplementedError unless overridden in the `Actor` subclass
+    # @raise NotImplementedError unless overridden in the +Actor+ subclass
     # 
     # @!visibility public
     def act(*message)
       raise NotImplementedError.new("#{self.class} does not implement #act")
     end
 
-    # @private
+    # @!visibility private
     def on_run # :nodoc:
       queue.clear
     end
 
-    # @private
+    # @!visibility private
     def on_stop # :nodoc:
       queue.clear
       queue.push(:stop)
     end
 
-    # @private
+    # @!visibility private
     def on_task # :nodoc:
       package = queue.pop
       return if package == :stop
@@ -235,8 +235,8 @@ module Concurrent
         if notifier.is_a?(Event) && ! notifier.set?
           package.handler.push(result || ex)
           package.notifier.set
-        elsif package.handler.is_a?(Contract)
-          package.handler.complete(result, ex)
+        elsif package.handler.is_a?(IVar)
+          package.handler.complete(! result.nil?, result, ex)
         elsif package.handler.respond_to?(:post) && ex.nil?
           package.handler.post(result)
         end
@@ -246,7 +246,7 @@ module Concurrent
       end
     end
 
-    # @private
+    # @!visibility private
     def on_error(time, msg, ex) # :nodoc:
     end
   end

data/lib/concurrent/agent.rb

@@ -13,83 +13,165 @@ module Concurrent
   # 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.
+  #
+  # @example Basic usage
+  #   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)
+  #   score.value #=> 220
+  #   
+  #   score << proc{|current| current - 50 }
+  #   sleep(0.1)
+  #   score.value #=> 170
+  #
+  # @!attribute [r] timeout
+  #   @return [Fixnum] the maximum number of seconds before an update is cancelled
   class Agent
-    include Observable
     include Dereferenceable
     include UsesGlobalThreadPool
 
+    # The default timeout value (in seconds); used when no timeout option
+    # is given at initialization
     TIMEOUT = 5
 
-    attr_reader :initial
     attr_reader :timeout
 
+    # Initialize a new Agent with the given initial value and provided options.
+    #
+    # @param [Object] initial the initial value
+    # @param [Hash] opts the options used to define the behavior at update and deref
+    # @option opts [Fixnum] :timeout (TIMEOUT) maximum number of seconds before an update is cancelled
+    # @option opts [String] :dup_on_deref (false) call +#dup+ before returning the data
+    # @option opts [String] :freeze_on_deref (false) call +#freeze+ before returning the data
+    # @option opts [String] :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 = []
-      @validator = nil
-      @timeout = opts[:timeout] || TIMEOUT
+      @validator = Proc.new { |result| true }
+      @timeout = opts.fetch(:timeout, TIMEOUT).freeze
+      @observers = CopyOnWriteObserverSet.new
       init_mutex
       set_deref_options(opts)
     end
 
-    def rescue(clazz = nil, &block)
+    # Specifies a block operation to be performed when an update operation raises
+    # an exception. Rescue blocks will be checked in order they were added. The first
+    # block for which the raised exception "is-a" subclass of the given +clazz+ will
+    # be called. If no +clazz+ is given the block will match any caught exception.
+    # This behavior is intended to be identical to Ruby's +begin/rescue/end+ behavior.
+    # Any number of rescue handlers can be added. If no rescue handlers are added then
+    # caught exceptions will be suppressed.
+    #
+    # @param [Exception] clazz the class of exception to catch
+    # @yield the block to be called when a matching exception is caught
+    # @yieldparam [StandardError] ex the caught exception
+    #
+    # @example
+    #   score = Concurrent::Agent.new(0).
+    #             rescue(NoMethodError){|ex| puts "Bam!" }.
+    #             rescue(ArgumentError){|ex| puts "Pow!" }.
+    #             rescue{|ex| puts "Boom!" }
+    #   
+    #   score << proc{|current| raise ArgumentError }
+    #   sleep(0.1)
+    #   #=> puts "Pow!"
+    def rescue(clazz = StandardError, &block)
       unless block.nil?
         mutex.synchronize do
           @rescuers << Rescuer.new(clazz, block)
         end
       end
-      return self
+      self
     end
     alias_method :catch, :rescue
     alias_method :on_error, :rescue
 
+    # A block operation to be performed after every update to validate if the new
+    # value is valid. If the new value is not valid then the current value is not
+    # updated. If no validator is provided then all updates are considered valid.
+    #
+    # @yield the block to be called after every update operation to determine if
+    #   the result is valid
+    # @yieldparam [Object] value the result of the last update operation
+    # @yieldreturn [Boolean] true if the value is valid else false
     def validate(&block)
       @validator = block unless block.nil?
-      return self
+      self
     end
     alias_method :validates, :validate
     alias_method :validate_with, :validate
     alias_method :validates_with, :validate
 
+    # Update the current value with the result of the given block operation
+    #
+    # @yield the operation to be performed with the current value in order to calculate
+    #   the new value
+    # @yieldparam [Object] value the current value
+    # @yieldreturn [Object] the new value
     def post(&block)
       Agent.thread_pool.post{ work(&block) } unless block.nil?
     end
 
+    # Update the current value with the result of the given block operation
+    #
+    # @yield the operation to be performed with the current value in order to calculate
+    #   the new value
+    # @yieldparam [Object] value the current value
+    # @yieldreturn [Object] the new value
     def <<(block)
       self.post(&block)
-      return self
+      self
+    end
+
+    def add_observer(observer, func=:update)
+      @observers.add_observer(observer, func)
     end
 
     alias_method :add_watch, :add_observer
 
+    def delete_observer(observer)
+      @observers.delete_observer(observer)
+    end
+
     private
 
-    # @private
-    Rescuer = Struct.new(:clazz, :block)
+    # @!visibility private
+    Rescuer = Struct.new(:clazz, :block) # :nodoc:
 
-    # @private
+    # @!visibility private
     def try_rescue(ex) # :nodoc:
       rescuer = mutex.synchronize do
-        @rescuers.find{|r| r.clazz.nil? || ex.is_a?(r.clazz) }
+        @rescuers.find{|r| ex.is_a?(r.clazz) }
       end
       rescuer.block.call(ex) if rescuer
     rescue Exception => ex
       # supress
     end
 
-    # @private
+    # @!visibility private
     def work(&handler) # :nodoc:
       begin
+
+        should_notify = false
+
         mutex.synchronize do
           result = Concurrent::timeout(@timeout) do
             handler.call(@value)
           end
-          if @validator.nil? || @validator.call(result)
+          if @validator.call(result)
             @value = result
-            changed
+            should_notify = true
           end
         end
-        notify_observers(Time.now, self.value) if self.changed?
+        time = Time.now
+        @observers.notify_observers{ [time, self.value] } if should_notify
       rescue Exception => ex
         try_rescue(ex)
       end