task_batcher 0.1.0

data/LICENSE

@@ -0,0 +1,30 @@
+Released under the three-clause BSD open source license.
+http://opensource.org/licenses/BSD-3-Clause
+
+Copyright (c) 2013, Apartment List
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+     list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+     this list of conditions and the following disclaimer in the documentation
+     and/or other materials provided with the distribution.
+
+ * Neither the name of Apartment List nor the names of its contributors may
+     be used to endorse or promote products derived from this software without
+     specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,118 @@
+TaskBatcher
+===
+
+Some tasks, like database inserts, are much more efficient to process in a
+batch.  However, we generally want our tasks to be processed "soon" even if
+there's only one task.  The TaskBatcher gem groups tasks by a taskname
+parameter, and starts a timer when the first task comes in.  After the batch
+timer expires, it processes all tasks that it received in that time.  (The
+caller provides the block to process the tasks.)
+
+Uses EventMachine under the hood.  May be combined with Messenger for
+durability guarantees.
+
+Tested under Ruby 1.9.3 and 2.0.0.
+
+Released under the three-clause BSD open source license.
+http://opensource.org/licenses/BSD-3-Clause
+See the LICENSE file.
+
+Usage
+===
+You can either use the TaskManager module to make procedural calls, or
+instantiate a BatchManager object.  BatchManager objects have a cleaner API,
+if you have tasks which are all processed in the same scope.
+
+Using a BatchManager
+---
+```ruby
+taskname = 'db-insert'    # can be any valid hash key: string, symbol, etc.
+duration = 15             # batch duration of 15 seconds
+callback = lambda { |result| print "The return value was #{result}.\n" }
+
+mgr = TaskBatcher::BatchManager.new(taskname, callback, duration) do |tasks|
+   # This batcher performs the operation of inserting rows into a DB.
+   # This is an example of how to aggregate processing of many tasks.
+   sql = "INSERT INTO pet_owners VALUES ("
+   tasks.each do |task|
+     # each +task+ is the params hash from a single call to #task
+     sql += "( #{task[:name]}, #{task[:pet]} ), "
+   end
+   sql += ")\n"
+   result = (execute that SQL)    # +result+ will be available to a callback
+end
+
+mgr.task  name: 'Alice', pet: 'moa'
+mgr.task  name: 'Bob',   pet: 'cassowary'
+#  ... etc. ...
+```
+
+Using the TaskBatcher module
+---
+```ruby
+ taskname = 'db-insert'    # can be any valid hash key: string, symbol, etc.
+ TaskBatcher.set_batch_duration(taskname, 15)
+ callback = lambda {|retval| print "The return value was #{retval}\n"}
+
+ def db_insert(data_list)
+   sql = "INSERT INTO pet_owners VALUES ("
+   data_list.each do |data|
+     # each +data+ row is the params hash from a single call to #task
+     sql += "( #{data[:name]}, #{data[:pet]} ), "
+   end
+   sql += ")\n"
+   retval = (execute that SQL)    # retval will be available to a callback
+ end
+
+ pet_owner_1 = {name: 'Alice', pet: 'moa'}
+ TaskBatcher.task(taskname, pet_owner_1, callback) do |tasks|
+     db_insert(tasks)
+ end
+
+ pet_owner_2 = {name: 'Bob', pet: 'cassowary'}
+ TaskBatcher.task(taskname, pet_owner_2, callback) do |tasks|
+     db_insert(tasks)
+ end
+  ... etc. ...
+```
+
+Setting batch durations
+===
+```ruby
+  TaskBatcher.default_batch_duration           # returns 60, the initial default
+
+  mytask = 'task name 1'
+  TaskBatcher.set_batch_duration(mytask, 120)  # 2 minutes
+  TaskBatcher.batch_duration(mytask)           # returns 120
+  TaskBatcher.batch_duration('your task')      # returns 60, the default
+
+  TaskBatcher.set_default_batch_duration(30)
+  TaskBatcher.batch_duration('another task')   # returns 30
+  TaskBatcher.batch_duration('your task')      # returns 30 -- default changed
+  TaskBatcher.batch_duration(mytask)           # still returns 120
+```
+
+Notes
+===
+  * Batches are grouped by +taskname+.  ('db-insert' in the first example.)
+  * If no batch duration is given, the default batch duration is used.  The
+      default batch duration is initially 60 seconds, but clients can change
+      the default.
+  * Batch parameters may be of any type, though hashes seem an obvious choice.
+      The batched function block must accept a data-list, where a single
+      data-item  constitutes the parameters of a single call within the batch.
+  * The batched function block can return any data type.  If a callback is
+      provided, it must accept the data type returned by the block.  A
+      callback value of nil indicates that the return value may be discarded.
+  * TaskBatcher uses Event Machine.  Event-driven programming is tricky, and
+      Event Machine is complex on top of that.  Due to fundamental
+      limitations, TaskBatcher can only guarantee that batches will be
+      processed after a delay of *at least* the batch duration.
+  * Since Ruby's threading has limitations, TaskBatcher gives best performance
+      if most/all of the client code is event-driven and uses Event Machine.
+
+References:
+===
+  * Event Machine: http://everburning.com/wp-content/uploads/2009/02/eventmachine_introduction_10.pdf
+
+  * Batchers: http://www.youtube.com/watch?v=EIyixC9NsLI

data/lib/task_batcher.rb

@@ -0,0 +1,301 @@
+# TaskBatcher allows clients to trigger jobs (such as database writes, e.g.)
+# which are more efficiently processed in batches, but which should be processed
+# reasonably quickly in any case.  Each batch has a batch duration.  Initially,
+# invoking #task starts a batch and adds the initial task's parameters, and
+# also starts a timer.  Until the batch duration expires, any other calls to
+# #task (with the same task name) will add the new call's parameters to the
+# batch's collection.  When the batch duration expires, the block processes the
+# list of parameters.
+#
+# A procedural API (in the TaskBatcher module) and a BatchManager object are
+# both provided.  The BatchManager has a cleaner API, if your tasks are all
+# processed within the same scope.
+#
+# Example usage:
+#
+# * BatchManager (OO) API:
+# =============================================================================
+#  taskname = 'db-insert'    # can be any valid hash key: string, symbol, etc.
+#  duration = 15             # batch duration of 15 seconds
+#  callback = lambda { |result| print "The return value was #{result}.\n" }
+#
+#  mgr = TaskBatcher::BatchManager.new(taskname, callback, duration) do |tasks|
+#     # This batcher performs the operation of inserting rows into a DB.
+#     # This is an example of how to aggregate processing of many tasks.
+#     sql = "INSERT INTO pet_owners VALUES ("
+#     tasks.each do |task|
+#       # each +task+ is the params hash from a single call to #task
+#       sql += "( #{task[:name]}, #{task[:pet]} ), "
+#     end
+#     sql += ")\n"
+#     result = (execute that SQL)    # +result+ will be available to a callback
+#  end
+#
+#  mgr.task  name: 'Alice', pet: 'moa'
+#  mgr.task  name: 'Bob',   pet: 'cassowary'
+#  #  ... etc. ...
+# =============================================================================
+#
+# * Procedural TaskBatcher API:
+# =============================================================================
+#  taskname = 'db-insert'  # can be any valid hash key: string, symbol, etc.
+#  callback = lambda {|retval| print "The return value was #{retval}\n"}
+#  TaskBatcher.set_batch_duration(taskname, 15)
+#
+#  def db_insert(data_list)
+#    sql = "INSERT INTO pet_owners VALUES ("
+#    data_list.each do |data|
+#      # each +data+ row is the params hash from a single call to #task
+#      sql += "( #{data[:name]}, #{data[:pet]} ), "
+#    end
+#    sql += ")\n"
+#    retval = (execute that SQL)    # retval will be available to a callback
+#  end
+#
+#  pet_owner_1 = {name: 'Alice', pet: 'moa'}
+#  TaskBatcher.task(taskname, pet_owner_1, callback) do |tasks|
+#      db_insert(tasks)
+#  end
+#
+#  pet_owner_2 = {name: 'Bob', pet: 'cassowary'}
+#  TaskBatcher.task(taskname, pet_owner_2, callback) do |tasks|
+#      db_insert(tasks)
+#  end
+#   ... etc. ...
+# =============================================================================
+#
+# Notes:
+#  * Batches are grouped by +taskname+.  ('db-insert' in the example above.)
+#  * If no batch duration is given, the default batch duration is used.  The
+#      default batch duration is initially 60 seconds, but clients can change
+#      the default.
+#  * Batch parameters may be of any type, though hashes seem an obvious choice.
+#      The batched function block must accept a data-list, where a single
+#      data-item  constitutes the parameters of a single call within the batch.
+#  * The batched function block can return any data type.  If a callback is
+#      provided, it must accept the data type returned by the block.  A
+#      callback value of nil indicates that the return value may be discarded.
+#  * TaskBatcher uses Event Machine.  Event-driven programming is tricky, and
+#      Event Machine is complex on top of that.  Due to fundamental
+#      limitations, TaskBatcher can only guarantee that batches will be
+#      processed after a delay of *at least* the batch duration.
+#  * Since Ruby's threading has limitations, TaskBatcher gives best performance
+#      if most/all of the client code is event-driven and uses Event Machine.
+#
+# References:
+#  * Event Machine: http://everburning.com/wp-content/uploads/2009/02/eventmachine_introduction_10.pdf
+#
+
+require 'eventmachine'
+
+module TaskBatcher
+  class Error < ::StandardError; end
+
+  # Clients can set the default batch duration.  If client does not set the
+  # default batch duration, it has the following value.
+  METADEFAULT_DURATION = 60   # in seconds
+  private_constant :METADEFAULT_DURATION
+
+  # Reset all state; forget everything about batches in progress, tasknames,
+  # customized durations, etc.
+  def reset
+    @default_batch_duration = @batch_durations = @batches = @mutex = nil
+
+    # Other system components might be using EM.  If an EM reactor is running,
+    # do nothing.  If not, start one on a thread that we'll own.
+    if not EM.reactor_running?
+      @em_thread = Thread.new { EM.run }
+      while not EM.reactor_running?; sleep 0.01; end
+    end
+  end
+
+  # With no guidance from the client, the default batch duration is the value of
+  # METADEFAULT_DURATION.  However, in addition to being able to set the batch
+  # duration of any taskname, clients can set the global default batch duration.
+  #
+  # @param seconds [Fixnum] default batch duration in seconds
+  def set_default_batch_duration(seconds)
+    @default_batch_duration = seconds
+  end
+
+  # Return the default batch duration in seconds.  (This will be the value of
+  # METADEFAULT_DURATION, unless you have called #set_default_batch_duration.)
+  #
+  # @return [Fixnum] the default batch duration in seconds
+  def default_batch_duration
+    @default_batch_duration || METADEFAULT_DURATION
+  end
+
+  # Set the batch duration for a particular task name.
+  #
+  # @param taskname [String,Symbol] taskname for which we set the batch duration
+  # @param seconds [Fixnum] number of seconds to delay before running the batch
+  def set_batch_duration(taskname, seconds)
+    durations[taskname] = seconds
+  end
+
+  # Return the batch duration for a particular task name.
+  #
+  # @return [Fixnum] number of seconds to delay before running this batch
+  def batch_duration(taskname)
+    durations[taskname] || default_batch_duration
+  end
+
+  # Add a task to a batch, or start a new batch if none exists with this
+  # taskname.
+  #
+  # Once the batch duration expires, all tasks in the batch will be run, i.e.
+  # the block will be passed a list of task_args_hash values and the block is
+  # expected to process that entire list.
+  #
+  # Usage:
+  # TaskBatcher.task('taskname', {var1: 'foo', var2: 'bar'}) do |args_hashes|
+  #   var1s = args_hashes.map { |h| h[:var1] }
+  #   var2s = args_hashes.map { |h| h[:var2] }
+  #   print "This batcher was invoked with #{args_hashes.count} tasks.\n"
+  #   print "Hopefully the tasks can be batched efficiently.\n"
+  #   print "Then it would be faster to invoke 'func1(var1s); func2(var2s)' \n"
+  #   print "instead of 'args_hashes.each { |h| func12(h[:var1], h[:var2]) }'\n"
+  # end
+  #
+  # Only the batch's FIRST callback and block are respected!
+  #   # assuming the batch is empty here...
+  #
+  #   TaskBatcher.task('mytask', args1, callback1) { func1 }
+  #   TaskBatcher.task('mytask', args2, callback2) { func2 }
+  #   TaskBatcher.task('mytask', args3, callback3) { func3 }
+  #
+  #   # ... then this batch will invoke func1([args1, args2, args3]) and invoke
+  #   # callback1 on the result.  func2/func3 and callback2/callback3 will
+  #   # never be used!
+  #
+  def task(taskname, task_args_hash, callback=nil, &block)
+    raise Error, 'taskname required' if taskname.nil?
+    mutex.synchronize do
+      this_batch = batches[taskname]
+      if this_batch.nil?
+        batches[taskname] = {
+          block:       block,
+          callback:    callback,
+          args_hashes: [ task_args_hash ],
+        }
+        EM.add_timer(batch_duration(taskname)) do
+          EM.defer { process_batch(taskname) }
+        end
+      else
+        this_batch[:args_hashes] << task_args_hash
+      end
+    end
+  end
+
+  # Generally, the #process_batch method will be called by Event Machine when
+  # the batch duration expires.  However, it is public because the caller may
+  # want to explicitly process a batch.
+  #
+  # @param taskname [String,Symbol] the name of the batch to process
+  def process_batch(taskname)
+    this_batch = nil
+
+    # Grab the batch.  If another TaskBatcher call is added immediately after
+    # this synchronize step, then it just starts a new batch.
+    mutex.synchronize do
+      this_batch = batches[taskname]
+      batches[taskname] = nil
+    end
+    return nil if this_batch.nil?
+
+    # Grab the block, list of batch args, and callback.  Then run the batch!
+    batch_processor = this_batch[:block]
+    args_hashes = this_batch[:args_hashes]
+    callback = this_batch[:callback] || lambda {|arg_hashes| nil}
+    begin
+      results = batch_processor[args_hashes]
+    rescue Exception => e
+      raise Error, "Exception raised during TaskBatcher processing:\n" +
+        "#{e.backtrace.join("\n   ")}"
+    end
+
+    # Run the callback.  The callback's return value isn't accessible in any
+    # meaningful way.
+    callback[results]
+  end
+
+
+  private
+
+  def mutex; @mutex ||= Mutex.new; end
+  def batches; @batches ||= {}; end
+  def durations; @batch_durations ||= {}; end
+
+  extend self
+  reset
+end
+
+# The BatchManager class provides a more OO-style API to the functionality of
+# TaskBatcher.  Multiple BatchManagers can be instantiated, and there is no
+# need to repeat the callback and block parameters multiple times in your
+# code.
+#
+# This is a cleaner interface if your batched jobs get added in a reasonably
+# localized scope (where your BatchManager can live).  If batched jobs get
+# added all over the code base, the TaskBatcher interface is probably a better
+# fit, even though you'll have to repeat the callback and block every time
+# you add a job.
+#
+class BatchManager
+
+  # Create a BatchManager to wrap calls to TaskBatcher.
+  #
+  # @param name [String,Symbol] arbitrary task identifier, or nil to
+  #    auto-generate one
+  # @param callback [#call] callable which takes one parameter (of whatever
+  #    type is returned by the block), or nil to discard block's return value
+  # @param duration [Fixnum] batch duration, or nil to use the default
+  # @param block [#call] callable which takes one parameter (list of
+  #    parameter-groups, one per #add invocation) and batch-processes them
+  def initialize(name=nil, callback=nil, duration=nil, &block)
+    @name = name || "ObjectID:#{self.object_id}"
+    @callback = callback
+    @block = block
+    (self.batch_duration = duration) if duration
+  end
+
+  # Add a job to the TaskBatch, to be executed when the batch duration expires.
+  #
+  # Once the batch duration expires, all tasks in the batch will be run, i.e.
+  # the block will be passed a list of task_args_hash values and the block is
+  # expected to process that entire list.
+  #
+  # Usage:
+  # batch = TaskBatch.new('mybatch', mycallback) {|data_list| myfn(data_list)}
+  # batch.task(params1)
+  # batch.task(params2)
+  # ...
+  # # after the batch duration expires, any params in the batch will be
+  # # processed all at once
+  #
+  def task(task_params)
+    TaskBatcher.task(@name, task_params, @callback, &@block)
+  end
+
+  # Set the batch duration for this TaskBatch.
+  #
+  # @param seconds [Fixnum] number of seconds to delay before running the batch
+  def batch_duration=(seconds)
+    TaskBatcher.set_batch_duration(@name, seconds)
+  end
+
+  # Return the batch duration for this TaskBatch
+  #
+  # @return [Fixnum] number of seconds to delay before running this batch
+  def batch_duration
+    TaskBatcher.batch_duration(@name)
+  end
+
+  # Generally, the #process_batch method will be called by Event Machine when
+  # the batch duration expires.  However, this method is public because the
+  # caller may want to explicitly process a batch.
+  def process_batch
+    TaskBatcher.process_batch(@name)
+  end
+end

