debouncer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c5f11d271a659197a50ff8aeeec2ca4de582a46
-  data.tar.gz: 2de745511d408a7a3885ab51127ffc972059aa06
+  metadata.gz: 48c4780e6aab992ab7ecf77f240897bd9e7474f4
+  data.tar.gz: 8e311281e918f6bf12e0f8051e30be08638d1424
 SHA512:
-  metadata.gz: 7fb76db2e170d28b71e30515b91be732b3336d078333059565996a77873e5b83c08e856bf460e9ea0d61b99bdfa7adbfdc8795b3f9a8708b456b5541f7be0aa8
-  data.tar.gz: 65d859b8392e1f3962b384ed29866a4e08c4f9ab0745c335449e92f7dd80c0eb5a6cb1aebc3b34040a596aace74c838ecaf1ccab4ba4654c2d41a66e0c4c4332
+  metadata.gz: 969290d4ad850a13892552d0ee8e66ad442a2bbfbf736220f1596a4d8e3cd4d28b28b3d01566d01fe31496b8c11ead1a8cb943a5444512f698e7cd9a1f451ed5
+  data.tar.gz: 84226ab4da39584b1c96a7e3c81b535514c7b5eaf7ca1c83bc23b016544c038169d16975732f1f72e6dfd3f85f6d670feb975c38c991b5e3758155484ae2373a

data/README.md

@@ -20,7 +20,176 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### The easy way
+
+Generally all you want to do is debounce an instance or class method. The `Debounceable` module gives you everything you need to get your bouncing methods debounced.
+
+```ruby
+require 'debouncer/debounceable'
+
+class DangerZone
+  extend Debouncer::Debounceable
+  
+  def send_warning
+    system "echo We are about to get crazy! | wall"
+  end
+  
+  debounce :send_warning, 2
+end
+```
+
+Each call to `send_warning` will be delayed on a background thread for 2 seconds before firing. If, during those two seconds, it's called again, the count-down will restart, and only one warning will actually be sent.
+
+If you want to send your warning immediately, your original method has been given a suffix so you can still access it:
+
+```ruby
+DangerZone.new.send_warning_immediately
+```
+
+A couple of methods have also been added to help work with background threads:
+
+```ruby
+dz = DangerZone.new
+
+dz.join_send_warning   # Wait for all warnings to be sent
+dz.flush_send_warning  # Send warnings immediately if any are waiting
+dz.cancel_send_warning # Cancel all waiting warnings
+```
+
+You can also debounce your calls in groups. By setting the `grouped: true` option, the first argument passed to the debounced method will be used to create a separate debouncer thread.
+ 
+```ruby
+class DangerZone
+  extend Debouncer::Debounceable
+  
+  def send_warning(message)
+    system "echo #{message.shellescape} | wall"
+  end
+  
+  debounce :send_warning, 2, grouped: true
+end
+```
+
+Now, each unique message will have its own separate timeout. You can also pass group identifiers to `join_`, `flush_`, and `cancel_` methods to affect only those groups.
+
+Arguments are always passed to your original method intact, and by default, the last set of arguments in a group wins. If the example above didn't use grouping:
+
+```ruby
+d = DangerZone.new
+d.send_warning "We're going down!"
+d.send_warning "Spiders are attacking!"
+```
+
+The first warning would be replaced by the second when the method is eventually run.
+
+You can combine arguments to produce an end result however you like, using a reducer:
+
+```ruby
+class DangerZone
+  extend Debouncer::Debounceable
+  
+  def send_warning(*messages)
+    system "echo #{messages.map(&:shellescape).join ';'} | wall"
+  end
+  
+  debounce :send_warning, 2, reduce_with: :combine_messages
+  
+  def combine_messages(memo, messages)
+    memo + messages
+  end
+end
+```
+
+The `combine_messages` method will be called whenever `send_warning` is called. The first argument is the last value it returned, or an empty array if this is the first call for the thread. The second argument is an array of the arguments supplied to `send_warning`. It should return an array of arguments that will ultimately be passed to the original method.
+
+A reducer method is a good place to call `flush_*` if you hit some sort of limit or threshold. Just remember to still return the array of arguments you want to call.
+
+```ruby
+def combine_messages(memo, messages)
+  result = memo + messages
+  flush_send_warning if result.length >= 5
+  result
+end
+```
+
+Finally, you can also debounce class/module methods using the `mdebounce` method. If you want to combine calls on various instances of a class, a sound pattern is to debounce a class method and have instances call it. For example, consider broadcasting data changes to browsers, where you want to group changes to the same model together into single broadcasts:
+
+```ruby
+class Record
+  extend Debouncer::Debounceable
+  
+  def self.broadcast(record_id)
+    look_up(record_id).broadcast
+  end
+  
+  mdebounce :broadcast, 0.5, grouped: true
+   
+  def save
+    write_to_database
+    Record.broadcast id
+  end
+end
+```
+
+In a web application, it's common for several instances of a model representing the same data record to existing during the course of a request. Debouncing the `broadcast` method on the instance wouldn't be effective, since each instance would have its own debouncer. By using a debounced class method, records are grouped by their ID instead of the Ruby objects that represent them.
+
+### The clean(er) way
+
+Under the hood, the `Debounceable` module uses a `Debouncer` instance as a thread controller. If you prefer not to have any extra methods defined on your class, you can use a `Debouncer` instance to achieve the same results.
+
+```ruby
+require 'debouncer'
+
+d = Debouncer.new(2) { |message| puts message }
+d.call 'I have arrived'
+```
+
+This will print the message "I have arrived!" after 2 seconds.
+
+Grouping is simple with a debouncer:
+
+```ruby
+d.group(:warnings).call 'I am about to arrive...'
+d.group(:alerts).call 'I have arrived!'
+d.group(:alerts).flush
+```
+
+When adding an argument reducer, you can also specify an initial value:
+
+```ruby
+d = Debouncer.new(2) { |*messages| puts messages }
+d.reducer('Here are some messages:', '') { |memo, messages| memo + messages }
+d.call "Evented Ruby isn't so bad"
+d.call "And it's threaded, too!"
+```
+
+After 2 seconds, the above code will print:
+
+```text
+Here are some messages:
+
+Evented Ruby isn't so bad
+And it's threaded, too!
+```
+
+If your reducer simply adds or OR's two arrays together, you can use a symbol instead:
+
+```ruby
+d.reducer 'Here are some messages:', '', :+
+```
+
+This will have the same result as the block form. If you use `:|` instead of `:+`, it will be like `memo | messages`, so messages won't be repeated between calls.
+
+Methods like `flush`, `kill`, and `join` are available too, and to exactly what you'd expect. You can call them directly on your debouncer, or after a `group(id)` call if you want to target a specific group.
+
+```ruby
+# These lines are equivalent:
+d.join :messages
+d.group(:messages).join
+
+# This will join all threads:
+d.join
+```
 
 ## Development
 
