lspace 0.1.pre.1 → 0.1

data/lib/lspace/class_methods.rb

@@ -0,0 +1,129 @@
+class LSpace
+
+  # Create a new clean LSpace.
+  #
+  # This LSpace does not inherit any LSpace variables in the currently active LSpace.
+  #
+  # @example
+  #   RSpec.configure do |c|
+  #     c.around(:each) do |example|
+  #       LSpace.clean do
+  #         example.run
+  #       end
+  #     end
+  #   end
+  #
+  # @param [Proc] block  The logical block that will be run in the clean LSpace
+  # @see LSpace.enter
+  def self.clean(&block)
+    enter new({}, nil), &block
+  end
+
+  # Create a new LSpace with the given keys set to the given values.
+  #
+  # The LSpace will inherit any unspecified keys from the currently active LSpace.
+  #
+  # @example
+  #   LSpace.update :user_id => 6 do
+  #     LSpace.update :job_id => 7 do
+  #       LSpace[:user_id] == 6
+  #       LSpace[:job_id] == 7
+  #     end
+  #   end
+  #
+  # @param [Hash] hash  The keys to update
+  # @param [Proc] block  The logical block to run with the updated LSpace
+  # @see LSpace.enter
+  def self.update(hash={}, &block)
+    enter new(hash, current), &block
+  end
+
+  # Enter an LSpace for the logical duration of the block.
+  #
+  # The LSpace will be active at least for the duration of the block's callstack,
+  # but if the block creates any closures (using LSpace.preserve directly, or in
+  # library form) then the logical duration will also encompass code run in those
+  # closures.
+  #
+  # Entering an LSpace will also cause any around_filters defined on it and its parents to
+  # be run.
+  #
+  # @example
+  #   class Job
+  #     def initialize
+  #       @lspace = LSpace.new(:job_id => self.id)
+  #       LSpace.enter(@lspace){ setup_lspace }
+  #     end
+  #
+  #     def run!
+  #       LSpace.enter(@lspace) { run }
+  #     end
+  #   end
+  #
+  # @param [LSpace] lspace  The LSpace to enter
+  # @param [Proc] block  The logical block to run with the given LSpace
+  def self.enter(lspace, &block)
+    previous = current
+    self.current = lspace
+
+    filters = lspace.hierarchy.take_while{ |lspace| lspace != previous }.map(&:around_filters).flatten
+
+    filters.inject(block) do |blk, filter|
+      lambda{ filter.call(&blk) }
+    end.call
+  ensure
+    self.current = previous
+  end
+
+  # Create a closure that will re-enter the current LSpace when the block is called.
+  #
+  # @example
+  #   class TaskQueue
+  #     def queue(&block)
+  #       @queue << LSpace.preserve(&block)
+  #     end
+  #   end
+  #
+  # @see Proc#in_lspace
+  # @param [Proc] block  The logical block to wrap
+  def self.preserve(&block)
+    current.wrap(&block)
+  end
+
+  # Get the value for the key in the current LSpace or its parents
+  #
+  # @see LSpace#[]
+  def self.[](key)
+    current[key]
+  end
+
+  # Set the value for the key in the current LSpace
+  #
+  # @see LSpace#[]=
+  def self.[]=(key, value)
+    current[key] = value
+  end
+
+  # Add an around filter to the current LSpace
+  #
+  # @see LSpace#around_filter
+  def self.around_filter(&filter)
+    current.around_filter(&filter)
+  end
+
+  # Get the current LSpace
+  #
+  # @return [LSpace]
+  def self.current
+    Thread.current[:lspace] ||= LSpace.new({}, nil)
+  end
+
+  private
+
+  # Update the current LSpace
+  #
+  # @see LSpace.enter
+  def self.current=(lspace)
+    Thread.current[:lspace] = lspace
+  end
+end

data/lib/lspace/core_ext.rb

@@ -1,4 +1,48 @@
 class Module
+  # Create getter methods for LSpace
+  #
+  # Assumes that your LSpace keys are Symbols.
+  #
+  # @example
+  #   class Job
+  #     lspace_reader :user_id
+  #
+  #     def user
+  #       User.find(user_id)
+  #     end
+  #   end
+  #
+  #   LSpace[:user_id] = 6
+  #   Job.new.user == #<User:6>
+  #
+  # @param [Symbol] *attrs The accessors to create
+  def lspace_reader(*attrs)
+    attrs.each do |attr|
+      define_method(attr) do
+        LSpace[attr]
+      end
+    end
+  end
+
+  # Preserve lspace of all blocks passed to this function.
+  #
+  # This wraps both the &block parameter, and also any Procs
+  # that are passed into the function directly.
+  #
+  # If you need more complicated logic (i.e. wrapping Procs
+  # that are passed to a function in a dictionary) you're
+  # on your own.
+  #
+  # @example
+  #   class << Thread
+  #     in_lspace :new, :start, :fork
+  #   end
+  #
+  #   LSpace.new :user_id => 2 do
+  #     Thread.new{ LSpace[:user_id] == 2 }
+  #   end
+  #
+  # @param [Symbol] *methods  The methods to wrap
   def in_lspace(*methods)
     methods.each do |method|
       method_without_lspace = "#{method}_without_lspace"
@@ -16,21 +60,18 @@ class Module
       protected method if protected_method_defined?(method_without_lspace)
     end
   end
-
-  def attr_lspace(*attrs)
-    attrs.each do |attr|
-      define_method(attr) do
-        LSpace[attr]
-      end
-
-      define_method("#{attr}=") do |value|
-        LSpace[attr] = value
-      end
-    end
-  end
 end
 
 class Proc
+  # Preserve LSpace when this Proc is run.
+  #
+  # @example
+  #   todo = LSpace.new :user_id => 2 do
+  #            proc{ LSpace[:user_id] }.in_lspace
+  #          end
+  #   todo.call == 2
+  # @see LSpace.preserve
+  # @return [Proc] A version of self that re-enters LSpace before running
   def in_lspace
     LSpace.preserve(&self)
   end

data/lib/lspace/eventmachine.rb

@@ -1,39 +1,79 @@
 require 'eventmachine'
+require 'lspace'
 module EventMachine
+
+  # Most of the low-level EventMachine stuff goes through singleton methods on the
+  # EventMachine class.
+  #
+  # We use in_lspace to preserve the LSpace of any blocks passed to these methods.
+  class << self
+    in_lspace :add_timer, :next_tick, :error_handler, :defer, :run, :run_block, :schedule, :fork_reactor
+    in_lspace :add_shutdown_hook if method_defined?(:add_shutdown_hook) # only some versions of EM
+  end
+
+  # Many EM APIs (e.g. em-http-request) are based on deferrables. Preserving lspace for
+  # both callbacks and errbacks makes these libraries "just work".
   module Deferrable
     in_lspace :callback, :errback
   end
 
-  class << Connection
-    alias_method :allocate_without_lspace, :allocate
+  class Connection
+
+    class << self
+      # As EM uses a custom implementation of {new}, the only sane way to
+      # set up the LSpace in advance is to override allocate.
+      alias_method :allocate_without_lspace, :allocate
+    end
 
-    def allocate
+    # Overridden allocate which sets up a new LSpace.
+    #
+    # Each connection object is run in its own LSpace, which can be
+    # configured by implementing the {setup_lspace} method.
+    def self.allocate
       allocate_without_lspace.instance_eval do
         extend EventMachine::LSpacePreserver
-        @lspace_context = LSpace.new
-        lspace_setup
+        LSpace.update do
+          setup_lspace
+          @lspace = LSpace.current
+        end
         self
       end
     end
 
+    # Override this method to setup the LSpace in a manner which you require.
+    #
+    # This method is called before initialize() and before post_init().
+    #
+    # @example
+    #   module EchoServer
+    #     def setup_lspace
+    #       LSpace.around_filter do |&block|
+    #         begin
+    #           block.call
+    #         rescue => e
+    #           self.rescue(e)
+    #         end
+    #       end
+    #     end
+    #
+    #     def rescue(e)
+    #       puts "An exception occurred!: #{e}"
+    #     end
+    #   end
+    def setup_lspace; end
   end
 
-  class Connection
-    def lspace_setup; end
-  end
-
+  # A module that's included at the beginning of the method-resolution chain of
+  # connections which restores LSpace whenever a callback is fired by the eventloop.
   module LSpacePreserver
     [:initialize, :post_init, :connection_completed, :receive_data, :ssl_verify_peer, :ssl_handshake_completed].each do |method|
-      define_method(method) { |*a, &b| LSpace.enter(@lspace_context) { super(*a, &b) } }
+      define_method(method) { |*a, &b| LSpace.enter(@lspace) { super(*a, &b) } }
     end
 
+    # EM uses the arity of unbind to decide which arguments to pass it.
+    # AFAIK the no-argument version is considerably more popular, so we use that here.
     [:unbind].each do |method|
-      define_method(method) { LSpace.enter(@lspace_context) { super() } }
+      define_method(method) { LSpace.enter(@lspace) { super() } }
     end
   end
 end
-
-class << EventMachine
-  in_lspace :add_timer, :next_tick, :error_handler, :defer, :run, :run_block, :schedule, :fork_reactor
-  in_lspace :add_shutdown_hook if method_defined?(:add_shutdown_hook)
-end

data/lspace.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "lspace"
-  s.version = "0.1.pre.1"
+  s.version = "0.1"
   s.platform = Gem::Platform::RUBY
   s.author = "Conrad Irwin"
   s.email = "conrad.irwin@gmail.com"
@@ -9,4 +9,8 @@ Gem::Specification.new do |s|
   s.description = "Provides the convenience of global variables, without the safety concerns."
   s.files = `git ls-files`.split("\n")
   s.require_path = "lib"
