lspace 0.1.pre.1

data/LICENSE.MIT

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Conrad Irwin <conrad.irwin@gmail.com>
+
+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,23 @@
+*in progress*
+
+LSpace — Safe operation-local storage.
+
+Global variables are awesome. Unfortunately they become a bit useless when you have
+multiple threads because you often want different "global" state per-thread...
+
+Thread-local variables are even more awesome! Unfortunately they become a bit useless when
+you are doing multiple things on the same thread because you often want different
+"thread-local" state per operation...
+
+Operation-local variables are most awesome!
+
+`LSpace`, named after the Discworld's [L-Space](http://en.wikipedia.org/wiki/Other_dimensions_of_the_Discworld#L-space)
+gives you effective, safe operation-local variables.
+
+It does this by following your operation as it jumps between thread-pools, or fires
+callbacks on your event-loop; and makes sure to clean up after itself so that no state
+accidentally leaks.
+
+If you're using this on EventMachine, you should be ready to rock by requiring 'lspace/eventmachine'.
+If you've got your own thread-pool, or are doing something fancy, you'll need to do some
+manual work.

data/lib/lspace/core_ext.rb

@@ -0,0 +1,37 @@
+class Module
+  def in_lspace(*methods)
+    methods.each do |method|
+      method_without_lspace = "#{method}_without_lspace"
+      next if method_defined?(method_without_lspace) || private_method_defined?(method_without_lspace)
+
+      alias_method method_without_lspace, method
+
+      define_method(method) do |*args, &block|
+        args.map!{ |a| Proc === a ? a.in_lspace : a }
+        block = block && block.in_lspace
+        __send__(method_without_lspace, *args, &block)
+      end
+
+      private method if private_method_defined?(method_without_lspace)
+      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
+  def in_lspace
+    LSpace.preserve(&self)
+  end
+end

data/lib/lspace/eventmachine.rb

@@ -0,0 +1,39 @@
+require 'eventmachine'
+module EventMachine
+  module Deferrable
+    in_lspace :callback, :errback
+  end
+
+  class << Connection
+    alias_method :allocate_without_lspace, :allocate
+
+    def allocate
+      allocate_without_lspace.instance_eval do
+        extend EventMachine::LSpacePreserver
+        @lspace_context = LSpace.new
+        lspace_setup
+        self
+      end
+    end
+
+  end
+
+  class Connection
+    def lspace_setup; end
+  end
+
+  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) } }
+    end
+
+    [:unbind].each do |method|
+      define_method(method) { LSpace.enter(@lspace_context) { 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/lib/lspace/thread.rb

@@ -0,0 +1,7 @@
+class << Thread
+  in_lspace :new, :start, :fork
+end
+
+module Kernel
+  in_lspace :fork
+end

data/lib/lspace.rb

@@ -0,0 +1,214 @@
+require File.expand_path('../lspace/core_ext', __FILE__)
+
+module LSpace
+
+  class << self
+    # Get the most specific value for the key.
+    #
+    # If nested LSpaces are active, returns the value set in the innermost scope.
+    # If this key is not present in any of the nested LSpaces, nil is returned.
+    #
+    # @example
+    #   LSpace.new :user_id => 5 do
+    #     LSpace.new :user_id => 6 do
+    #       LSpace[:user_id] == 6
+    #     end
+    #   end
+    # @param [Object] key
+    # @return [Object]
+    def [](key)
+      active.each do |c|
+        return c[key] if c.has_key?(key)
+      end
+      nil
+    end
+
+    # Sets the value for the key in the currently active LSpace.
+    #
+    # This does not have any effect on outer LSpaces.
+    #
+    # If your LSpace is shared between threads, you should think very hard before
+    # changing a value, it's often better to create a new LSpace if you want to
+    # override a value temporarily.
+    #
+    # @example
+    #   LSpace.new :user_id => 5 do
+    #     LSpace.new do
+    #       LSpace[:user_id] = 6
+    #       LSpace[:user_id] == 6
+    #     end
+    #     LSpace[:user_id] == 5
+    #   end
+    #
+    # @param [Object] key
+    # @param [Object] value
+    # @return [Object] value
+    def []=(key, value)
+      current[key] = value
+    end
+
+    # Create a new LSpace.
+    #
+    # If a block is passed, then the block is called in the new LSpace,
+    # otherwise you can manually pass the LSpace to {LSpace.enter} later.
+    #
+    # The returned LSpace will inherit from the currently active LSpace:
+    #
+    # @example
+    #   LSpace.new :job_id => 7 do
+    #     LSpace[:job_id] == 7
+    #   end
+    #
+    # @example
+    #   class Job
+    #     def initialize
+    #       @lspace = LSpace.new
+    #     end
+    #
+    #     def run!
+    #       LSpace.enter(@lspace){ run }
+    #     end
+    #   end
+    #
+    # @param [Hash] new  Values to set in the new LSpace
+    # @param [Proc] block  The block to run
+    # @return [Hash] The new LSpace (unless a block is given)
+    # @return [Object]  The return value of the block (if a block is given)
+    def new(new={}, &block)
+      new[:outer_lspace] = current
+      if block_given?
+        enter(new, &block)
+      else
+        new
+      end
+    end
+
+    # Enter an LSpace
+    #
+    # This sets a new LSpace to be current for the duration of the block,
+    # it also runs any around filters for the new space. (Around filters that
+    # were present in the previous space are not run again).
+    #
+    # @example
+    #   class Job
+    #     def initialize
+    #       @lspace = LSpace.new
+    #     end
+    #
+    #     def run!
+    #       LSpace.enter(@lspace){ run }
+    #     end
+    #   end
+    #
+    # @param [Hash] new  The LSpace to enter
+    # @param [Proc] block  The block to run
+    def enter(new, &block)
+      previous = current
+      self.current = new
+
+      new_frames = active.take_while{ |space| space != previous }
+      filters = new_frames.map{ |space| space[:around_filter] }.compact
+
+      filters.inject(block) do |block, filter|
+        lambda{ filter.call(&block) }
+      end.call
+    ensure
+      self.current = previous
+    end
+
+    # Preserve the current LSpace when this block is called
+    #
+    # @example
+    #   LSpace.new :user_id => 1 do
+    #     $todo = LSpace.preserve do |args|
+    #               LSpace[:user_id]
+    #             end
+    #   end
+    #   $todo.call == 1
+    #
+    # @see [Proc#in_lspace]
+    # @param [Proc] original  The block to wrap
+    # @return [Proc] A modified block that will be executed in the current LSpace.
+    def preserve(&original)
+      current = self.current
+
+      proc do |*args, &block|
+        LSpace.enter(current) do
+          original.call(*args, &block)
+        end
+      end
+    end
+
+    # Add an around filter for the current LSpace
+    #
+    # The filter will be called every time this LSpace is entered on a new call stack, which
+    # makes it suitable for maintaining state in libraries that are not LSpace aware (like
+    # log4r) or implementing unified fallback error handling.
+    #
+    # Bear in mind that when you add an around_filter to the current LSpace it will not be
+    # running. For this reason, you should try and set up around filters before using the
+    # LSpace properly.
+    #
+    # @example
+    #   class Job
+    #     def initialize
+    #       LSpace.new do
+    #
+    #         LSpace.around_filter do |&block|
+    #           begin
+    #             block.call
+    #           rescue => e
+    #             puts "Job #{LSpace[:job_id]} failed with: #{e}"
+    #           end
+    #         end
+    #
+    #         @lspace = LSpace.current
+    #       end
+    #     end
+    #
+    #     def run!
+    #       LSpace.enter(@lspace){ run }
+    #     end
+    #   end
+    #
+    # @param [Proc] new_filter A Proc that takes a &block argument.
+    def around_filter(&new_filter)
+      if old_filter = current[:around_filter]
+        current[:around_filter] = lambda{ |&block| old_filter.call{ new_filter.call(&block) } }
+      else
+        current[:around_filter] = new_filter
+      end
+    end
+
+    # Get the currently active LSpace
+    #
+    # @see LSpace.enter
+    # @param [Hash] new  The new LSpace
+    def current
+      Thread.current[:lspace] ||= {}
+    end
+
+    private
+
+    # Set the current LSpace
+    #
+    # @see LSpace.enter
+    # @param [Hash] new  The new LSpace
+    def current=(new)
+      Thread.current[:lspace] = new
+    end
+
+    # All active LSpaces from most-specific to most-generic
+    #
+    # @return [Array<Hash>]
+    def active
+      c = self.current
+      a = []
+      while c
+        a << c
+        c = c[:outer_lspace]
+      end
+      a
+    end
+  end
+end

data/lspace.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new do |s|
+  s.name = "lspace"
+  s.version = "0.1.pre.1"
+  s.platform = Gem::Platform::RUBY
+  s.author = "Conrad Irwin"
+  s.email = "conrad.irwin@gmail.com"
+  s.homepage = "http://github.com/ConradIrwin/lspace"
+  s.summary = "Provides local global storage"
+  s.description = "Provides the convenience of global variables, without the safety concerns."
+  s.files = `git ls-files`.split("\n")
+  s.require_path = "lib"
+end

data/spec/lspace_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+describe LSpace do
+  it "should act like a hash" do
+    LSpace[:foo] = 1
+    LSpace[:foo].should == 1
+  end
+
+  it "should isolate changes to nested spaces" do
+    LSpace[:foo] = 2
+
+    LSpace.new do
+      LSpace[:foo] = 1
+      LSpace[:foo].should == 1
+    end
+
+    LSpace[:foo].should == 2
+  end
+
+  it "should fallback to outer spaces" do
+    LSpace[:bar] = 1
+    LSpace.new do
+      LSpace[:bar].should == 1
+    end
+  end
+
+  it "should be isolated between different threads" do
+    LSpace[:foo] = 1
+    Thread.new{ LSpace[:foo].should == nil }.join
+  end
+
+  it "should be isolated between different fibers" do
+    LSpace[:foo] = 1
+    Fiber.new{ LSpace[:foo].should == nil }.resume
+  end
+
+  it "should allow preserving spaces" do
+    p = LSpace.new(:foo => 1){ proc{ LSpace[:foo] }.in_lspace }
+    p.call.should == 1
+  end
+
+  it "should allow resuming spaces in different threads" do
+    p = LSpace.new(:foo => 1){ proc{ LSpace[:foo] }.in_lspace }
+    Thread.new{ p.call.should == 1 }.join
+  end
+
+  it "should allow resuming spaces in different fibers" do
+    p = LSpace.new(:foo => 1){ LSpace.preserve{ LSpace[:foo] } }
+    Fiber.new{ p.call.should == 1 }.resume
+  end
+
+  it "should clean up lspace after resuming" do
+    p = LSpace.new(:foo => 1){ proc{ LSpace[:foo] }.in_lspace }
+    p.call.should == 1
+    LSpace[:foo].should == nil
+  end
+
+  it "should resume the entire nested lspace" do
+    p = LSpace.new(:foo => 1) {
+          LSpace.new(:bar => 2) {
+            LSpace.new(:baz => 3) {
+              lambda &LSpace.preserve{ LSpace[:foo] + LSpace[:bar] + LSpace[:baz] }
+            }
+          }
+        }
+
+    p.call.should == 6
+  end
+
+  it "should return to enclosing lspace after re-entering new lspace" do
+    LSpace.new(:baz => 1) do
+      p = LSpace.new(:baz => 2){ proc{ LSpace[:baz] }.in_lspace }
+      p.call.should == 2
+      LSpace[:baz].should == 1
+    end
+  end
+
+  it "should clean up lspaces properly even if an exception is raised" do
+    LSpace.new(:baz => 1) do
+      begin
+        LSpace.new(:baz => 1) do
+          raise "OOPS"
+        end
+      rescue => e
+        LSpace[:baz].should == 1
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require_relative '../lib/lspace'
+RSpec.configure do |c|
+  c.around(:each) do |example|
+    LSpace.new do
+      example.run
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: lspace
+version: !ruby/object:Gem::Version
+  version: 0.1.pre.1
+  prerelease: 4
+platform: ruby
+authors:
+- Conrad Irwin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-22 00:00:00.000000000 Z
+dependencies: []
+description: Provides the convenience of global variables, without the safety concerns.
+email: conrad.irwin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.MIT
+- README.md
+- lib/lspace.rb
+- lib/lspace/core_ext.rb
+- lib/lspace/eventmachine.rb
+- lib/lspace/thread.rb
+- lspace.gemspec
+- spec/lspace_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/ConradIrwin/lspace
+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: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Provides local global storage
+test_files: []
+has_rdoc: