carbon 2.0.3 → 2.1.0

data/lib/carbon.rb

@@ -5,6 +5,7 @@ require 'carbon/future'
 
 module Carbon
   DOMAIN = 'http://impact.brighterplanet.com'
+  CONCURRENCY = 16
 
   # @private
   # Make sure there are no warnings about class vars.
@@ -17,6 +18,7 @@ module Carbon
   # @return [nil]
   def Carbon.key=(key)
     @@key = key
+    nil
   end
 
   # Get the key you've set.
@@ -26,51 +28,146 @@ module Carbon
     @@key
   end
 
-  # Do a simple query.
+  # Get impact estimates from Brighter Planet CM1; low-level method that does _not_ require you to define {Carbon::ClassMethods#emit_as} blocks; just pass emitter/param or objects that respond to +#as_impact_query+.
   #
-  # See the {file:README.html#API_response section about API responses} for an explanation of +Hashie::Mash+.
+  # Return values are {http://rdoc.info/github/intridea/hashie/Hashie/Mash Hashie::Mash} objects because they are a simple way to access a deeply nested response.
   #
-  # @param [String] emitter The {http://impact.brighterplanet.com/emitters.json camelcased emitter name}.
-  # @param [Hash] params Characteristics, your API key (if you didn't set it globally), timeframe, compliance, etc.
+  # Here's a map of what's included in a response:
   #
-  # @option params [Timeframe] :timeframe (Timeframe.this_year) What time period to focus the calculation on. See {https://github.com/rossmeissl/timeframe timeframe} documentation.
-  # @option params [Array<Symbol>] :comply ([]) What {http://impact.brighterplanet.com/protocols.json calculation protocols} to require.
-  # @option params [String, Numeric] _characteristic_ Pieces of data about an emitter. The {http://impact.brighterplanet.com/flights/options Flight characteristics API} lists valid keys like +:aircraft+, +:origin_airport+, etc.
+  #     certification
+  #     characteristics.{}.description
+  #     characteristics.{}.object
+  #     compliance.[]
+  #     decisions.{}.description
+  #     decisions.{}.methodology
+  #     decisions.{}.object
+  #     emitter
+  #     equivalents.{}
+  #     errors.[]
+  #     methodology
+  #     scope
+  #     timeframe.endDate
+  #     timeframe.startDate
   #
-  # @return [Hashie::Mash, Carbon::Future] An {file:README.html#API_response API response as documented in the README}
+  # @overload query(emitter, params)
+  #   Simplest form.
+  #   @param [String] emitter The {http://impact.brighterplanet.com/emitters.json emitter name}.
+  #   @param [optional, Hash] params Characteristics like airline/airport/etc., your API key (if you didn't set it globally), timeframe, compliance, etc.
+  #   @option params [Timeframe] :timeframe (Timeframe.this_year) What time period to focus the calculation on. See {https://github.com/rossmeissl/timeframe timeframe} documentation.
+  #   @option params [Array<Symbol>] :comply ([]) What {http://impact.brighterplanet.com/protocols.json calculation protocols} to require.
+  #   @option params [String, Numeric] <i>characteristic</i> Pieces of data about an emitter. The {http://impact.brighterplanet.com/flights/options Flight characteristics API} lists valid keys like +:aircraft+, +:origin_airport+, etc.
+  #   @return [Hashie::Mash] The API response, contained in an easy-to-use +Hashie::Mash+
   #
-  # @example A flight taken in 2009
-  #   Carbon.query('Flight', :origin_airport => 'MSN', :destination_airport => 'ORD', :date => '2009-01-01', :timeframe => Timeframe.new(:year => 2009), :comply => [:tcr])
-  def Carbon.query(emitter, params = {})
-    future = Future.new emitter, params
-    future.result
-  end
-
-  # Perform many queries in parallel. Can be *more than 90% faster* than doing them serially (one after the other).
+  # @overload query(o)
+  #   Pass in a single query-able object.
+  #   @param [#as_impact_query] o An object that responds to +#as_impact_query+, generally because you've declared {Carbon::ClassMethods#emit_as} on its parent class.
+  #   @return [Hashie::Mash] The API response, contained in an easy-to-use +Hashie::Mash+
   #
-  # See the {file:README.html#API_response section about API responses} for an explanation of +Hashie::Mash+.
+  # @overload query(os)
+  #   Get multiple impact estimates for arrays and/or query-able objects concurrently.
+  #   @param [Array<Array, #as_impact_query>] os An array of arrays in +[emitter, params]+ format and/or objects that respond to +#as_impact_query+.
+  #   @return [Array<Hashie::Mash>] An array of +Hashie::Mash+ objects in the same order.
   #
-  # @param [Array<Array>] queries Multiple queries like you would pass to {Carbon.query}
+  # @note We make up to 16 requests concurrently (hardcoded, per the Brighter Planet Terms of Service) and it can be more than 90% faster than running queries serially!
   #
-  # @return [Array<Hashie::Mash>] An array of {file:README.html#API_response API responses}, each a +Hashie::Mash+, in the same order as the queries.
+  # @note Using concurrency on JRuby, you may get errors like SOCKET: SET COMM INACTIVITY UNIMPLEMENTED 10 because under the hood we're using {https://github.com/igrigorik/em-http-request em-http-request}, which suffers from {https://github.com/eventmachine/eventmachine/issues/155 an issue with +pending_connect_timeout+}.
   #
-  # @note You may get errors like +SOCKET: SET COMM INACTIVITY UNIMPLEMENTED 10+ on JRuby because under the hood we're using {https://github.com/igrigorik/em-http-request em-http-request}, which suffers from {https://github.com/eventmachine/eventmachine/issues/155 an issue with +pending_connect_timeout+}.
+  # @example A flight taken in 2009
+  #   Carbon.query('Flight', :origin_airport => 'MSN', :destination_airport => 'ORD', :date => '2009-01-01', :timeframe => Timeframe.new(:year => 2009), :comply => [:tcr])
+  #
+  # @example How do I use a +Hashie::Mash+?
+  #   1.8.7 :001 > require 'rubygems'
+  #    => true 
+  #   1.8.7 :002 > require 'hashie/mash'
+  #    => true 
+  #   1.8.7 :003 > mash = Hashie::Mash.new(:hello => 'world')
+  #    => #<Hashie::Mash hello="world"> 
+  #   1.8.7 :004 > mash.hello
+  #    => "world" 
+  #   1.8.7 :005 > mash['hello']
+  #    => "world" 
+  #   1.8.7 :006 > mash[:hello]
+  #    => "world" 
+  #   1.8.7 :007 > mash.keys
+  #    => ["hello"] 
   #
-  # @example Two flights and an automobile trip
+  # @example Other examples of what's in the response
+  #   my_impact.carbon.object.value
+  #   my_impact.characteristics.airline.description
+  #   my_impact.equivalents.lightbulbs_for_a_week
+  #
+  # @example Flights and cars (concurrently, as arrays)
   #   queries = [
-  #     ['Flight', :origin_airport => 'MSN', :destination_airport => 'ORD', :date => '2009-01-01', :timeframe => Timeframe.new(:year => 2009), :comply => [:tcr]],
-  #     ['Flight', :origin_airport => 'SFO', :destination_airport => 'LAX', :date => '2011-09-29', :timeframe => Timeframe.new(:year => 2011), :comply => [:iso]],
-  #     ['AutomobileTrip', :make => 'Nissan', :model => 'Altima', :timeframe => Timeframe.new(:year => 2008), :comply => [:tcr]]
+  #     ['Flight', {:origin_airport => 'MSN', :destination_airport => 'ORD', :date => '2009-01-01', :timeframe => Timeframe.new(:year => 2009), :comply => [:tcr]}],
+  #     ['Flight', {:origin_airport => 'SFO', :destination_airport => 'LAX', :date => '2011-09-29', :timeframe => Timeframe.new(:year => 2011), :comply => [:iso]}],
+  #     ['Automobile', {:make => 'Nissan', :model => 'Altima', :timeframe => Timeframe.new(:year => 2008), :comply => [:tcr]}]
   #   ]
-  #   Carbon.multi(queries)
-  def Carbon.multi(queries)
-    futures = queries.map do |emitter, params|
-      future = Future.new emitter, params
-      future.multi!
-      future
-    end
-    Future.multi(futures).map do |future|
+  #   Carbon.query(queries)
+  #
+  # @example Flights and cars (concurrently, as query-able objects)
+  #   Carbon.query(MyFlight.all+MyCar.all)
+  #
+  # @example Cars month-by-month
+  #   cars_by_month = MyCar.all.inject([]) do |memo, my_car|
+  #     months.each do |first_day_of_the_month|
+  #       my_car.as_impact_query(:date => first_day_of_the_month)
+  #     end
+  #   end
+  #   Carbon.query(cars_by_month)
+  def Carbon.query(*args)
+    case Carbon.method_signature(*args)
+    when :query_array
+      query_array = args
+      future = Future.wrap query_array
+      future.result
+    when :o
+      o = args.first
+      future = Future.wrap o
       future.result
+    when :os
+      os = args.first
+      futures = os.map do |o|
+        future = Future.wrap o
+        future.multi!
+        future
+      end
+      Future.multi(futures).map do |future|
+        future.result
+      end
+    end
+  end
+
+  # Determine if a variable is a +[emitter, param]+ style "query"
+  # @private
+  def Carbon.is_query_array?(query)
+    return false unless query.is_a?(::Array)
+    return false unless query.first.is_a?(::String) or query.first.is_a?(::Symbol)
+    return true if query.length == 1
+    return true if query.length == 2 and query.last.is_a?(::Hash)
+    false
+  end
+
+  # Determine what method signature/overloading/calling style is being used
+  # @private
+  def Carbon.method_signature(*args)
+    first_arg = args.first
+    case args.length
+    when 1
+      if is_query_array?(args)
+        # query('Flight')
+        :query_array
+      elsif first_arg.respond_to?(:as_impact_query)
+        # query(my_flight)
+        :o
+      elsif first_arg.is_a?(::Array) and first_arg.all? { |o| o.respond_to?(:as_impact_query) or is_query_array?(o) }
+        # query([my_flight, my_flight])
+        :os
+      end
+    when 2
+      if is_query_array?(args)
+        # query('Flight', :origin_airport => 'LAX')
+        :query_array
+      end
     end
   end
 
@@ -84,18 +181,14 @@ module Carbon
   module ClassMethods
     # DSL for declaring how to represent this class an an emitter.
     #
+    # See also {Carbon::Registry::Registrar#provide}.
+    #
     # You get this when you +include Carbon+ in a class.
     #
     # @param [String] emitter The {http://impact.brighterplanet.com/emitters.json camelcased emitter name}.
     #
     # @return [nil]
     #
-    # Things to note in the MyFlight example:
-    #
-    # * Sending +:origin+ to Brighter Planet *as* +:origin_airport+. Otherwise Brighter Planet won't recognize +:origin+.
-    # * Saying we're *keying* on one code or another. Otherwise Brighter Planet will first try against full names and possibly other columns.
-    # * Giving *blocks* to pull codes from +MyAircraft+ and +MyAirline+ objects. Otherwise you might get a querystring like +airline[iata_code]=#<MyAirline [...]>+
-    #
     # @example MyFlight
     #   # A a flight in your data warehouse
     #   class MyFlight
@@ -135,6 +228,15 @@ module Carbon
   end
 
   # A query like what you could pass into +Carbon.query+.
+  #
+  # @param [Hash] extra_params Anything you want to override.
+  #
+  # @option extra_params [Timeframe] :timeframe
+  # @option extra_params [Array<Symbol>] :comply
+  # @option extra_params [String] :key In case you didn't define it globally, or want to use a different one here.
+  # @option extra_params [String, Numeric] <i>characteristic</i> Override pieces of data about an emitter.
+  #
+  # @return [Array] Something you could pass into +Carbon.query+.
   def as_impact_query(extra_params = {})
     registration = Registry.instance[self.class.name]
     params = registration.characteristics.inject({}) do |memo, (method_id, translation_options)|
@@ -155,34 +257,18 @@ module Carbon
     [ registration.emitter, params.merge(extra_params) ]
   end
 
-  # Get an impact estimate from Brighter Planet CM1.
+  # Get an impact estimate from Brighter Planet CM1; high-level convenience method that requires a {Carbon::ClassMethods#emit_as} block.
   #
   # You get this when you +include Carbon+ in a class.
   #
-  # The return value is a {http://rdoc.info/github/intridea/hashie/Hashie/Mash Hashie::Mash} because it's a simple way to access a deep response object.
+  # See {Carbon.query} for an explanation of the return value, a +Hashie::Mash+.
   #
-  # Here's a map of what's included in a response:
-  #
-  #       certification
-  #       characteristics.{}.description
-  #       characteristics.{}.object
-  #       compliance.[]
-  #       decisions.{}.description
-  #       decisions.{}.methodology
-  #       decisions.{}.object
-  #       emitter
-  #       equivalents.{}
-  #       errors.[]
-  #       methodology
-  #       scope
-  #       timeframe.endDate
-  #       timeframe.startDate
-  #
-  # @param [Hash] extra_params Anything that your +emit_as+ won't include.
+  # @param [Hash] extra_params Anything you want to override.
   #
   # @option extra_params [Timeframe] :timeframe
   # @option extra_params [Array<Symbol>] :comply
   # @option extra_params [String] :key In case you didn't define it globally, or want to use a different one here.