+
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'pry-rescue'
+  s.add_development_dependency 'eventmachine'
 end

data/spec/class_method_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+describe LSpace do
+  before do
+    @lspace = LSpace.new({}, nil)
+  end
+
+  describe ".current" do
+    it "should return the most recently entered LSpace" do
+      LSpace.enter @lspace do
+        LSpace.current.should == @lspace
+      end
+    end
+
+    it "should ignore changes on other threads" do
+      LSpace.enter @lspace do
+        Thread.new{ LSpace.current.should_not == @lspace }.join
+      end
+    end
+  end
+
+  describe ".update" do
+    it "should enter a new LSpace with the new variables set" do
+      LSpace.update(:foo => 5) do
+        LSpace[:foo].should == 5
+      end
+    end
+
+    it "should enter a new LSpace which delegates to the current parent" do
+      LSpace.update(:foo => 5) do
+        LSpace.update(:bar => 4) do
+          LSpace[:foo].should == 5
+        end
+      end
+    end
+  end
+
+  describe ".clean" do
+    it "should enter a new LSpace with no parent" do
+      LSpace.update(:foo => 5) do
+        LSpace.clean do
+          LSpace[:foo].should == nil
+        end
+      end
+    end
+  end
+
+  describe ".enter" do
+    it "should update LSpace.current" do
+      LSpace.enter(@lspace) do
+        LSpace.current.should == @lspace
+      end
+    end
+
+    it "should revert that change at the end of the block" do
+      lspace = LSpace.current
+      LSpace.enter(@lspace) do
+        # yada yada
+      end
+      LSpace.current.should == lspace
+    end
+
+    it "should revert that change even if the block raises an exception" do
+      lspace = LSpace.current
+      lambda do
+        LSpace.enter(@lspace) do
+          raise "OOPS"
+        end
+      end.should raise_error /OOPS/
+      LSpace.current.should == lspace
+    end
+
+    it "should not effect other threads" do
+      LSpace.enter(@lspace) do
+        Thread.new{ LSpace.current.should_not == @lspace }.join
+      end
+    end
+
+    it "should not effect other fibers" do
+      LSpace.enter(@lspace) do
+        Fiber.new{ LSpace.current.should_not == @lspace }.resume
+      end
+    end
+  end
+
+  describe ".preserve" do
+    it "should delegate to LSpace.current" do
+      LSpace.current.should_receive(:wrap).once
+      LSpace.preserve{ 5 }
+    end
+  end
+
+  describe ".[]" do
+    it "should delegate to LSpace.current" do
+      LSpace.current.should_receive(:[]).once.with(:foo).and_return(:bar)
+      LSpace[:foo].should == :bar
+    end
+  end
+
+  describe ".[]=" do
+    it "should delegate to LSpace.current" do
+      LSpace.current.should_receive(:[]=).once.with(:foo, :bar)
+      LSpace[:foo] = :bar
+    end
+  end
+
+  describe ".around_filter" do
+    it "should delegate to LSpace.current" do
+      @lspace.should_receive(:around_filter).once
+      LSpace.enter @lspace do
+        LSpace.around_filter do |&block|
+          block.call
+        end
+      end
+    end
+  end
+end

data/spec/core_ext_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+
+describe Module do
+  describe "#lspace_reader" do
+    it "should define a reader for LSpace" do
+      klass = Class.new{ lspace_reader :user_id }
+
+      LSpace.update(:user_id => 8) do
+        klass.new.user_id.should == 8
+      end
+    end
+  end
+
+  describe "#in_lspace" do
+    before do
+      @klass = Class.new do
+        def initialize(task=nil, &block)
+          @block = block || task
+        end
+        in_lspace :initialize
+
+        def call
+          @block.call
+        end
+
+        private
+
+        def private_test(&block)
+          block
+        end
+
+        protected
+
+        def protected_test(&block)
+          block
+        end
+
+        in_lspace :private_test, :protected_test
+      end
+    end
+
+    it "should automatically preserve LSpace for blocks that are passed in" do
+      @task = LSpace.update :user_id => 6 do
+                @klass.new{ LSpace[:user_id] }
+              end
+
+      @task.call.should == 6
+    end
+
+    it "should automatically preserve LSpace for procs that are passed in" do
+      @task = LSpace.update :user_id => 6 do
+                @klass.new proc{ LSpace[:user_id] }
+              end
+
+      @task.call.should == 6
+    end
+
+    it "should preserve visibility of methods" do
+      @klass.private_method_defined?(:private_test).should == true
+      @klass.protected_method_defined?(:protected_test).should == true
+    end
+  end
+end
+
+describe Proc do
+  describe "#in_lspace" do
+    it "should create a wrapper which preserves the LSpace" do
+      p = LSpace.update(:job_id => 19) do
+           lambda{ LSpace[:job_id] }.in_lspace
+          end
+
+      p.call.should == 19
+    end
+  end
+end