[Docs] Update docs for the Activity Worker (temporalio#100)

* Add YARD docs to all Activity Worker related classes/methods

* Update README with Activity Worker info

* Add signal handling example to README

Author: antstorm

.yardopts

@@ -0,0 +1,3 @@
+--exclude lib/gen
+--exclude lib/thermite_patch.rb
+lib/**/*.rb

README.md

@@ -23,12 +23,17 @@ At this point the SDK only supports the **Temporal Client** capabilities:
 - gRPC access to Temporal Server
 - Temporal Cloud is not yet supported due to the lack of TLS support, but it's coming soon
 
+As well as **Activity Worker** capabilities:
+
+- Definiting activities
+- Activity heartbeats/cancellations
+- Running activity workers
 
 ## Quick Start
 
 ### Installation
 
-Add the [`temporalio` gem](https://rubygems.org/gems/temporalio) to your Gemfile:
+Add the [temporalio gem](https://rubygems.org/gems/temporalio) to your Gemfile:
 
 ```ruby
 gem 'temporalio'
@@ -82,12 +87,164 @@ The default data converter supports converting multiple types including:
 
 - `nil`
 - bytes (`String` with `Encoding::ASCII_8BIT`)
-- Anything that [`JSON.generate`](https://ruby-doc.org/stdlib-3.0.0/libdoc/json/rdoc/JSON.html#method-i-generate)
+- Anything that [JSON.generate](https://ruby-doc.org/stdlib-3.0.0/libdoc/json/rdoc/JSON.html#method-i-generate)
   supports
 
 This notably doesn't include any `Date`, `Time`, or `DateTime` objects as they may not work across
 different SDKs. A custom payload converter can be implemented to support these.
 
+### Workers
+
+Workers host workflows (coming soon) and/or activities. Here's how to run a worker:
+
+```ruby
+require 'temporal'
+
+# Establish a gRPC connection to the server
+connection = Temporal::Connection.new('localhost:7233')
+
+# Initialize a new worker with your activities
+worker = Temporal::Worker.new(connection, 'my-namespace', 'my-task-queue', activities: [MyActivity])
+
+# Occupy the thread by running the worker
+worker.run
+```
+
+Some things to note about the above code:
+
+- This creates/uses the same connection that is used for initializing a client
+- Workers can have many more options not shown here (e.g. data converters and interceptors)
+
+In order to have more control over running of a worker you can provide a block of code by the end of
+which the worker will shut itself down:
+
+```ruby
+# Initialize worker_1, worker_2 and worker_3 as in the example above
+
+# Run the worker for 5 seconds, then shut down
+worker_1.run { sleep 5 }
+
+# Or shut the worker down when a workflow completes (very useful for running specs):
+client = Temporal::Client.new(connection, 'my-namespace')
+handle = client.start_workflow('MyWorkflow', 'some input', id: 'my-id', task_queue: 'my-task-queue')
+worker_2.run { handle.result }
+
+# Or wait for some external signal to stop the worker
+stop_queue = Queue.new
+Signal.trap('USR1') { stop_queue.close }
+worker_3.run { stop_queue.pop }
+```
+
+You can also shut down a running worker by calling `Temporal::Worker#shutdown` from a separate
+thread at any time.
+
+#### Running multiple workers
+
+In order to run multiple workers in the same thread you can use the `Temporal::Worker.run` method:
+
+```ruby
+# Initialize workers
+worker_1 = Temporal::Worker.new(connection, 'my-namespace-1', 'my-task-queue-1', activities: [MyActivity1, MyActivity2])
+worker_2 = Temporal::Worker.new(connection, 'my-namespace-2', 'my-task-queue-1', activities: [MyActivity3])
+worker_3 = Temporal::Worker.new(connection, 'my-namespace-1', 'my-task-queue-2', activities: [MyActivity4])
+
+Temporal::Worker.run(worker_1, worker_2, worker_3)
+```
+
+Please note that similar to `Temporal::Worker#run`, `Temporal::Worker.run` accepts a block that
+behaves the same way — the workers will be shut down when the block finishes.
+
+#### Worker Shutdown
+
+The `Temporal::Worker#run` (as well as `Temporal::Worker#shutdown`) invocation will wait on all
+activities to complete, so if a long-running activity does not at least respect cancellation, the
+shutdown may never complete.
+
+### Activities
+
+#### Definition
+
+Activities are defined by subclassing `Temporal::Activity` class:
+
+```ruby
+class SayHelloActivity < Temporal::Activity
+  # Optionally specify a custom activity name:
+  #   (The class name `SayHelloActivity` will be used by default)
+  activity_name 'say-hello'
+
+  def execute(name)
+    return "Hello, #{name}!"
+  end
+end
+```
+
+Some things to note about activity definitions:
+
+- Long running activities should regularly heartbeat and handle cancellation
+- Activities can only have positional arguments. Best practice is to only take a single argument
+  that is an object/dataclass of fields that can be added to as needed.
+
+#### Activity Context
+
+Activity classes have access to `Temporal::Activity::Context` via the `activity` method. Which
+itself provides access to useful methods, specifically:
+
+- `info` - Returns the immutable info of the currently running activity
+- `heartbeat(*details)` - Record a heartbeat
+- `cancelled?` - Whether a cancellation has been requested on this activity
+- `shield` - Prevent cancel exception from being thrown during the provided block of code
+
+##### Heartbeating and Cancellation
+
+In order for a non-local activity to be notified of cancellation requests, it must call
+`activity.heartbeat`. It is strongly recommended that all but the fastest executing activities call
+this method regularly.
+
+In addition to obtaining cancellation information, heartbeats also support detail data that is
+persisted on the server for retrieval during activity retry. If an activity calls
+`activity.heartbeat(123, 456)` and then fails and is retried, `activity.info.heartbeat_details` will
+return an array containing `123` and `456` on the next run.
+
+A cancellation is implemented using the `Thread#raise` method, which will raise a
+`Temporal::Error::CancelledError` during the execution of an activity. This means that your code
+might get interrupted at any point and never complete. In order to protect critical parts of your
+activities wrap them in `activity.shield`:
+
+```ruby
+class ActivityWithCriticalLogic < Temporal::Activity
+  def execute
+    activity.shield do
+      run_business_critical_logic_1
+    end
+
+    run_non_critical_logic
+
+    activity.shield do
+      run_business_critical_logic_2
+    end
+  end
+end
+```
+
+This will ensure that a cancellation request received while inside the `activity.shield` block will
+not raise an exception until that block finishes.
+
+In case the entire activity is considered critical, you can mark it as `shielded!` and ignore
+cancellation requests altogether:
+
+```ruby
+class CriticalActivity < Temporal::Activity
+  shielded!
+
+  def execute
+    ...
+  end
+end
+```
+
+For any long-running activity using this approach it is recommended to periodically check
+`activity.cancelled?` flag and respond accordingly.
+
 
 ## Dev Setup
 

lib/temporalio/activity.rb

@@ -1,25 +1,77 @@
 module Temporalio
+  # This is an abstract superclass for implementing activities.
+  #
+  # Temporal SDK users are expected to subclass it and implement the {#execute} method by adding
+  # their desired business logic.
+  #
+  # @abstract
+  #
+  # @example "Hello World" Activity
+  #   class HelloWorld < Temporalio::Activity
+  #     def execute(name)
+  #       "Hello, #{name}!"
+  #     end
+  #   end
   class Activity
+    # Specify a custom name to be used for this activity.
+    #
+    # By default a full class (with any namespace modules/classes) name will be used.
+    #
+    # @param new_name [String] Name to be used for this activity
+    #
+    # @example
+    #   class Test < Temporalio::Activity
+    #     activity_name 'custom-activity-name'
+    #
+    #     def execute
+    #       ...
+    #     end
+    #   end
     def self.activity_name(new_name)
       @activity_name = new_name
     end
 
+    # Mark the activity as shielded from cancellations.
+    #
+    # Activity cancellations are implemented using the `Thread#raise`, which can unsafely terminate
+    # your implementation. To disable this behaviour make sure to mark critical activities as
+    # `shielded!`. For shielding a part of your activity consider using
+    # {Temporalio::Activity::Context#shield}.
+    #
+    # @example
+    #   class Test < Temporalio::Activity
+    #     shielded!
+    #
+    #     def execute
+    #       ...
+    #     end
+    #   end
     def self.shielded!
       @shielded = true
     end
 
+    # @api private
     def self._name
       @activity_name || name || ''
     end
 
+    # @api private
     def self._shielded
       @shielded || false
     end
 
+    # @api private
     def initialize(context)
       @context = context
     end
 
+    # This is the main body of your activity's implementation.
+    #
+    # When implementing this method, you can use as many positional arguments as needed, which will
+    # get converted based on the activity invocation in your workflow.
+    #
+    # Inside of this method you have access to activity's context using the `activity` method. Check
+    # out {Temporalio::Activity::Context} for more information on how to use it.
     def execute(*_args)
       raise NoMethodError, 'must implement #execute'
     end

lib/temporalio/activity/context.rb

@@ -2,9 +2,14 @@
 
 module Temporalio
   class Activity
+    # This class provides methods that can be called from activity classes.
     class Context
+      # Information about the running activity.
+      #
+      # @return [Temporalio::Activity::Info]
       attr_reader :info
 
+      # @api private
       def initialize(info, heartbeat_proc, shielded: false)
         @thread = Thread.current
         @info = info
@@ -14,10 +19,25 @@ def initialize(info, heartbeat_proc, shielded: false)
         @mutex = Mutex.new
       end
 
+      # Send a heartbeat for the current activity.
+      #
+      # @param details [Array<any>] Data to store with the heartbeat.
       def heartbeat(*details)
         heartbeat_proc.call(*details)
       end
 
+      # Protect a part of activity's implementation from cancellations.
+      #
+      # Activity cancellations are implemented using the `Thread#raise`, which can unsafely
+      # terminate your implementation. To disable this behaviour make sure to wrap critical parts of
+      # your business logic in this method.
+      #
+      # For shielding a whole activity consider using {Temporalio::Activity.shielded!}.
+      #
+      # A cancellation that got requested while in a shielded block will not interrupt the execution
+      # and will raise a {Temporalio::Error::CancelledError} right after the block has finished.
+      #
+      # @yield Block to be protected from cancellations.
       def shield(&block)
         # The whole activity is shielded, called from a nested shield
         #   or while handling a CancelledError (in a rescue or ensure blocks)
@@ -40,10 +60,16 @@ def shield(&block)
         end
       end
 
+      # Whether a cancellation was ever requested on this activity.
+      #
+      # @return [Boolean] true if the activity has had a cancellation request, false otherwise.
       def cancelled?
         @cancelled
       end
 
+      # Cancel the running activity.
+      #
+      # @api private
       def cancel
         @cancelled = true
 

lib/temporalio/activity/info.rb

@@ -1,5 +1,6 @@
 module Temporalio
   class Activity
+    # Class containing information about an activity.
     class Info < Struct.new(
       :activity_id,
       :activity_type,
@@ -20,6 +21,44 @@ class Info < Struct.new(
       :workflow_type,
       keyword_init: true,
     )
+      # @!attribute [r] activity_id
+      #   @return [String] Activity ID.
+      # @!attribute [r] activity_type
+      #   @return [String] Name of the activity.
+      # @!attribute [r] attempt
+      #   @return [Integer] Activity's execution attempt.
+      # @!attribute [r] current_attempt_scheduled_time
+      #   @return [Time] Scheduled time of the current attempt.
+      # @!attribute [r] heartbeat_details
+      #   @return [Array<any>] Details submitted with the last heartbeat.
+      # @!attribute [r] heartbeat_timeout
+      #   @return [Float] Max time between heartbeats (in seconds).
+      # @!attribute [r] local
+      #   @return [Boolean] Whether activity is local or not.
+      # @!attribute [r] schedule_to_close_timeout
+      #   @return [Float] Max overall activity execution time (in seconds).
+      # @!attribute [r] scheduled_time
+      #   @return [Time] Time when activity was first scheduled.
+      # @!attribute [r] start_to_close_timeout
+      #   @return [Floaat] Max time of a single invocation (in seconds).
+      # @!attribute [r] started_time
+      #   @return [Time] Time when activity was started.
+      # @!attribute [r] task_queue
+      #   @return [String] Task queue on which the activity got scheduled.
+      # @!attribute [r] task_token
+      #   @return [String] A token for completing the activity.
+      # @!attribute [r] workflow_id
+      #   @return [String] Workflow ID.
+      # @!attribute [r] workflow_namespace
+      #   @return [String] Workflow namespace.
+      # @!attribute [r] workflow_run_id
+      #   @return [String] Workflow run ID.
+      # @!attribute [r] workflow_type
+      #   @return [String] Name of the workflow.
+
+      # Whether activity is local or not
+      #
+      # @return [Boolean] True for local activities, falst otherwise.
       def local?
         local
       end

lib/temporalio/bridge.rb

@@ -5,6 +5,7 @@
 BRIDGE_DIR = File.expand_path('..', __dir__ || '.')
 
 module Temporalio
+  # @api private
   module Bridge
     Rutie
       .new(:bridge, lib_path: '', lib_suffix: 'so', lib_prefix: '')

lib/temporalio/bridge/error.rb

@@ -1,5 +1,6 @@
 module Temporalio
   module Bridge
+    # @api private
     class Error < StandardError
       class WorkerShutdown < Error; end
     end

lib/temporalio/client/implementation.rb

@@ -12,6 +12,7 @@
 
 module Temporalio
   class Client
+    # @api private
     class Implementation
       def initialize(connection, namespace, converter, interceptors)
         @connection = connection