ruck 0.2.0 → 0.3.0

data/lib/ruck/event_clock.rb

@@ -0,0 +1,39 @@
+
+module Ruck
+  class EventClock
+    attr_reader :now
+    
+    def initialize
+      @now = 0
+      @waiting = Hash.new { |hash, event| hash[event] = [] }
+      @raised = []
+    end
+    
+    # fast-forward this clock by the given time delta
+    def fast_forward(dt)
+      @now += dt
+    end
+    
+    def schedule(obj, event = nil)
+      @waiting[event] << obj
+    end
+    
+    def unschedule(obj)
+      @waiting.each { |event, objs| objs.delete(obj) }
+      @raised.delete(obj)
+    end
+    
+    def next
+      [@raised.first, 0] if @raised.length > 0
+    end
+    
+    def unschedule_next
+      [@raised.shift, 0] if @raised.length > 0
+    end
+    
+    def raise_all(event)
+      @raised += @waiting[event]
+      @waiting[event].clear
+    end
+  end
+end

data/lib/ruck/shred.rb

@@ -0,0 +1,135 @@
+
+module Ruck
+  
+  # A resumable Proc implemented using continuation. If the given
+  # block calls #pause during its execution, its execution is paused
+  # and the caller resumed. The second time the Shred is called, it
+  # resumes where it left off.
+  # 
+  # If #pause is called anywhere but inside the given block, I can
+  # almost guarantee that strange things will happen.
+  
+  class CallccShred
+    # I don't mean to actually expose @proc. I noticed that Ruby 1.8's
+    # garbage collection cycles become much longer when @proc (a
+    # Continuation) is returned from a custom method, but not
+    # if returned from an attr_reader. I use attr_reader and alias it
+    # to running? to avoid this cost.
+    attr_reader :proc
+    alias running? proc
+    
+    @@current_shreds = []
+    
+    # the currently executing shred
+    def self.current
+      @@current_shreds.last
+    end
+    
+    def initialize(&block)
+      @proc = block || Proc.new{}
+    end
+    
+    # pause execution by saving this execution point and returning
+    # to the point where go was called
+    def pause
+      return unless Shred.current == self
+      
+      @@current_shreds.pop
+      
+      callcc do |cont|
+        @proc = cont
+        @caller.call
+      end
+    end
+    
+    # begin or resume execution
+    def call(*args)
+      return unless @proc
+      
+      callcc do |cont|
+        @caller = cont
+        
+        @@current_shreds << self
+        @proc.call
+        
+        # if we made it here, we're done
+        @@current_shreds.pop
+        @proc = nil
+        @caller.call
+      end
+    end
+    
+    # alias for call. It takes arguments, but ignores them.
+    def [](*args)
+      call(*args)
+    end
+    
+    # returns true if calling this Shred again will have no effect
+    def finished?
+      !running?
+    end
+    
+    # makes it so calling this Shred in the future will have no effect
+    def kill
+      @proc = nil
+    end
+  end
+  
+  # See the documentation for CallccShred
+  class FiberShred
+    @@current_shreds = []
+    
+    def self.current
+      @@current_shreds.last
+    end
+    
+    def initialize(&block)
+      @fiber = Fiber.new(&block)
+    end
+    
+    def pause
+      return unless Shred.current == self
+      
+      @@current_shreds.pop
+      
+      Fiber.yield
+    end
+    
+    def call(*args)
+      return unless @fiber
+      @@current_shreds << self
+      @fiber.resume
+    rescue FiberError
+      @fiber = nil
+    ensure
+      @@current_shreds.pop
+    end
+    
+    def [](*args)
+      call(*args)
+    end
+    
+    def finished?
+      @fiber.nil?
+    end
+    
+    def running?
+      !finished?
+    end
+    
+    def kill
+      @fiber = nil
+    end
+  end
+  
+  # Fiber was introduced in Ruby 1.9 and supports a cleaner implementation
+  # of Shred than the callcc-based version, but I would like to support
+  # Ruby 1.8 as well.
+  if defined? Fiber
+    class Shred < FiberShred
+    end
+  else
+    class Shred < CallccShred
+    end
+  end
+end

