concurrent-ruby 0.3.1.pre.1 → 0.3.1.pre.2

data/README.md

@@ -6,32 +6,35 @@ Inspired by Erlang, Clojure, Go, JavaScript, actors, and classic concurrency pat
 If you find this gem useful you should check out my [functional-ruby](https://github.com/jdantonio/functional-ruby)
 gem, too. This gem uses several of the tools in that gem.
 
-## 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
-* ["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
-* I'll be giving ["Advanced Concurrent Programming in Ruby"](http://codemash.org/sessions)
-  at [CodeMash 2014](http://codemash.org/)
-
 ## Introduction
 
-The old-school "lock and synchronize" approach to concurrency is dead. The future of concurrency
-is asynchronous. Send out a bunch of independent [actors](http://en.wikipedia.org/wiki/Actor_model)
-to do your bidding and process the results when you are ready. Although the idea of the concurrent
-actor originated in the early 1970's it has only recently started catching on. Although there is
-no one "true" actor implementation (what *exactly* is "object oriented," what *exactly* is
-"concurrent programming"), many modern programming languages implement variations on the actor
-theme. This library implements a few of the most interesting and useful of those variations.
-
-Remember, *there is no silver bullet in concurrent programming.* Concurrency is hard. Very hard.
+The old-school "lock and synchronize" approach to concurrency is dead. The
+future of concurrency is asynchronous. Send out a bunch of independent
+[actors](http://en.wikipedia.org/wiki/Actor_model) to do your bidding and
+process the results when you are ready. Many modern programming languages (like
+[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)...)
+provide asynchronous concurrency mechanisms within their standard libraries, the
+runtime environment, or the language iteself. This library implements a few of
+the most interesting and useful of those variations.
+
+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
+
 The project is hosted on the following sites:
 
 * [RubyGems project page](https://rubygems.org/gems/concurrent-ruby)
@@ -41,17 +44,19 @@ The project is hosted on the following sites:
 * [Dependency tracking on Gemnasium](https://gemnasium.com/jdantonio/concurrent-ruby)
 * [Follow me on Twitter](https://twitter.com/jerrydantonio)
 
-### Goals
-
-My history with high-performance, highly-concurrent programming goes back to my days with C/C++.
-I have the same scars as everyone else doing that kind of work with those languages.
-I'm fascinated by modern concurrency patterns like [Actors](http://en.wikipedia.org/wiki/Actor_model),
-[Agents](http://doc.akka.io/docs/akka/snapshot/java/agents.html), and
-[Promises](http://promises-aplus.github.io/promises-spec/). I'm equally fascinated by languages
-with strong concurrency support like [Erlang](http://www.erlang.org/doc/getting_started/conc_prog.html),
-[Go](http://golang.org/doc/articles/concurrency_patterns.html), and
-[Clojure](http://clojure.org/concurrent_programming). My goal is to implement those patterns in Ruby.
-Specifically:
+### 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
+* ["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
+* I'll be giving ["Advanced Concurrent Programming in Ruby"](http://codemash.org/sessions)
+  at [CodeMash 2014](http://codemash.org/)
+
+## Goals
 
 * Stay true to the spirit of the languages providing inspiration
 * But implement in a way that makes sense for Ruby

data/lib/concurrent/scheduled_task.rb

@@ -1,14 +1,11 @@
 require 'observer'
-
 require 'concurrent/obligation'
-require 'concurrent/runnable'
 
 module Concurrent
 
   class ScheduledTask
     include Obligation
     include Observable
-    include Runnable
 
     attr_reader :schedule_time
 
@@ -30,9 +27,12 @@ module Concurrent
       end
 
       @state = :pending
-      @task = block
       @schedule_time.freeze
+      @task = block
       set_deref_options(opts)
+
+      @thread = Thread.new{ work }
+      @thread.abort_on_exception = false
     end
 
     def cancelled?
@@ -55,15 +55,16 @@ module Concurrent
         end
       end
     end
+    alias_method :stop, :cancel
 
     def add_observer(observer, func = :update)
-      return false unless @state == :pending || @state == :in_progress
+      return false unless [:pending, :in_progress].include?(@state)
       super
     end
 
     protected
 
-    def on_task
+    def work
       while (diff = @schedule_time.to_f - Time.now.to_f) > 0
         sleep( diff > 60 ? 60 : diff )
       end

data/lib/concurrent/timer_task.rb

@@ -1,20 +1,22 @@
 require 'thread'
 require 'observer'
 
+require 'concurrent/dereferenceable'
 require 'concurrent/runnable'
 require 'concurrent/utilities'
 
 module Concurrent
 
   class TimerTask
+    include Dereferenceable
     include Runnable
     include Observable
 
     EXECUTION_INTERVAL = 60
     TIMEOUT_INTERVAL = 30
 
-    attr_reader :execution_interval
-    attr_reader :timeout_interval
+    attr_accessor :execution_interval
+    attr_accessor :timeout_interval
 
     def initialize(opts = {}, &block)
       raise ArgumentError.new('no block given') unless block_given?
@@ -22,9 +24,9 @@ module Concurrent
       @execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL
       @timeout_interval = opts[:timeout] || opts[:timeout_interval] || TIMEOUT_INTERVAL
       @run_now = opts[:now] || opts[:run_now] || false
-      @block_args = opts[:args] || opts [:arguments] || []
 
       @task = block
+      set_deref_options(opts)
     end
 
     def kill
@@ -65,17 +67,18 @@ module Concurrent
     end
 
     def execute_task
+      @value = ex = nil
       @worker = Thread.new do
         Thread.current.abort_on_exception = false
-        Thread.current[:result] = @task.call(*@block_args)
+        Thread.current[:result] = @task.call(self)
       end
       raise TimeoutError if @worker.join(@timeout_interval).nil?
-      changed
-      notify_observers(Time.now, @worker[:result], nil)
+      mutex.synchronize { @value = @worker[:result] }
     rescue Exception => ex
-      changed
-      notify_observers(Time.now, nil, ex)
+      # suppress
     ensure
+      changed
+      notify_observers(Time.now, self.value, ex)
       unless @worker.nil?
         Thread.kill(@worker)
         @worker = nil

data/lib/concurrent/version.rb

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

data/md/timer_task.md

@@ -1,36 +1,29 @@
-# To Gobbler's Knob. It's Groundhog Day.
+# To Gobbler's Knob. It's Groundhog Day!
 
 A very common currency pattern is to run a thread that performs a task at regular
 intervals. The thread that peforms the task sleeps for the given interval then
-waked up and performs the task. Later, rinse, repeat... This pattern causes two
+wakes up and performs the task. Lather, rinse, repeat... This pattern causes two
 problems. First, it is difficult to test the business logic of the task becuse the
-task itself is tightly couple with the threading. Second, an exception in the task
-can cause the entire thread to abend. In a long-running application where the task
-thread is intended to run for days/weeks/years a crashed task thread can pose a real
-problem. The `TimerTask` class alleviates both problems.
-
-When a TimerTask is launched it starts a thread for monitoring the execution interval.
-The TimerTask thread does not perform the task, however. Instead, the TimerTask
-launches the task on a separat thread. The advantage of this approach is that if
-the task crashes it will only kill the task thread, not the TimerTask thread. The
-TimerTask thread can then log the success or failure of the task. The TimerTask
-can even be configured with a timeout value allowing it to kill a task that runs
-to long and then log the error.
-
-One other advantage of the `TimerTask` class is that it forces the bsiness logic to
-be completely decoupled from the threading logic. The business logic can be tested
-separately then passed to the a TimerTask for scheduling and running.
-
-The `TimerTask` is the yin to to the
-[Supervisor's](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md)
-yang. Where the `Supervisor` is intended to manage long-running threads that operate
-continuously, the `TimerTask` is intended to manage fairly short operations that
-occur repeatedly at regular intervals.
-
-Unlike some of the others concurrency objects in the library, TimerTasks do not
-run on the global thread pool. In my experience the types of tasks that will benefit
-from the `TimerTask` class tend to also be long running. For this reason they get
-their own thread every time the task is executed.
+task itself is tightly coupled with the concurrency logic. Second, an exception in
+raised while performing the task can cause the entire thread to abend. In a
+long-running application where the task thread is intended to run for days/weeks/years
+a crashed task thread can pose a significant problem. `TimerTask` alleviates both problems.
+
+When a `TimerTask` is launched it starts a thread for monitoring the execution interval.
+The `TimerTask` thread does not perform the task, however. Instead, the TimerTask
+launches the task on a separate thread. Should the task experience an unrecoverable
+crash only the task thread will crash. This makes the `TimerTask` very fault tolerant
+Additionally, the `TimerTask` thread can respond to the success or failure of the task,
+performing logging or ancillary operations. `TimerTask` can also be configured with a
+timeout value allowing it to kill a task that runs too long.
+
+One other advantage of `TimerTask` is it forces the bsiness logic to be completely decoupled
+from the concurrency logic. The business logic can be tested separately then passed to the
+`TimerTask` for scheduling and running.
+
+Unlike other abstraction in this library, `TimerTask` does not run on the global thread pool.
+In my experience the types of tasks that will benefit from `TimerTask` tend to also be long
+running. For this reason they get their own thread every time the task is executed.
 
 ## Observation
 

data/spec/concurrent/scheduled_task_spec.rb

@@ -1,7 +1,6 @@
 require 'spec_helper'
 require 'timecop'
 require_relative 'obligation_shared'
-require_relative 'runnable_shared'
 
 module Concurrent
 
@@ -9,32 +8,21 @@ module Concurrent
 
     context 'behavior' do
 
-      # runnable
-
-      subject { ScheduledTask.new(0.5){ nil } }
-      it_should_behave_like :runnable
-
       # obligation
 
       let!(:fulfilled_value) { 10 }
       let!(:rejected_reason) { StandardError.new('mojo jojo') }
 
       let(:pending_subject) do
-        task = ScheduledTask.new(1){ fulfilled_value }
-        task.run!
-        task
+        ScheduledTask.new(1){ fulfilled_value }
       end
 
       let(:fulfilled_subject) do
-        task = ScheduledTask.new(0.1){ fulfilled_value }
-        task.run
-        task
+        ScheduledTask.new(0.1){ fulfilled_value }.tap(){ sleep(0.2) }
       end
 
       let(:rejected_subject) do
-        task = ScheduledTask.new(0.1){ raise rejected_reason }
-        task.run
-        task
+        ScheduledTask.new(0.1){ raise rejected_reason }.tap(){ sleep(0.2) }
       end
 
       it_should_behave_like :obligation
@@ -84,14 +72,12 @@ module Concurrent
 
       it 'returns false if the task has already been performed' do
         task = ScheduledTask.new(0.1){ 42 }
-        task.run!
         sleep(0.2)
         task.cancel.should be_false
       end
 
       it 'returns false if the task is already in progress' do
         task = ScheduledTask.new(0.1){ sleep(1); 42 }
-        task.run!
         sleep(0.2)
         task.cancel.should be_false
       end
@@ -99,7 +85,6 @@ module Concurrent
       it 'cancels the task if it has not yet started' do
         @expected = true
         task = ScheduledTask.new(0.3){ @expected = false }
-        task.run!
         sleep(0.1)
         task.cancel
         sleep(0.5)
@@ -108,44 +93,25 @@ module Concurrent
 
       it 'returns true on success' do
         task = ScheduledTask.new(0.3){ @expected = false }
-        task.run!
         sleep(0.1)
         task.cancel.should be_true
       end
 
       it 'sets the state to :cancelled when cancelled' do
         task = ScheduledTask.new(10){ 42 }
-        task.run!
         sleep(0.1)
         task.cancel
         task.should be_cancelled
       end
-
-      it 'stops the runnable' do
-        task = ScheduledTask.new(0.2){ 42 }
-        task.run!
-        sleep(0.1)
-        task.cancel
-        sleep(0.2)
-        task.should_not be_running
-      end
     end
 
     context 'execution' do
 
       it 'sets the state to :in_progress when the task is running' do
         task = ScheduledTask.new(0.1){ sleep(1); 42 }
-        task.run!
         sleep(0.2)
         task.should be_in_progress
       end
-
-      it 'stops itself on task completion' do
-        task = ScheduledTask.new(0.1){ 42 }
-        task.run!
-        sleep(0.2)
-        task.should_not be_running
-      end
     end
 
     context 'observation' do
@@ -167,13 +133,11 @@ module Concurrent
 
       it 'returns true for an observer added while :pending' do
         task = ScheduledTask.new(1){ 42 }
-        task.run!
         task.add_observer(observer).should be_true
       end
 
       it 'returns true for an observer added while :in_progress' do
         task = ScheduledTask.new(0.1){ sleep(1); 42 }
-        task.run!
         sleep(0.2)
         task.add_observer(observer).should be_true
       end
@@ -185,7 +149,6 @@ module Concurrent
 
       it 'returns false for an observer added once :cancelled' do
         task = ScheduledTask.new(1){ 42 }
-        task.run!
         sleep(0.1)
         task.cancel
         sleep(0.1)
@@ -194,14 +157,12 @@ module Concurrent
 
       it 'returns false for an observer added once :fulfilled' do
         task = ScheduledTask.new(0.1){ 42 }
-        task.run!
         sleep(0.2)
         task.add_observer(observer).should be_false
       end
 
       it 'returns false for an observer added once :rejected' do
         task = ScheduledTask.new(0.1){ raise StandardError }
-        task.run!
         sleep(0.2)
         task.add_observer(observer).should be_false
       end
@@ -209,7 +170,6 @@ module Concurrent
       it 'notifies all observers on fulfillment' do
         task = ScheduledTask.new(0.1){ 42 }
         task.add_observer(observer)
-        task.run!
         sleep(0.2)
         task.value.should == 42
         task.reason.should be_nil
@@ -220,7 +180,6 @@ module Concurrent
       it 'notifies all observers on rejection' do
         task = ScheduledTask.new(0.1){ raise StandardError }
         task.add_observer(observer)
-        task.run!
         sleep(0.2)
         task.value.should be_nil
         task.reason.should be_a(StandardError)
@@ -247,7 +206,6 @@ module Concurrent
       it 'does not notify an observer added after cancellation' do
         observer.should_not_receive(:update).with(any_args())
         task = ScheduledTask.new(0.5){ 42 }
-        task.run!
         sleep(0.1)
         task.cancel
         sleep(0.1)

data/spec/concurrent/timer_task_spec.rb

@@ -65,19 +65,6 @@ module Concurrent
           }.should raise_error
         end
 
-        it 'passes the options to the new TimerTask' do
-          opts = {
-            execution_interval: 100,
-            timeout_interval: 100,
-            run_now: false,
-            logger: proc{ nil },
-            block_args: %w[one two three]
-          }
-          @subject = TimerTask.new(opts){ nil }
-          TimerTask.should_receive(:new).with(opts).and_return(@subject)
-          Concurrent::TimerTask.run!(opts)
-        end
-
         it 'passes the block to the new TimerTask' do
           @expected = false
           block = proc{ @expected = true }
@@ -91,6 +78,30 @@ module Concurrent
           Thread.should_receive(:new).with(any_args()).and_return(thread)
           @subject = TimerTask.run!{ nil }
         end
+
+        specify '#execution_interval is writeable' do
+          @subject = TimerTask.new(execution_interval: 1) do |task|
+            task.execution_interval = 3
+          end
+          @subject.execution_interval.should == 1
+          @subject.execution_interval = 0.1
+          @subject.execution_interval.should == 0.1
+          @thread = Thread.new { @subject.run }
+          sleep(0.2)
+          @subject.execution_interval.should == 3
+        end
+
+        specify '#execution_interval is writeable' do
+          @subject = TimerTask.new(timeout_interval: 1, execution_interval: 0.1) do |task|
+            task.timeout_interval = 3
+          end
+          @subject.timeout_interval.should == 1
+          @subject.timeout_interval = 2
+          @subject.timeout_interval.should == 2
+          @thread = Thread.new { @subject.run }
+          sleep(0.2)
+          @subject.timeout_interval.should == 3
+        end
       end
     end
 
@@ -126,15 +137,14 @@ module Concurrent
         @expected.should be_true
       end
 
-      it 'passes any given arguments to the execution block' do
-        args = [1,2,3,4]
+      it 'passes a "self" reference to the block as the sole argument' do
         @expected = nil
-        @subject = TimerTask.new(execution_interval: 0.5, args: args) do |*args|
-          @expected = args
+        @subject = TimerTask.new(execution_interval: 1, run_now: true) do |task|
+          @expected = task
         end
         @thread = Thread.new { @subject.run }
-        sleep(1)
-        @expected.should eq args
+        sleep(0.2)
+        @expected.should eq @subject
       end
 
       it 'kills the worker thread if the timeout is reached' do

metadata

@@ -1,32 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: concurrent-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.1.pre.1
+  version: 0.3.1.pre.2
+  prerelease: 6
 platform: ruby
 authors:
 - Jerry D'Antonio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-03 00:00:00.000000000 Z
+date: 2013-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: |2
-      Modern concurrency tools including agents, futures, promises, thread pools, actors, supervisors, and more.
-      Inspired by Erlang, Clojure, Go, JavaScript, actors, and classic concurrency patterns.
+description: ! "    Modern concurrency tools including agents, futures, promises,
+  thread pools, actors, supervisors, and more.\n    Inspired by Erlang, Clojure, Go,
+  JavaScript, actors, and classic concurrency patterns.\n"
 email: jerry.dantonio@gmail.com
 executables: []
 extensions: []
@@ -95,29 +98,28 @@ files:
 homepage: http://www.concurrent-ruby.com
 licenses:
 - MIT
-metadata: {}
-post_install_message: |2
-      future = Concurrent::Future.new{ 'Hello, world!' }
-      puts future.value
-      #=> Hello, world!
+post_install_message: ! "    future = Concurrent::Future.new{ 'Hello, world!' }\n
+  \   puts future.value\n    #=> Hello, world!\n"
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>'
+  - - ! '>'
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.10
+rubygems_version: 1.8.24
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Modern concurrency tools including agents, futures, promises, thread pools,
   actors, and more.
 test_files:
@@ -143,3 +145,4 @@ test_files:
 - spec/concurrent/utilities_spec.rb
 - spec/spec_helper.rb
 - spec/support/functions.rb
+has_rdoc: 

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 86c7da12ad6b46036abb100e98a1450eda80fbb1
-  data.tar.gz: 43e1758062fd717a6e4a0c690890ef8149aa7b9e
-SHA512:
-  metadata.gz: 1d46489016358e9138bf0a627617ef780d2feb8e9a0d2b1f2a4ac1aa25ff8ec94dab7c72ad5c62743adc8d6ce36b0b119d80c3aa57724685aa33788e541f2aea
-  data.tar.gz: b482b8b50ee0217bb0ed13dcb8d3c91f58984d660f91240484d867f72e7583b87fcde09558beb1349ecff39ba88e9d9ddc44863cb91f14a74d4109cf1ebcac05