temporalio 0.1.1 → 0.3.0

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

data/lib/temporalio/worker/tuner.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Temporalio
+  class Worker
+    # Worker tuner that allows for dynamic customization of some aspects of worker configuration.
+    class Tuner
+      # Slot supplier used for reserving slots for execution. Currently the only implementations allowed are {Fixed} and
+      # {ResourceBased}.
+      class SlotSupplier
+        # A fixed-size slot supplier that will never issue more than a fixed number of slots.
+        class Fixed < SlotSupplier
+          # @return [Integer] The maximum number of slots that can be issued.
+          attr_reader :slots
+
+          # Create fixed-size slot supplier.
+          #
+          # @param slots [Integer] The maximum number of slots that can be issued.
+          def initialize(slots) # rubocop:disable Lint/MissingSuper
+            @slots = slots
+          end
+        end
+
+        # A slot supplier that will dynamically adjust the number of slots based on resource usage.
+        #
+        # @note WARNING: This API is experimental.
+        class ResourceBased < SlotSupplier
+          attr_reader :tuner_options, :slot_options
+
+          # Create a reosurce-based slot supplier.
+          #
+          # @param tuner_options [ResourceBasedTunerOptions] General tuner options.
+          # @param slot_options [ResourceBasedSlotOptions] Slot-supplier-specific tuner options.
+          def initialize(tuner_options:, slot_options:) # rubocop:disable Lint/MissingSuper
+            @tuner_options = tuner_options
+            @slot_options = slot_options
+          end
+        end
+      end
+
+      # Options for {create_resource_based} or {SlotSupplier::ResourceBased}.
+      #
+      # @!attribute target_memory_usage
+      #   @return [Float] A value between 0 and 1 that represents the target (system) memory usage. It's not recommended
+      #     to set this higher than 0.8, since how much memory a workflow may use is not predictable, and you don't want
+      #     to encounter OOM errors.
+      # @!attribute target_cpu_usage
+      #   @return [Float] A value between 0 and 1 that represents the target (system) CPU usage. This can be set to 1.0
+      #     if desired, but it's recommended to leave some headroom for other processes.
+      ResourceBasedTunerOptions = Struct.new(
+        :target_memory_usage,
+        :target_cpu_usage,
+        keyword_init: true
+      )
+
+      # Options for a specific slot type being used with {SlotSupplier::ResourceBased}.
+      #
+      # @!attribute min_slots
+      #   @return [Integer, nil] Amount of slots that will be issued regardless of any other checks. Defaults to 5 for
+      #     workflows and 1 for activities.
+      # @!attribute max_slots
+      #   @return [Integer, nil] Maximum amount of slots permitted. Defaults to 500.
+      # @!attribute ramp_throttle
+      #   @return [Float, nil] Minimum time we will wait (after passing the minimum slots number) between handing out
+      #     new slots in seconds. Defaults to 0 for workflows and 0.05 for activities.
+      #
+      #     This value matters because how many resources a task will use cannot be determined ahead of time, and thus
+      #     the system should wait to see how much resources are used before issuing more slots.
+      ResourceBasedSlotOptions = Struct.new(
+        :min_slots,
+        :max_slots,
+        :ramp_throttle,
+        keyword_init: true
+      )
+
+      # Create a fixed-size tuner with the provided number of slots.
+      #
+      # @param workflow_slots [Integer] Maximum number of workflow task slots.
+      # @param activity_slots [Integer] Maximum number of activity slots.
+      # @param local_activity_slots [Integer] Maximum number of local activity slots.
+      # @return [Tuner] Created tuner.
+      def self.create_fixed(
+        workflow_slots: 100,
+        activity_slots: 100,
+        local_activity_slots: 100
+      )
+        new(
+          workflow_slot_supplier: SlotSupplier::Fixed.new(workflow_slots),
+          activity_slot_supplier: SlotSupplier::Fixed.new(activity_slots),
+          local_activity_slot_supplier: SlotSupplier::Fixed.new(local_activity_slots)
+        )
+      end
+
+      # Create a resource-based tuner with the provided options.
+      #
+      # @param target_memory_usage [Float] A value between 0 and 1 that represents the target (system) memory usage.
+      #   It's not recommended to set this higher than 0.8, since how much memory a workflow may use is not predictable,
+      #   and you don't want to encounter OOM errors.
+      # @param target_cpu_usage [Float] A value between 0 and 1 that represents the target (system) CPU usage. This can
+      #   be set to 1.0 if desired, but it's recommended to leave some headroom for other processes.
+      # @param workflow_options [ResourceBasedSlotOptions] Resource-based options for workflow slot supplier.
+      # @param activity_options [ResourceBasedSlotOptions] Resource-based options for activity slot supplier.
+      # @param local_activity_options [ResourceBasedSlotOptions] Resource-based options for local activity slot
+      #   supplier.
+      # @return [Tuner] Created tuner.
+      def self.create_resource_based(
+        target_memory_usage:,
+        target_cpu_usage:,
+        workflow_options: ResourceBasedSlotOptions.new(min_slots: 5, max_slots: 500, ramp_throttle: 0.0),
+        activity_options: ResourceBasedSlotOptions.new(min_slots: 1, max_slots: 500, ramp_throttle: 0.05),
+        local_activity_options: ResourceBasedSlotOptions.new(min_slots: 1, max_slots: 500, ramp_throttle: 0.05)
+      )
+        tuner_options = ResourceBasedTunerOptions.new(target_memory_usage:, target_cpu_usage:)
+        new(
+          workflow_slot_supplier: SlotSupplier::ResourceBased.new(
+            tuner_options:, slot_options: workflow_options
+          ),
+          activity_slot_supplier: SlotSupplier::ResourceBased.new(
+            tuner_options:, slot_options: activity_options
+          ),
+          local_activity_slot_supplier: SlotSupplier::ResourceBased.new(
+            tuner_options:, slot_options: local_activity_options
+          )
+        )
+      end
+
+      # @return [SlotSupplier] Slot supplier for workflows.
+      attr_reader :workflow_slot_supplier
+
+      # @return [SlotSupplier] Slot supplier for activities.
+      attr_reader :activity_slot_supplier
+
+      # @return [SlotSupplier] Slot supplier for local activities.
+      attr_reader :local_activity_slot_supplier
+
+      # Create a tuner from 3 slot suppliers.
+      #
+      # @param workflow_slot_supplier [SlotSupplier] Slot supplier for workflows.
+      # @param activity_slot_supplier [SlotSupplier] Slot supplier for activities.
+      # @param local_activity_slot_supplier [SlotSupplier] Slot supplier for local activities.
+      def initialize(
+        workflow_slot_supplier:,
+        activity_slot_supplier:,
+        local_activity_slot_supplier:
+      )
+        @workflow_slot_supplier = workflow_slot_supplier
+        @activity_slot_supplier = activity_slot_supplier
+        @local_activity_slot_supplier = local_activity_slot_supplier
+      end
+    end
+  end
+end

data/lib/temporalio/worker/workflow_executor/thread_pool.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require 'etc'
+require 'temporalio/internal/bridge/api'
+require 'temporalio/internal/proto_utils'
+require 'temporalio/internal/worker/workflow_instance'
+require 'temporalio/scoped_logger'
+require 'temporalio/worker/thread_pool'
+require 'temporalio/worker/workflow_executor'
+require 'temporalio/workflow'
+require 'temporalio/workflow/definition'
+require 'timeout'
+
+module Temporalio
+  class Worker
+    class WorkflowExecutor
+      # Thread pool implementation of {WorkflowExecutor}.
+      #
+      # Users should use {default} unless they have specific needs to change the thread pool or max threads.
+      class ThreadPool < WorkflowExecutor
+        # @return [ThreadPool] Default executor that lazily constructs an instance with default values.
+        def self.default
+          @default ||= ThreadPool.new
+        end
+
+        # Create a thread pool executor. Most users may prefer {default}.
+        #
+        # @param max_threads [Integer] Maximum number of threads to use concurrently.
+        # @param thread_pool [Worker::ThreadPool] Thread pool to use.
+        def initialize(max_threads: [4, Etc.nprocessors].max, thread_pool: Temporalio::Worker::ThreadPool.default) # rubocop:disable Lint/MissingSuper
+          @max_threads = max_threads
+          @thread_pool = thread_pool
+          @workers_mutex = Mutex.new
+          @workers = []
+          @workers_by_worker_state_and_run_id = {}
+        end
+
+        # @!visibility private
+        def _validate_worker(worker, worker_state)
+          # Do nothing
+        end
+
+        # @!visibility private
+        def _activate(activation, worker_state, &)
+          # Get applicable worker
+          worker = @workers_mutex.synchronize do
+            run_key = [worker_state, activation.run_id]
+            @workers_by_worker_state_and_run_id.fetch(run_key) do
+              # If not found, get a new one either by creating if not enough or find the one with the fewest.
+              new_worker = if @workers.size < @max_threads
+                             created_worker = Worker.new(self)
+                             @workers << Worker.new(self)
+                             created_worker
+                           else
+                             @workers.min_by(&:workflow_count)
+                           end
+              @workers_by_worker_state_and_run_id[run_key] = new_worker
+              new_worker.workflow_count += 1
+              new_worker
+            end
+          end
+          raise "No worker for run ID #{activation.run_id}" unless worker
+
+          # Enqueue activation
+          worker.enqueue_activation(activation, worker_state, &)
+        end
+
+        # @!visibility private
+        def _thread_pool
+          @thread_pool
+        end
+
+        # @!visibility private
+        def _remove_workflow(worker_state, run_id)
+          @workers_mutex.synchronize do
+            worker = @workers_by_worker_state_and_run_id.delete([worker_state, run_id])
+            if worker
+              worker.workflow_count -= 1
+              # Remove worker from array if done. The array should be small enough that the delete being O(N) is not
+              # worth using a set or a map.
+              if worker.workflow_count.zero?
+                @workers.delete(worker)
+                worker.shutdown
+              end
+            end
+          end
+        end
+
+        # @!visibility private
+        class Worker
+          LOG_ACTIVATIONS = false
+
+          attr_accessor :workflow_count
+
+          def initialize(executor)
+            @executor = executor
+            @workflow_count = 0
+            @queue = Queue.new
+            executor._thread_pool.execute { run }
+          end
+
+          # @!visibility private
+          def enqueue_activation(activation, worker_state, &completion_block)
+            @queue << [:activate, activation, worker_state, completion_block]
+          end
+
+          # @!visibility private
+          def shutdown
+            @queue << [:shutdown]
+          end
+
+          private
+
+          def run
+            loop do
+              work = @queue.pop
+              if work.is_a?(Exception)
+                Warning.warn("Failed activation: #{work}")
+              elsif work.is_a?(Array)
+                case work.first
+                when :shutdown
+                  return
+                when :activate
+                  activate(work[1], work[2], &work[3])
+                end
+              end
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              Warning.warn("Unexpected failure during run: #{e.full_message}")
+            end
+          end
+
+          def activate(activation, worker_state, &)
+            worker_state.logger.debug("Received workflow activation: #{activation}") if LOG_ACTIVATIONS
+
+            # Check whether it has eviction
+            cache_remove_job = activation.jobs.find { |j| !j.remove_from_cache.nil? }&.remove_from_cache
+
+            # If it's eviction only, just evict inline and do nothing else
+            if cache_remove_job && activation.jobs.size == 1
+              evict(worker_state, activation.run_id)
+              worker_state.logger.debug('Sending empty workflow completion') if LOG_ACTIVATIONS
+              yield Internal::Bridge::Api::WorkflowCompletion::WorkflowActivationCompletion.new(
+                run_id: activation.run_id,
+                successful: Internal::Bridge::Api::WorkflowCompletion::Success.new
+              )
+              return
+            end
+
+            completion = Timeout.timeout(
+              worker_state.deadlock_timeout,
+              DeadlockError,
+              # TODO(cretz): Document that this affects all running workflows on this worker
+              # and maybe test to see how that is mitigated
+              "[TMPRL1101] Potential deadlock detected: workflow didn't yield " \
+              "within #{worker_state.deadlock_timeout} second(s)."
+            ) do
+              # Get or create workflow
+              instance = worker_state.get_or_create_running_workflow(activation.run_id) do
+                create_instance(activation, worker_state)
+              end
+
+              # Activate. We expect most errors in here to have been captured inside.
+              instance.activate(activation)
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              worker_state.logger.error("Failed activation on workflow run ID: #{activation.run_id}")
+              worker_state.logger.error(e)
+              Internal::Worker::WorkflowInstance.new_completion_with_failure(
+                run_id: activation.run_id,
+                error: e,
+                failure_converter: worker_state.data_converter.failure_converter,
+                payload_converter: worker_state.data_converter.payload_converter
+              )
+            end
+
+            # Go ahead and evict if there is an eviction job
+            evict(worker_state, activation.run_id) if cache_remove_job
+
+            # Complete the activation
+            worker_state.logger.debug("Sending workflow completion: #{completion}") if LOG_ACTIVATIONS
+            yield completion
+          end
+
+          def create_instance(initial_activation, worker_state)
+            # Extract start job
+            init_job = initial_activation.jobs.find { |j| !j.initialize_workflow.nil? }&.initialize_workflow
+            raise 'Missing initialize job in initial activation' unless init_job
+
+            # Obtain definition
+            definition = worker_state.workflow_definitions[init_job.workflow_type] ||
+                         worker_state.workflow_definitions[nil]
+            unless definition
+              raise Error::ApplicationError.new(
+                "Workflow type #{init_job.workflow_type} is not registered on this worker, available workflows: " +
+                  worker_state.workflow_definitions.keys.compact.sort.join(', '),
+                type: 'NotFoundError'
+              )
+            end
+
+            Internal::Worker::WorkflowInstance.new(
+              Internal::Worker::WorkflowInstance::Details.new(
+                namespace: worker_state.namespace,
+                task_queue: worker_state.task_queue,
+                definition:,
+                initial_activation:,
+                logger: worker_state.logger,
+                metric_meter: worker_state.metric_meter,
+                payload_converter: worker_state.data_converter.payload_converter,
+                failure_converter: worker_state.data_converter.failure_converter,
+                interceptors: worker_state.workflow_interceptors,
+                disable_eager_activity_execution: worker_state.disable_eager_activity_execution,
+                illegal_calls: worker_state.illegal_calls,
+                workflow_failure_exception_types: worker_state.workflow_failure_exception_types
+              )
+            )
+          end
+
+          def evict(worker_state, run_id)
+            worker_state.evict_running_workflow(run_id)
+            @executor._remove_workflow(worker_state, run_id)
+          end
+        end
+
+        private_constant :Worker
+
+        # Error raised when a processing a workflow task takes more than the expected amount of time.
+        class DeadlockError < Exception; end # rubocop:disable Lint/InheritException
+      end
+    end
+  end
+end

data/lib/temporalio/worker/workflow_executor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'temporalio/worker/workflow_executor/thread_pool'
+
+module Temporalio
+  class Worker
+    # Workflow executor that executes workflow tasks. Unlike {ActivityExecutor}, this class is not meant for user
+    # implementation. The only implementation that is currently accepted is {WorkflowExecutor::ThreadPool}.
+    class WorkflowExecutor
+      # @!visibility private
+      def initialize
+        raise 'Cannot create custom executors'
+      end
+
+      # @!visibility private
+      def _validate_worker(worker, worker_state)
+        raise NotImplementedError
+      end
+
+      # @!visibility private
+      def _activate(activation, worker_state, &)
+        raise NotImplementedError
+      end
+    end
+  end
+end