data/lib/ruck/shreduler.rb

@@ -0,0 +1,149 @@
+
+module Ruck
+  class Shreduler
+    attr_reader :clock
+    attr_reader :event_clock
+    
+    def initialize
+      @clock = Clock.new
+      @event_clock = EventClock.new
+      @clock.add_child_clock(@event_clock)
+    end
+    
+    # this Shreduler's idea of the current time
+    def now
+      @clock.now
+    end
+    
+    # schedules the given Shred at the given time, on the given Clock.
+    # if no time is given, it is scheduled for immediate execution.
+    # if no Clock is given, it is scheduled on the default Clock.
+    def shredule(shred, time = nil, clock = nil)
+      (clock || @clock).schedule(shred, time)
+      shred
+    end
+    
+    # unschedules the provided Shred
+    def unshredule(shred)
+      @clock.unschedule(shred)
+    end
+    
+    # wakes up all Shreds waiting on the given event
+    def raise_all(event)
+      event_clock.raise_all(event)
+    end
+    
+    # runs the next scheduled Shred, if one exists, returning that Shred
+    def run_one
+      shred, relative_time = @clock.unschedule_next
+      return nil unless shred
+      
+      fast_forward(relative_time) if relative_time > 0
+      invoke_shred(shred)
+    end
+    
+    # runs until all Shreds have died, or are all waiting on events
+    def run
+      loop { return unless run_one }
+    end
+    
+    # runs shreds until the given target time, then fast-forwards to
+    # that time
+    def run_until(target_time)
+      return if target_time < now
+      
+      loop do
+        shred, relative_time = next_shred
+        break unless shred
+        break unless now + relative_time <= target_time
+        run_one
+      end
+      
+      # I hope rounding errors are okay
+      fast_forward(target_time - now)
+    end
+    
+    # makes this the global shreduler, adding convenience methods to
+    # Object and Shred to make it easier to use
+    def make_convenient
+      $shreduler = self
+      
+      Shred.module_eval do
+        class << self
+          include ShredConvenienceMethods
+        end
+      end
+      Object.module_eval { include ObjectConvenienceMethods }
+    end
+    
+    protected
+      
+      def invoke_shred(shred)
+        begin
+          shred.call
+        rescue Exception => e
+          puts e.inspect
+        end
+        shred
+      end
+      
+      # if you override this method, you should probably call super
+      def fast_forward(dt)
+        @clock.fast_forward(dt)
+      end
+      
+      def next_shred
+        clock.next
+      end
+  end
+  
+  module ShredConvenienceMethods
+    # yields the given amount of time on the global Shreduler, using the
+    # provided Clock if given
+    def yield(dt, clock = nil)
+      clock ||= $shreduler.clock
+      $shreduler.shredule(Shred.current, clock.now + dt, clock)
+      Shred.current.pause
+    end
+    
+    # sleeps, waiting on the given event on the default EventClock of
+    # the global Shreduler
+    def wait_on(event)
+      $shreduler.shredule(Shred.current, event, $shreduler.event_clock)
+      Shred.current.pause
+    end
+  end
+  
+  module ObjectConvenienceMethods
+    # creates a new Shred with the given block on the global Shreduler
+    def spork(&block)
+      $shreduler.shredule(Shred.new(&block))
+    end
+    
+    # creates a new Shred with the given block on the global Shreduler,
+    # automatically surrounded by loop { }. If the delay_or_event parameter
+    # is given, a Shred.yield(delay) or Shred.wait_on(event) is inserted
+    # before the call to your block.
+    def spork_loop(delay_or_event = nil, clock = nil, &block)
+      shred = Shred.new do
+        while Shred.current.running?
+          if delay_or_event
+            if delay_or_event.is_a?(Numeric)
+              Shred.yield(delay_or_event, clock)
+            else
+              Shred.wait_on(delay_or_event)
+            end
+          end
+          
+          block.call
+        end
+      end
+      $shreduler.shredule(shred)
+    end
+    
+    # raises an event on the default EventClock of the global Shreduler.
+    def raise_event(event)
+      $shreduler.event_clock.raise_all(event)
+    end
+  end
+end

