ruck 0.2.0 → 0.3.0

data/spec/shred_spec.rb

@@ -0,0 +1,116 @@
+
+require "ruck"
+
+include Ruck
+
+describe Shred do
+  context "when calling call" do
+    it "should execute the given block" do
+      $ran = false
+      @shred = Shred.new { $ran = true }
+      @shred.call
+      $ran.should == true
+    end
+    
+    it "should resume execution" do
+      $ran = 0
+      
+      @shred = Shred.new do
+        $ran = 1
+        Shred.current.pause
+        $ran = 2
+      end
+      
+      @shred.call
+      $ran.should == 1
+      @shred.call
+      $ran.should == 2
+    end
+    
+    it "should not mind if you run it too many times" do
+      @shred = Shred.new { }
+      @shred.call
+      @shred.call
+    end
+    
+    it "should not let you pause the wrong shred" do
+      @shred1 = Shred.new do
+        @shred2.call
+      end
+      @shred2 = Shred.new do
+        @shred1.pause
+        $shred2_ran = true
+      end
+      
+      $shred2_ran = false
+      @shred1.call
+      $shred2_ran.should be_true
+    end
+    
+    it "should let you use [] instead of #call" do
+      $ran = false
+      @shred = Shred.new { $ran = true }
+      @shred[]
+      $ran.should == true
+    end
+  end
+  
+  context "when killing" do
+    it "should not resume the next time you call it" do
+      $ran = 0
+      
+      @shred = Shred.new do
+        $ran = 1
+        Shred.current.pause
+        $ran = 2
+      end
+      
+      @shred.call
+      $ran.should == 1
+      @shred.kill
+      @shred.call
+      $ran.should == 1
+    end
+  end
+  
+  context "when checking finished? and running?" do
+    it "finished? should be false just after creation" do
+      @shred = Shred.new { }
+      @shred.finished?.should be_false
+      @shred.running?.should be_true
+    end
+    
+    it "finished? should be true just after executing the shred for the last time" do
+      pending "not yet supported in Ruby 1.9 because Fiber#alive? is missing"
+      @shred = Shred.new { }
+      @shred.call
+      @shred.finished?.should be_true
+      @shred.running?.should be_false
+    end
+    
+    it "finished? should be true just after killing the shred" do
+      @shred = Shred.new { }
+      @shred.kill
+      @shred.finished?.should be_true
+      @shred.running?.should be_false
+    end
+  end
+  
+  context "when calling a shred from a shred" do
+    it "should update Shred.current appropriately when the inner shred returns" do
+      @shred1 = Shred.new do
+        Shred.current.should == @shred1
+        @shred2.call
+        Shred.current.should == @shred1
+      end
+      @shred2 = Shred.new do
+        Shred.current.should == @shred2
+        $shred2_ran = true
+      end
+      
+      $shred2_ran = false
+      @shred1.call
+      $shred2_ran.should be_true
+    end
+  end
+end

data/spec/shreduler_spec.rb

@@ -0,0 +1,200 @@
+
+require "ruck"
+
+include Ruck
+
+class MockShred
+  def self.next_name
+    @@next_name ||= "a"
+    name = @@next_name
+    @@next_name = @@next_name.succ
+    name
+  end
+  
+  def initialize(runs_until_finished = 1, shreduler = nil)
+    @name = MockShred.next_name
+    @finished = false
+    @runs_until_finished = runs_until_finished
+    @shreduler = shreduler
+  end
+  
+  def inspect
+    "MockShred<#{@name}>"
+  end
+  
+  def call
+    $runs << self
+    @runs_until_finished -= 1
+    @finished = (@runs_until_finished == 0)
+    @shreduler.shredule(self) unless @finished || @shreduler == nil
+  end
+  
+  def finished?
+    @finished
+  end
+end
+
+describe Shreduler do
+  before(:each) do
+    @shreduler = Shreduler.new
+    $runs = []
+  end
+  
+  context "when calling run" do
+    # this is internal behavior, but should be tested as run_one is an important override point
+    it "should run the shred with run_one" do
+      @shreduler.should_receive(:run_one)
+      @shreduler.run
+    end
+    
+    context "with one shred" do
+      it "should run it" do
+        @shred = MockShred.new
+        @shreduler.shredule(@shred)
+        @shreduler.run
+        $runs.should == [@shred]
+      end
+      
+      it "should end up at the shred's shreduled time" do
+        @shred = MockShred.new
+        @shreduler.shredule(@shred, 3)
+        @shreduler.run
+        @shreduler.now.should == 3
+      end
+    end
+    
+    context "with multiple shreds" do
+      it "should run them in order if shreduled in order" do
+        @shreds = [MockShred.new, MockShred.new]
+        @shreduler.shredule(@shreds[0], 0)
+        @shreduler.shredule(@shreds[1], 1)
+        @shreduler.run
+        
+        $runs.should == [@shreds[0], @shreds[1]]
+      end
+      
+      it "should run them in order if shreduled out of order" do
+        @shreds = [MockShred.new, MockShred.new]
+        @shreduler.shredule(@shreds[1], 1)
+        @shreduler.shredule(@shreds[0], 0)
+        @shreduler.run
+        
+        $runs.should == [@shreds[0], @shreds[1]]
+      end
+      
+      it "should run them until they are finished" do
+        @shred = MockShred.new(5, @shreduler)
+        @shreduler.shredule(@shred, 0)
+        @shreduler.run
+        
+        $runs.should == (1..5).map { @shred }
+      end
+    end
+  end
+  
+  context "when calling run_one" do
+    it "should only run one shred" do
+      @shreds = [MockShred.new, MockShred.new]
+      @shreduler.shredule(@shreds[1], 1)
+      @shreduler.shredule(@shreds[0], 0)
+      @shreduler.run_one
+      
+      $runs.should == [@shreds[0]]
+    end
+    
+    # fast_forward is protected, but a crucial override point, so should be tested
+    it "should call fast_forward before executing the shred" do
+      $runs_when_fast_forward_triggered = nil
+      
+      @shreds = [MockShred.new]
+      @shreduler.shredule(@shreds[0], 1)
+      @shreduler.should_receive(:fast_forward).with(1).and_return { $runs_when_fast_forward_triggered = $runs.dup; nil }
+      @shreduler.run_one
+      
+      $runs_when_fast_forward_triggered.should == []
+    end
+  end
+  
+  context "when unshreduling" do
+    it "should work" do
+      @shred = MockShred.new
+      @shreduler.shredule(@shred)
+      @shreduler.unshredule(@shred)
+      @shreduler.run
+      $runs.should == []
+    end
+  end
+  
+  context "when convenient" do
+    before(:each) do
+      @shreduler = Shreduler.new
+      @shreduler.make_convenient
+    end
+    
+    context "when scheduling with spork" do
+      it "should let you schedule with spork" do
+        $ran = false
+        spork { $ran = true }
+        @shreduler.run
+        $ran.should be_true
+      end
+    end
+    
+    context "when scheduling with spork_loop" do
+      it "should let you schedule a looping shred with spork_loop" do
+        $ran = 0
+        spork_loop do
+          $ran += 1
+          if $ran == 3
+            Shred.current.kill
+          else
+            Shred.yield(1)
+          end
+        end
+        
+        @shreduler.run
+        $ran.should == 3
+      end
+      
+      it "should let you specify an amount to automatically yield after before run" do
+        $ran = 0
+        spork_loop(1) do
+          $ran += 1
+          Shred.current.kill if $ran == 3
+        end
+        
+        @shreduler.run
+        $ran.should == 3
+        @shreduler.now.should == 3
+      end
+    end
+    
+    context "when waiting on events" do
+      it "should let you wait with Shred.wait_on" do
+        $ran = false
+        spork do
+          Shred.wait_on(:booger)
+          $ran = true
+        end
+        @shreduler.run
+        $ran.should be_false
+        @shreduler.raise_all(:booger)
+        @shreduler.run
+        $ran.should be_true
+      end
+      
+      it "should let you raise an event with raise_event" do
+        $ran = false
+        spork do
+          Shred.wait_on(:booger)
+          $ran = true
+        end
+        @shreduler.run
+        $ran.should be_false
+        raise_event(:booger)
+        @shreduler.run
+        $ran.should be_true
+      end
+    end
+  end
+end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ruck
 version: !ruby/object:Gem::Version 
