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, 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

  • 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) 


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

def initialize(wait:, leading: false, trailing: true, max_wait: nil, on_execute: nil, on_cancel: nil, on_flush: nil, on_error: nil, &block)
  raise ArgumentError, 'block is required' unless block

  @wait = wait
  @leading = leading
  @trailing = trailing
  @max_wait = max_wait
  @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



42
43
44
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 42

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



50
51
52
53
54
55
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 50

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

#cancel_all ⇒ void

This method returns an undefined value.

Cancel all pending executions.



81
82
83
84
85
86
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 81

def cancel_all
  @mutex.synchronize do
    @debouncers.each_value(&:cancel)
    @debouncers.clear
  end
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



61
62
63
64
65
66
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 61

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

#flush_all ⇒ void

This method returns an undefined value.

Flush all pending keyed debouncers immediately.



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

def flush_all
  @mutex.synchronize do
    @debouncers.each_value(&:flush)
    @debouncers.clear
  end
end

#pending_keys ⇒ Array

List keys that have pending executions.

Returns:

  • (Array) —

    keys with pending executions



91
92
93
94
95
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 91

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))



100
101
102
103
104
 
# File 'lib/philiprehberger/debounce/keyed_debouncer.rb', line 100

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