data/task_batcher.gemspec

@@ -0,0 +1,41 @@
+
+Gem::Specification.new do |s|
+  s.name = %q{task_batcher}
+  s.version = '0.1.0'
+  s.platform = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 1.9.3'
+
+  if s.respond_to? :required_rubygems_version=
+    s.required_rubygems_version = Gem::Requirement.new(">= 1.2")
+  end
+  s.authors = ['Jon Snitow']
+  s.email = ['opensource@verticalbrands.com']
+  s.date = '2013-04-09'
+  s.summary = 'Dynamically add tasks to batches, process batches after a time'
+  s.description = <<-EOT
+Some tasks, like database inserts, are much more efficient to process in a
+batch.  However, we generally want our tasks to be processed "soon" even if
+there's only one task.  The TaskBatcher gem groups tasks by a taskname
+parameter, and starts a timer when the first task comes in.  After the batch
+timer expires, it processes all tasks that it received in that time.  (The
+caller provides the block to process the tasks.)
+
+Uses EventMachine under the hood.  May be combined with Messenger for
+durability guarantees.
+EOT
+  s.files = Dir[
+      '{lib}/**/*.rb',
+      'LICENSE',
+      '*.md',
+      'task_batcher.gemspec',
+      ]
+  s.require_paths = ['lib']
+
+  s.rubyforge_project = 'task_batcher'
+  s.rubygems_version = '>= 1.8.6'
+  s.homepage = 'http://github.com/apartmentlist'
+
+  s.add_dependency('eventmachine')
+  s.add_development_dependency('rspec')
+  s.add_development_dependency('mocha')
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: task_batcher
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jon Snitow
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: mocha
+  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: ! 'Some tasks, like database inserts, are much more efficient to process
+  in a
+
+  batch.  However, we generally want our tasks to be processed "soon" even if
+
+  there''s only one task.  The TaskBatcher gem groups tasks by a taskname
+
+  parameter, and starts a timer when the first task comes in.  After the batch
+
+  timer expires, it processes all tasks that it received in that time.  (The
+
+  caller provides the block to process the tasks.)
+
+
+  Uses EventMachine under the hood.  May be combined with Messenger for
+
+  durability guarantees.
+
+'
+email:
+- opensource@verticalbrands.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/task_batcher.rb
+- LICENSE
+- README.md
+- task_batcher.gemspec
+homepage: http://github.com/apartmentlist
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '1.2'
+requirements: []
+rubyforge_project: task_batcher
+rubygems_version: 1.8.19
+signing_key: 
+specification_version: 3
+summary: Dynamically add tasks to batches, process batches after a time
+test_files: []
+has_rdoc: