temporalio 0.2.0 → 0.3.0

data/lib/temporalio/worker/interceptor.rb

@@ -2,85 +2,359 @@
 
 module Temporalio
   class Worker
-    # Mixin for intercepting worker work. Clases that `include` may implement their own {intercept_activity} that
-    # returns their own instance of {ActivityInbound}.
-    #
-    # @note Input classes herein may get new required fields added and therefore the constructors of the Input classes
-    #   may change in backwards incompatible ways. Users should not try to construct Input classes themselves.
     module Interceptor
-      # Method called when intercepting an activity. This is called when starting an activity attempt.
+      # Mixin for intercepting activity worker work. Clases that `include` may implement their own {intercept_activity}
+      # that returns their own instance of {Inbound}.
       #
-      # @param next_interceptor [ActivityInbound] Next interceptor in the chain that should be called. This is usually
-      #   passed to {ActivityInbound} constructor.
-      # @return [ActivityInbound] Interceptor to be called for activity calls.
-      def intercept_activity(next_interceptor)
-        next_interceptor
-      end
-
-      # Input for {ActivityInbound.execute}.
-      ExecuteActivityInput = Struct.new(
-        :proc,
-        :args,
-        :headers,
-        keyword_init: true
-      )
-
-      # Input for {ActivityOutbound.heartbeat}.
-      HeartbeatActivityInput = Struct.new(
-        :details,
-        keyword_init: true
-      )
-
-      # Inbound interceptor for intercepting inbound activity calls. This should be extended by users needing to
-      # intercept activities.
-      class ActivityInbound
-        # @return [ActivityInbound] Next interceptor in the chain.
-        attr_reader :next_interceptor
-
-        # Initialize inbound with the next interceptor in the chain.
+      # @note Input classes herein may get new required fields added and therefore the constructors of the Input classes
+      #   may change in backwards incompatible ways. Users should not try to construct Input classes themselves.
+      module Activity
+        # Method called when intercepting an activity. This is called when starting an activity attempt.
         #
-        # @param next_interceptor [ActivityInbound] Next interceptor in the chain.
-        def initialize(next_interceptor)
-          @next_interceptor = next_interceptor
+        # @param next_interceptor [Inbound] Next interceptor in the chain that should be called. This is usually passed
+        #   to {Inbound} constructor.
+        # @return [Inbound] Interceptor to be called for activity calls.
+        def intercept_activity(next_interceptor)
+          next_interceptor
         end
 
-        # Initialize the outbound interceptor. This should be extended by users to return their own {ActivityOutbound}
-        # implementation that wraps the parameter here.
-        #
-        # @param outbound [ActivityOutbound] Next outbound interceptor in the chain.
-        # @return [ActivityOutbound] Outbound activity interceptor.
-        def init(outbound)
-          @next_interceptor.init(outbound)
+        # Input for {Inbound.execute}.
+        ExecuteInput = Data.define(
+          :proc,
+          :args,
+          :headers
+        )
+
+        # Inbound interceptor for intercepting inbound activity calls. This should be extended by users needing to
+        # intercept activities.
+        class Inbound
+          # @return [Inbound] Next interceptor in the chain.
+          attr_reader :next_interceptor
+
+          # Initialize inbound with the next interceptor in the chain.
+          #
+          # @param next_interceptor [Inbound] Next interceptor in the chain.
+          def initialize(next_interceptor)
+            @next_interceptor = next_interceptor
+          end
+
+          # Initialize the outbound interceptor. This should be extended by users to return their own {Outbound}
+          # implementation that wraps the parameter here.
+          #
+          # @param outbound [Outbound] Next outbound interceptor in the chain.
+          # @return [Outbound] Outbound activity interceptor.
+          def init(outbound)
+            @next_interceptor.init(outbound)
+          end
+
+          # Execute an activity and return result or raise exception. Next interceptor in chain (i.e. `super`) will
+          # perform the execution.
+          #
+          # @param input [ExecuteInput] Input information.
+          # @return [Object] Activity result.
+          def execute(input)
+            @next_interceptor.execute(input)
+          end
         end
 
-        # Execute an activity and return result or raise exception. Next interceptor in chain (i.e. `super`) will
-        # perform the execution.
-        #
-        # @param input [ExecuteActivityInput] Input information.
-        # @return [Object] Activity result.
-        def execute(input)
-          @next_interceptor.execute(input)
+        # Input for {Outbound.heartbeat}.
+        HeartbeatInput = Data.define(
+          :details
+        )
+
+        # Outbound interceptor for intercepting outbound activity calls. This should be extended by users needing to
+        # intercept activity calls.
+        class Outbound
+          # @return [Outbound] Next interceptor in the chain.
+          attr_reader :next_interceptor
+
+          # Initialize outbound with the next interceptor in the chain.
+          #
+          # @param next_interceptor [Outbound] Next interceptor in the chain.
+          def initialize(next_interceptor)
+            @next_interceptor = next_interceptor
+          end
+
+          # Issue a heartbeat.
+          #
+          # @param input [HeartbeatInput] Input information.
+          def heartbeat(input)
+            @next_interceptor.heartbeat(input)
+          end
         end
       end
 
-      # Outbound interceptor for intercepting outbound activity calls. This should be extended by users needing to
-      # intercept activity calls.
-      class ActivityOutbound
-        # @return [ActivityInbound] Next interceptor in the chain.
-        attr_reader :next_interceptor
-
-        # Initialize outbound with the next interceptor in the chain.
+      # Mixin for intercepting workflow worker work. Classes that `include` may implement their own {intercept_workflow}
+      # that returns their own instance of {Inbound}.
+      #
+      # @note Input classes herein may get new required fields added and therefore the constructors of the Input classes
+      #   may change in backwards incompatible ways. Users should not try to construct Input classes themselves.
+      module Workflow
+        # Method called when intercepting a workflow. This is called when creating a workflow instance.
         #
-        # @param next_interceptor [ActivityOutbound] Next interceptor in the chain.
-        def initialize(next_interceptor)
-          @next_interceptor = next_interceptor
+        # @param next_interceptor [Inbound] Next interceptor in the chain that should be called. This is usually passed
+        #   to {Inbound} constructor.
+        # @return [Inbound] Interceptor to be called for workflow calls.
+        def intercept_workflow(next_interceptor)
+          next_interceptor
         end
 
-        # Issue a heartbeat.
-        #
-        # @param input [HeartbeatActivityInput] Input information.
-        def heartbeat(input)
-          @next_interceptor.heartbeat(input)
+        # Input for {Inbound.execute}.
+        ExecuteInput = Data.define(
+          :args,
+          :headers
+        )
+
+        # Input for {Inbound.handle_signal}.
+        HandleSignalInput = Data.define(
+          :signal,
+          :args,
+          :definition,
+          :headers
+        )
+
+        # Input for {Inbound.handle_query}.
+        HandleQueryInput = Data.define(
+          :id,
+          :query,
+          :args,
+          :definition,
+          :headers
+        )
+
+        # Input for {Inbound.validate_update} and {Inbound.handle_update}.
+        HandleUpdateInput = Data.define(
+          :id,
+          :update,
+          :args,
+          :definition,
+          :headers
+        )
+
+        # Inbound interceptor for intercepting inbound workflow calls. This should be extended by users needing to
+        # intercept workflows.
+        class Inbound
+          # @return [Inbound] Next interceptor in the chain.
+          attr_reader :next_interceptor
+
+          # Initialize inbound with the next interceptor in the chain.
+          #
+          # @param next_interceptor [Inbound] Next interceptor in the chain.
+          def initialize(next_interceptor)
+            @next_interceptor = next_interceptor
+          end
+
+          # Initialize the outbound interceptor. This should be extended by users to return their own {Outbound}
+          # implementation that wraps the parameter here.
+          #
+          # @param outbound [Outbound] Next outbound interceptor in the chain.
+          # @return [Outbound] Outbound workflow interceptor.
+          def init(outbound)
+            @next_interceptor.init(outbound)
+          end
+
+          # Execute a workflow and return result or raise exception. Next interceptor in chain (i.e. `super`) will
+          # perform the execution.
+          #
+          # @param input [ExecuteInput] Input information.
+          # @return [Object] Workflow result.
+          def execute(input)
+            @next_interceptor.execute(input)
+          end
+
+          # Handle a workflow signal. Next interceptor in chain (i.e. `super`) will perform the handling.
+          #
+          # @param input [HandleSignalInput] Input information.
+          def handle_signal(input)
+            @next_interceptor.handle_signal(input)
+          end
+
+          # Handle a workflow query and return result or raise exception. Next interceptor in chain (i.e. `super`) will
+          # perform the handling.
+          #
+          # @param input [HandleQueryInput] Input information.
+          # @return [Object] Query result.
+          def handle_query(input)
+            @next_interceptor.handle_query(input)
+          end
+
+          # Validate a workflow update. Next interceptor in chain (i.e. `super`) will perform the validation.
+          #
+          # @param input [HandleUpdateInput] Input information.
+          def validate_update(input)
+            @next_interceptor.validate_update(input)
+          end
+
+          # Handle a workflow update and return result or raise exception. Next interceptor in chain (i.e. `super`) will
+          # perform the handling.
+          #
+          # @param input [HandleUpdateInput] Input information.
+          # @return [Object] Update result.
+          def handle_update(input)
+            @next_interceptor.handle_update(input)
+          end
+        end
+
+        # Input for {Outbound.cancel_external_workflow}.
+        CancelExternalWorkflowInput = Data.define(
+          :id,
+          :run_id
+        )
+
+        # Input for {Outbound.execute_activity}.
+        ExecuteActivityInput = Data.define(
+          :activity,
+          :args,
+          :task_queue,
+          :schedule_to_close_timeout,
+          :schedule_to_start_timeout,
+          :start_to_close_timeout,
+          :heartbeat_timeout,
+          :retry_policy,
+          :cancellation,
+          :cancellation_type,
+          :activity_id,
+          :disable_eager_execution,
+          :headers
+        )
+
+        # Input for {Outbound.execute_local_activity}.
+        ExecuteLocalActivityInput = Data.define(
+          :activity,
+          :args,
+          :schedule_to_close_timeout,
+          :schedule_to_start_timeout,
+          :start_to_close_timeout,
+          :retry_policy,
+          :local_retry_threshold,
+          :cancellation,
+          :cancellation_type,
+          :activity_id,
+          :headers
+        )
+
+        # Input for {Outbound.initialize_continue_as_new_error}.
+        InitializeContinueAsNewErrorInput = Data.define(
+          :error
+        )
+
+        # Input for {Outbound.signal_child_workflow}.
+        SignalChildWorkflowInput = Data.define(
+          :id,
+          :signal,
+          :args,
+          :cancellation,
+          :headers
+        )
+
+        # Input for {Outbound.signal_external_workflow}.
+        SignalExternalWorkflowInput = Data.define(
+          :id,
+          :run_id,
+          :signal,
+          :args,
+          :cancellation,
+          :headers
+        )
+
+        # Input for {Outbound.sleep}.
+        SleepInput = Data.define(
+          :duration,
+          :summary,
+          :cancellation
+        )
+
+        # Input for {Outbound.start_child_workflow}.
+        StartChildWorkflowInput = Data.define(
+          :workflow,
+          :args,
+          :id,
+          :task_queue,
+          :cancellation,
+          :cancellation_type,
+          :parent_close_policy,
+          :execution_timeout,
+          :run_timeout,
+          :task_timeout,
+          :id_reuse_policy,
+          :retry_policy,
+          :cron_schedule,
+          :memo,
+          :search_attributes,
+          :headers
+        )
+
+        # Outbound interceptor for intercepting outbound workflow calls. This should be extended by users needing to
+        # intercept workflow calls.
+        class Outbound
+          # @return [Outbound] Next interceptor in the chain.
+          attr_reader :next_interceptor
+
+          # Initialize outbound with the next interceptor in the chain.
+          #
+          # @param next_interceptor [Outbound] Next interceptor in the chain.
+          def initialize(next_interceptor)
+            @next_interceptor = next_interceptor
+          end
+
+          # Cancel external workflow.
+          #
+          # @param input [CancelExternalWorkflowInput] Input.
+          def cancel_external_workflow(input)
+            @next_interceptor.cancel_external_workflow(input)
+          end
+
+          # Execute activity.
+          #
+          # @param input [ExecuteActivityInput] Input.
+          # @return [Object] Activity result.
+          def execute_activity(input)
+            @next_interceptor.execute_activity(input)
+          end
+
+          # Execute local activity.
+          #
+          # @param input [ExecuteLocalActivityInput] Input.
+          # @return [Object] Activity result.
+          def execute_local_activity(input)
+            @next_interceptor.execute_local_activity(input)
+          end
+
+          # Initialize continue as new error.
+          #
+          # @param input [InitializeContinueAsNewErrorInput] Input.
+          def initialize_continue_as_new_error(input)
+            @next_interceptor.initialize_continue_as_new_error(input)
+          end
+
+          # Signal child workflow.
+          #
+          # @param input [SignalChildWorkflowInput] Input.
+          def signal_child_workflow(input)
+            @next_interceptor.signal_child_workflow(input)
+          end
+
+          # Signal external workflow.
+          #
+          # @param input [SignalExternalWorkflowInput] Input.
+          def signal_external_workflow(input)
+            @next_interceptor.signal_external_workflow(input)
+          end
+
+          # Sleep.
+          #
+          # @param input [SleepInput] Input.
+          def sleep(input)
+            @next_interceptor.sleep(input)
+          end
+
+          # Start child workflow.
+          #
+          # @param input [StartChildWorkflowInput] Input.
+          # @return [Workflow::ChildWorkflowHandle] Child workflow handle.
+          def start_child_workflow(input)
+            @next_interceptor.start_child_workflow(input)
+          end
         end
       end
     end

data/lib/temporalio/worker/thread_pool.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+# Much of this logic taken from
+# https://github.com/ruby-concurrency/concurrent-ruby/blob/044020f44b36930b863b930f3ee8fa1e9f750469/lib/concurrent-ruby/concurrent/executor/ruby_thread_pool_executor.rb,
+# see MIT license at
+# https://github.com/ruby-concurrency/concurrent-ruby/blob/044020f44b36930b863b930f3ee8fa1e9f750469/LICENSE.txt
+
+module Temporalio
+  class Worker
+    # Implementation of a thread pool. This implementation is a stripped down form of Concurrent Ruby's
+    # `CachedThreadPool`.
+    class ThreadPool
+      # @return [ThreadPool] Default/shared thread pool instance with unlimited max threads.
+      def self.default
+        @default ||= new
+      end
+
+      # @!visibility private
+      def self._monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Create a new thread pool that creates threads as needed.
+      #
+      # @param max_threads [Integer, nil] Maximum number of thread workers to create, or nil for unlimited max.
+      # @param idle_timeout [Float] Number of seconds before a thread worker with no work should be stopped. Note,
+      #   the check of whether a thread worker is idle is only done on each new {execute} call.
+      def initialize(max_threads: nil, idle_timeout: 20)
+        @max_threads = max_threads
+        @idle_timeout = idle_timeout
+
+        @mutex = Mutex.new
+        @pool = []
+        @ready = []
+        @queue = []
+        @scheduled_task_count = 0
+        @completed_task_count = 0
+        @largest_length       = 0
+        @workers_counter = 0
+        @prune_interval = @idle_timeout / 2
+        @next_prune_time = ThreadPool._monotonic_time + @prune_interval
+      end
+
+      # Execute the given block in a thread. The block should be built to never raise and need no arguments.
+      #
+      # @yield Block to execute.
+      def execute(&block)
+        @mutex.synchronize do
+          locked_assign_worker(&block) || locked_enqueue(&block)
+          @scheduled_task_count += 1
+          locked_prune_pool if @next_prune_time < ThreadPool._monotonic_time
+        end
+      end
+
+      # @return [Integer] The largest number of threads that have been created in the pool since construction.
+      def largest_length
+        @mutex.synchronize { @largest_length }
+      end
+
+      # @return [Integer] The number of tasks that have been scheduled for execution on the pool since construction.
+      def scheduled_task_count
+        @mutex.synchronize { @scheduled_task_count }
+      end
+
+      # @return [Integer] The number of tasks that have been completed by the pool since construction.
+      def completed_task_count
+        @mutex.synchronize { @completed_task_count }
+      end
+
+      # @return [Integer] The number of threads that are actively executing tasks.
+      def active_count
+        @mutex.synchronize { @pool.length - @ready.length }
+      end
+
+      # @return [Integer] The number of threads currently in the pool.
+      def length
+        @mutex.synchronize { @pool.length }
+      end
+
+      # @return [Integer] The number of tasks in the queue awaiting execution.
+      def queue_length
+        @mutex.synchronize { @queue.length }
+      end
+
+      # Gracefully shutdown each thread when it is done with its current task. This should not be called until all
+      # workers using this executor are complete. This does not need to be called at all on program exit (e.g. for the
+      # global default).
+      def shutdown
+        @mutex.synchronize do
+          # Stop all workers
+          @pool.each(&:stop)
+        end
+      end
+
+      # Kill each thread. This should not be called until all workers using this executor are complete. This does not
+      # need to be called at all on program exit (e.g. for the global default).
+      def kill
+        @mutex.synchronize do
+          # Kill all workers
+          @pool.each(&:kill)
+          @pool.clear
+          @ready.clear
+        end
+      end
+
+      # @!visibility private
+      def _remove_busy_worker(worker)
+        @mutex.synchronize { locked_remove_busy_worker(worker) }
+      end
+
+      # @!visibility private
+      def _ready_worker(worker, last_message)
+        @mutex.synchronize { locked_ready_worker(worker, last_message) }
+      end
+
+      # @!visibility private
+      def _worker_died(worker)
+        @mutex.synchronize { locked_worker_died(worker) }
+      end
+
+      # @!visibility private
+      def _worker_task_completed
+        @mutex.synchronize { @completed_task_count += 1 }
+      end
+
+      private
+
+      def locked_assign_worker(&block)
+        # keep growing if the pool is not at the minimum yet
+        worker, = @ready.pop || locked_add_busy_worker
+        if worker
+          worker << block
+          true
+        else
+          false
+        end
+      end
+
+      def locked_enqueue(&block)
+        @queue << block
+      end
+
+      def locked_add_busy_worker
+        return if @max_threads && @pool.size >= @max_threads
+
+        @workers_counter += 1
+        @pool << (worker = Worker.new(self, @workers_counter))
+        @largest_length = @pool.length if @pool.length > @largest_length
+        worker
+      end
+
+      def locked_prune_pool
+        now = ThreadPool._monotonic_time
+        stopped_workers = 0
+        while !@ready.empty? && (@pool.size - stopped_workers).positive?
+          worker, last_message = @ready.first
+          break unless now - last_message > @idle_timeout
+
+          stopped_workers += 1
+          @ready.shift
+          worker << :stop
+
+        end
+
+        @next_prune_time = ThreadPool._monotonic_time + @prune_interval
+      end
+
+      def locked_remove_busy_worker(worker)
+        @pool.delete(worker)
+      end
+
+      def locked_ready_worker(worker, last_message)
+        block = @queue.shift
+        if block
+          worker << block
+        else
+          @ready.push([worker, last_message])
+        end
+      end
+
+      def locked_worker_died(worker)
+        locked_remove_busy_worker(worker)
+        replacement_worker = locked_add_busy_worker
+        locked_ready_worker(replacement_worker, ThreadPool._monotonic_time) if replacement_worker
+      end
+
+      # @!visibility private
+      class Worker
+        def initialize(pool, id)
+          @queue = Queue.new
+          @thread = Thread.new(@queue, pool) do |my_queue, my_pool|
+            catch(:stop) do
+              loop do
+                case block = my_queue.pop
+                when :stop
+                  pool._remove_busy_worker(self)
+                  throw :stop
+                else
+                  begin
+                    block.call
+                    my_pool._worker_task_completed
+                    my_pool._ready_worker(self, ThreadPool._monotonic_time)
+                  rescue StandardError => e
+                    # Ignore
+                    warn("Unexpected execute block error: #{e.full_message}")
+                  rescue Exception => e # rubocop:disable Lint/RescueException
+                    warn("Unexpected execute block exception: #{e.full_message}")
+                    my_pool._worker_died(self)
+                    throw :stop
+                  end
+                end
+              end
+            end
+          end
+          @thread.name = "temporal-thread-#{id}"
+        end
+
+        # @!visibility private
+        def <<(block)
+          @queue << block
+        end
+
+        # @!visibility private
+        def stop
+          @queue << :stop
+        end
+
+        # @!visibility private
+        def kill
+          @thread.kill
+        end
+      end
+
+      private_constant :Worker
+    end
+  end
+end