data/ruck.gemspec

@@ -5,44 +5,81 @@
 
 Gem::Specification.new do |s|
   s.name = %q{ruck}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tom Lieber"]
-  s.date = %q{2010-07-10}
+  s.date = %q{2010-08-15}
   s.description = %q{      Ruck uses continuations and a simple scheduler to ensure "shreds"
       (Ruck threads) are woken at precisely the right time according
       to its virtual clock. Schedulers can map virtual time to samples
       in a WAV file, real time, time in a MIDI file, or anything else
       by overriding "sim_to" in the Shreduler class.
+      
+      A small library of useful unit generators and plenty of examples
+      are provided. See the README or the web page for details.
 }
   s.email = %q{tom@alltom.com}
   s.extra_rdoc_files = [
-    "README"
+    "LICENSE",
+     "README.markdown"
   ]
   s.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",
-     "ruck.gemspec"
+     "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"
   ]
   s.homepage = %q{http://github.com/alltom/ruck}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{strong timing for Ruby: cooperative threads on a virtual clock}
+  s.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"
+  ]
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<PriorityQueue>, [">= 0"])
     else
+      s.add_dependency(%q<PriorityQueue>, [">= 0"])
     end
   else
+    s.add_dependency(%q<PriorityQueue>, [">= 0"])
   end
 end
 

data/spec/clock_spec.rb

@@ -0,0 +1,218 @@
+
+require "ruck"
+
+include Ruck
+
+class MockOccurrenceObj
+  def self.next_name
+    @@next_name ||= "a"
+    name = @@next_name
+    @@next_name = @@next_name.succ
+    name
+  end
+  
+  def initialize
+    @name = MockOccurrenceObj.next_name
+  end
+  
+  def inspect
+    "MockOccurrenceObj<#{@name}>"
+  end
+end
+
+describe Clock do
+  before(:each) do
+    @clock = Clock.new
+    @clocks = [@clock]
+  end
+  
+  context "when creating" do
+    it "starts with now = 0" do
+      Clock.new.now.should == 0
+    end
+  end
+  
+  context "when fast-forwarding" do
+    it "works" do
+      @clock.fast_forward(1)
+      @clock.now.should == 1
+      @clock.fast_forward(1)
+      @clock.now.should == 2
+    end
+  end
+  
+  context "when scheduling" do
+    it "should default to using the current time" do
+      @clock.fast_forward(3)
+      @occurrence = MockOccurrenceObj.new
+      @clock.schedule(@occurrence)
+      @clock.next.should == [@occurrence, 0]
+    end
+    
+    it "should use the given time if provided" do
+      @clock.fast_forward(3)
+      @occurrence = MockOccurrenceObj.new
+      @clock.schedule(@occurrence, 5)
+      @clock.next.should == [@occurrence, 2]
+    end
+    
+    context "with no occurrences" do
+      it "next should be nil" do
+        @clock.next.should == nil
+      end
+    end
+    
+    context "with multiple occurrences" do
+      before(:each) do
+        @next_occurrence = MockOccurrenceObj.new
+        @occurrence_after = MockOccurrenceObj.new
+        @clock.schedule(@occurrence_after, 2)
+        @clock.schedule(@next_occurrence, 1)
+      end
+      
+      it "knows the next scheduled occurrence" do
+        @clock.next.should == [@next_occurrence, 1]
+      end
+      
+      it "can dequeue the next scheduled occurrence" do
+        @clock.unschedule_next.should == [@next_occurrence, 1]
+        @clock.next.should == [@occurrence_after, 2]
+      end
+      
+      it "can enqueue and dequeue a new occurrence" do
+        @last_occurrence = MockOccurrenceObj.new
+        @clock.schedule(@last_occurrence, 3)
+        @clock.unschedule_next.should == [@next_occurrence, 1]
+        @clock.unschedule_next.should == [@occurrence_after, 2]
+        @clock.next.should == [@last_occurrence, 3]
+      end
+      
+      it "can interleavedly enqueue and dequeue a new occurrence" do
+        @last_occurrence = MockOccurrenceObj.new
+        @clock.unschedule_next.should == [@next_occurrence, 1]
+        @clock.schedule(@last_occurrence, 1)
+        @clock.unschedule_next.should == [@last_occurrence, 1]
+        @clock.next.should == [@occurrence_after, 2]
+      end
+    end
+  end
+  
+  context "with sub-clocks" do
+    before do
+      # clock/clocks[0]
+      # - clocks[1] x1
+      # - clocks[2] x2
+      #   - clocks[3] x2
+      @clocks << @clock.add_child_clock(Clock.new(1))
+      @clocks << @clock.add_child_clock(Clock.new(2))
+      @clocks << @clocks[2].add_child_clock(Clock.new(2))
+    end
+    
+    context "when fast-forwarding" do
+      it "fast-forwards children clocks" do
+        @clock.fast_forward(1)
+        @clocks[1].now.should == 1
+        @clocks[2].now.should == 2
+        @clocks[3].now.should == 4
+      end
+    end
+    
+    context "when finding the next occurrence" do
+      it "should return the correct time offset" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[2].schedule(@occurrence, 4)
+        @clock.next.should == [@occurrence, 2]
+      end
+      
+      it "should return the correct time offset in a sub-clock 2 levels deep" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[3].schedule(@occurrence, 8)
+        @clock.next.should == [@occurrence, 2]
+      end
+      
+      it "should return the correct time offset after a fast-forward" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[2].schedule(@occurrence, 4)
+        @clock.fast_forward(1)
+        @clock.next.should == [@occurrence, 1]
+      end
+      
+      it "should return the correct time offset in a sub-clock 2 levels deep after a fast-forward" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[3].schedule(@occurrence, 8)
+        @clock.fast_forward(1)
+        @clock.next.should == [@occurrence, 1]
+      end
+    end
+    
+    context "when dequeuing the next occurrence" do
+      it "should work when the occurrence is on the parent clock" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[0].schedule(@occurrence, 4)
+        @clock.unschedule_next.should == [@occurrence, 4]
+      end
+      
+      it "should work when the occurrence is one clock deep" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[1].schedule(@occurrence, 4)
+        @clock.unschedule_next.should == [@occurrence, 4]
+      end
+      
+      it "should work when the occurrence is one clock deep and account for rate" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[2].schedule(@occurrence, 4)
+        @clock.unschedule_next.should == [@occurrence, 2]
+      end
+      
+      it "should work when the occurrence is two clocks deep and account for rate" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[3].schedule(@occurrence, 4)
+        @clock.unschedule_next.should == [@occurrence, 1]
+      end
+    end
+  end
+  
+  context "when dequeuing occurrences" do
+    it "should work" do
+      @occurrence = MockOccurrenceObj.new
+      @clock.schedule(@occurrence, 2)
+      @clock.unschedule(@occurrence).should == 2
+    end
+    
+    context "with sub-clocks" do
+      before(:each) do
+        # clock/clocks[0]
+        # - clocks[1] x1
+        # - clocks[2] x2
+        #   - clocks[3] x2
+        @clocks << @clock.add_child_clock(Clock.new(1))
+        @clocks << @clock.add_child_clock(Clock.new(2))
+        @clocks << @clocks[2].add_child_clock(Clock.new(2))
+      end
+      
+      it "should work with the parent clock" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[0].schedule(@occurrence, 2)
+        @clocks[0].unschedule(@occurrence).should == 2
+      end
+      
+      it "should work one clock deep" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[1].schedule(@occurrence, 2)
+        @clocks[0].unschedule(@occurrence).should == 2
+      end
+      
+      it "should work one clock deep and adjust for rate" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[2].schedule(@occurrence, 2)
+        @clocks[0].unschedule(@occurrence).should == 1
+      end
+      
+      it "should work two clocks deep and adjust for rate" do
+        @occurrence = MockOccurrenceObj.new
+        @clocks[3].schedule(@occurrence, 4)
+        @clocks[0].unschedule(@occurrence).should == 1
+      end
+    end
+  end
+end