Class: Philiprehberger::Debounce::KeyedDebouncer

Inherits:
Object
  • Object
show all
Defined in:
lib/philiprehberger/debounce/keyed_debouncer.rb

Overview

Manages per-key debouncer instances, allowing independent debouncing for different keys using the same configuration.

Examples:

keyed = Philiprehberger::Debounce.keyed(wait: 0.5) { |key, query| search(key, query) }
keyed.call(:user_1, 'ruby')
keyed.call(:user_2, 'python')  # independent debounce timers

Instance Method Summary collapse

Constructor Details

#initialize(wait:, leading: false, trailing: true, max_wait: nil, max_keys: nil, on_execute: nil, on_cancel: nil, on_flush: nil, on_error: nil, &block) ⇒ KeyedDebouncer

Returns a new instance of KeyedDebouncer.

Parameters:

  • wait (Float) —

    delay in seconds

  • leading (Boolean) (defaults to: false) —

    fire on the leading edge

  • trailing (Boolean) (defaults to: true) —

    fire on the trailing edge

  • max_wait (Float, nil) (defaults to: nil) —

    maximum time to wait before forcing execution

  • max_keys (Integer, nil) (defaults to: nil) —

    maximum number of keys to hold; oldest key is evicted when exceeded

  • on_execute (Proc, nil) (defaults to: nil) —

    callback after block executes

  • on_cancel (Proc, nil) (defaults to: nil) —

    callback when cancel is invoked

  • on_flush (Proc, nil) (defaults to: nil) —

    callback when flush is invoked

  • block (Proc) —

    the block to execute

Raises:

  • (ArgumentError) 


22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 22

def initialize(wait:, leading: false, trailing: true, max_wait: nil, # rubocop:disable Metrics/ParameterLists
               max_keys: nil, on_execute: nil, on_cancel: nil, on_flush: nil,
               on_error: nil, &block)
  raise ArgumentError, 'block is required' unless block
  raise ArgumentError, 'max_keys must be a positive integer' if max_keys && (!max_keys.is_a?(Integer) || max_keys < 1)

  @wait = wait
  @leading = leading
  @trailing = trailing
  @max_wait = max_wait
  @max_keys = max_keys
  @on_execute = on_execute
  @on_cancel = on_cancel
  @on_flush = on_flush
  @on_error = on_error
  @block = block
  @debouncers = {}
  @mutex = Mutex.new
end

Instance Method Details

#call(key, *args) ⇒ void

This method returns an undefined value.

Invoke the debouncer for the given key.

Parameters:

  • key (Object) —

    the key to debounce independently

  • args (Array) —

    arguments forwarded to the block



47
48
49
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 47

def call(key, *args)
  debouncer_for(key).call(*args)
end

#cancel(key) ⇒ void

This method returns an undefined value.

Cancel the pending execution for a specific key.

Parameters:

  • key (Object) —

    the key to cancel



55
56
57
58
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 55

def cancel(key)
  debouncer = @mutex.synchronize { @debouncers.delete(key) }
  debouncer&.cancel
end

#cancel_all ⇒ void

This method returns an undefined value.

Cancel all pending executions.



84
85
86
87
88
89
90
91
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 84

def cancel_all
  debouncers = @mutex.synchronize do
    current = @debouncers.values
    @debouncers.clear
    current
  end
  debouncers.each(&:cancel)
end

#flush(key) ⇒ void

This method returns an undefined value.

Flush the pending execution for a specific key immediately.

Parameters:

  • key (Object) —

    the key to flush



64
65
66
67
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 64

def flush(key)
  debouncer = @mutex.synchronize { @debouncers.delete(key) }
  debouncer&.flush
end

#flush_all ⇒ void

This method returns an undefined value.

Flush all pending keyed debouncers immediately.



72
73
74
75
76
77
78
79
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 72

def flush_all
  debouncers = @mutex.synchronize do
    current = @debouncers.values
    @debouncers.clear
    current
  end
  debouncers.each(&:flush)
end

#pending_keys ⇒ Array

List keys that have pending executions.

Returns:

  • (Array) —

    keys with pending executions



96
97
98
99
100
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 96

def pending_keys
  @mutex.synchronize do
    @debouncers.select { |_key, debouncer| debouncer.pending? }.keys
  end
end

#size ⇒ Integer

Number of active keyed debouncers currently held internally.

Returns:

  • (Integer) —

    count of tracked keys (O(1))



105
106
107
108
109
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 105

def size
  @mutex.synchronize do
    @debouncers.size
  end
end