Cable: Periodic timers refresh

* Rewrite docs
* Support blocks in addition to method names and Proc args
* Check for valid arguments
* Convert `periodically :method_name` to Proc callbacks
* Drop periodic runner methods from the worker pool
* Ensure we clear active periodic timers after shutdown

1 files changed, 45 insertions, 7 deletions

diff --git a/actioncable/lib/action_cable/channel/periodic_timers.rb b/actioncable/lib/action_cable/channel/periodic_timers.rb
index 28352d7509..dab604440f 100644
--- a/actioncable/lib/action_cable/channel/periodic_timers.rb
+++ b/actioncable/lib/action_cable/channel/periodic_timers.rb
@@ -12,11 +12,42 @@ module ActionCable
       end
 
       module ClassMethods
-        # Allows you to call a private method periodically. Specify the period, in seconds, using the <tt>every</tt> keyword argument.
-        # This periodic timer can be useful for sending a steady flow of updates to a client based off an object that was configured on subscription.
-        # It's an alternative to using streams if the channel is able to do the work internally.
-        def periodically(callback, every:)
-          self.periodic_timers += [ [ callback, every: every ] ]
+        # Periodically performs a task on the channel, like updating an online
+        # user counter, polling a backend for new status messages, sending
+        # regular "heartbeat" messages, or doing some internal work and giving
+        # progress updates.
+        #
+        # Pass a method name or lambda argument or provide a block to call.
+        # Specify the calling period in seconds using the <tt>every:</tt>
+        # keyword argument.
+        #
+        #     periodically :transmit_progress, every: 5.seconds
+        #
+        #     periodically every: 3.minutes do
+        #       transmit action: :update_count, count: current_count
+        #     end
+        #
+        def periodically(callback_or_method_name = nil, every:, &block)
+          callback =
+            if block_given?
+              raise ArgumentError, 'Pass a block or provide a callback arg, not both' if callback_or_method_name
+              block
+            else
+              case callback_or_method_name
+              when Proc
+                callback_or_method_name
+              when Symbol
+                -> { __send__ callback_or_method_name }
+              else
+                raise ArgumentError, "Expected a Symbol method name or a Proc, got #{callback_or_method_name.inspect}"
+              end
+            end
+
+          unless every.kind_of?(Numeric) && every > 0
+            raise ArgumentError, "Expected every: to be a positive number of seconds, got #{every.inspect}"
+          end
+
+          self.periodic_timers += [[ callback, every: every ]]
         end
       end
 
@@ -27,14 +58,21 @@ module ActionCable
 
         def start_periodic_timers
           self.class.periodic_timers.each do |callback, options|
-            active_periodic_timers << connection.server.event_loop.timer(options[:every]) do
-              connection.worker_pool.async_run_periodic_timer(self, callback)
+            active_periodic_timers << start_periodic_timer(callback, every: options.fetch(:every))
+          end
+        end
+
+        def start_periodic_timer(callback, every:)
+          connection.server.event_loop.timer every do
+            connection.worker_pool.async_invoke connection do
+              instance_exec(&callback)
             end
           end
         end
 
         def stop_periodic_timers
           active_periodic_timers.each { |timer| timer.shutdown }
+          active_periodic_timers.clear
         end
     end
   end