+  # @option extra_params [String, Numeric] <i>characteristic</i> Override pieces of data about an emitter.
   #
   # @return [Hashie::Mash]
   #
@@ -197,21 +283,9 @@ module Carbon
   #   => "kilograms"
   #   ?> my_impact.methodology
   #   => "http://impact.brighterplanet.com/flights?[...]"
-  #
-  # @example How do I use a Hashie::Mash?
-  #   ?> mash['hello']
-  #   => "world"
-  #   ?> mash.hello
-  #   => "world"
-  #   ?> mash.keys
-  #   => ["hello"]
-  #
-  # @example Other examples of what's in the response
-  #   my_impact.carbon.object.value
-  #   my_impact.characteristics.airline.description
-  #   my_impact.equivalents.lightbulbs_for_a_week
   def impact(extra_params = {})
-    future = Future.new(*as_impact_query(extra_params))
+    query_array = as_impact_query extra_params
+    future = Future.wrap query_array
     future.result
   end
 end

data/lib/carbon/future.rb

@@ -3,59 +3,42 @@ require 'net/http'
 require 'cache_method'
 require 'hashie/mash'
 require 'multi_json'
+require 'em-http-request'
 
 module Carbon
   # @private
   class Future
     class << self
+      def wrap(query_array_or_o)
+        if query_array_or_o.is_a?(::Array)
+          new(*query_array_or_o)
+        else
+          new(*query_array_or_o.as_impact_query)
+        end
+      end
+
       def single(future)
         uri = ::URI.parse("#{Carbon::DOMAIN}/#{future.emitter.underscore.pluralize}.json")
         raw_result = ::Net::HTTP.post_form(uri, future.params)
-        result = ::Hashie::Mash.new
-        case raw_result
-        when ::Net::HTTPSuccess
-          result.status = raw_result.code.to_i
-          result.success = true
-          result.merge! ::MultiJson.decode(raw_result.body)
-        else
-          result.status = raw_result.code.to_i
-          result.success = false
-          result.errors = [raw_result.body]
-        end
-        result
+        future.finalize raw_result.code.to_i, raw_result.body
+        future
       end
 
       def multi(futures)
-        uniq_pending_futures = futures.uniq.select do |future|
-          future.pending?
-        end
+        uniq_pending_futures = futures.uniq.select { |future| future.pending? }
         return futures if uniq_pending_futures.empty?
-        require 'em-http-request'
+        pool_size = [Carbon::CONCURRENCY, uniq_pending_futures.length].min
         multi = ::EventMachine::MultiRequest.new
+        pool = (0..(pool_size-1)).map { ::EventMachine::HttpRequest.new(Carbon::DOMAIN) }
+        pool_idx = 0
         ::EventMachine.run do
           uniq_pending_futures.each do |future|
-            multi.add future, ::EventMachine::HttpRequest.new(Carbon::DOMAIN).post(:path => "/#{future.emitter.underscore.pluralize}.json", :body => future.params)
+            multi.add future, pool[pool_idx].post(:path => "/#{future.emitter.underscore.pluralize}.json", :body => future.params)
+            pool_idx = (pool_idx + 1) % pool_size
           end
           multi.callback do
-            multi.responses[:callback].each do |future, http|
-              result = ::Hashie::Mash.new
-              result.status = http.response_header.status
-              if (200..299).include?(result.status)
-                result.success = true
-                result.merge! ::MultiJson.decode(http.response)
-              else
-                result.success = false
-                result.errors = [http.response]
-              end
-              future.result = result
-            end
-            multi.responses[:errback].each do |future, http|
-              result = ::Hashie::Mash.new
-              result.status = http.response_header.status
-              result.success = false
-              result.errors = ['Timeout or other network error.']
-              future.result = result
-            end
+            multi.responses[:callback].each { |future, http| future.finalize http.response_header.status, http.response }
+            multi.responses[:errback].each  { |future, http| future.finalize http.response_header.status }
             ::EventMachine.stop
           end
         end
@@ -86,16 +69,27 @@ module Carbon
       @result.nil? and !cache_method_cached?(:result)
     end
 
