cfiber 0.0.2

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+ * Initial setup

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2010 Jean-Denis Vauguet
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+CFiber is [Fibers](http://rubydoc.info/stdlib/core/1.9.2/Fiber) implemented using continuations, using the native Ruby [Continuation](http://rubydoc.info/stdlib/core/1.9.2/Continuation) class.
+
+Experimental! It is based on [tmm1's work](https://gist.github.com/48802).
+
+# Synopsis
+
+Continuations in Ruby are like time-machine engineers. They let you take snapshots of your runtime environment, and jump (back) to a particular "save point" at any time. Continuation objects, which you may store, are like an object representing a frozen point in time where one may jump back and start a new life. Fibers are a way to pause and resume an execution frame by hand, scheduling its execution within the wrapping thread (which may be another Fiber!).
+
+All in all, it is all about jumping back and forth between several states, so with some smart design, continuations should let us achieve the Fiber pattern! This project is an attempt at implementing the Ruby 1.9 Fiber API using only continuations. The Continuation API is made of only two methods:
+
+* `#callcc`, which stands for *Call With Current Continuation*; it allows for capturing the runtime state and associate a pending block to it. The "current continuation" is a way to talk about the "remaining/pending code left to run" at the time the continuation is captured. In a way, capturing a new continuation sets a checkpoint which allows you to jump back to a particular state, so you effectively gain access to "the remaining code at this time" for you now have a way to jump back in the past to reach what was the current state (that's for the "past/current" confusion);
+* `#call`, which have us jump back in time and trigger the block in the context of the current runtime, where "current" really means "the captured state" (again).
+
+Those are the basis for CFiber. See the *Interesting readings* section for more information.
+
+## Installation
+
+Not available as a gem yet. You should clone this repository.
+
+You may build and install a local gem running `gem build cfiber.gemspec && gem install cfiber*.gem` though.
+
+## Usage
+
+Run `ruby spec/cfiber_spec.rb`. Run and **read** `ruby examples/use_cases.rb`. Then play with `Fiber`.
+
+In a Ruby console, `require ./lib/cfiber.rb` (when inside cfiber's root directory) or `require 'cfiber'` (if you built and installed a local gem).
+
+By installing the [Logg](http://github.com/chikamichi/logg) gem, you'll gain debugging output. Pass the `-d` flag: `ruby examples/use_cases.rb`.
+
+## TODO
+
+* coroutines using `#transfer` do not work atm.
+* `#alive?` implementation is challenging
+
+## Interesting readings
+
+### Doc
+
+* http://rubydoc.info/stdlib/core/1.9.2/Fiber
+* http://rubydoc.info/stdlib/core/1.9.2/Continuation
+
+### Continuations
+
+* http://www.intertwingly.net/blog/2005/04/13/Continuations-for-Curmudgeons
+* http://gnuu.org/2009/03/21/demystifying-continuations-in-ruby/
+* http://onestepback.org/articles/callcc/
+* http://www.ibm.com/developerworks/java/library/os-lightweight9/
+
+### Fibers
+
+* http://masanjin.net/blog/fibers
+* http://www.davidflanagan.com/2007/08/coroutines-via-fibers-in-ruby-19.html
+* http://pragdave.blogs.pragprog.com/pragdave/2007/12/pipelines-using.html
+* http://blog.zacharyvoase.com/2010/01/02/nice-redis-em/

data/lib/cfiber.rb

@@ -0,0 +1,172 @@
+# Based on this 1.8 try: https://gist.github.com/48802
+
+class FiberError < StandardError; end
+class Fiber
+  require 'continuation'
+  require './lib/cfiber/debug'
+
+  attr_reader :alive
+  attr_accessor :state
+
+  # Like an implicit Fiber.yield, the first one: it acts the same as
+  # Fiber.yield but for the &block call!
+  #
+  def initialize(&block)
+    @alive = true
+    unless @yield = callcc { |cc| cc }
+      @args = Fiber.current.instance_exec(@args, &block)
+      @resume.call
+    end
+    self.class.log.debug "initial state for #{self}: #{@yield}"
+  end
+
+  def self.current
+    Thread.current[:__cfiber]
+  end
+
+  # Fiber.yield delegates to the current fiber instance #yield method.
+  #
+  # In order to retrieve the current fiber, a reference should have been
+  # stored. It's thread-safe for it uses a Thread.current-local variable to
+  # store the ref.
+  #
+  def self.yield(*args)
+    Fiber.current.yield(*args)
+  end
+
+  # Wake a fiber up, passing its args to the resumed block.
+  #
+  # First, it captures a new continuation to save a breakpoint, then it yields
+  # its arguments. Along the way, a reference for the current fiber object is
+  # stored within the current thread.
+  #
+  def resume(*args)
+    # Using callcc as a breakpoint, storing the continuation outside the block
+    # scope. This allows for the lazy-evaluation of an else clause.
+    if @resume = callcc { |cc| cc }
+      Fiber.current = self
+      Fiber.current.state = :awake
+      @args = args.size > 1 ? args : args.first
+      @yield.call # the first #resume call will trigger the #initialize block
+                  # execution, until a call to Fiber.yield is made inside the
+                  # very block; whereas subsequent #resume calls will resume
+                  # the block's execution from the last Fiber.yield point.
+    else
+      log.debug "outputing inside #resume for #{self}"
+      @args
+    end
+  rescue NoMethodError => e # undefined method call for nil:NilClass, that is
+    @alive = false
+    raise FiberError, "dead fiber #{Fiber.current} called"
+  end
+
+  # Pause the current fiber, while yielding its args in the fiber's context.
+  #
+  # First, it captures a new continuation to save a breakpoint, then it yields
+  # its arguments ("passing along any arguments that were passed to it").
+  #
+  def yield(*args)
+    if @yield = callcc { |cc| cc }
+      @args = args.size > 1 ? args : args.first
+      @resume.call
+    else
+      log.debug "outputing inside #yield for #{self}"
+      @args
+    end
+  rescue NoMethodError => e # undefined method call for nil:NilClass, that is
+    @alive = false
+    raise FiberError, "dead fiber #{Fiber.current} called"
+  end
+
+  def transfer_yield(*args)
+    self.state = :paused
+    unless @yield = callcc { |cc| cc }
+      puts "yielding #{self}"
+      @resume.call
+    end
+  end
+
+  # Useful to implement coroutines.
+  #
+  # @example
+  #   f = g = nil
+  #
+  #   f = Fiber.new do |x|
+  #     puts "F1: #{x}"
+  #     x = g.transfer(x+1)
+  #     puts "F2: #{x}"
+  #     x = g.transfer(x+1)
+  #     puts "F3: #{x}"
+  #   end
+  #
+  #   g = Fiber.new do |x|
+  #     puts "G1: #{x}"
+  #     x = f.transfer(x+1)
+  #     puts "G2: #{x}"
+  #     x = f.transfer(x+1)
+  #   end
+  #
+  #   f.transfer(100)
+  #
+  #   -----------------
+  #
+  #   g = Fiber.new { |x|
+  #     puts "G1: #{x}"
+  #     x = Fiber.yield(x+1) # f.transfer => Thread.current[:__cfiber_transfer] != nil => Thread.current[:__cfiber_transfer] = nil && Fiber.yield
+  #     puts "G2: #{x}"
+  #     x = Fiber.yield(x+1)
+  #   }
+  #
+  #   f = Fiber.new { |x|
+  #     puts "F1: #{x}"
+  #     x = g.resume(x+1) # g.transfer => Thread.current[:__cfiber_transfer] = Fiber.current && g.resume
+  #     puts "F2: #{x}"
+  #     x = g.resume(x+1) # pareil
+  #     puts "F3: #{x}"
+  #   }
+  #
+  #   f.resume(100) # f.transfer => Fiber.current == nil => f.resume
+  #
+  # FIXME: the tricky part is init. In the example above, f.transfer(100)
+  # triggers f.resume(100), which in turns reach g.transfer(101). This
+  # triggers g.yield(f.resume(101)) but this is wrong. One must atomically
+  # pause (yield) g and resume f.
+  #
+  def transfer(*args)
+    if Fiber.current.nil?
+      log.debug ""
+      log.debug "cas 1"
+      Thread.current[:__cfiber_transfer] = nil
+      self.resume(*args)
+
+    elsif Thread.current[:__cfiber_transfer].nil?
+      log.debug ""
+      log.debug "cas 2"
+      log.debug "resuming #{self}"
+      Thread.current[:__cfiber_transfer] = Fiber.current
+      self.resume(*args)
+
+    elsif Thread.current[:__cfiber_transfer].is_a?(Fiber)
+      log.debug ""
+      log.debug "cas 3"
+      log.debug "pausing #{Fiber.current}"
+      Thread.current[:__cfiber_transfer] = nil
+      Fiber.yield(*args)
+      #Fiber.yield(self.resume(*args)) # TODO: handle multiple coroutines
+    else
+      log.debug ""
+      log.debug "cas 4"
+      raise FiberError, "transfer mismatch"
+    end
+  end
+
+  def alive?
+    Fiber.current.instance_variable_get(:@alive)
+  end
+
+  private
+
+  def self.current=(fiber)
+    Thread.current[:__cfiber] = fiber
+  end
+end

data/lib/cfiber/debug.rb

@@ -0,0 +1,25 @@
+class Fiber
+  begin
+    require 'logg'
+    include Logg::Machine
+
+    log.as(:debug) do |msg|
+      if $DEBUG
+        puts "[DEBUG] #{msg}"
+      end
+    end
+
+    log.debug 'output ready'
+  rescue LoadError
+    def self.log
+      Object.new.extend( Module.new do
+        def debug(*args, &block)
+          # do nothing
+        end
+      end)
+    end
+    def log
+      self.class.log
+    end
+  end
+end

data/lib/cfiber/version.rb

@@ -0,0 +1,6 @@
+module CFiber
+  MAJOR = 0
+  MINOR = 0
+  PATCH = 2
+  VERSION = [MAJOR, MINOR, PATCH].join('.')
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: cfiber
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Jean-Denis Vauguet <jd@vauguet.fr>
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-28 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logg
+  requirement: &75456510 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *75456510
+description: Continuations used to implement Fibers as provided by Ruby 1.9. Works
+  in 1.8 as well.
+email: jd@vauguet.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/cfiber.rb
+- lib/cfiber/debug.rb
+- lib/cfiber/version.rb
+- MIT-LICENSE
+- README.md
+- CHANGELOG.md
+homepage: http://www.github.com/chikamichi/cfiber
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: Ruby Fibers using Ruby Continuations
+test_files: []