strand 0.1.0 → 0.2.0.rc0

data/spec/strand/pass.rb

@@ -0,0 +1,9 @@
+
+shared_examples_for "Strand#pass" do
+
+    describe "pass" do
+        it "returns nil" do
+            Strand.pass.should == nil
+        end
+    end
+end

data/spec/strand/queue.rb

@@ -0,0 +1,124 @@
+shared_examples_for "a queue" do
+
+    # These specs are derived from rubyspec for ruby's standard Queue class
+
+    context :enqueue do
+
+        it "adds an element to the Queue" do
+            q = Strand::Queue.new
+            q.size.should == 0
+            q << Object.new
+            q.size.should == 1
+            q.push(Object.new)
+            q.size.should == 2
+            q.enq(Object.new)
+            q.size.should == 3
+        end
+
+    end
+
+    context :dequeue do
+        it "removes an item from the Queue" do
+            q = Strand::Queue.new
+            q << Object.new
+            q.size.should == 1
+            q.pop
+            q.size.should == 0
+        end
+
+        it "returns items in the order they were added" do
+            q = Strand::Queue.new
+            q << 1
+            q << 2
+            q.deq.should == 1
+            q.shift.should == 2
+        end
+
+        it "blocks until there are items in the queue" do
+            q = Strand::Queue.new
+            v = 0
+
+            s = Strand.new do
+                q.pop
+                v = 1
+            end
+
+            v.should == 0
+            q << Object.new
+            s.join()
+            v.should == 1
+        end
+
+        it "raises a StrandError if Queue is empty" do
+            q = Strand::Queue.new
+            lambda { q.pop(true) }.should raise_error(strand_exception)
+        end
+    end
+
+    context :length do
+        it "returns the number of elements" do
+            q = Strand::Queue.new
+            q.length.should == 0
+            q << Object.new
+            q << Object.new
+            q.length.should == 2
+        end
+    end
+
+    context :empty do
+        it "returns true on an empty Queue" do
+            q = Strand::Queue.new
+            q.empty?.should be_true
+        end
+
+        it "returns false when Queue is not empty" do
+            q = Strand::Queue.new
+            q << Object.new
+            q.empty?.should be_false
+        end
+    end
+
+    context :num_waiting do
+        it "reports the number of Strands waiting on the Queue" do
+            q = Strand::Queue.new
+            fibers = []
+
+            5.times do |i|
+                q.num_waiting.should == i
+                f = Strand.new { q.deq }
+                Strand.pass until f.status and f.status == 'sleep'
+                fibers << f
+            end
+
+            fibers.each { q.enq Object.new }
+
+            fibers.each { |f| Strand.pass while f.alive? }
+
+            q.num_waiting.should == 0
+        end
+    end
+
+    context :doc_example do
+        it "handles the doc example" do
+            queue = Strand::Queue.new
+
+            producer = Strand.new do
+                5.times do |i|
+                    Strand.sleep rand(i/4) # simulate expense
+                    queue << i
+                    puts "#{i} produced"
+                end            
+            end
+
+            consumer = Strand.new do
+                5.times do |i|
+                    value = queue.pop
+                    Strand.sleep rand(i/8) # simulate expense
+                    puts "consumed #{value}"
+                end            
+            end
+
+            consumer.join
+        end
+    end
+end

data/spec/strand/raise.rb

@@ -0,0 +1,142 @@
+shared_examples_for "Strand#raise" do
+    context :raise do
+        it "ignores dead strands" do
+            t = Strand.new { :dead }
+            Strand.pass while t.alive?
+            lambda {t.raise("Kill the strand")}.should_not raise_error
+            lambda {t.value}.should_not raise_error
+        end
+    end
+
+    context "raise on a sleeping strand" do
+        before :each do
+            ScratchPad.clear
+            @str = StrandSpecs.sleeping_strand
+            Strand.pass while @str.status and @str.status != "sleep"
+        end
+
+        after :each do
+            @str.kill
+        end
+
+        it "raises a RuntimeError if no exception class is given" do
+            @str.raise
+            Strand.pass while @str.status
+            ScratchPad.recorded.should be_kind_of(RuntimeError)
+        end
+
+        it "raises the given exception" do
+            @str.raise Exception
+            Strand.pass while @str.status
+            ScratchPad.recorded.should be_kind_of(Exception)
+        end
+
+        it "raises the given exception with the given message" do
+            @str.raise Exception, "get to work"
+            Strand.pass while @str.status
+            ScratchPad.recorded.should be_kind_of(Exception)
+            ScratchPad.recorded.message.should == "get to work"
+        end
+
+        it "is captured and raised by Strand#value" do
+            t = Strand.new do
+                Strand.sleep
+            end
+
+            StrandSpecs.spin_until_sleeping(t)
+
+            t.raise
+            lambda { t.value }.should raise_error(RuntimeError)
+        end
+
+        it "raises a RuntimeError when called with no arguments" do
+            t = Strand.new do
+                begin
+                    1/0
+                rescue ZeroDivisionError
+                    Strand.sleep 3
+                end
+            end
+            begin
+                raise RangeError
+            rescue
+                StrandSpecs.spin_until_sleeping(t)
+                t.raise
+            end
+            lambda {t.value}.should raise_error(RuntimeError)
+            t.kill
+        end
+    end
+
+    #TODO do these make sense?
+    quarantine! do
+
+        context "Strand#raise on a running strand" do
+            before :each do
+                ScratchPad.clear
+                StrandSpecs.clear_state
+
+                @str = StrandSpecs.running_strand
+                Strand.pass until StrandSpecs.state == :running
+            end
+
+            after :each do
+                @str.kill
+            end
+
+            it "raises a RuntimeError if no exception class is given" do
+                @str.raise
+                Strand.pass while @str.status
+                ScratchPad.recorded.should be_kind_of(RuntimeError)
+            end
+
+            it "raises the given exception" do
+                @str.raise Exception
+                Strand.pass while @str.status
+                ScratchPad.recorded.should be_kind_of(Exception)
+            end
+
+            it "raises the given exception with the given message" do
+                @str.raise Exception, "get to work"
+                Strand.pass while @str.status
+                ScratchPad.recorded.should be_kind_of(Exception)
+                ScratchPad.recorded.message.should == "get to work"
+            end
+
+            it "can go unhandled" do
+                t = Strand.new do
+                    loop {}
+                end
+
+                t.raise
+                lambda {t.value}.should raise_error(RuntimeError)
+            end
+
+            it "raise the given argument even when there is an active exception" do
+                raised = false
+                t = Strand.new do
+                    begin
+                        1/0
+                    rescue ZeroDivisionError
+                        raised = true
+                        loop { }
+                    end
+                end
+                begin
+                    raise "Create an active exception for the current strand too"
+                rescue
+                    Strand.pass until raised || !t.alive?
+                    t.raise RangeError
+                    lambda {t.value}.should raise_error(RangeError)
+                end
+            end
+
+        end
+    end
+    #TODO find out what the spec for :kernel_raise is
+    quarantine! do
+        context "Strand#raise on same strand" do
+            it_behaves_like :kernel_raise, :raise, Strand.current
+        end
+    end
+end

data/spec/strand/run.rb

@@ -0,0 +1,5 @@
+
+describe "Thread#run" do
+  it_behaves_like :thread_wakeup, :run
+end
+

data/spec/strand/shared.rb

@@ -0,0 +1,14 @@
+
+require 'strand/strand'
+require 'strand/local_storage'
+require 'strand/mutex'
+require 'strand/queue'
+require 'strand/condition_variable'
+
+shared_examples_for Strand do
+    it_behaves_like "a strand"
+    it_behaves_like "strand local storage"
+    it_behaves_like "a mutex"
+    it_behaves_like "a queue"
+    it_behaves_like "a condition variable"
+end

data/spec/strand/sleep.rb

@@ -0,0 +1,51 @@
+
+shared_examples_for "Strand#sleep" do
+    context "sleep" do
+        it "pauses execution for approximately the duration requested" do
+            duration = 0.1
+            start = Time.now
+            Strand.sleep duration
+            (Time.now - start).should be_within(0.1).of(duration)
+        end
+
+        it "returns the rounded number of seconds asleep" do
+            Strand.sleep(0.01).should be_kind_of(Integer)
+        end
+        it "raises a TypeError when passed a non-numeric duration" do
+            # Kernel.sleep raises error for nil, Strand.sleep will sleep forever
+            #lambda { Strand.sleep(nil)   }.should raise_error(TypeError)
+            lambda { Strand.sleep('now') }.should raise_error(TypeError)
+            lambda { Strand.sleep('2')   }.should raise_error(TypeError)
+        end
+
+        it "pauses execution indefinitely if not given a duration" do
+            lock = Strand::Queue.new
+            t = Strand.new do
+                lock << :ready
+                Strand.sleep
+                5
+            end
+            lock.shift.should == :ready
+            # wait until the thread has gone to sleep
+            Strand.pass while t.status and t.status != "sleep"
+            t.run
+            t.value.should == 5
+        end
+       
+        # Strand.sleep handles nil differently to kernel.sleep 
+        it "pauses execution indefinitely if given a nil duration" do
+            lock = Strand::Queue.new
+            t = Strand.new do
+                lock << :ready
+                Strand.sleep(nil)
+                5
+            end
+            lock.shift.should == :ready
+            # wait until the thread has gone to sleep
+            Strand.pass while t.status and t.status != "sleep"
+            t.run
+            t.value.should == 5
+        end
+        it "needs to be reviewed for spec completeness"
+    end
+end

data/spec/strand/status.rb

@@ -0,0 +1,44 @@
+shared_examples_for "Strand#status" do
+    context :status do
+        it "can check it's own status" do
+            StrandSpecs.status_of_current_strand.status.should == 'run'
+        end
+
+        quarantine! do
+            # There's no way to interact with a running strand from another strand
+            it "describes a running strand" do
+                StrandSpecs.status_of_running_strand.status.should == 'run'
+            end
+        end
+
+        it "describes a sleeping strand" do
+            StrandSpecs.status_of_sleeping_strand.status.should == 'sleep'
+        end
+
+        it "describes a blocked strand" do
+            StrandSpecs.status_of_blocked_strand.status.should == 'sleep'
+        end
+
+        it "describes a completed strand" do
+            StrandSpecs.status_of_completed_strand.status.should == false
+        end
+
+        it "describes a killed strand" do
+            StrandSpecs.status_of_killed_strand.status.should == false
+        end
+
+        it "describes a strand with an uncaught exception" do
+            StrandSpecs.status_of_strand_with_uncaught_exception.status.should == nil
+        end
+
+        it "describes a dying sleeping strand" do
+            StrandSpecs.status_of_dying_sleeping_strand.status.should == 'sleep'
+        end
+
+        quarantine! do
+            it "reports aborting on a killed strand" do
+                StrandSpecs.status_of_aborting_strand.status.should == 'aborting'
+            end
+        end
+    end
+end

data/spec/strand/stop.rb

@@ -0,0 +1,58 @@
+
+shared_examples_for "Strand#stop" do
+
+    context :stop  do
+        it "causes the current strand to sleep indefinitely" do
+            t = Strand.new { Strand.stop; 5 }
+            Strand.pass while t.status and t.status != 'sleep'
+            t.status.should == 'sleep'
+            t.run
+            t.value.should == 5
+        end
+    end
+
+    context "stop?" do
+        it "can check it's own status" do
+            StrandSpecs.status_of_current_strand.stop?.should == false
+        end
+        quarantine! do
+            #Can't really have a running strand
+            it "describes a running strand" do
+                StrandSpecs.status_of_running_strand.stop?.should == false
+            end
+        end
+        it "describes a sleeping strand" do
+            StrandSpecs.status_of_sleeping_strand.stop?.should == true
+        end
+
+        it "describes a blocked strand" do
+            StrandSpecs.status_of_blocked_strand.stop?.should == true
+        end
+
+        it "describes a completed strand" do
+            StrandSpecs.status_of_completed_strand.stop?.should == true
+        end
+
+        it "describes a killed strand" do
+            StrandSpecs.status_of_killed_strand.stop?.should == true
+        end
+
+        it "describes a strand with an uncaught exception" do
+            StrandSpecs.status_of_strand_with_uncaught_exception.stop?.should == true
+        end
+
+        it "describes a dying running strand" do
+            StrandSpecs.status_of_dying_running_strand.stop?.should == false
+        end
+
+        it "describes a dying sleeping strand" do
+            StrandSpecs.status_of_dying_sleeping_strand.stop?.should == true
+        end
+
+        quarantine! do
+            it "reports aborting on a killed strand" do
+                StrandSpecs.status_of_aborting_strand.stop?.should == false
+            end
+        end
+    end
+end