+  hash: 19
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Tom Lieber
@@ -14,26 +15,58 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-10 00:00:00 -07:00
+date: 2010-08-15 00:00:00 -07:00
 default_executable: 
-dependencies: []
-
-description: "      Ruck uses continuations and a simple scheduler to ensure \"shreds\"\n      (Ruck threads) are woken at precisely the right time according\n      to its virtual clock. Schedulers can map virtual time to samples\n      in a WAV file, real time, time in a MIDI file, or anything else\n      by overriding \"sim_to\" in the Shreduler class.\n"
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: PriorityQueue
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: "      Ruck uses continuations and a simple scheduler to ensure \"shreds\"\n      (Ruck threads) are woken at precisely the right time according\n      to its virtual clock. Schedulers can map virtual time to samples\n      in a WAV file, real time, time in a MIDI file, or anything else\n      by overriding \"sim_to\" in the Shreduler class.\n      \n      A small library of useful unit generators and plenty of examples\n      are provided. See the README or the web page for details.\n"
 email: tom@alltom.com
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- README
+- LICENSE
+- README.markdown
 files: 
 - .gitignore
-- README
+- LICENSE
+- README.markdown
 - Rakefile
 - VERSION
+- examples/ex01.rb
+- examples/ex02.rb
+- examples/ex03.rb
+- examples/ex04.rb
+- examples/ex05.rb
+- examples/ex06.rb
+- examples/space/media/Beep.wav
+- examples/space/media/Space.png
+- examples/space/media/Star.png
+- examples/space/media/Starfighter.bmp
+- examples/space/space.rb
 - lib/ruck.rb
-- lib/ruck/shreduling.rb
+- lib/ruck/clock.rb
+- lib/ruck/event_clock.rb
+- lib/ruck/shred.rb
+- lib/ruck/shreduler.rb
 - ruck.gemspec
+- spec/clock_spec.rb
+- spec/shred_spec.rb
+- spec/shreduler_spec.rb
 has_rdoc: true
 homepage: http://github.com/alltom/ruck
 licenses: []
@@ -44,25 +77,38 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: "strong timing for Ruby: cooperative threads on a virtual clock"
-test_files: []
-
+test_files: 
+- spec/clock_spec.rb
+- spec/shred_spec.rb
+- spec/shreduler_spec.rb
+- examples/ex01.rb
+- examples/ex02.rb
+- examples/ex03.rb
+- examples/ex04.rb
+- examples/ex05.rb
+- examples/ex06.rb
+- examples/space/space.rb

data/README

@@ -1,48 +0,0 @@
-A port of ChucK's strong timing to Ruby!
-
-ruck lets you easily create a virtual clock against
-which precise timing of execution can be guaranteed. The
-virtual clock can be kept roughly in sync with real time
-if you want it to, but you don't have to. For example, in
-ChucK, even if your scripts take too long to generate
-samples in real time, the audio stream isn't compromised
-because it's timed against the virtual clock.
-
-ruck provides an easily extended scheduler for non-preemptive
-shreds (threads) implemented using continuations.
-Cooperatively scheduled threads usually don't require
-synchronization since execution is never interrupted.
-
-A few example shredulers (schedulers) are provided:
-
-UGenShreduler:
-
-  Recently moved to its own gem: ruck-ugen
-
-RealTimeShreduler
-
-  Recently moved to its own gem: ruck-realtime
-
-MIDIShreduler
-
-  Recently moved to its own gem: ruck-midi
-
-GLAppShreduler
-
-  You don't want to know. But see ruck-glapp if you do.
-
-USAGE
-=====
-
-This project has tons of examples because even though the library
-is tiny, there's a lot to test, and a lot of ways to use it.
-
-For examples of how to implement your own Shreduler, see the bottom
-of lib/ruck/shreduling.rb and all the scripts in bin/.
-
-For example of how to use the provided Shredulers, check the
-examples/ directory. Those scripts contain no boilerplate includes
-because they are written to be invoked on the command line by
-one of the bin/ scripts. For example:
-
-  $ ruck_ugen examples/ugen/ex01.rb