strand 0.1.0 → 0.2.0.rc0

data/spec/strand/exit.rb

@@ -0,0 +1,148 @@
+
+shared_examples_for "Strand#exit"  do
+
+    context :exit do
+        it "kills sleeping strand" do
+            sleeping_strand = Strand.new do
+                Strand.sleep
+                ScratchPad.record :after_sleep
+            end
+            sleeping_strand.exit
+            sleeping_strand.join
+            ScratchPad.recorded.should == nil
+        end
+
+        it "kills current strand" do
+            strand = Strand.new do
+                Strand.current.kill
+                ScratchPad.record :after_sleep
+            end
+            strand.join
+            ScratchPad.recorded.should == nil
+        end
+
+        it "runs ensure clause" do
+            strand = StrandSpecs.dying_strand_ensures(:kill) { ScratchPad.record :in_ensure_clause }
+            strand.join
+            ScratchPad.recorded.should == :in_ensure_clause
+        end
+
+        quarantine! do
+            # >1.9.2 has this as undefined
+            it "runs nested ensure clauses" do
+                ScratchPad.record []
+                outer = Strand.new do
+                    begin
+                        inner = Strand.new do
+                            begin
+                                Strand.sleep
+                            ensure
+                                ScratchPad << :inner_ensure_clause
+                            end
+                        end
+                        Strand.sleep
+                    ensure
+                        ScratchPad << :outer_ensure_clause
+                        Strand.pass while inner.status and inner.status != "sleep"
+                        # exit is private for thread, but not for em::thread
+                        inner.terminate
+                        inner.join
+                    end
+                end
+                outer.terminate
+                outer.join
+                ScratchPad.recorded.should include(:inner_ensure_clause)
+                ScratchPad.recorded.should include(:outer_ensure_clause)
+            end
+        end
+        it "does not set $!" do
+            strand = StrandSpecs.dying_strand_ensures(:kill) { ScratchPad.record $! }
+            strand.join
+            ScratchPad.recorded.should == nil
+        end
+
+        it "cannot be rescued" do
+            strand = Strand.new do
+                begin
+                    Strand.current.kill
+                rescue Exception
+                    ScratchPad.record :in_rescue
+                end
+                ScratchPad.record :end_of_strand_block
+            end
+
+            strand.join
+            ScratchPad.recorded.should == nil
+        end
+
+        it "killing dying running does nothing" do
+            # Not applicable for Strands (there can be no "running" status)
+        end
+
+        quarantine! do
+
+            it "propogates inner exception to Strand.join if there is an outer ensure clause" do
+                strand = StrandSpecs.dying_strand_with_outer_ensure(:kill) { }
+                lambda { strand.join }.should raise_error(RuntimeError, "In dying strand")
+            end
+
+            it "runs all outer ensure clauses even if inner ensure clause raises exception" do
+                strand = StrandSpecs.join_dying_strand_with_outer_ensure(:kill) { ScratchPad.record :in_outer_ensure_clause }
+                ScratchPad.recorded.should == :in_outer_ensure_clause
+            end
+
+            it "sets $! in outer ensure clause if inner ensure clause raises exception" do
+                strand = StrandSpecs.join_dying_strand_with_outer_ensure(:kill) { ScratchPad.record $! }
+                ScratchPad.recorded.to_s.should == "In dying strand"
+            end
+        end
+
+        it "can be rescued by outer rescue clause when inner ensure clause raises exception" do
+            strand = Strand.new do
+                begin
+                    begin
+                        Strand.current.send(:kill)
+                    ensure
+                        raise "In dying strand"
+                    end
+                rescue Exception
+                    ScratchPad.record $!
+                end
+                :end_of_strand_block
+            end
+
+            strand.value.should == :end_of_strand_block
+            ScratchPad.recorded.to_s.should == "In dying strand"
+        end
+
+        it "is deferred if ensure clause does Strand.stop" do
+            StrandSpecs.wakeup_dying_sleeping_strand(:kill) { Strand.stop; ScratchPad.record :after_sleep }
+            ScratchPad.recorded.should == :after_sleep
+        end
+
+        # Hangs on 1.8.6.114 OS X, possibly also on Linux
+        # FIX: There is no such thing as not_compliant_on(:ruby)!!!
+        quarantine! do
+            not_compliant_on(:ruby) do # Doing a sleep in the ensure block hangs the process
+                it "is deferred if ensure clause sleeps" do
+                    StrandSpecs.wakeup_dying_sleeping_strand(:kill) { sleep; ScratchPad.record :after_sleep }
+                    ScratchPad.recorded.should == :after_sleep
+                end
+            end
+
+            # This case occurred in JRuby where native strands are used to provide
+            # the same behavior as MRI green strands. Key to this issue was the fact
+            # that the strand which called #exit in its block was also being explicitly
+            # sent #join from outside the strand. The 100.times provides a certain
+            # probability that the deadlock will occur. It was sufficient to reliably
+            # reproduce the deadlock in JRuby.
+            it "does not deadlock when called from within the strand while being joined from without" do
+                100.times do
+                    t = Strand.new { Strand.stop; Strand.current.send(:kill) }
+                    t.wakeup.should == t
+                    t.join.should == t
+                end
+            end
+        end
+    end
+end

