concurrent-ruby 0.5.0 → 0.6.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fbc70b72314ff5cf4607764c2e542b5a82d40749
-  data.tar.gz: 37bd7b03c39b679d06155efc494509d9cf458b8c
+  metadata.gz: 8e4a4e756232abaffd4ca55c37e049af25f9884a
+  data.tar.gz: 9345ebbf4f1a05e1c5b0eccd8df0d111407c293e
 SHA512:
-  metadata.gz: 98bc47e45b277667f4040757848fffc83c5836885f445b9eb242658bca1af78271a72be563e7f38c504af1e9c23db44af5abc7f25c2f12b527f8ac3d35271c94
-  data.tar.gz: f9328fde5f48922e1497683c7593fade6fc5aa79b9fe6e3de322a92530f61f872a77dd54165176adb307a2bfabcce66a4c975d4c6b2507fbc636b0fa18664fb7
+  metadata.gz: 1e5b34f7f631e3cb76248674f8cae5b1bee56c8485c71f32cff53d2625fb5475d84e7ff0b1f07272efbfe860652f391ea5f1078652e0c47edc2117a5099152e1
+  data.tar.gz: 5c736c6a669fd952268275f9b1e802f32eac4dc78386df90b871f1bb6dc66985b9b5e7e2046ce5bf81235608c1bc3340a1dcbd49573fb65d8cacf8b6b53f3d06

data/README.md

@@ -1,26 +1,37 @@
 # 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) [![Inline docs](http://inch-pages.github.io/github/jdantonio/concurrent-ruby.png)](http://inch-pages.github.io/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).*
-
+<table>
+<tr>
+<td align="left" valign="top">
+<p>
 Modern concurrency tools for Ruby. Inspired by
-[Erlang](http://www.erlang.org/doc/reference_manual/processes.html),
-[Clojure](http://clojure.org/concurrent_programming),
-[Scala](http://www.scala-lang.org/api/current/index.html#scala.actors.Actor),
-[Haskell](http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell),
-[F#](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx),
-[C#](http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx),
-[Java](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html),
+<a href="http://www.erlang.org/doc/reference_manual/processes.html">Erlang</a>,
+<a href="http://clojure.org/concurrent_programming">Clojure</a>,
+<a href="http://www.scala-lang.org/api/current/index.html#scala.actors.Actor">Scala</a>,
+<a href="http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell">Haskell</a>,
+<a href="http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx">F#</a>,
+<a href="http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx">C#</a>,
+<a href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html">Java</a>,
 and classic concurrency patterns.
-
+</p>
+<p>
 The design goals of this gem are:
-
-* Stay true to the spirit of the languages providing inspiration
-* But implement in a way that makes sense for Ruby
-* Keep the semantics as idiomatic Ruby as possible
-* Support features that make sense in Ruby
-* Exclude features that don't make sense in Ruby
-* Be small, lean, and loosely coupled
+<ul>
+<li>Stay true to the spirit of the languages providing inspiration</li>
+<li>But implement in a way that makes sense for Ruby</li>
+<li>Keep the semantics as idiomatic Ruby as possible</li>
+<li>Support features that make sense in Ruby</li>
+<li>Exclude features that don't make sense in Ruby</li>
+<li>Be small, lean, and loosely coupled</li>
+</ul>
+</p>
+</td>
+<td align="right" valign="top">
+<img src="https://raw.githubusercontent.com/wiki/jdantonio/concurrent-ruby/logo/concurrent-ruby-logo-300x300.png"/>
+</td>
+</tr>
+</table>
 
 ## Features & Documentation
 
@@ -29,19 +40,21 @@ or the [API documentation](http://rubydoc.info/github/jdantonio/concurrent-ruby/
 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),
+into several general groups:
+
+* Asynchronous concurrency abstractions including
+  [Async](https://github.com/jdantonio/concurrent-ruby/wiki/Async),
+  [Agent](https://github.com/jdantonio/concurrent-ruby/wiki/Agent),
+  [Future](https://github.com/jdantonio/concurrent-ruby/wiki/Future),
+  [Promise](https://github.com/jdantonio/concurrent-ruby/wiki/Promise),
+  [ScheduledTask](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
+  atomic counters, and [software transactional memory](https://github.com/jdantonio/concurrent-ruby/wiki/TVar-(STM))
 * 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)
@@ -53,73 +66,68 @@ 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, 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.
+MRI 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 interpreter that is compliant with Ruby 1.9.3 or newer.
 
-### Example
+### Examples
 
 Many more code examples can be found in the documentation for each class (linked above).
 This one simple example shows some of the power of this gem.
 
 ```ruby
 require 'concurrent'
-require 'faker'
-
-class EchoActor < Concurrent::Actor
-  def act(*message)
-    puts "#{message} handled by #{self}"
+require 'thread'   # for Queue
+require 'open-uri' # for open(uri)
+
+class Ticker
+  def get_year_end_closing(symbol, year)
+    uri = "http://ichart.finance.yahoo.com/table.csv?s=#{symbol}&a=11&b=01&c=#{year}&d=11&e=31&f=#{year}&g=m"
+    data = open(uri) {|f| f.collect{|line| line.strip } }
+    data[1].split(',')[4].to_f
   end
 end
 
-mailbox, pool = EchoActor.pool(5)
-
-timer_proc = proc do
-  mailbox.post(Faker::Company.bs)
-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!
-
-#=> ["mesh proactive platforms"] handled by #<EchoActor:0x007fa5ac18bdf8>
-#=> ["maximize sticky portals"] handled by #<EchoActor:0x007fa5ac18bdd0>
-#=> ["morph bleeding-edge markets"] handled by #<EchoActor:0x007fa5ac18bd80>
-#=> ["engage clicks-and-mortar interfaces"] handled by #<EchoActor:0x007fa5ac18bd58>
-#=> ["monetize transparent infrastructures"] handled by #<EchoActor:0x007fa5ac18bd30>
-#=> ["morph sexy e-tailers"] handled by #<EchoActor:0x007fa5ac18bdf8>
-#=> ["exploit dot-com models"] handled by #<EchoActor:0x007fa5ac18bdd0>
-#=> ["incentivize virtual deliverables"] handled by #<EchoActor:0x007fa5ac18bd80>
-#=> ["enhance B2B models"] handled by #<EchoActor:0x007fa5ac18bd58>
-#=> ["envisioneer real-time architectures"] handled by #<EchoActor:0x007fa5ac18bd30>
-
-overlord.stop
+# Future
+price = Concurrent::Future.execute{ Ticker.new.get_year_end_closing('TWTR', 2013) }
+price.state #=> :pending
+sleep(1)    # do other stuff
+price.value #=> 63.65
+price.state #=> :fulfilled
+
+# Promise
+prices = Concurrent::Promise.new{ puts Ticker.new.get_year_end_closing('AAPL', 2013) }.
+           then{ puts Ticker.new.get_year_end_closing('MSFT', 2013) }.
+           then{ puts Ticker.new.get_year_end_closing('GOOG', 2013) }.
+           then{ puts Ticker.new.get_year_end_closing('AMZN', 2013) }.execute
+prices.state #=> :pending
+sleep(1)     # do other stuff
+#=> 561.02
+#=> 37.41
+#=> 1120.71
+#=> 398.79
+
+# ScheduledTask
+task = Concurrent::ScheduledTask.execute(2){ Ticker.new.get_year_end_closing('INTC', 2013) }
+task.state #=> :pending
+sleep(3)   # do other stuff
+task.value #=> 25.96
+
+# Async
+ticker = Ticker.new
+ticker.extend(Concurrent::Async)
+hpq = ticker.async.get_year_end_closing('HPQ', 2013)
+ibm = ticker.await.get_year_end_closing('IBM', 2013)
+hpq.value #=> 27.98
+ibm.value #=> 187.57
 ```
 
-### Disclaimer
-
-Remember, *there is no silver bullet in concurrent programming.* Concurrency is hard.
-These tools will help ease the burden, but at the end of the day it is essential that you
-*know what you are doing.*
-
-* Decouple business logic from concurrency logic
-* Test business logic separate from concurrency logic
-* Keep the intersection of business logic and concurrency and small as possible
-* Don't share mutable data unless absolutely necessary
-* Protect shared data as much as possible (prefer [immutability](https://github.com/harukizaemon/hamster))
-* Don't mix Ruby's [concurrency](http://ruby-doc.org/core-2.0.0/Thread.html)
-  [primitives](http://www.ruby-doc.org/core-2.0.0/Mutex.html) with asynchronous concurrency libraries
-
 ## Contributors
 
+* [Jerry D'Antonio](https://github.com/jdantonio)
 * [Michele Della Torre](https://github.com/mighe)
 * [Chris Seaton](https://github.com/chrisseaton)
+* [Lucas Allan](https://github.com/lucasallan)
 * [Giuseppe Capizzi](https://github.com/gcapizzi)
 * [Brian Shirai](https://github.com/brixen)
 * [Chip Miller](https://github.com/chip-miller)
@@ -136,5 +144,8 @@ These tools will help ease the burden, but at the end of the day it is essential
 
 ## License and Copyright
 
-*Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
-It is free software released under the [MIT License](http://www.opensource.org/licenses/MIT).
+*Concurrent Ruby* is free software released under the [MIT License](http://www.opensource.org/licenses/MIT).
+
+The *Concurrent Ruby* [logo](https://github.com/jdantonio/concurrent-ruby/wiki/Logo)
+was designed by [David Jones](https://twitter.com/zombyboy).
+It is Copyright &copy; 2014 [Jerry D'Antonio](https://twitter.com/jerrydantonio). All Rights Reserved.

data/lib/concurrent.rb

@@ -1,4 +1,5 @@
 require 'concurrent/version'
+require 'concurrent/configuration'
 
 require 'concurrent/atomic'
 require 'concurrent/count_down_latch'
@@ -10,14 +11,17 @@ require 'concurrent/ivar'
 
 require 'concurrent/actor'
 require 'concurrent/agent'
-require 'concurrent/channel'
+require 'concurrent/async'
 require 'concurrent/dataflow'
+require 'concurrent/delay'
 require 'concurrent/dereferenceable'
 require 'concurrent/event'
+require 'concurrent/exchanger'
 require 'concurrent/future'
 require 'concurrent/mvar'
 require 'concurrent/obligation'
 require 'concurrent/postable'
+require 'concurrent/processor_count'
 require 'concurrent/promise'
 require 'concurrent/runnable'
 require 'concurrent/scheduled_task'
@@ -25,13 +29,24 @@ require 'concurrent/stoppable'
 require 'concurrent/supervisor'
 require 'concurrent/thread_local_var'
 require 'concurrent/timer_task'
+require 'concurrent/tvar'
 require 'concurrent/utilities'
 
-require 'concurrent/global_thread_pool'
+require 'concurrent/channel/probe'
+require 'concurrent/channel/channel'
+require 'concurrent/channel/unbuffered_channel'
+require 'concurrent/channel/buffered_channel'
+require 'concurrent/channel/ring_buffer'
+require 'concurrent/channel/blocking_ring_buffer'
+
+require 'concurrent/actor_context'
+require 'concurrent/simple_actor_ref'
 
 require 'concurrent/cached_thread_pool'
 require 'concurrent/fixed_thread_pool'
 require 'concurrent/immediate_executor'
+require 'concurrent/per_thread_executor'
+require 'concurrent/thread_pool_executor'
 
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.

data/lib/concurrent/actor.rb

@@ -119,6 +119,8 @@ module Concurrent
   #   
   #   ping << :pong
   #
+  # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
+  #
   # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
   class Actor
     include Observable
@@ -174,7 +176,10 @@ module Concurrent
     #   #=> [6] handled by #<EchoActor:0x007fc8014fb8b8>
     #   #=> [7] handled by #<EchoActor:0x007fc8014fb818>
     #   #=> [8] handled by #<EchoActor:0x007fc8014fb890>
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def self.pool(count, *args, &block)
+      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `ActorContext`.'
       raise ArgumentError.new('count must be greater than zero') unless count > 0
       mailbox = Queue.new
       actors = count.times.collect do
@@ -202,24 +207,34 @@ module Concurrent
     # @return [Object] the result obtained when the message is successfully processed
     #
     # @raise NotImplementedError unless overridden in the +Actor+ subclass
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     # 
     # @!visibility public
     def act(*message)
+      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `ActorContext`.'
       raise NotImplementedError.new("#{self.class} does not implement #act")
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_run # :nodoc:
+      warn '[DEPRECATED] `Actor` is deprecated and will be replaced with `ActorContext`.'
       queue.clear
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_stop # :nodoc:
       queue.clear
       queue.push(:stop)
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_task # :nodoc:
       package = queue.pop
       return if package == :stop
@@ -247,6 +262,8 @@ module Concurrent
     end
 
     # @!visibility private
+    #
+    # @deprecated +Actor+ is being replaced with a completely new framework prior to v1.0.0
     def on_error(time, msg, ex) # :nodoc:
     end
   end

data/lib/concurrent/actor_context.rb

@@ -0,0 +1,31 @@
+require 'concurrent/simple_actor_ref'
+
+module Concurrent
+
+  module ActorContext
+
+    def on_start
+    end
+
+    def on_reset
+    end
+
+    def on_shutdown
+    end
+
+    def on_error(time, message, exception)
+    end
+
+    def self.included(base)
+
+      class << base
+        protected :new
+
+        def spawn(opts = {})
+          args = opts.fetch(:args, [])
+          Concurrent::SimpleActorRef.new(self.new(*args), opts)
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor_ref.rb

@@ -0,0 +1,39 @@
+require 'concurrent/copy_on_notify_observer_set'
+
+module Concurrent
+
+  module ActorRef
+
+    #NOTE: Required API methods
+    #      Must be implemented in all subclasses
+    #def post(*msg, &block)
+    #def post!(*msg)
+    #def running?
+    #def shutdown?
+    #def shutdown
+    #def join(timeout = nil)
+
+    def <<(message)
+      post(*message)
+      self
+    end
+
+    def add_observer(*args)
+      @observers.add_observer(*args)
+    end
+
+    def delete_observer(*args)
+      @observers.delete_observer(*args)
+    end
+
+    def delete_observers
+      @observers.delete_observers
+    end
+
+    protected
+
+    def observers
+      @observers ||= CopyOnNotifyObserverSet.new
+    end
+  end
+end

data/lib/concurrent/agent.rb

@@ -1,8 +1,8 @@
 require 'thread'
 require 'observer'
 
+require 'concurrent/configuration'
 require 'concurrent/dereferenceable'
-require 'concurrent/global_thread_pool'
 require 'concurrent/utilities'
 
 module Concurrent
@@ -34,7 +34,7 @@ module Concurrent
   #   @return [Fixnum] the maximum number of seconds before an update is cancelled
   class Agent
     include Dereferenceable
-    include UsesGlobalThreadPool
+    include OptionsParser
 
     # The default timeout value (in seconds); used when no timeout option
     # is given at initialization
@@ -46,7 +46,15 @@ module Concurrent
     #
     # @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 [Boolean] :operation (false) when +true+ will execute the future on the global
+    #   operation pool (for long-running operations), when +false+ will execute the future on the
+    #   global task pool (for short-running tasks)
+    # @option opts [object] :executor when provided will run all operations on
+    #   this executor rather than the global thread pool (overrides :operation)
+    #
     # @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
@@ -57,6 +65,7 @@ module Concurrent
       @validator = Proc.new { |result| true }
       @timeout = opts.fetch(:timeout, TIMEOUT).freeze
       @observers = CopyOnWriteObserverSet.new
+      @executor = get_executor_from(opts)
       init_mutex
       set_deref_options(opts)
     end
@@ -116,7 +125,7 @@ module Concurrent
     # @yieldparam [Object] value the current value
     # @yieldreturn [Object] the new value
     def post(&block)
-      Agent.thread_pool.post{ work(&block) } unless block.nil?
+      @executor.post{ work(&block) } unless block.nil?
     end
 
     # Update the current value with the result of the given block operation