@@ -30,7 +199,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/debouncer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/hx/debouncer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 
 ## License

data/lib/debouncer.rb

@@ -1,23 +1,37 @@
 require 'debouncer/version'
+require 'debouncer/inspection'
+require 'debouncer/group'
+require 'debouncer/debounceable'
 
 class Debouncer
+  include Inspection
+
+  DEFAULT_GROUP = Object.new
+  EMPTY         = Object.new
+
+  attr_reader :delay
+
   def initialize(delay, &block)
-    raise ArgumentError, 'Expected a number' unless delay.is_a? Numeric
-    @delay    = delay
+    self.delay = delay
+    raise ArgumentError, 'Expected a block' unless block
     @timeouts = {}
     @threads  = []
-    @lock     = Mutex.new
     @rescuers = {}
-    block.arity.zero? ? instance_exec(&block) : yield(self) if block
+    @block    = block
+    @lock     = Mutex.new
   end
 
-  def reducer(*initial, &block)
-    @reducer = [initial, block]
-    self
+  def delay=(delay)
+    raise ArgumentError, "Expected Numeric, but got #{delay.class.name}" unless delay.is_a? Numeric
+    @delay = delay
   end
 
-  def limiter(&block)
-    @limiter = block
+  def arity
+    @block.arity
+  end
+
+  def reducer(*initial, &block)
+    @reducer = [initial, block || initial.pop]
     self
   end
 
@@ -26,76 +40,111 @@ class Debouncer
     self
   end
 
-  def debounce(id = nil, *args, &block)
-    raise ArgumentError, 'Expected a block' unless block
+  def group(id)
+    Group.new self, id
+  end
+
+  def call(*args, &block)
+    call_with_id DEFAULT_GROUP, *args, &block
+  end
+  alias_method :[], :call
+
+  def call_with_id(id, *args, &block)
+    args << block if block
+    thread = nil
     exclusively do
