work_batcher 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7d90286860b0a7594c9cdc2207024afa543e060c
+  data.tar.gz: ef489fbfa4c8c4eb55ca5d0d6e48b9f369823e6c
+SHA512:
+  metadata.gz: def16c19e043e1cc52b66832512e93a289d69ba8bd8364f59f5276151d7450afc427b58915e4f873e5443d8da855ff889581fe2e9847d2317be9727dacade246
+  data.tar.gz: 103d09310207b8dd001f34bcdb444021ad8952130835a9546ae67a7f72f75711e5f118c86855748cc27a1ed0c5f4fc648d6a11bbe75136efd7ae55bdaa2c2c97

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Phusion B.V.
+
+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,138 @@
+# Small library for batching work
+
+Many types of work can be performed more efficiently when performed in batches rather than individually. For example, performing a single coarse-grained HTTP API call with multiple inputs is often faster than performing multiple smaller HTTP API calls because it reduces the number of network roundtrips. Enter WorkBatcher: a generic library for performing any kind of work in batches.
+
+WorkBatcher works as follows. First you tell WorkBatcher whether you want to batch by time or by size (or both). Then you pass work objects to WorkBatcher, which WorkBatcher adds to an internal store (the batch). When either the batch size limit or the time limit has been reached, WorkBatcher calls a user-specified callback (passing it the batch) to perform the actual processing of the batch.
+
+Below is a small example that batches by time. Given a WorkBatcher object, call the `#add` method to add work objects. When the given time limit is reached (2 seconds in this example), it will call the `process_batch` lambda with all work objects that have been batched during that 2 seconds interval.
+
+~~~ruby
+process_batch = lambda do |batch|
+  # Warning! Code is executed in a different thread!
+  puts "Processing batch: #{batch.inspect}"
+end
+
+wb = WorkBatcher.new(processor: process_batch, time_limit: 2)
+wb.add('work object 1')
+wb.add('work object 2')
+sleep 3
+# => Processing batch: ["work object 1", "work object 2"]
+
+wb.add('work object 1')
+wb.add('work object 4')
+sleep 3
+# => Processing batch: ["work object 1", "work object 4"]
+
+# Don't forget to cleanup.
+wb.shutdown
+~~~
+
+**Table of contents**
+
+ * [Installation](#installation)
+ * [Features](#features)
+ * [Not a background job system](#not-a-background-job-system)
+ * [API](#api)
+   - [Constructor options](#constructor-options)
+   - [Adding work objects](#adding-work-objects)
+   - [Deduplicating work objects](#deduplicating-work-objects)
+   - [Concurrency notes](#concurrency-notes)
+
+--------
+
+## Installation
+
+    gem install work_batcher
+
+## Features
+
+ * Lightweight library, not a background job system with daemon.
+ * You can configure it to process the batch either after a time limit, or after a certain number of items have been queued, or both.
+ * Able to avoid double work by [deduplicating work objects](#deduplicating work objects].
+ * Introspectable: you can query its processing status at any time.
+ * Thread-safe.
+ * Uses threads under the hood.
+ * The only dependency is concurrent-ruby. Unlike e.g. [task_batcher](http://www.rubydoc.info/gems/task_batcher), this library does not depend on EventMachine.
+
+## Not a background job system
+
+This library is *not* a background job system such as Sidekiq, BackgrounDRb or Resque. Those libraries are daemons that you run in the background for processing work. This library is for *batching* work. But you could combine this library with a background job system in order to add batching capabilities.
+
+## API
+
+### Constructor options
+
+The constructor supports the following options.
+
+Required:
+
+ * `:processor` (callable) -- will be called when WorkBatcher determines that it is time to process a batch. The callable will receive exactly one argument: an array of batched objects. The callable is called in a background thread; see [Concurrency notes](#concurrency-notes).
+
+Optional:
+
+ * `:size_limit` (Integer) -- if the internal queue reaches this given size, then the current batch will be processed. Defaults to nil, meaning that WorkBatcher does not check the size.
+ * `:time_limit` (Float) -- if this much time has passed since the first time a work object has been placed in an empty queue, then the current batch will be processed. The unit is seconds, and may be a floating point number. Defaults to 5.
+ * `:deduplicate` (Boolean) -- whether to [deduplicate work objects](#deduplicating-work-objects) or not. Defaults to false.
+ * `:deduplicator` (callable) -- see [Deduplicating work objects](#deduplicating-work-objects) for more information.
+ * `:executor` -- a [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) executor or thread pool object to perform background work in. Defaults to `Concurrent.global_io_executor`.
+
+Note that `:size_limit` and `:time_limit` can be combined. If either condition is reached then the batch will be processed.
+
+### Adding work objects
+
+Add work objects with either the `#add` method (for adding a single object) or the `#add_multiple` method (for adding multiple objects). If you have multiple work objects, then it is more efficient to call `#add_multiple` once instead of calling `#add` many times.
+
+    work_batcher.add(work_object)
+    work_batcher.add_multiple([work_object1, work_object2])
+
+A work object can be anything. Work_batcher does not do anything with the objects themselves; they are simply passed to the processor callable (although they may be [deduplicated](#deduplicating-work-objects) first).
+
+### Deduplicating work objects
+
+In some use cases it is desirable to deduplicate added work objects. Suppose that you are writing a social network in which each user can upload an avatar. You want to pass recently uploaded avatars to an image compressor service, and in order to reduce network roundtrips you want to do this in batches. What happens if you have _just_ added an avatar to a batch, but before the batch is sent out to the compressor service, the user uploads a new avatar? You want to replace that user's avatar in the batch with his/her latest one.
+
+Enter deduplication. It starts by setting the `:deduplicate` option to true. When you add a work object, WorkBatcher will look in the batch for any objects that look like duplicates and remove them. By default, two work objects are considered equal if `#eql?` is true and (at the same time) their `#hash` are equal. This is because deduplication is internally implemented using a Hash.
+
+The criteria for what is considered "duplicate" is configurable through the `:deduplicator` option. This option is to be set to a callable, which accepts a work object and which outputs a key object. Two work objects are considered duplicates if their key objects are the same (according to `#eql?` and `#hash`).
+
+Here is an example on how to deduplicate avatars:
+
+~~~ruby
+deduplicator = lambda do |avatar|
+  # We consider two avatars to be duplicates if they are from the
+  # same user, so we return the user ID here.
+  avatar.user_id
+end
+
+processor = lambda do |avatars|
+  send_avatars_to_compressor_service(avatars)
+end
+
+wb = WorkBatcher.new(
+  deduplicate: true,
+  deduplicator: deduplicator,
+  processor: processor)
+
+while !$quitting
+  avatar = receive_next_avatar
+  wb.add(avatar1)
+end
+~~~
+
+Deduplication is disabled by default.
+
+### Concurrency notes
+
+WorkBatcher uses threads internally. The processor callback is called in a background thread, so care should be taken to ensure that your processor callback is thread-safe.
+
+When using Rails, if your processor callback does anything with ActiveRecord then you must ensure that the processor callback releases the ActiveRecord thread-local connection, otherwise you will exhaust the ActiveRecord connection pool. Here is an example:
+
+~~~ruby
+processor = lambda do |batch|
+  begin
+    ...
+  ensure
+    ActiveRecord::Base.connection_pool.release_connection
+  end
+end
+~~~

data/Rakefile

@@ -0,0 +1,4 @@
+desc 'Run unit tests'
+task :test do
+  sh 'bundle exec rspec -f d -c spec/*_spec.rb'
+end

data/lib/work_batcher.rb

@@ -0,0 +1,168 @@
+# Copyright (c) 2016 Phusion B.V.
+#
+# 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.
+
+
+require 'thread'
+require 'concurrent'
+require 'concurrent/scheduled_task'
+
+class WorkBatcher
+  def initialize(options = {})
+    @size_limit   = get_option(options, :size_limit)
+    @time_limit   = get_option(options, :time_limit, 5)
+    @deduplicate  = get_option(options, :deduplicate)
+    @deduplicator = get_option(options, :deduplicator, method(:default_deduplicator))
+    @executor     = get_option(options, :executor, Concurrent.global_io_executor)
+    @processor    = get_option!(options, :processor)
+
+    @mutex = Mutex.new
+    if @deduplicate
+      @queue = {}
+    else
+      @queue = []
+    end
+    @processed = 0
+  end
+
+  def shutdown
+    task = @mutex.synchronize do
+      @scheduled_processing_task
+    end
+    if task
+      task.reschedule(0)
+      task.wait!
+    end
+  end
+
+  def add(work_object)
+    add_multiple([work_object])
+  end
+
+  def add_multiple(work_objects)
+    return if work_objects.empty?
+
+    @mutex.synchronize do
+      if @deduplicate
+        work_objects.each do |work_object|
+          key = @deduplicator.call(work_object)
+          @queue[key] = work_object
+        end
+      else
+        @queue.concat(work_objects)
+      end
+      schedule_processing
+    end
+  end
+
+  def status
+    result = {}
+    @mutex.synchronize do
+      if @scheduled_processing_task
+        result[:scheduled_processing_time] = @scheduled_processing_time
+      end
+      result[:queue_count] = @queue.size
+      result[:processed_count] = @processed
+    end
+    result
+  end
+
+  def inspect_queue
+    @mutex.synchronize do
+      if @deduplicate
+        @queue.values.dup
+      else
+        @queue.dup
+      end
+    end
+  end
+
+private
+  def schedule_processing
+    if @scheduled_processing_task
+      if @size_limit && @queue.size >= @size_limit
+        @scheduled_processing_time = Time.now
+        @scheduled_processing_task.reschedule(0)
+      end
+    else
+      if @size_limit && @queue.size >= @size_limit
+        @scheduled_processing_task = create_scheduled_processing_task(0)
+      else
+        @scheduled_processing_task = create_scheduled_processing_task(@time_limit)
+      end
+    end
+  end
+
+  def create_scheduled_processing_task(delay)
+    @scheduled_processing_time = Time.now + delay
+    args = [delay, executor: @executor]
+    Concurrent::ScheduledTask.execute(*args) do
+      handle_uncaught_exception do
+        @mutex.synchronize do
+          begin
+            process_queue
+          ensure
+            @scheduled_processing_task = nil
+            @scheduled_processing_time = nil
+          end
+        end
+      end
+    end
+  end
+
+  def process_queue
+    if @deduplicate
+      @processor.call(@queue.values)
+    else
+      @processor.call(@queue.dup)
+    end
+    @processed += @queue.size
+    @queue.clear
+  end
+
+  def default_deduplicator(work_object)
+    work_object
+  end
+
+  def handle_uncaught_exception
+    begin
+      yield
+    rescue Exception => e
+      STDERR.puts(
+        "Uncaught exception in WorkBatcher: #{e} (#{e.class})\n" \
+        "#{e.backtrace.join("\n")}")
+    end
+  end
+
+  def get_option(options, key, default_value = nil)
+    if options.key?(key)
+      options[key]
+    else
+      default_value
+    end
+  end
+
+  def get_option!(options, key)
+    if options.key?(key)
+      options[key]
+    else
+      raise ArgumentError, "Option required: #{key}"
+    end
+  end
+end

data/work_batcher.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+  s.name         = 'work_batcher'
+  s.version      = '1.0.0'
+  s.summary      = 'Library for batching work'
+  s.description  = 'Library for batching work.'
+  s.email        = 'info@phusion.nl'
+  s.homepage     = 'https://github.com/phusion/work_batcher'
+  s.authors      = ['Hongli Lai']
+  s.license      = 'MIT'
+  s.files        = [
+    'work_batcher.gemspec',
+    'README.md',
+    'LICENSE.md',
+    'Rakefile',
+    'lib/work_batcher.rb'
+  ]
+  s.add_dependency 'concurrent-ruby'
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: work_batcher
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Hongli Lai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Library for batching work.
+email: info@phusion.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/work_batcher.rb
+- work_batcher.gemspec
+homepage: https://github.com/phusion/work_batcher
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Library for batching work
+test_files: []
+has_rdoc: