lspace 0.2 → 0.3

data/README.md

@@ -1,90 +1,100 @@
 LSpace, named after the Discworld's [L-Space](http://en.wikipedia.org/wiki/L-Space), is an
 implementation of dynamic scoping for Ruby.
 
-Dynamic scope is a fancy term for a variable which changes its value depending on the
-current context that your application is running in. i.e. the same function can see a
-different value for a dynamically scoped variable depending on the code-path taken to
-reach that function.
+Dynamic scope
+=============
 
-This is particularly useful for implementing many utility functions in applications. For
-example, let's say I want to use the master database connection for some database
-operations. I don't want to have to pass a reference to the database connection all the
-way throughout my code, so I just push it into the LSpace:
+Variables that are stored inside an LSpace are dynamically scoped, this means that they
+take effect only for the duration of a block:
 
 ```ruby
-require 'lspace'
-class DatabaseConnection
-  def get_connection
-    LSpace[:preferred_connection] || any_free_connection
-  end
+LSpace.with(:user_id => 5) do
+  LSpace[:user_id] == 5
+end
+LSpace[:user_id] == nil
+```
 
-  def self.use_master(&block)
-    LSpace.with(:preferred_connection => master_connection) do
-      block.call
-    end
+You can enter a new LSpace as many times as you need, to add as much state as you need:
+
+```ruby
+LSpace.with(:user_id => 5) do
+  LSpace.with(:database_shard => 7) do
+    LSpace[:user_id] == 5
+    LSpace[:database_shard] == 7
   end
 end
+```
 
-DatabaseConnection.use_master do
-  very_important_transactions!
+Operation safety
+================
+
+LSpace is thread-safe, so entering a new LSpace on one thread won't affect any of the
+other Threads. In addition, LSpace also comes with extensions for
+[eventmachine](https://github.com/eventmachine/eventmachine) and
+[celluloid](http://celluloid.io/) which extends the notion of thread-safety to
+operation-safety.
+
+This means that even if you're doing multiple things on one thread, or one thing using
+many threads, the changes you make to LSpace will still be local to that thing.
+
+```ruby
+require 'lspace/eventmachine'
+EM::run
+  LSpace.with(:user_id => 5) do
+    EM::defer{ LSpace[:user_id] == 5; EM::stop }
+  end
 end
 ```
 
-Everything that happens in the `very_important_transactions!` block will use
-`LSpace[:preferred_connection]`, which is set to be the master database.
+See also [examples/eventmachine.rb](https://github.com/ConradIrwin/lspace/tree/master/examples/eventmachine.rb).
 
-This is useful for a whole host of stuff, we use it to ensure that every line logged by a
-given Http request is prefixed by a unique value, so we can tie them back together again.
-We also use it for generating trees of performance metrics.
 
-All of these concerns have one thing in common: they're not important to what your program
-is trying to do, but they are important for the way your program is trying to do things.
-It doesn't make sense to stuff everything into `LSpace`, though early versions of Lisp
-essentialy did that, because it makes your code harder to understand.
+```ruby
+require 'lspace/celluloid'
+class Actor
+  include Celluloid
+  def example
+    LSpace[:user_id] == 5
+  end
+end
 
-Eventmachine
-============
+LSpace.with(:user_id => 5) do
+  Actor.new.example!
+end
+```
 
-LSpace also comes with optional eventmachine integration. This adds a few hooks to
-Eventmachine to ensure that the current LSpace is preserved, even if your code has
-asynchronous callbacks; or runs things in eventmachine's threadpool:
+See also [examples/celluloid.rb](https://github.com/ConradIrwin/lspace/tree/master/examples/celluloid.rb).
 
-```ruby
-require 'lspace/eventmachine'
-require 'em-http-request'
+`lspace_reader`
+===============
 
-class Fetcher
-  lspace_reader :log_prefix
+Because reading from the current LSpace is the most common thing to do, you can define an
+accessor function that lets you do this:
 
-  def log(str)
-    puts "#{log_prefix}\t#{str}"
-  end
+```ruby
+class Task
+  lspace_reader :user_id
 
-  def fetch(url)
-    log "Fetching #{url}"
-    EM::HttpRequest.new(url).get.callback do
-      log "Fetched #{url}"
-    end
+  def process
+    puts "Running #{self} for User##{user_id}"
   end
 end
 
-EM::run do
-  LSpace.with(:log_prefix => rand(50000)) do
-    Fetcher.new.fetch("http://www.google.com")
-    Fetcher.new.fetch("http://www.yahoo.com")
-  end
-  LSpace.with(:log_prefix => rand(50000)) do
-    Fetcher.new.fetch("http://www.microsoft.com")
-  end
+LSpace.with(:user_id => 7) do
+  Task.new.process
 end
 ```
 
 Around filters
 ==============
 
-In addition to just storing variables across call-stacks, LSpace allows you to wrap each
-re-entry to your code with around filters. This lets you do things like maintain
-thread-local state in libraries like log4r that don't support LSpace.
+The ability of LSpace to be operation-local instead of merely thread local also enables
+you to add around filters to your code. Whenever your operation jumps between threads,
+or fires a callback, the around filters are called so that code running in the context of
+your operation is always wrapped.
+
+This is useful for maintaining operation-local state in libraries that only support
+thread-local state (like Log4r):
 
 ```ruby
 LSpace.around_filter do |&block|
@@ -97,9 +107,9 @@ LSpace.around_filter do |&block|
   end
 end
 ```
-
-You can also use this to log any unhandled exceptions that happen while your job is
-running without hitting the eventmachine default error handler:
+You can also use this to log any unhandled exceptions that happen while your operation is
+running without hitting the default error handler for your thread-pool or event loop. This
+makes tracking down the causes of unexpected exceptions much easier:
 
 ```ruby
 LSpace.around_filter do |&block|
@@ -111,11 +121,52 @@ LSpace.around_filter do |&block|
 end
 ```
 
+Use cases
+=========
+
+LSpace is good for the parts of your application that are not directly relevant to what
+you're actually trying to do, but are important to the manner in which your application is
+written.
+
+For example, when showing a user's page, it's normally fine to use a database slave. If
+the user is looking at their own page, then it's important to use a master database in
+case they've just edited their profile. To implement this without LSpace you have to push
+the `use_master_database` flag down through all of your page-rendering logic. With LSpace
+you can make this change in a much less brittle way:
+
+```ruby
+require 'lspace'
+class DatabaseConnection
+  def get_connection
+    LSpace[:preferred_connection] || any_free_connection
+  end
+
+  def self.use_master(&block)
+    LSpace.with(:preferred_connection => master_connection) do
+      block.call
+    end
+  end
+end
+
+DatabaseConnection.use_master do
+  very_important_transactions!
+end
+```
+
+Another good example is logging. We want to prefix log messages involved with handling one
+particular web request with the same unique string every time, so that we can tie all of
+those message together despite a large number of concurrent requests being handled.
+Without LSpace this would be a nightmare, as we'd have to push the `log_prefix` down into
+all parts of our code, with LSpace it becomes simple.
+
+Because the changes to LSpace are only visible within the current operation, or current
+block, it's much safer than global state; though it has many of the same benefits.
+
 Integrating with new libraries
 ================================
 
 If you are using a Thread-pool, or an actor system, or an event loop, you will need to
-teach it about LSpace in order to get the full benefit of the system.
+teach it about LSpace in order to get the correct operation-local semantics.
 
 There are two kinds of integration. Firstly, when your library accepts blocks from the
 programmer's code, and proceeds to run them on a different call-stack, you should call

data/examples/celluloid.rb

@@ -0,0 +1,45 @@
+require_relative '../lib/lspace/celluloid'
+module Logging
+  lspace_reader :log_prefix
+  def log(str)
+    puts "INFO #{log_prefix}: #{str}"
+  end
+end
+class Customer
+  include Logging
+  include Celluloid
+  def initialize(bob)
+    @bob = bob
+  end
+
+  def eat_lunch
+    consume @bob.make_sandwich
+  end
+
+  def consume(sandwich)
+    log "eating a #{sandwich}"
+  end
+end
+
+class Caterer
+  include Logging
+  include Celluloid
+  def make_sandwich
+    choice = ["Bacon", "Lettuce", "Tomato", "Ham", "Cheese", "Pickle", "Nutella"].sample
+    log "making a #{choice} sandwich"
+    sleep rand
+    "#{choice} sandwich"
+  end
+end
+
+bob = Caterer.new
+
+LSpace.with(:log_prefix => "Table 1") do
+  Customer.new(bob).eat_lunch!
+  Customer.new(bob).eat_lunch!
+end
+LSpace.with(:log_prefix => "Table 2") do
+  Customer.new(bob).eat_lunch!
+end
+
+sleep 1

data/examples/eventmachine.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+require 'lspace/eventmachine'
+require 'em-http-request'
+
+class Fetcher
+  lspace_reader :log_prefix
+
+  def log(str)
+    puts "#{log_prefix}\t#{str}"
+  end
+
+  def fetch(url)
+    log "Fetching #{url}"
+    EM::HttpRequest.new(url).get.callback do
+      log "Fetched #{url}"
+    end
+  end
+end
+
+EM::run do
+  LSpace.with(:log_prefix => rand(50000)) do
+    Fetcher.new.fetch("http://www.google.com")
+    Fetcher.new.fetch("http://www.yahoo.com")
+  end
+  LSpace.with(:log_prefix => rand(50000)) do
+    Fetcher.new.fetch("http://www.microsoft.com")
+  end
+end

data/lib/lspace/celluloid.rb

@@ -0,0 +1,29 @@
+require 'celluloid'
+require 'lspace'
+
+module Celluloid
+  class Call
+    alias_method :initialize_without_lspace, :initialize
+
+    def initialize(*args, &block)
+      initialize_without_lspace(*args, &block)
+      @lspace = LSpace.new
+    end
+  end
+
+  class SyncCall < Call
+    alias_method :dispatch_without_lspace, :dispatch
+
+    def dispatch(*args, &block)
+      LSpace.enter(@lspace) { dispatch_without_lspace(*args, &block) }
+    end
+  end
+
+  class AsyncCall < Call
+    alias_method :dispatch_without_lspace, :dispatch
+
+    def dispatch(*args, &block)
+      LSpace.enter(@lspace) { dispatch_without_lspace(*args, &block) }
+    end
+  end
+end

data/lib/lspace/eventmachine.rb

@@ -50,6 +50,7 @@ module EventMachine
     # @example
     #   module EchoServer
     #     def setup_lspace
+    #       LSpace[:log_prefix] = rand(100000).to_s(16)
     #       LSpace.around_filter do |&block|
     #         begin
     #           block.call
@@ -76,7 +77,11 @@ module EventMachine
     # 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) { super() } }
+      define_method(method) do |*a, &b|
+        LSpace.enter(@lspace) do
+          super()
+        end
+      end
     end
   end
 end

data/lspace.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "lspace"
-  s.version = "0.2"
+  s.version = "0.3"
   s.platform = Gem::Platform::RUBY
   s.author = "Conrad Irwin"
   s.email = "conrad.irwin@gmail.com"
@@ -14,4 +14,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'pry-rescue'
   s.add_development_dependency 'pry-stack_explorer'
   s.add_development_dependency 'eventmachine'
+  s.add_development_dependency 'celluloid'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'redcarpet'
 end

data/spec/celluloid_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+
+describe LSpace do
+  it "should be preserved across sync calls" do
+    seen = nil
+    actor = Class.new do
+      include Celluloid
+      define_method(:update_seen) do
+        seen = LSpace[:to_see]
+      end
+    end
+
+    LSpace.with(:to_see => 5) {
+      actor.new.update_seen
+    }
+    seen.should == 5
+  end
+
+  it "should be preserved across async calls" do
+    seen = nil
+    actor = Class.new do
+      include Celluloid
+      define_method(:update_seen) do
+        seen = LSpace[:to_see]
+      end
+    end
+
+    LSpace.with(:to_see => 7) {
+      actor.new.async.update_seen
+    }
+    sleep 0.1 # TODO, actor.join or equivalent?
+    seen.should == 7
+  end
+
+  it "should be preserved across async calls" do
+    seen = nil
+    actor = Class.new do
+      include Celluloid
+      define_method(:update_seen) do
+        seen = LSpace[:to_see]
+      end
+    end
+
+    LSpace.with(:to_see => 7) {
+      f = actor.new.future.update_seen
+      f.value
+    }
+    seen.should == 7
+  end
+end

data/spec/spec_helper.rb

@@ -1,5 +1,6 @@
 require_relative '../lib/lspace'
 require_relative '../lib/lspace/eventmachine'
+require_relative '../lib/lspace/celluloid'
 require 'pry-rescue/rspec'
 
 RSpec.configure do |c|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lspace
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-27 00:00:00.000000000 Z
+date: 2012-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -75,6 +75,54 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: celluloid
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides the convenience of global variables, without the safety concerns.
 email: conrad.irwin@gmail.com
 executables: []
@@ -85,12 +133,16 @@ files:
 - Gemfile
 - LICENSE.MIT
 - README.md
+- examples/celluloid.rb
+- examples/eventmachine.rb
 - lib/lspace.rb
+- lib/lspace/celluloid.rb
 - lib/lspace/class_methods.rb
 - lib/lspace/core_ext.rb
 - lib/lspace/eventmachine.rb
 - lib/lspace/thread.rb
 - lspace.gemspec
+- spec/celluloid_spec.rb
 - spec/class_method_spec.rb
 - spec/core_ext_spec.rb
 - spec/eventmachine_spec.rb