-      thread = @timeouts[id] ||= new_thread { begin_delay id, &block }
-      @flush = [id]
-      args   = reduce_args(thread, args, id)
-      if (@limiter && !@limiter[*args]) || @flush == true
+      thread        = @timeouts[id] ||= new_thread { begin_delay id, args }
+      @flush        = [id]
+      old_args      = thread[:args]
+      thread[:args] =
+          if @reducer
+            initial, reducer = @reducer
+            old_args         ||= initial || []
+            if reducer.is_a? Symbol
+              old_args.__send__ reducer, args
+            elsif reducer.respond_to? :call
+              reducer.call old_args, args, id
+            end
+          else
+            args.empty? ? old_args : args
+          end
+      if @flush == true
         thread.kill
         @timeouts.delete id
         @threads.delete thread
         @flush = false
       else
-        thread[:args]   = args
         thread[:run_at] = Time.now + @delay
       end
     end or
-        yield *args
+        run_block thread
     self
   end
 
-  def flush(*args)
-    if args.empty?
-      if @lock.owned?
-        @flush = true
-      else
-        flush @timeouts.keys.first while @timeouts.any?
-      end
+  def flush(id = EMPTY)
+    if @lock.owned?
+      raise ArgumentError, 'You cannot flush other groups from inside a reducer' unless id == EMPTY || [id] == @flush
+      @flush = true
+    elsif id == EMPTY
+      flush @timeouts.keys.first while @timeouts.any?
     else
-      id = args.first
-      if @lock.owned? && @flush == [id]
-        @flush = true
-      else
-        dead = exclusively do
-          if (thread = @timeouts.delete(id))
-            thread.kill
-            @threads.delete thread
-          end
+      dead = exclusively do
+        if (thread = @timeouts.delete(id))
+          thread.kill
+          @threads.delete thread
         end
-        dead[:block].call *dead[:args] if dead
       end
+      run_block dead if dead
     end
     self
   end
 
-  def join(kill_first = false)
-    while (thread = exclusively { @threads.find &:alive? })
+  def join(id = EMPTY, kill_first: false)
+    if id == EMPTY
+      while (thread = exclusively { @threads.find &:alive? })
+        thread.kill if kill_first
+        thread.join
+      end
+      exclusively { [@threads, @timeouts].each &:clear } if kill_first
+    elsif (thread = exclusively { @timeouts.delete id })
+      @threads.delete thread
       thread.kill if kill_first
       thread.join
     end
-    exclusively { [@threads, @timeouts].each &:clear } if kill_first
     self
   end
 
-  def kill
-    join true
+  def kill(id = EMPTY)
+    join id, kill_first: true
   end
 
-  def inspect
-    "#<#{self.class}:0x#{'%014x' % (object_id << 1)} delay: #{@delay} timeouts: #{@timeouts.count} threads: #{@threads.count}>"
+  def inspect_params
+    {delay: @delay, timeouts: @timeouts.count, threads: @threads.count}
+  end
+
+  def to_proc
+    method(:call).to_proc
+  end
+
+  def sleeping?
+    @timeouts.length.nonzero?
+  end
+
+  def runs_at(id = DEFAULT_GROUP)
+    thread = @timeouts[id]
+    thread && thread[:run_at]
   end
 
   private
 
-  def begin_delay(id, &block)
-    thread[:block] = block
+  def begin_delay(id, args)
+    thread[:run_at] = Time.now + @delay
+    thread[:args] ||= args
     sleep @delay
     until exclusively { (thread[:run_at] <= Time.now).tap { |ready| @timeouts.delete id if ready } }
       sleep [thread[:run_at] - Time.now, 0].max
     end
-    yield *thread[:args]
+    run_block thread
   rescue => ex
     @timeouts.reject! { |_, v| v == thread }
     (rescuer = @rescuers.find { |klass, _| ex.is_a? klass }) && rescuer.last[ex]
@@ -103,14 +152,8 @@ class Debouncer
     exclusively { @threads.delete thread }
   end
 
-  def reduce_args(thread, new_args, id)
-    old_args = thread[:args]
-    if @reducer
-      initial, reducer = @reducer
-      reducer[old_args || initial || [], new_args, id]
-    else
-      new_args.empty? ? old_args : new_args
-    end
+  def run_block(thread)
+    @block.call *thread[:args]
   end
 
   def new_thread(*args, &block)

data/lib/debouncer/debounceable.rb

@@ -1,74 +1,50 @@
-require 'debouncer'
-
 class Debouncer
   module Debounceable
-    def debounce(name, delay, rescue_with: nil, group_by: :object_id, reduce_with: nil)
+    SUFFIXES = {
+        '?' => '_predicate',
+        '!' => '_dangerous',
+        '=' => '_assignment'
+    }
+    def debounce(name, delay, rescue_with: nil, grouped: false, reduce_with: nil, class_method: false)
       name =~ /^(\w+)([?!=]?)$/ or
           raise ArgumentError, 'Invalid method name'
 
       base_name = $1
       suffix    = $2
       immediate = "#{base_name}_immediately#{suffix}"