data/spec/strand/join.rb

@@ -0,0 +1,60 @@
+shared_examples_for "Strand#join" do
+
+    context :join do
+        it "returns the strand when it is finished" do
+            t = Strand.new {}
+            t.join.should equal(t)
+        end
+
+        it "returns the strand when it is finished when given a timeout" do
+            t = Strand.new {}
+            t.join
+            t.join(0).should equal(t)
+        end
+
+        it "returns nil if it is not finished when given a timeout" do
+            c = Strand::Queue.new
+            t = Strand.new { c.shift }
+            begin
+                t.join(0).should == nil
+            ensure
+                c << true
+            end
+            t.join.should == t
+        end
+
+        it "accepts a floating point timeout length" do
+            c = Strand::Queue.new
+            t = Strand.new { c.shift }
+            begin
+                t.join(0.01).should == nil
+            ensure
+                c << true
+            end
+            t.join.should == t
+        end
+
+        it "raises any exceptions encountered in the strand body" do
+            t = Strand.new { raise NotImplementedError.new("Just kidding") }
+            lambda { t.join }.should raise_error(NotImplementedError)
+        end
+
+        it "returns the dead strand" do
+            t = Strand.new { Strand.current.kill }
+            t.join.should equal(t)
+        end
+
+        quarantine! do
+        # This was pre 1.9 behaviour
+        it "returns the dead strand even if an uncaught exception is thrown from ensure block" do
+            t = StrandSpecs.dying_strand_ensures { raise "In dying strand" }
+            t.join.should equal(t)
+        end
+        end
+
+        it "raises any uncaught exception encountered in ensure block" do
+            t = StrandSpecs.dying_strand_ensures { raise NotImplementedError.new("Just kidding") }
+            lambda { t.join }.should raise_error(NotImplementedError)
+        end
+    end
+end

data/spec/strand/local_storage.rb

@@ -0,0 +1,98 @@
+
+shared_examples_for "strand local storage" do
+
+    context "[]" do
+        it "gives access to strand local values" do
+            th = Strand.new do
+                Strand.current[:value] = 5
+            end
+            th.join
+            th[:value].should == 5
+            Strand.current[:value].should == nil
+        end
+
+        it "is not shared across strands" do
+            t1 = Strand.new do
+                Strand.current[:value] = 1
+            end
+            t2 = Strand.new do
+                Strand.current[:value] = 2
+            end
+            [t1,t2].each {|x| x.join}
+            t1[:value].should == 1
+            t2[:value].should == 2
+        end
+
+        it "is accessable using strings or symbols" do
+            t1 = Strand.new do
+                Strand.current[:value] = 1
+            end
+            t2 = Strand.new do
+                Strand.current["value"] = 2
+            end
+            [t1,t2].each {|x| x.join}
+            t1[:value].should == 1
+            t1["value"].should == 1
+            t2[:value].should == 2
+            t2["value"].should == 2
+        end
+
+        it "raises exceptions on the wrong type of keys" do
+            lambda { Strand.current[nil] }.should raise_error(TypeError)
+            lambda { Strand.current[5] }.should raise_error(TypeError)
+        end
+    end
+
+    context "[]=" do
+        it "raises exceptions on the wrong type of keys" do
+            lambda { Strand.current[nil] = true }.should raise_error(TypeError)
+            lambda { Strand.current[5] = true }.should raise_error(TypeError)
+        end
+    end
+
+    context "keys" do
+        it "returns an array of the names of the thread-local variables as symbols" do
+            th = Strand.new do
+                Strand.current["cat"] = 'woof'
+                Strand.current[:cat] = 'meow'
+                Strand.current[:dog] = 'woof'
+            end
+            th.join
+            th.keys.sort_by {|x| x.to_s}.should == [:cat,:dog]
+        end
+    end
+
+    context "key?" do
+        before :each do
+            @th = Strand.new do
+                Strand.current[:oliver] = "a"
+            end
+            @th.join
+        end
+
+        it "tests for existance of strand local variables using symbols or strings" do
+            @th.key?(:oliver).should == true
+            @th.key?("oliver").should == true
+            @th.key?(:stanley).should == false
+            @th.key?(:stanley.to_s).should == false
+        end
+
+        quarantine! do
+            ruby_version_is ""..."1.9" do
+                it "raises exceptions on the wrong type of keys" do
+                    lambda { Strand.current.key? nil }.should raise_error(TypeError)
+                    lambda { Strand.current.key? 5 }.should raise_error(ArgumentError)
+                end
+            end
+
+        end
+
+        # Ruby spec says 1.9 should raise TypeError
+        it "raises exceptions on the wrong type of keys" do
+            lambda { Strand.current.key? nil }.should raise_error(TypeError)
+            lambda { Strand.current.key? 5 }.should raise_error(TypeError)
+        end
+
+    end
+end
+

data/spec/strand/mutex.rb

@@ -0,0 +1,244 @@
+
+# This spec derived from rubyspec for mutex
+shared_examples "a mutex" do
+
+    context :lock  do
+
+        it "returns self" do
+            m = Strand::Mutex.new
+            m.lock.should == m
+            m.unlock
+        end
+
+        it "waits if the lock is not available" do
+            m = Strand::Mutex.new
+
+            status = nil
+            m.lock
+
+            s = Strand.new do
+                m.lock
+                status = :after_lock
+            end
+
+            status.should be_nil
+            m.unlock
+            s.join
+            status.should == :after_lock
+        end
+
+        #GG there's no test for this in rubyspec
+        # but there is a test below for locked?
+        it "acquires a lock previously held by a dead Fiber" do
+            m = Strand::Mutex.new
+
+            m.lock
+
+            # s1 acquires the lock but does not release it before
+            # it dies, something needs to resume s2
+            # we 
+            s1 = Strand.new { m.lock; Strand.pass }
+            s2 = Strand.new { m.lock; }
+
+            m.unlock
+            s2.join
+        end
+
+        it "acquires a lock previously held by a killed Fiber" do
+            m = Strand::Mutex.new
+            m.lock
+
+            s1 = Strand.new { m.lock; Strand.sleep }
+            s2 = Strand.new { m.lock; }
+
+            m.unlock
+            s1.kill
+            s2.join
+        end
+
+        it "acquires a lock in a queue behind a killed Fiber" do
+
+            m = Strand::Mutex.new
+            m.lock
+            s1 = Strand.new { m.lock }
+            s2 = Strand.new { m.lock }
+            s3 = Strand.new { m.lock }
+
+            s2.kill
+            m.unlock
+            s3.join
+
+        end
+    end
+
+    context :unlock do
+        it "raises StrandError unless Mutex is locked" do
+            mutex = Strand::Mutex.new
+            lambda { mutex.unlock }.should raise_error(strand_exception)
+        end
+
+        it "raises StrandError unless thread owns Mutex" do
+            mutex = Strand::Mutex.new
+            wait = Strand::Mutex.new
+            wait.lock
+
+            s = Strand.new do
+                mutex.lock
+                wait.lock
+            end
+
+            lambda { mutex.unlock }.should raise_error(strand_exception)
+
+            wait.unlock
+            s.join
+        end
+
+        it "raises StrandError if previously locking thread is gone" do
+            mutex = Strand::Mutex.new
+            s = Strand.new do
+                mutex.lock
+            end
+
+            s.join
+            #TODO This doesn't make sense, because it would raise error
+            # as per above test
+            lambda { mutex.unlock }.should raise_error(strand_exception)
+        end
+    end
+
+    context :locked do
+        it "returns true if locked" do
+            m = Strand::Mutex.new
+            m.lock
+            m.locked?.should be_true
+        end
+
+        it "returns false if unlocked" do
+            m = Strand::Mutex.new
+            m.locked?.should be_false
+        end
+
+        it "returns the status of the lock" do
+
+            m1 = Strand::Mutex.new
+            m2 = Strand::Mutex.new
+
+            m2.lock # hold s with only m1 locked
+
+            s = Strand.new do
+                m1.lock
+                m2.lock
+            end
+            Strand.pass while s.status and s.status != "sleep"
+            m1.locked?.should be_true
+            m2.unlock # release s
+            s.join
+            #TODO GG implies that I should be able to get m1
+            # but there is no test for this case!
+            m1.locked?.should be_false
+        end
+    end
+
+    context :try_lock do
+        it "locks the mutex if it can" do
+            m = Strand::Mutex.new
+            m.try_lock
+
+            m.locked?.should be_true
+            lambda { m.try_lock.should be_false }.should_not raise_error(strand_exception)
+        end
+
+        it "returns false if lock can not be aquired immediately" do
+            m1 = Strand::Mutex.new
+            m2 = Strand::Mutex.new
+
+            m2.lock
+            s = Strand.new do
+                m1.lock
+                m2.lock
+            end
+            Strand.pass while s.status and s.status != "sleep"
+            # s owns m1 so try_lock should return false
+            m1.try_lock.should be_false
+            m2.unlock
+            s.join
+            # once th is finished m1 should be released
+            m1.try_lock.should be_true
+        end
+    end
+    context :synchronize do
+        it "wraps the lock/unlock pair in an ensure" do
+            m1 = Strand::Mutex.new
+            m2 = Strand::Mutex.new
+            m2.lock
+
+            s = Strand.new do
+                lambda do
+                    m1.synchronize do
+                        m2.lock
+                        raise Exception
+                    end
+                end.should raise_error(Exception)
+            end
+
+            Strand.pass while s.status and s.status != "sleep"
+            m1.locked?.should be_true
+            m2.unlock
+            s.join
+            m1.locked?.should be_false
+        end
+    end
+
+    context :sleep do
+        it "raises StrandError if not locked by the current thread" do
+            m = Strand::Mutex.new
+            lambda { m.sleep }.should raise_error(strand_exception)
+        end
+
+        it "pauses execution for approximately the duration requested" do
+            m = Strand::Mutex.new
+            m.lock
+            duration = 0.1
+            start = Time.now
+            m.sleep duration
+            (Time.now - start).should be_within(0.1).of(duration)
+        end
+
+        it "unlocks the mutex while sleeping" do
+            m = Strand::Mutex.new
+            s = Strand.new { m.lock; m.sleep }
+            Strand.pass while s.status and s.status != "sleep"
+            m.locked?.should be_false
+            s.run
+            s.join
+        end
+
+        it "relocks the mutex when woken" do
+            m = Strand::Mutex.new
+            m.lock
+            m.sleep(0.01)
+            m.locked?.should be_true
+        end
+
+        it "relocks the mutex when woken by an exception being raised" do
+            m = Strand::Mutex.new
+            s = Strand.new do
+                m.lock
+                begin
+                    m.sleep
+                rescue Exception
+                    m.locked?
+                end
+            end
+            Strand.pass while s.status and s.status != "sleep"
+            s.raise(Exception)
+            s.value.should be_true
+        end
+
+        it "returns the rounded number of seconds asleep" do
+            m = Strand::Mutex.new
+            m.lock
+            m.sleep(0.01).should be_kind_of(Integer)
+        end
+    end
+end