Class: CMDx::CallbackRegistry

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/cmdx/callback_registry.rb

Overview

Registry for managing callbacks that can be executed at various points during task execution.

Callbacks are organized by type and can be registered with optional conditions and options. Each callback type represents a specific execution phase or outcome.

Supports copy-on-write semantics: a duped registry shares the parent’s data until a write operation triggers materialization.

Constant Summary collapse

TYPES =

Rbs:

%i[
  before_validation
  before_execution
  on_complete
  on_interrupted
  on_executed
  on_success
  on_skipped
  on_failed
  on_good
  on_bad
].freeze

Instance Method Summary collapse

Constructor Details

#initialize(registry = nil) ⇒ CallbackRegistry

Returns a new instance of CallbackRegistry.

Parameters:

  • registry (Hash, nil) (defaults to: nil) —

    Initial registry hash, defaults to empty

Rbs:

  • (?Hash[Symbol, Set[Array]]? registry) -> void



38
39
40
 
# File 'lib/cmdx/callback_registry.rb', line 38

def initialize(registry = nil)
  @registry = registry || {}
end

Instance Method Details

#deregister(type, *callables, **options, &block) ⇒ CallbackRegistry

Removes one or more callables for a specific callback type

Examples:

Remove a specific callback

registry.deregister(:before_execution, :validate_inputs)

Parameters:

  • type (Symbol) —

    The callback type from TYPES

  • callables (Array<#call>) —

    Callable objects to remove

  • options (Hash) —

    Options that were used during registration

  • block (Proc) —

    Optional block to remove

Options Hash (**options):

  • :* (Object) —

    Any option key-value pairs

Returns:

Rbs:

  • (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self



112
113
114
115
116
117
118
119
120
121
 
# File 'lib/cmdx/callback_registry.rb', line 112

def deregister(type, *callables, **options, &block)
  materialize!

  callables << block if block_given?
  return self unless @registry[type]

  @registry[type].delete([callables, options])
  @registry.delete(type) if @registry[type].empty?
  self
end

#initialize_dup(source) ⇒ Object

Sets up copy-on-write state when duplicated via dup.

Parameters:

Rbs:

  • (CallbackRegistry source) -> void



47
48
49
50
51
 
# File 'lib/cmdx/callback_registry.rb', line 47

def initialize_dup(source)
  @parent = source
  @registry = nil
  super
end

#invoke(type, task) ⇒ Object

Invokes all registered callbacks for a given type

Examples:

Invoke all before_execution callbacks

registry.invoke(:before_execution, task)

Parameters:

  • type (Symbol) —

    The callback type to invoke

  • task (Task) —

    The task instance to pass to callbacks

Raises:

  • (TypeError) —

    When type is not a valid callback type

Rbs:

  • (Symbol type, Task task) -> void



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/cmdx/callback_registry.rb', line 134

def invoke(type, task)
  raise TypeError, "unknown callback type #{type.inspect}" unless TYPES_SET.include?(type)
  return unless registry[type]

  registry[type].each do |callables, options|
    next unless Utils::Condition.evaluate(task, options)

    Utils::Wrap.array(callables).each do |callable|
      if callable.is_a?(Symbol)
        task.send(callable)
      elsif callable.is_a?(Proc)
        task.instance_exec(&callable)
      elsif callable.respond_to?(:call)
        callable.call(task)
      else
        raise "cannot invoke #{callable}"
      end
    end
  end
end

#register(type, *callables, **options, &block) ⇒ CallbackRegistry

Registers one or more callables for a specific callback type

Examples:

Register a method callback

registry.register(:before_execution, :validate_inputs)

Register a block with conditions

registry.register(:on_success, if: { status: :completed }) do |task|
  task.log("Success callback executed")
end

Parameters:

  • type (Symbol) —

    The callback type from TYPES

  • callables (Array<#call>) —

    Callable objects to register

  • options (Hash) —

    Options to pass to the callback

  • block (Proc) —

    Optional block to register as a callable

Options Hash (**options):

  • :if (Hash) —

    Condition hash for conditional execution

  • :unless (Hash) —

    Inverse condition hash for conditional execution

Returns:

Raises:

  • (ArgumentError) —

    When type is not a valid callback type

Rbs:

  • (Symbol type, *untyped callables, **untyped options) ?{ (Task) -> void } -> self



88
89
90
91
92
93
94
95
96
 
# File 'lib/cmdx/callback_registry.rb', line 88

def register(type, *callables, **options, &block)
  materialize!

  callables << block if block_given?

  @registry[type] ||= Set.new
  @registry[type] << [callables, options]
  self
end

#registry ⇒ Hash{Symbol => Set<Array>} Also known as: to_h

Returns the internal registry of callbacks organized by type. Delegates to the parent registry when not yet materialized.

Examples:

registry.registry # => { before_execution: #<Set: [[[:validate], {}]]> }

Returns:

  • (Hash{Symbol => Set<Array>}) —

    Hash mapping callback types to their registered callables

Rbs:

  • () -> Hash[Symbol, Set[Array]]



62
63
64
 
# File 'lib/cmdx/callback_registry.rb', line 62

def registry
  @registry || @parent.registry
end