-    def result=(result)
-      @result = result
-      self.result # force this to be cached
+    def finalize(code, body = nil)
+      memo = ::Hashie::Mash.new
+      memo.code = code
+      case code
+      when (200..299)
+        memo.success = true
+        memo.merge! ::MultiJson.decode(body)
+      else
+        memo.success = false
+        memo.errors = [body]
+      end
+      @result = memo
+      self.result # make sure it gets cached
     end
 
     def result
       if @result
         @result
       elsif not multi?
-        @result = Future.single(self)
+        Future.single self
+        @result
       end
     end
     cache_method :result, 3_600 # one hour

data/lib/carbon/registry.rb

@@ -23,6 +23,8 @@ module Carbon
       
       # Indicate that you will send in a piece of data about the emitter.
       #
+      # Called inside of {Carbon::ClassMethods#emit_as} blocks.
+      #
       # @param [Symbol] method_id What method to call to get the value in question.
       #
       # @option translation_options [Symbol] :as (name of the method) If your method name does not match the Brighter Planet characteristic name.
@@ -34,6 +36,22 @@ module Carbon
       #
       # @yield [] Pass a block for the common use case of calling a method on a object.
       #
+      # Things to note in the MyFlight example:
+      #
+      # * Sending +:origin+ to Brighter Planet *as* +:origin_airport+. Otherwise Brighter Planet won't recognize +:origin+.
+      # * Saying we're *keying* on one code or another. Otherwise Brighter Planet will first try against full names and possibly other columns.
+      # * Giving *blocks* to pull codes from +MyAircraft+ and +MyAirline+ objects. Otherwise you might get a querystring like +airline[iata_code]=#<MyAirline [...]>+
+      #
+      # @example The canonical MyFlight example
+      #   emit_as 'Flight' do
+      #     provide :segments_per_trip
+      #     provide :trips
+      #     provide :origin, :as => :origin_airport, :key => :iata_code
+      #     provide :destination, :as => :destination_airport, :key => :iata_code
+      #     provide(:airline, :key => :iata_code) { |f| f.airline.try(:iata_code) }
+      #     provide(:aircraft, :key => :icao_code) { { |f| f.aircraft.try(:icao_code) }
+      #   end
+      #
       # @example Your method is named one thing but should be sent +:as+ something else.
       #   provide :my_distance, :as => :distance
       #

data/lib/carbon/version.rb

@@ -1,3 +1,3 @@
 module Carbon
-  VERSION = "2.0.3"
+  VERSION = "2.1.0"
 end

data/test/carbon_test.rb

@@ -34,7 +34,6 @@ class MyNissanAltima
     provide :model
     provide :model_year, :as => :year
     provide :fuel_type, :as => :automobile_fuel, :key => :code
-    
     provide(:nil_make) { |my_nissan_altima| my_nissan_altima.nil_make.try(:blam!) }
     provide :nil_model
   end
@@ -46,114 +45,81 @@ describe Carbon do
   end
 
   describe :query do
-    it "calculates flight impact" do
-      result = Carbon.query('Flight', :origin_airport => 'LAX', :destination_airport => 'SFO', :segments_per_trip => 1, :trips => 1)
-      result.decisions.carbon.object.value.must_be_close_to 200, 50
-    end
-    it "gets back characteristics" do
-      result = Carbon.query('Flight', :origin_airport => 'LAX', :destination_airport => 'SFO', :segments_per_trip => 1, :trips => 1)
-      result.characteristics.origin_airport.description.must_match %r{lax}i
-    end
-    it "tells you if the query is successful" do
-      result = Carbon.query('Flight')
-      result.success.must_equal true
-    end
-    it "is gentle about errors" do
-      result = Carbon.query('Monkey')
-      result.success.must_equal false
-    end
-    it "sends timeframe properly" do
-      result = Carbon.query('Flight', :timeframe => Timeframe.new(:year => 2009))
-      result.timeframe.startDate.must_equal '2009-01-01'
-      result.timeframe.endDate.must_equal '2010-01-01'
-    end
-    it "sends key properly" do
-      with_web_mock do
-        WebMock.stub_request(:post, 'http://impact.brighterplanet.com/flights.json').with(:key => 'carbon_test').to_return(:status => 500, :body => 'Good job')
-        result = Carbon.query('Flight')
-        result.errors.first.must_equal 'Good job'
+    describe '(one at a time)' do
+      it "calculates flight impact" do
+        result = Carbon.query('Flight', :origin_airport => 'LAX', :destination_airport => 'SFO', :segments_per_trip => 1, :trips => 1)
+        result.decisions.carbon.object.value.must_be_close_to 200, 50
       end
-    end
-  end
-
-  describe :multi do
-    before do
-      @queries = []
-      @queries << ['Flight', {:origin_airport => 'LAX', :destination_airport => 'SFO', :segments_per_trip => 1, :trips => 1}]
-      @queries << ['Flight', {:origin_airport => 'MSN', :destination_airport => 'ORD', :segments_per_trip => 1, :trips => 1}]
-      @queries << ['Flight', {:origin_airport => 'IAH', :destination_airport => 'DEN', :segments_per_trip => 1, :trips => 1}]
-      @queries << ['RailTrip', {:distance => 25}]
-      @queries << ['RailTrip', {:rail_class => 'commuter'}]
-      @queries << ['RailTrip', {:rail_traction => 'electric'}]
-      @queries << ['AutomobileTrip', {:make => 'Nissan', :model => 'Altima'}]
-      @queries << ['AutomobileTrip', {:make => 'Toyota', :model => 'Prius'}]
-      @queries << ['AutomobileTrip', {:make => 'Ford', :model => 'Taurus'}]
-      @queries << ['Residence', {:urbanity => 'City'}]
-      @queries << ['Residence', {:zip_code => '53703'}]
-      @queries << ['Residence', {:bathrooms => 4}]
-      @queries << ['Monkey', {:bananas => '1'}]
-      @queries << ['Monkey', {:bananas => '2'}]
-      @queries << ['Monkey', {:bananas => '3'}]
-      @queries = @queries.sort_by { rand }
-    end
-    it "doesn't hang up on 0 queries" do
-      Timeout.timeout(0.5) { Carbon.multi([]) }.must_equal []
-    end
-    it "runs multiple queries at once" do
-      reference_results = @queries.map do |query|
-        Carbon.query(*query)
-      end
-      flush_cache! # important!
-      multi_results = Carbon.multi(@queries)
-      error_count = 0
-      multi_results.each do |result|
-        if result.success
-          result.decisions.carbon.object.value.must_be :>, 0
-          result.decisions.carbon.object.value.must_be :<, 10_000
-        else
-          error_count += 1
-        end
+      it "can be used on an object that response to #as_impact_query" do
+        Carbon.query(MyNissanAltima.new(2006)).decisions.must_equal MyNissanAltima.new(2006).impact.decisions
       end
-      error_count.must_equal 3
-      reference_results.each_with_index do |reference_result, idx|
-        if reference_result.success
-          multi_results[idx].decisions.must_equal reference_result.decisions
-        else
-          multi_results[idx].must_equal reference_result
-        end
+      it "gets back characteristics" do
+        result = Carbon.query('Flight', :origin_airport => 'LAX', :destination_airport => 'SFO', :segments_per_trip => 1, :trips => 1)
+        result.characteristics.origin_airport.description.must_match %r{lax}i
       end
-    end
-    it "is faster than just calling .query over and over" do
-      # warm up the cache on the other end
-      @queries.each { |query| Carbon.query(*query) }
-      flush_cache! # important!
-      single_threaded_time = ::Benchmark.realtime do
-        @queries.each { |query| Carbon.query(*query) }
+      it "tells you if the query is successful" do
+        result = Carbon.query('Flight')
+        result.success.must_equal true
       end
-      flush_cache! # important!
-      multi_threaded_time = ::Benchmark.realtime do
-        Carbon.multi(@queries)
+      it "is gentle about errors" do
+        result = Carbon.query('Monkey')
+        result.success.must_equal false
       end
-      cached_single_threaded_time = ::Benchmark.realtime do
-        @queries.each { |query| Carbon.query(*query) }
+      it "sends timeframe properly" do
+        result = Carbon.query('Flight', :timeframe => Timeframe.new(:year => 2009))
+        result.timeframe.startDate.must_equal '2009-01-01'
+        result.timeframe.endDate.must_equal '2010-01-01'
       end
-      cached_multi_threaded_time = ::Benchmark.realtime do
-        Carbon.multi(@queries)
+      it "sends key properly" do
+        with_web_mock do
+          WebMock.stub_request(:post, 'http://impact.brighterplanet.com/flights.json').with(:key => 'carbon_test').to_return(:status => 500, :body => 'Good job')
+          result = Carbon.query('Flight')
+          result.errors.first.must_equal 'Good job'
+        end
       end
-      multi_threaded_time.must_be :<, single_threaded_time
-      cached_single_threaded_time.must_be :<, multi_threaded_time
-      cached_multi_threaded_time.must_be :<, multi_threaded_time
-      $stderr.puts "   Multi-threaded was #{((single_threaded_time - multi_threaded_time) / single_threaded_time * 100).round}% faster than single-threaded"
-      $stderr.puts "   Cached single-threaded was #{((multi_threaded_time - cached_single_threaded_time) / multi_threaded_time * 100).round}% faster than uncached multi-threaded"
-      $stderr.puts "   Cached multi-threaded was #{((multi_threaded_time - cached_multi_threaded_time) / multi_threaded_time * 100).round}% faster than uncached multi-threaded"
     end
-    it "safely uniq's and caches queries" do
-      reference_results = @queries.map do |query|
-        Carbon.query(*query)
+    describe '(in parallel)' do
+      before do
+        @queries = []
+        @queries << ['Flight', {:origin_airport => 'LAX', :destination_airport => 'SFO', :segments_per_trip => 1, :trips => 1}]
+        @queries << ['Flight', {:origin_airport => 'MSN', :destination_airport => 'ORD', :segments_per_trip => 1, :trips => 1}]
+        @queries << ['Flight', {:origin_airport => 'IAH', :destination_airport => 'DEN', :segments_per_trip => 1, :trips => 1}]
+        @queries << ['RailTrip', {:distance => 25}]
+        @queries << ['RailTrip', {:rail_class => 'commuter'}]
+        @queries << ['RailTrip', {:rail_traction => 'electric'}]
+        @queries << ['AutomobileTrip', {:make => 'Nissan', :model => 'Altima'}]
+        @queries << ['AutomobileTrip', {:make => 'Toyota', :model => 'Prius'}]
+        @queries << ['AutomobileTrip', {:make => 'Ford', :model => 'Taurus'}]
+        @queries << ['Residence', {:urbanity => 'City'}]
+        @queries << ['Residence', {:zip_code => '53703'}]
+        @queries << ['Residence', {:bathrooms => 4}]
+        @queries << ['Monkey', {:bananas => '1'}]
+        @queries << ['Monkey', {:bananas => '2'}]
+        @queries << ['Monkey', {:bananas => '3'}]
+        @queries = @queries.sort_by { rand }
+      end
+      it "doesn't hang up on 0 queries" do
+        Timeout.timeout(0.5) { Carbon.query([]) }.must_equal []
+      end
+      it "can be used on objects that respond to #as_impact_query" do
+        Carbon.query([MyNissanAltima.new(2001), MyNissanAltima.new(2006)]).map(&:decisions).must_equal Carbon.query([MyNissanAltima.new(2001).as_impact_query, MyNissanAltima.new(2006).as_impact_query]).map(&:decisions)
       end
-      flush_cache! # important!
-      3.times do
-        multi_results = Carbon.multi(@queries)
+      it "runs multiple queries at once" do
+        reference_results = @queries.map do |query|
+          Carbon.query(*query)
+        end
+        flush_cache! # important!
+        multi_results = Carbon.query(@queries)
+        error_count = 0
+        multi_results.each do |result|
+          if result.success
+            result.decisions.carbon.object.value.must_be :>, 0
+            result.decisions.carbon.object.value.must_be :<, 10_000
+          else
+            error_count += 1
+          end
+        end
+        error_count.must_equal 3
         reference_results.each_with_index do |reference_result, idx|
           if reference_result.success
             multi_results[idx].decisions.must_equal reference_result.decisions
@@ -162,9 +128,92 @@ describe Carbon do
           end
         end
       end
+      it "is faster than single threaded" do
+        # warm up the cache on the other end
+        @queries.each { |query| Carbon.query(*query) }
+        flush_cache! # important!
+        single_threaded_time = ::Benchmark.realtime do
+          @queries.each { |query| Carbon.query(*query) }
+        end
+        flush_cache! # important!
+        multi_threaded_time = ::Benchmark.realtime do
+          Carbon.query(@queries)
+        end
+        cached_single_threaded_time = ::Benchmark.realtime do
+          @queries.each { |query| Carbon.query(*query) }
+        end
+        cached_multi_threaded_time = ::Benchmark.realtime do
+          Carbon.query(@queries)
+        end
+        multi_threaded_time.must_be :<, single_threaded_time
+        cached_single_threaded_time.must_be :<, multi_threaded_time
+        cached_multi_threaded_time.must_be :<, multi_threaded_time
+        $stderr.puts "   Multi-threaded was #{((single_threaded_time - multi_threaded_time) / single_threaded_time * 100).round}% faster than single-threaded"
+        $stderr.puts "   Cached single-threaded was #{((multi_threaded_time - cached_single_threaded_time) / multi_threaded_time * 100).round}% faster than uncached multi-threaded"
+        $stderr.puts "   Cached multi-threaded was #{((multi_threaded_time - cached_multi_threaded_time) / multi_threaded_time * 100).round}% faster than uncached multi-threaded"
+      end
+      it "safely uniq's and caches queries" do
+        reference_results = @queries.map do |query|
+          Carbon.query(*query)
+        end
+        flush_cache! # important!
+        3.times do
+          multi_results = Carbon.query(@queries)
+          reference_results.each_with_index do |reference_result, idx|
+            if reference_result.success
+              multi_results[idx].decisions.must_equal reference_result.decisions
+            else
+              multi_results[idx].must_equal reference_result
+            end
+          end
+        end
+      end
     end
   end
-  
+
+  describe :method_signature do
+    it "recognizes emitter_param" do
+      Carbon.method_signature('Flight').must_equal :query_array
+      Carbon.method_signature('Flight', :origin_airport => 'LAX').must_equal :query_array
+      Carbon.method_signature(:flight).must_equal :query_array
+      Carbon.method_signature(:flight, :origin_airport => 'LAX').must_equal :query_array
+    end
+    it "recognizes o" do
+      Carbon.method_signature(MyNissanAltima.new(2006)).must_equal :o
+    end
+    it "recognizes os" do
+      Carbon.method_signature([MyNissanAltima.new(2001)]).must_equal :os
+      Carbon.method_signature([['Flight']]).must_equal :os
+      Carbon.method_signature([['Flight', {:origin_airport => 'LAX'}]]).must_equal :os
+      Carbon.method_signature([['Flight'], ['Flight']]).must_equal :os
+      Carbon.method_signature([['Flight', {:origin_airport => 'LAX'}], ['Flight', {:origin_airport => 'LAX'}]]).must_equal :os
+      [MyNissanAltima.new(2006), ['Flight'], ['Flight', {:origin_airport => 'LAX'}]].permutation.each do |p|
+        Carbon.method_signature(p).must_equal :os
+      end
+    end
+    it "does not want splats for concurrent queries" do
+      Carbon.method_signature(['Flight'], ['Flight']).must_be_nil
+      Carbon.method_signature(MyNissanAltima.new(2001), MyNissanAltima.new(2001)).must_be_nil
+      [MyNissanAltima.new(2006), ['Flight'], ['Flight', {:origin_airport => 'LAX'}]].permutation.each do |p|
+        Carbon.method_signature(*p).must_be_nil
+      end
+    end
+    it "does not like weirdness" do
+      Carbon.method_signature('Flight', 'Flight').must_be_nil
+      Carbon.method_signature('Flight', ['Flight']).must_be_nil
+      Carbon.method_signature(['Flight'], 'Flight').must_be_nil
+      Carbon.method_signature(['Flight', 'Flight']).must_be_nil
+      Carbon.method_signature(['Flight', ['Flight']]).must_be_nil
+      Carbon.method_signature([['Flight'], 'Flight']).must_be_nil
+      Carbon.method_signature(MyNissanAltima.new(2001), [MyNissanAltima.new(2001)]).must_be_nil
+      Carbon.method_signature([MyNissanAltima.new(2001)], MyNissanAltima.new(2001)).must_be_nil
+      Carbon.method_signature([MyNissanAltima.new(2001)], [MyNissanAltima.new(2001)]).must_be_nil
+      Carbon.method_signature([MyNissanAltima.new(2001), [MyNissanAltima.new(2001)]]).must_be_nil
+      Carbon.method_signature([[MyNissanAltima.new(2001)], MyNissanAltima.new(2001)]).must_be_nil
+      Carbon.method_signature([[MyNissanAltima.new(2001)], [MyNissanAltima.new(2001)]]).must_be_nil
+    end
+  end
+
   describe "mixin" do
     describe :emit_as do
       it "overwrites old emit_as blocks" do
@@ -176,7 +225,7 @@ describe Carbon do
       end
     end
     describe '#as_impact_query' do
-      it "sets up an query to be run by Carbon.multi" do
+      it "sets up an query to be run by Carbon.query" do
         a = MyNissanAltima.new(2006)
         a.as_impact_query.must_equal ["Automobile", {:make=>"Nissan", :model=>"Altima", :year=>2006, "automobile_fuel[code]"=>"R"}]
       end