fiber_recycling 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 746dc55b0a096b0ae4cf0b155fd499ef0fd1ca5e
-  data.tar.gz: 1846000c858ba6daa221bd38dd71249a6403fea3
+  metadata.gz: 630db3827d3b2a636f707e11f6595dc987627718
+  data.tar.gz: 33a112a7bdfbfc4e08daf71e45bf5ca2e35bed44
 SHA512:
-  metadata.gz: ad2b976c652a19ab8ae5965f321b070fe5d4d47f6f2241532bc07bd84a4de37e22500707673ac7d2c7cb7e4411025f576e3506cacec5e75098a0b2c2ddb6d187
-  data.tar.gz: 7ce95f737843b39d461b028b62b29d961ae7aabe1661c09497ee5464844cb28e836bdcb57aa673ee2fe021fd393f9c8f093d8b6a26df57651ac55f79f861dbcf
+  metadata.gz: 39a32ddb2a25f409eb60350a1dcdc1b56f6e70a92e12ea2fd1f8358989f10b8a663f2bdf325ea848d274c9187e350da3ef5a860b03e66166095fc3ae62c89529
+  data.tar.gz: 8eee84fc7780c79be520918267a1a3992fcaf06b2bedcda4662624c6e157d7c756d14d1be21860c5f1ddafcd728e21004cdf12fb20483995a2048157e1f3d52c

data/README.md

@@ -1,2 +1,55 @@
-# Ruby Gem: FiberRecycling
-This gem offers a ducktype for `Fiber` that will reuse old native fibers for a small performance gain. It will work as a drop in replacment for Ruby's natve `Fiber`.
+# FiberRecycling
+This Ruby Gem offers a duck type for `Fiber` that will reuse old native fibers for a small performance gain. It will work as a drop in replacment for Ruby's natve `Fiber`, offering a small performance gain.
+
+# Install
+`gem install fiber_recycling`
+
+Then simply `require 'fiber_recycling'` in your project.
+
+# Example
+`FiberRecycling::Fiber` can be used just like `::Fiber`.
+```ruby
+fiber = FiberRecycling::Fiber.new do |a, b|
+  c = FiberRecycling::Fiber.yield(a)
+  d = FiberRecycling::Fiber.yield(c + 1)
+  d
+end
+
+fiber.resume(1, 2) # => 1
+fiber.resume(3) # => 4
+fiber.resume(5) # => 5
+```
+
+```ruby
+fiber = FiberRecycling::Fiber.new do
+  FiberRecycling::Fiber.yield
+end
+
+fiber.resume # => nil
+fiber.resume # => nil
+fiber.resume # => FiberRecycling::FiberError, dead fiber called
+```
+
+To integrate *FiberRecycling* into an existing project that relies on `Fiber` you can `include` `FiberRecycling::DuckTypes`.
+```ruby
+module A
+  include FiberRecycling::DuckTypes
+  
+  def self.a
+    fiber = Fiber.new do
+      Fiber.yield
+    end
+    
+    fiber # => FiberRecycling::Fiber
+    fiber.resume # => nil
+    fiber.resume # => nil
+    fiber.resume # => FiberRecycling::FiberError, dead fiber resumed
+  end
+  
+end
+
+A.a
+```
+
+# How It Works
+As fibers can only be resumed in the thread that they were created, a native fiber pool will be created on demand for each thread that a pool is needed. The native fibers in each pool also only be created on demand. When a new `FiberRecycling::Fiber` is created, it will create a new native fiber if none are available in thread's pool. The native fiber will only be returned to the pool when the `FiberRecycling::Fiber` has completed executing it's block (is in a dead state). As each pool is shared globally, possibly being accessed by multiple code bases that have no knowledge of each other, it is impossible to allow a code base to set a maximum pool size limit. One project may want a maximum size of 5 native fibers per thread while another may want 10, there is no way to satisfy both requests. As such *FiberRecycling* will put no constraint on the number of native fibers that can be created. Therefore, it is important to keep in mind that *FiberRecycling* will create as many native fibers as is simoustanly demanded and will not delete them until the thread gets garbage collected (if you are creating fibers in the main thread, this will obviously never happen). It is up to the developer of the code base to ensure that only a reasonable amount of `FiberRecycling::Fiber` will ever be alive simoustanly.

data/lib/fiber_recycling/duck_types.rb

@@ -3,6 +3,6 @@ module FiberRecycling
   
     Fiber = Fiber
     FiberError = FiberError
-  
+    
   end
 end

data/lib/fiber_recycling/fiber.rb

@@ -12,6 +12,10 @@ module FiberRecycling
       Thread.current.thread_variable_get(:fiber_recycling__root_fiber)
     end
     
+    def self.root?
+      current == root
+    end
+    
     def self.yield(*args)
       current.backend.class.yield(*args)
     end
@@ -47,5 +51,9 @@ module FiberRecycling
       @backend.transfer(*args)
     end
     
+    def variables
+      @backend.variables
+    end
+    
   end
 end

data/lib/fiber_recycling/normal_fiber_backend.rb

@@ -8,8 +8,11 @@ module FiberRecycling
       return_value
     end
     
+    attr_reader :variables
+    
     def initialize(fiber, block)
       @state = 'created'
+      @variables = {}
       @recycled_fiber = RecycledFiberPool.local.release_recycled_fiber
       @recycled_fiber.run { execute(fiber, block) }
     end

data/lib/fiber_recycling/root_fiber_backend.rb

@@ -5,6 +5,12 @@ module FiberRecycling
       raise FiberError, "can't yield from root fiber"
     end
     
+    attr_reader :variables
+    
+    def initialize
+      @variables = {}
+    end
+    
     def alive?
       ::Fiber.root.alive?
     end

data/lib/fiber_recycling/thread_extensions.rb

@@ -0,0 +1,21 @@
+module FiberRecycling
+  module ThreadExtensions
+  
+    def [](key)
+      if key == :fiber_recycling__fiber || Fiber.root?
+        super
+      else
+        Fiber.current.variables[key]
+      end
+    end
+    
+    def []=(key, value)
+      if key == :fiber_recycling__fiber || Fiber.root?
+        super
+      else
+        Fiber.current.variables[key] = value
+      end
+    end
+    
+  end
+end  

data/lib/fiber_recycling.rb

@@ -11,6 +11,8 @@ require 'fiber_recycling/normal_fiber_backend'
 require 'fiber_recycling/recycled_fiber'
 require 'fiber_recycling/recycled_fiber_pool'
 require 'fiber_recycling/root_fiber_backend'
+require 'fiber_recycling/thread_extensions'
+require_relative 'thread'
 
 module FiberRecycling
 end

data/lib/thread.rb

@@ -0,0 +1,4 @@
+class Thread
+  prepend FiberRecycling::ThreadExtensions
+  
+end

data/spec/thread_spec.rb

@@ -0,0 +1,85 @@
+require 'fiber_recycling'
+
+RSpec.describe Thread do
+
+  context "when calling native method" do
+    it "should work" do
+      expect(Thread.current.alive?).to eql true
+    end
+  end
+  
+  context "when in root FiberRecycling::Fiber" do
+    
+    context "when setting a variable" do
+      it "should persist" do
+        Thread.current[:a] = 1
+        expect(Thread.current[:a]).to eql 1
+      end
+    end
+    
+    context "when setting a variable" do
+      it "should not exist in FiberRecycling::Fiber" do
+        Thread.current[:a] = 1
+        fiber = FiberRecycling::Fiber.new do
+          Thread.current[:a]
+        end
+        expect(fiber.resume).to eql nil
+      end
+    end
+    
+    context "when setting a variable" do
+      it "should should persist a new FiberRecycling::Fiber" do
+        Thread.current[:a] = 1
+        fiber = FiberRecycling::Fiber.new do
+          Thread.current[:a] = 2
+        end
+        fiber.resume
+        expect(Thread.current[:a]).to eql 1
+      end
+    end
+    
+  end
+  
+  context "when in non root FiberRecycling::Fiber" do
+    
+    context "when getting a variable" do
+      it "should not exist outside FiberRecycling::Fiber" do
+        Thread.current[:a] = nil
+        fiber = FiberRecycling::Fiber.new do
+          Thread.current[:a] = 1
+        end
+        fiber.resume
+        expect(Thread.current[:a]).to eql nil
+      end
+    end
+    
+    context "when setting a variable" do
+      it "should persist a yield" do
+        Thread.current[:a] = nil
+        fiber = FiberRecycling::Fiber.new do
+          Thread.current[:a] = 1
+          FiberRecycling::Fiber.yield
+          Thread.current[:a]
+        end
+        fiber.resume
+        Thread.current[:a] = 2
+        expect(fiber.resume).to eql 1
+      end
+    end
+    
+    context "when setting a variable" do
+      it "should not leak to next fiber" do
+        Thread.current[:a] = nil
+        fiber1 = FiberRecycling::Fiber.new do
+          Thread.current[:a] = 1
+        end
+        fiber1.resume
+        fiber2 = FiberRecycling::Fiber.new do
+          Thread.current[:a]
+        end
+        expect(fiber2.resume).to eql nil
+      end
+    end
+    
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber_recycling
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Rob Fors
@@ -43,9 +43,12 @@ files:
 - lib/fiber_recycling/recycled_fiber.rb
 - lib/fiber_recycling/recycled_fiber_pool.rb
 - lib/fiber_recycling/root_fiber_backend.rb
+- lib/fiber_recycling/thread_extensions.rb
+- lib/thread.rb
 - spec/duck_types_spec.rb
 - spec/fiber_spec.rb
 - spec/spec_helper.rb
+- spec/thread_spec.rb
 homepage: https://github.com/robfors/fiber_recycling
 licenses:
 - MIT