-
-      debouncer_for_method name, delay do |d|
-        d.rescuer do |ex|
-          case rescue_with
-            when Symbol
-              __send__ rescue_with, ex
-            when Proc
-              rescue_with[ex]
-            else
-              # Silent failure
-          end
-        end if rescue_with
-
-        d.reducer do |old, args, id|
-          case reduce_with
-            when Symbol
-              debouncing_instance(name, id).__send__ reduce_with, old, args
-            when Proc
-              reduce_with[old, args, id]
-            else
-              raise ArgumentError
-          end
-        end if reduce_with
-      end
+      debouncer = "@#{base_name}#{SUFFIXES[suffix]}_debouncer"
+      extras    = ''
+      extras    << ".reducer { |old, new| self.#{reduce_with} old, new }" if reduce_with
+      extras    << ".rescuer { |ex| self.#{rescue_with} ex }" if rescue_with
 
       class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        #{'class << self' if class_method}
+      
         alias_method :#{immediate}, :#{name}
 
-        def #{name}(*args)
-          id = #{group_by}
-          #{self.name}.debouncing_instance :#{name}, id, self
-          #{self.name}.debouncer_for_method(:#{name}).debounce(id, *args) { |*args| #{immediate} *args }
+        def #{name}(*args, &block)
+          #{debouncer} ||= ::Debouncer.new(#{delay}) { |*args| self.#{immediate} *args }#{extras}
+          #{debouncer}#{'.group(args.first)' if grouped}.call *args, &block
         end
 
-        def flush_#{name}
-          #{self.name}.debouncer_for_method(:#{name}).flush #{group_by}
+        def flush_#{name}(*args)
+          #{debouncer}.flush *args if #{debouncer}
         end
 
-        def self.join_#{name}
-          debouncer_for_method(:#{name}).join
+        def join_#{name}(*args)
+          #{debouncer}.join *args if #{debouncer}
         end
 
-        def self.cancel_#{name}
-          debouncer_for_method(:#{name}).kill
+        def cancel_#{name}(*args)
+          #{debouncer}.kill *args if #{debouncer}
         end
-      RUBY
-    end
 
-    def debouncer_for_method(name, delay = 0, &block)
-      @method_debouncers       ||= {}
-      @method_debouncers[name] ||= Debouncer.new(delay, &block)
+        #{'end' if class_method}
+      RUBY
     end
 
-    def debouncing_instance(method, id, instance = nil)
-      hash = (@debouncing_instances ||= {})[method] ||= {}
-      if instance
-        hash[id] = instance
-      else
-        hash[id]
-      end
+    def mdebounce(name, delay, **opts)
+      debounce name, delay, class_method: true, **opts
     end
   end
 end

data/lib/debouncer/group.rb

@@ -0,0 +1,36 @@
+class Debouncer
+  class Group
+    include Inspection
+
+    attr_reader :id, :debouncer
+
+    def initialize(debouncer, id)
+      @debouncer = debouncer
+      @id        = id
+    end
+
+    def call(*args, &block)
+      @debouncer.call_with_id @id, *args, &block
+    end
+
+    def to_proc
+      method(:call).to_proc
+    end
+
+    def flush
+      @debouncer.flush @id
+    end
+
+    def join
+      @debouncer.join @id
+    end
+
+    def kill
+      @debouncer.kill @id
+    end
+
+    def inspect_params
+      {delay: @debouncer.delay, scheduled: @debouncer.runs_at(@id) || 'idle'}
+    end
+  end
+end

data/lib/debouncer/inspection.rb

@@ -0,0 +1,13 @@
+module Inspection
+  def inspect
+    '#<%s:0x%014x%s>' % [
+        self.class.name,
+        object_id << 1,
+        inspect_params.map { |k, v| " #{k}: #{v}" }.join
+    ]
+  end
+
+  def inspect_params
+    {}
+  end
+end

data/lib/debouncer/version.rb

@@ -1,3 +1,3 @@
 class Debouncer
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: debouncer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Neil E. Pearson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-24 00:00:00.000000000 Z
+date: 2017-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -73,6 +73,8 @@ files:
 - debouncer.gemspec
 - lib/debouncer.rb
 - lib/debouncer/debounceable.rb
+- lib/debouncer/group.rb
+- lib/debouncer/inspection.rb
 - lib/debouncer/version.rb
 homepage: https://github.com/hx/debouncer
 licenses: