temporalio 0.1.1 → 0.2.0

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

@@ -0,0 +1,254 @@
+# 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
+    class ActivityExecutor
+      # Activity executor for scheduling activities in their own thread. This implementation is a stripped down form of
+      # Concurrent Ruby's `CachedThreadPool`.
+      class ThreadPool < ActivityExecutor
+        # @return [ThreadPool] Default/shared thread pool executor 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 executor 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 activity.
+        def initialize(max_threads: nil, idle_timeout: 20) # rubocop:disable Lint/MissingSuper
+          @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
+
+        # @see ActivityExecutor.execute_activity
+        def execute_activity(_defn, &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
+
+        # @see ActivityExecutor.activity_context
+        def activity_context
+          Thread.current[:temporal_activity_context]
+        end
+
+        # @see ActivityExecutor.set_activity_context
+        def set_activity_context(defn, context)
+          Thread.current[:temporal_activity_context] = context
+          # If they have opted in to raising on cancel, wire that up
+          return unless defn.cancel_raise
+
+          thread = Thread.current
+          context&.cancellation&.add_cancel_callback do
+            thread.raise(Error::CanceledError.new('Activity canceled')) if thread[:temporal_activity_context] == context
+          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 activity block error: #{e}")
+                    rescue Exception => e # rubocop:disable Lint/RescueException
+                      warn("Unexpected activity block exception: #{e}")
+                      my_pool._worker_died(self)
+                      throw :stop
+                    end
+                  end
+                end
+              end
+            end
+            @thread.name = "activity-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
+end

data/lib/temporalio/worker/activity_executor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'temporalio/worker/activity_executor/fiber'
+require 'temporalio/worker/activity_executor/thread_pool'
+
+module Temporalio
+  class Worker
+    # Base class to be extended by activity executor implementations. Most users will not use this, but rather keep with
+    # the two defaults of thread pool and fiber executors.
+    class ActivityExecutor
+      # @return [Hash<Symbol, ActivityExecutor>] Default set of executors (immutable).
+      def self.defaults
+        @defaults ||= {
+          default: ThreadPool.default,
+          thread_pool: ThreadPool.default,
+          fiber: Fiber.default
+        }.freeze
+      end
+
+      # Initialize an activity. This is called on worker initialize for every activity that will use this executor. This
+      # allows executor implementations to do eager validation based on the definition. This does not have to be
+      # implemented and the default is a no-op.
+      #
+      # @param defn [Activity::Definition] Activity definition.
+      def initialize_activity(defn)
+        # Default no-op
+      end
+
+      # Execute the given block in the executor. The block is built to never raise and need no arguments. Implementers
+      # must implement this.
+      #
+      # @param defn [Activity::Definition] Activity definition.
+      # @yield Block to execute.
+      def execute_activity(defn, &)
+        raise NotImplementedError
+      end
+
+      # @return [Activity::Context, nil] Get the current activity context. This is called by users from inside the
+      #   activity. Implementers must implement this.
+      def activity_context
+        raise NotImplementedError
+      end
+
+      # Set the current activity context (or unset if nil). This is called by the system from within the block given to
+      # {execute_activity} with a context before user code is executed and with nil after user code is complete.
+      # Implementers must implement this.
+      #
+      # @param defn [Activity::Definition] Activity definition.
+      # @param context [Activity::Context, nil] The value to set.
+      def set_activity_context(defn, context)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/temporalio/worker/interceptor.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # @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.
+        #
+        # @param next_interceptor [ActivityInbound] 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 {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)
+        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)
+        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.
+        #
+        # @param next_interceptor [ActivityOutbound] Next interceptor in the chain.
+        def initialize(next_interceptor)
+          @next_interceptor = next_interceptor
+        end
+
+        # Issue a heartbeat.
+        #
+        # @param input [HeartbeatActivityInput] Input information.
+        def heartbeat(input)
+          @next_interceptor.heartbeat(input)
+        end
+      end
+    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