Module: Temporalio::Workflow

Defined in:
lib/temporalio/workflow.rb,
lib/temporalio/workflow/info.rb,
lib/temporalio/workflow/future.rb,
lib/temporalio/workflow/definition.rb,
lib/temporalio/workflow/update_info.rb,
lib/temporalio/workflow/nexus_client.rb,
lib/temporalio/workflow/parent_close_policy.rb,
lib/temporalio/workflow/child_workflow_handle.rb,
lib/temporalio/workflow/nexus_operation_handle.rb,
lib/temporalio/workflow/external_workflow_handle.rb,
lib/temporalio/workflow/handler_unfinished_policy.rb,
lib/temporalio/workflow/activity_cancellation_type.rb,
lib/temporalio/workflow/child_workflow_cancellation_type.rb,
lib/temporalio/workflow/nexus_operation_cancellation_type.rb

Overview

Module with all class-methods that can be made from a workflow. Methods on this module cannot be used outside of a workflow with the obvious exception of Workflow.in_workflow?. This module is not meant to be included or mixed in.

Defined Under Namespace

Modules: ActivityCancellationType, ChildWorkflowCancellationType, HandlerUnfinishedPolicy, NexusOperationCancellationType, ParentClosePolicy, Unsafe Classes: ChildWorkflowHandle, ContinueAsNewError, Definition, DefinitionOptions, ExternalWorkflowHandle, Future, Info, InvalidWorkflowStateError, NexusClient, NexusOperationHandle, NondeterminismError, UpdateInfo

Constant Summary collapse

Mutex =

Mutex is a workflow-safe wrapper around Mutex.

As of this writing, all methods on Mutex are safe for workflow use and are implicitly made deterministic by the Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of Mutex by non-workflow-safe code. However, users may prefer to use the more powerful wait_condition approach as a mutex (e.g. wait until a certain attribute is set to false then set it to true before continuing).

Unsafe._wrap_ruby_class_as_legal(::Mutex)
Queue =

Queue is a workflow-safe wrapper around Queue.

As of this writing, all methods on Queue are safe for workflow use and are implicitly made deterministic by the Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of Queue by non-workflow-safe code. However, users may prefer to use the more powerful wait_condition approach as a queue (e.g. wait until an array is non-empty before continuing).

Unsafe._wrap_ruby_class_as_legal(::Queue)
SizedQueue =

SizedQueue is a workflow-safe wrapper around SizedQueue.

As of this writing, all methods on SizedQueue are safe for workflow use and are implicitly made deterministic by the Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of SizedQueue by non-workflow-safe code. However, users may prefer to use the more powerful wait_condition approach as a queue (e.g. wait until an array is non-empty before continuing).

Unsafe._wrap_ruby_class_as_legal(::SizedQueue)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#attempt ⇒ Integer

Returns Current workflow attempt.

Returns:

  • (Integer) —

    Current workflow attempt.




# File 'lib/temporalio/workflow/info.rb', line 30

#continued_run_id ⇒ String?

Returns Run ID if this was continued.

Returns:

  • (String, nil) —

    Run ID if this was continued.




# File 'lib/temporalio/workflow/info.rb', line 30

#cron_schedule ⇒ String?

Returns Cron schedule if applicable.

Returns:

  • (String, nil) —

    Cron schedule if applicable.




# File 'lib/temporalio/workflow/info.rb', line 30

#execution_timeout ⇒ Float?

Returns Execution timeout for the workflow.

Returns:

  • (Float, nil) —

    Execution timeout for the workflow.




# File 'lib/temporalio/workflow/info.rb', line 30

#first_execution_run_id ⇒ String

Returns The very first run ID the workflow ever had, following continuation chains.

Returns:

  • (String) —

    The very first run ID the workflow ever had, following continuation chains.




# File 'lib/temporalio/workflow/info.rb', line 30

#has_last_result? ⇒ Boolean

Returns Successful result if this workflow is a continuation of a success.

Returns:

  • (Boolean) —

    Successful result if this workflow is a continuation of a success.




# File 'lib/temporalio/workflow/info.rb', line 30

#headers ⇒ Hash<String, Api::Common::V1::Payload>

Returns Headers.

Returns:




# File 'lib/temporalio/workflow/info.rb', line 30

#last_failure ⇒ Exception?

Returns Failure if this workflow run is a continuation of a failure.

Returns:

  • (Exception, nil) —

    Failure if this workflow run is a continuation of a failure.




# File 'lib/temporalio/workflow/info.rb', line 30

#last_result ⇒ Object?

Returns Successful result if this workflow is a continuation of a success.

Returns:

  • (Object, nil) —

    Successful result if this workflow is a continuation of a success.




# File 'lib/temporalio/workflow/info.rb', line 30

Class Method Details

.all_handlers_finished? ⇒ Boolean

Whether all update and signal handlers have finished executing. Consider waiting on this condition before workflow return or continue-as-new, to prevent interruption of in-progress handlers by workflow return: ‘Temporalio::Workflow.wait_condition { Temporalio::Workflow.all_handlers_finished? }“

Returns:

  • (Boolean) —

    Whether all update and signal handlers have finished executing. Consider waiting on this condition before workflow return or continue-as-new, to prevent interruption of in-progress handlers by workflow return: ‘Temporalio::Workflow.wait_condition { Temporalio::Workflow.all_handlers_finished? }“



29
30
31
 
# File 'lib/temporalio/workflow.rb', line 29

def self.all_handlers_finished?
  _current.all_handlers_finished?
end

.cancellation ⇒ Cancellation

Returns Cancellation for the workflow. This is canceled when a workflow cancellation request is received. This is the default cancellation for most workflow calls.

Returns:

  • (Cancellation) —

    Cancellation for the workflow. This is canceled when a workflow cancellation request is received. This is the default cancellation for most workflow calls.



35
36
37
 
# File 'lib/temporalio/workflow.rb', line 35

def self.cancellation
  _current.cancellation
end

.continue_as_new_suggested ⇒ Boolean

Returns Whether continue as new is suggested. This value is the current continue-as-new suggestion up until the current task. Note, this value may not be up to date when accessed in a query. When continue as new is suggested is based on server-side configuration.

Returns:

  • (Boolean) —

    Whether continue as new is suggested. This value is the current continue-as-new suggestion up until the current task. Note, this value may not be up to date when accessed in a query. When continue as new is suggested is based on server-side configuration.



42
43
44
 
# File 'lib/temporalio/workflow.rb', line 42

def self.continue_as_new_suggested
  _current.continue_as_new_suggested
end

.create_nexus_client(endpoint:, service:) ⇒ NexusClient

Create a Nexus client for executing operations.

WARNING: Nexus support is experimental.

Parameters:

  • endpoint (Symbol, String) —

    Endpoint name.

  • service (Symbol, String) —

    Service name.

Returns:

  • (NexusClient) —

    Client for executing Nexus operations.



53
54
55
 
# File 'lib/temporalio/workflow.rb', line 53

def self.create_nexus_client(endpoint:, service:)
  _current.create_nexus_client(endpoint:, service:)
end

.current_deployment_version ⇒ WorkerDeploymentVersion?

Get the deployment version of the worker which executed the current Workflow Task.

May be nil if the task was completed by a worker without a deployment version or build id. If this worker is the one executing this task for the first time and has a deployment version set, then its ID will be used. This value may change over the lifetime of the workflow run, but is deterministic and safe to use for branching. This is currently experimental.

Returns:



83
84
85
 
# File 'lib/temporalio/workflow.rb', line 83

def self.current_deployment_version
  _current.current_deployment_version
end

.current_details ⇒ String

Get current details for this workflow that may appear in UI/CLI. Unlike static details set at start, this value can be updated throughout the life of the workflow. This can be in Temporal markdown format and can span multiple lines. This is currently experimental.

Returns:

  • (String) —

    Current details. Default is empty string.



62
63
64
 
# File 'lib/temporalio/workflow.rb', line 62

def self.current_details
  _current.current_details
end

.current_details=(details) ⇒ Object

Set current details for this workflow that may appear in UI/CLI. Unlike static details set at start, this value can be updated throughout the life of the workflow. This can be in Temporal markdown format and can span multiple lines. This is currently experimental.

Parameters:

  • details (String) —

    Current details. Can use empty string to unset.



71
72
73
 
# File 'lib/temporalio/workflow.rb', line 71

def self.current_details=(details)
  _current.current_details = details
end

.current_history_length ⇒ Integer

Returns Current number of events in history. This value is the current history event count up until the current task. Note, this value may not be up to date when accessed in a query.

Returns:

  • (Integer) —

    Current number of events in history. This value is the current history event count up until the current task. Note, this value may not be up to date when accessed in a query.



89
90
91
 
# File 'lib/temporalio/workflow.rb', line 89

def self.current_history_length
  _current.current_history_length
end

.current_history_size ⇒ Integer

Returns Current history size in bytes. This value is the current history size up until the current task. Note, this value may not be up to date when accessed in a query.

Returns:

  • (Integer) —

    Current history size in bytes. This value is the current history size up until the current task. Note, this value may not be up to date when accessed in a query.



95
96
97
 
# File 'lib/temporalio/workflow.rb', line 95

def self.current_history_size
  _current.current_history_size
end

.current_update_info ⇒ UpdateInfo

Returns Current update info if this code is running inside an update. This is set via a Fiber-local storage so it is only visible to the current handler fiber.

Returns:

  • (UpdateInfo) —

    Current update info if this code is running inside an update. This is set via a Fiber-local storage so it is only visible to the current handler fiber.



101
102
103
 
# File 'lib/temporalio/workflow.rb', line 101

def self.current_update_info
  _current.current_update_info
end

.deprecate_patch(patch_id) ⇒ Object

Mark a patch as deprecated.

This marks a workflow that had patched in a previous version of the code as no longer applicable because all workflows that use the old code path are done and will never be queried again. Therefore the old code path is removed as well.

Parameters:

  • patch_id (Symbol, String) —

    Patch ID.



112
113
114
 
# File 'lib/temporalio/workflow.rb', line 112

def self.deprecate_patch(patch_id)
  _current.deprecate_patch(patch_id)
end

.execute_activity(activity, *args, task_queue: info.task_queue, summary: nil, schedule_to_close_timeout: nil, schedule_to_start_timeout: nil, start_to_close_timeout: nil, heartbeat_timeout: nil, retry_policy: nil, cancellation: Workflow.cancellation, cancellation_type: ActivityCancellationType::TRY_CANCEL, activity_id: nil, disable_eager_execution: false, priority: Priority.default, arg_hints: nil, result_hint: nil) ⇒ Object

Note:

Using an already-canceled cancellation may give a different exception than canceling after started. Use Error.canceled? to check if the exception is a cancellation either way.

Execute an activity and return its result. Either start_to_close_timeout or schedule_to_close_timeout must be set. The heartbeat_timeout should be set for any non-immediately-completing activity so it can receive cancellation. To run an activity in the background, use a Future.

Parameters:

  • activity (Class<Activity::Definition>, Symbol, String) —

    Activity definition class or activity name.

  • args (Array<Object>) —

    Arguments to the activity.

  • task_queue (String) (defaults to: info.task_queue) —

    Task queue to run the activity on. Defaults to the current workflow’s task queue.

  • summary (String, nil) (defaults to: nil) —

    Single-line summary for this activity that may appear in CLI/UI. This can be in single-line Temporal markdown format. This is currently experimental.

  • schedule_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take from first being scheduled to being completed before it times out. This is inclusive of all retries.

  • schedule_to_start_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take to be started from first being scheduled.

  • start_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time a single activity run can take from when it starts to when it completes. This is per retry.

  • heartbeat_timeout (Float, nil) (defaults to: nil) —

    How frequently an activity must invoke heartbeat while running before it is considered timed out. This also affects how heartbeats are throttled, see general heartbeating documentation.

  • retry_policy (RetryPolicy) (defaults to: nil) —

    How an activity is retried on failure. If unset, a server-defined default is used. Set maximum attempts to 1 to disable retries.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation to apply to the activity. How cancellation is treated is based on cancellation_type. This defaults to the workflow’s cancellation, but may need to be overridden with a new/detached one if an activity is being run in an ensure after workflow cancellation.

  • cancellation_type (ActivityCancellationType) (defaults to: ActivityCancellationType::TRY_CANCEL) —

    How the activity is treated when it is canceled from the workflow.

  • activity_id (String, nil) (defaults to: nil) —

    Optional unique identifier for the activity. This is an advanced setting that should not be set unless users are sure they need to. Contact Temporal before setting this value.

  • disable_eager_execution (Boolean) (defaults to: false) —

    Whether eager execution is disabled. Eager activity execution is an optimization on some servers that sends activities back to the same worker as the calling workflow if they can run there. If false (the default), eager execution may still be disabled at the worker level or may not be requested due to lack of available slots.

  • priority (Priority) (defaults to: Priority.default) —

    Priority of the activity. This is currently experimental.

  • arg_hints (Array<Object>, nil) (defaults to: nil) —

    Overrides converter hints for arguments if any. If unset/nil and the activity definition has arg hints, those are used by default.

  • result_hint (Object, nil) (defaults to: nil) —

    Overrides converter hint for result if any. If unset/nil and the activity definition has result hint, it is used by default.

Returns:

  • (Object) —

    Result of the activity.

Raises:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/temporalio/workflow.rb', line 159

def self.execute_activity(
  activity,
  *args,
  task_queue: info.task_queue,
  summary: nil,
  schedule_to_close_timeout: nil,
  schedule_to_start_timeout: nil,
  start_to_close_timeout: nil,
  heartbeat_timeout: nil,
  retry_policy: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ActivityCancellationType::TRY_CANCEL,
  activity_id: nil,
  disable_eager_execution: false,
  priority: Priority.default,
  arg_hints: nil,
  result_hint: nil
)
  _current.execute_activity(
    activity, *args,
    task_queue:, summary:, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
    heartbeat_timeout:, retry_policy:, cancellation:, cancellation_type:, activity_id:, disable_eager_execution:,
    priority:, arg_hints:, result_hint:
  )
end

.execute_child_workflow(workflow, *args, id: random.uuid, task_queue: info.task_queue, static_summary: nil, static_details: nil, cancellation: Workflow.cancellation, cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED, parent_close_policy: ParentClosePolicy::TERMINATE, execution_timeout: nil, run_timeout: nil, task_timeout: nil, id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE, retry_policy: nil, cron_schedule: nil, memo: nil, search_attributes: nil, priority: Priority.default, arg_hints: nil, result_hint: nil) ⇒ Object

Shortcut for start_child_workflow + Temporalio::Workflow::ChildWorkflowHandle#result. See those two calls for more details.



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/temporalio/workflow.rb', line 186

def self.execute_child_workflow(
  workflow,
  *args,
  id: random.uuid,
  task_queue: info.task_queue,
  static_summary: nil,
  static_details: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED,
  parent_close_policy: ParentClosePolicy::TERMINATE,
  execution_timeout: nil,
  run_timeout: nil,
  task_timeout: nil,
  id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE,
  retry_policy: nil,
  cron_schedule: nil,
  memo: nil,
  search_attributes: nil,
  priority: Priority.default,
  arg_hints: nil,
  result_hint: nil
)
  start_child_workflow(
    workflow, *args,
    id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
    parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
    retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, arg_hints:, result_hint:
  ).result
end

.execute_local_activity(activity, *args, summary: nil, schedule_to_close_timeout: nil, schedule_to_start_timeout: nil, start_to_close_timeout: nil, retry_policy: nil, local_retry_threshold: nil, cancellation: Workflow.cancellation, cancellation_type: ActivityCancellationType::TRY_CANCEL, activity_id: nil, arg_hints: nil, result_hint: nil) ⇒ Object

Note:

Using an already-canceled cancellation may give a different exception than canceling after started. Use Error.canceled? to check if the exception is a cancellation either way.

Execute an activity locally in this same workflow task and return its result. This should usually only be used for short/simple activities where the result performance matters. Either start_to_close_timeout or schedule_to_close_timeout must be set. To run an activity in the background, use a Future.

Parameters:

  • activity (Class<Activity::Definition>, Symbol, String) —

    Activity definition class or name.

  • args (Array<Object>) —

    Arguments to the activity.

  • summary (String, nil) (defaults to: nil) —

    Single-line summary for this activity that may appear in CLI/UI. This can be in single-line Temporal markdown format. This is currently experimental.

  • schedule_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take from first being scheduled to being completed before it times out. This is inclusive of all retries.

  • schedule_to_start_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take to be started from first being scheduled.

  • start_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time a single activity run can take from when it starts to when it completes. This is per retry.

  • retry_policy (RetryPolicy, nil) (defaults to: nil) —

    How an activity is retried on failure. If unset, a default policy is used. Set maximum attempts to 1 to disable retries.

  • local_retry_threshold (Float, nil) (defaults to: nil) —

    If the activity is retrying and backoff would exceed this value, a timer is scheduled and the activity is retried after. Otherwise, backoff will happen internally within the task. Defaults to 1 minute.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation to apply to the activity. How cancellation is treated is based on cancellation_type. This defaults to the workflow’s cancellation, but may need to be overridden with a new/detached one if an activity is being run in an ensure after workflow cancellation.

  • cancellation_type (ActivityCancellationType) (defaults to: ActivityCancellationType::TRY_CANCEL) —

    How the activity is treated when it is canceled from the workflow.

  • activity_id (String, nil) (defaults to: nil) —

    Optional unique identifier for the activity. This is an advanced setting that should not be set unless users are sure they need to. Contact Temporal before setting this value.

  • arg_hints (Array<Object>, nil) (defaults to: nil) —

    Overrides converter hints for arguments if any. If unset/nil and the activity definition has arg hints, those are used by default.

  • result_hint (Object, nil) (defaults to: nil) —

    Overrides converter hint for result if any. If unset/nil and the activity definition has result hint, it is used by default.

Returns:

  • (Object) —

    Result of the activity.

Raises:



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/temporalio/workflow.rb', line 254

def self.execute_local_activity(
  activity,
  *args,
  summary: nil,
  schedule_to_close_timeout: nil,
  schedule_to_start_timeout: nil,
  start_to_close_timeout: nil,
  retry_policy: nil,
  local_retry_threshold: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ActivityCancellationType::TRY_CANCEL,
  activity_id: nil,
  arg_hints: nil,
  result_hint: nil
)
  _current.execute_local_activity(
    activity, *args,
    summary:, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
    retry_policy:, local_retry_threshold:, cancellation:, cancellation_type:,
    activity_id:, arg_hints:, result_hint:
  )
end

.external_workflow_handle(workflow_id, run_id: nil) ⇒ ExternalWorkflowHandle

Get a handle to an external workflow for canceling and issuing signals.

Parameters:

  • workflow_id (String) —

    Workflow ID.

  • run_id (String, nil) (defaults to: nil) —

    Optional, specific run ID.

Returns:



283
284
285
 
# File 'lib/temporalio/workflow.rb', line 283

def self.external_workflow_handle(workflow_id, run_id: nil)
  _current.external_workflow_handle(workflow_id, run_id:)
end

.in_workflow? ⇒ Boolean

Returns Whether the current code is executing in a workflow.

Returns:

  • (Boolean) —

    Whether the current code is executing in a workflow.



288
289
290
 
# File 'lib/temporalio/workflow.rb', line 288

def self.in_workflow?
  _current_or_nil != nil
end

.info ⇒ Info

Returns Information about the current workflow.

Returns:

  • (Info) —

    Information about the current workflow.



293
294
295
 
# File 'lib/temporalio/workflow.rb', line 293

def self.info
  _current.info
end

.instance ⇒ Definition?

Returns Workflow class instance. This should always be present except in Temporalio::Worker::Interceptor::Workflow::Inbound#init where it will be nil.

Returns:



299
300
301
 
# File 'lib/temporalio/workflow.rb', line 299

def self.instance
  _current.instance
end

.logger ⇒ Logger

Returns Logger for the workflow. This is a scoped logger that automatically appends workflow details to every log and takes care not to log during replay.

Returns:

  • (Logger) —

    Logger for the workflow. This is a scoped logger that automatically appends workflow details to every log and takes care not to log during replay.



305
306
307
 
# File 'lib/temporalio/workflow.rb', line 305

def self.logger
  _current.logger
end

.memo ⇒ Hash{String, Symbol => Object}

Returns Memo for the workflow. This is a read-only view of the memo. To update the memo, use upsert_memo. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.

Returns:

  • (Hash{String, Symbol => Object}) —

    Memo for the workflow. This is a read-only view of the memo. To update the memo, use upsert_memo. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.



312
313
314
 
# File 'lib/temporalio/workflow.rb', line 312

def self.memo
  _current.memo
end

.metric_meter ⇒ Metric::Meter

Returns Metric meter to create metrics on. This metric meter already contains some workflow-specific attributes and takes care not to apply metrics during replay.

Returns:

  • (Metric::Meter) —

    Metric meter to create metrics on. This metric meter already contains some workflow-specific attributes and takes care not to apply metrics during replay.



318
319
320
 
# File 'lib/temporalio/workflow.rb', line 318

def self.metric_meter
  _current.metric_meter
end

.now ⇒ Time

Returns Current UTC time for this workflow. This creates and returns a new Time instance every time it is invoked, it is not the same instance continually mutated.

Returns:

  • (Time) —

    Current UTC time for this workflow. This creates and returns a new Time instance every time it is invoked, it is not the same instance continually mutated.



324
325
326
 
# File 'lib/temporalio/workflow.rb', line 324

def self.now
  _current.now
end

.patched(patch_id) ⇒ Boolean

Patch a workflow.

When called, this will only return true if code should take the newer path which means this is either not replaying or is replaying and has seen this patch before. Results for successive calls to this function for the same ID and workflow are memoized. Use deprecate_patch when all workflows are done and will never be queried again. The old code path can be removed at that time too.

Parameters:

  • patch_id (Symbol, String) —

    Patch ID.

Returns:

  • (Boolean) —

    True if this should take the newer patch, false if it should take the old path.



337
338
339
 
# File 'lib/temporalio/workflow.rb', line 337

def self.patched(patch_id)
  _current.patched(patch_id)
end

.payload_converter ⇒ Converters::PayloadConverter

Returns Payload converter for the workflow.

Returns:



342
343
344
 
# File 'lib/temporalio/workflow.rb', line 342

def self.payload_converter
  _current.payload_converter
end

.query_handlers ⇒ Hash<String, Definition::Query>

Returns Query handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_query method is best.

Returns:

  • (Hash<String, Definition::Query>) —

    Query handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_query method is best.



349
350
351
 
# File 'lib/temporalio/workflow.rb', line 349

def self.query_handlers
  _current.query_handlers
end

.random ⇒ Random

Returns Deterministic instance of Random for use in a workflow. This instance should be accessed each time needed, not stored. This instance may be recreated with a different seed in special cases (e.g. workflow reset). Do not use any other randomization inside workflow code.

Returns:

  • (Random) —

    Deterministic instance of Random for use in a workflow. This instance should be accessed each time needed, not stored. This instance may be recreated with a different seed in special cases (e.g. workflow reset). Do not use any other randomization inside workflow code.



356
357
358
 
# File 'lib/temporalio/workflow.rb', line 356

def self.random
  _current.random
end

.search_attributes ⇒ SearchAttributes

Returns Search attributes for the workflow. This is a read-only view of the attributes. To update the attributes, use upsert_search_attributes. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.

Returns:

  • (SearchAttributes) —

    Search attributes for the workflow. This is a read-only view of the attributes. To update the attributes, use upsert_search_attributes. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.



363
364
365
 
# File 'lib/temporalio/workflow.rb', line 363

def self.search_attributes
  _current.search_attributes
end

.signal_handlers ⇒ Hash<String, Definition::Signal>

Returns Signal handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_signal method is best.

Returns:

  • (Hash<String, Definition::Signal>) —

    Signal handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_signal method is best.



370
371
372
 
# File 'lib/temporalio/workflow.rb', line 370

def self.signal_handlers
  _current.signal_handlers
end

.sleep(duration, summary: nil, cancellation: Workflow.cancellation) ⇒ Object

Sleep in a workflow for the given time.

Parameters:

  • duration (Float, nil) —

    Time to sleep in seconds. nil represents infinite, which does not start a timer and just waits for cancellation. 0 is assumed to be 1 millisecond and still results in a server-side timer. This value cannot be negative. Since Temporal timers are server-side, timer resolution may not end up as precise as system timers.

  • summary (String, nil) (defaults to: nil) —

    A simple string identifying this timer that may be visible in UI/CLI. While it can be normal text, it is best to treat as a timer ID. This is currently experimental.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation for this timer.

Raises:



384
385
386
 
# File 'lib/temporalio/workflow.rb', line 384

def self.sleep(duration, summary: nil, cancellation: Workflow.cancellation)
  _current.sleep(duration, summary:, cancellation:)
end

.start_child_workflow(workflow, *args, id: random.uuid, task_queue: info.task_queue, static_summary: nil, static_details: nil, cancellation: Workflow.cancellation, cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED, parent_close_policy: ParentClosePolicy::TERMINATE, execution_timeout: nil, run_timeout: nil, task_timeout: nil, id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE, retry_policy: nil, cron_schedule: nil, memo: nil, search_attributes: nil, priority: Priority.default, arg_hints: nil, result_hint: nil) ⇒ ChildWorkflowHandle

Start a child workflow and return the handle.

Parameters:

  • workflow (Class<Workflow::Definition>, Symbol, String) —

    Workflow definition class or workflow name.

  • args (Array<Object>) —

    Arguments to the workflow.

  • id (String) (defaults to: random.uuid) —

    Unique identifier for the workflow execution. Defaults to a new UUID from random.

  • task_queue (String) (defaults to: info.task_queue) —

    Task queue to run the workflow on. Defaults to the current workflow’s task queue.

  • static_summary (String, nil) (defaults to: nil) —

    Fixed single-line summary for this workflow execution that may appear in CLI/UI. This can be in single-line Temporal markdown format. This is currently experimental.

  • static_details (String, nil) (defaults to: nil) —

    Fixed details for this workflow execution that may appear in CLI/UI. This can be in Temporal markdown format and can be multiple lines. This is a fixed value on the workflow that cannot be updated. For details that can be updated, use current_details= within the workflow. This is currently experimental.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation to apply to the child workflow. How cancellation is treated is based on cancellation_type. This defaults to the workflow’s cancellation.

  • cancellation_type (ChildWorkflowCancellationType) (defaults to: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED) —

    How the child workflow will react to cancellation.

  • parent_close_policy (ParentClosePolicy) (defaults to: ParentClosePolicy::TERMINATE) —

    How to handle the child workflow when the parent workflow closes.

  • execution_timeout (Float, nil) (defaults to: nil) —

    Total workflow execution timeout in seconds including retries and continue as new.

  • run_timeout (Float, nil) (defaults to: nil) —

    Timeout of a single workflow run inseconds.

  • task_timeout (Float, nil) (defaults to: nil) —

    Timeout of a single workflow task in seconds.

  • id_reuse_policy (WorkflowIDReusePolicy) (defaults to: WorkflowIDReusePolicy::ALLOW_DUPLICATE) —

    How already-existing IDs are treated.

  • retry_policy (RetryPolicy, nil) (defaults to: nil) —

    Retry policy for the workflow.

  • cron_schedule (String, nil) (defaults to: nil) —

    Cron schedule. Users should use schedules instead of this.

  • memo (Hash{String, Symbol => Object}, nil) (defaults to: nil) —

    Memo for the workflow.

  • search_attributes (SearchAttributes, nil) (defaults to: nil) —

    Search attributes for the workflow.

  • priority (Priority) (defaults to: Priority.default) —

    Priority of the workflow. This is currently experimental.

  • arg_hints (Array<Object>, nil) (defaults to: nil) —

    Overrides converter hints for arguments if any. If unset/nil and the workflow definition has arg hints, those are used by default.

  • result_hint (Object, nil) (defaults to: nil) —

    Overrides converter hint for result if any. If unset/nil and the workflow definition has result hint, it is used by default.

Returns:

Raises:



422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/temporalio/workflow.rb', line 422

def self.start_child_workflow(
  workflow,
  *args,
  id: random.uuid,
  task_queue: info.task_queue,
  static_summary: nil,
  static_details: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED,
  parent_close_policy: ParentClosePolicy::TERMINATE,
  execution_timeout: nil,
  run_timeout: nil,
  task_timeout: nil,
  id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE,
  retry_policy: nil,
  cron_schedule: nil,
  memo: nil,
  search_attributes: nil,
  priority: Priority.default,
  arg_hints: nil,
  result_hint: nil
)
  _current.start_child_workflow(
    workflow, *args,
    id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
    parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
    retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, arg_hints:, result_hint:
  )
end

.storage ⇒ Hash<Object, Object>

Returns General in-workflow storage. Most users will store state on the workflow class instance instead, this is only for utilities without access to the class instance.

Returns:

  • (Hash<Object, Object>) —

    General in-workflow storage. Most users will store state on the workflow class instance instead, this is only for utilities without access to the class instance.



454
455
456
 
# File 'lib/temporalio/workflow.rb', line 454

def self.storage
  _current.storage
end

.timeout(duration, exception_class = Timeout::Error, message = 'execution expired', summary: 'Timeout timer') { ... } ⇒ Object

Run the block until the timeout is reached. This is backed by sleep. This does not accept cancellation because it is expected the block within will properly handle/bubble cancellation.

Parameters:

  • duration (Float, nil) —

    Duration for the timeout. This is backed by sleep so see that method for details.

  • exception_class (Class<Exception>) (defaults to: Timeout::Error) —

    Exception to raise on timeout. Defaults to Timeout::Error like Timeout.timeout. Note that Timeout::Error is considered a workflow failure exception, not a task failure exception.

  • message (String) (defaults to: 'execution expired') —

    Message to use for timeout exception. Defaults to “execution expired” like Timeout.timeout.

  • summary (String) (defaults to: 'Timeout timer') —

    Timer summary for the timer created by this timeout. This is backed by sleep so see that method for details. This is currently experimental.

Yields:

  • Block to run with a timeout.

Returns:

  • (Object) —

    The result of the block.

Raises:

  • (Exception) —

    Upon timeout, raises whichever class is set in exception_class with the message of message.



473
474
475
476
477
478
479
480
481
 
# File 'lib/temporalio/workflow.rb', line 473

def self.timeout(
  duration,
  exception_class = Timeout::Error,
  message = 'execution expired',
  summary: 'Timeout timer',
  &
)
  _current.timeout(duration, exception_class, message, summary:, &)
end

.update_handlers ⇒ Hash<String, Definition::Update>

Returns Update handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_update method is best.

Returns:

  • (Hash<String, Definition::Update>) —

    Update handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_update method is best.



486
487
488
 
# File 'lib/temporalio/workflow.rb', line 486

def self.update_handlers
  _current.update_handlers
end

.upsert_memo(hash) ⇒ Object

Issue updates to the workflow memo.

Parameters:

  • hash (Hash{String, Symbol => Object, nil}) —

    Updates to apply. Value can be nil to effectively remove the memo value.



494
495
496
 
# File 'lib/temporalio/workflow.rb', line 494

def self.upsert_memo(hash)
  _current.upsert_memo(hash)
end

.upsert_search_attributes(*updates) ⇒ Object

Issue updates to the workflow search attributes.

Parameters:



502
503
504
 
# File 'lib/temporalio/workflow.rb', line 502

def self.upsert_search_attributes(*updates)
  _current.upsert_search_attributes(*updates)
end

.wait_condition(cancellation: Workflow.cancellation) { ... } ⇒ Object

Wait for the given block to return a “truthy” value (i.e. any value other than false or nil). The block must be side-effect free since it may be invoked frequently during event loop iteration. To timeout a wait, timeout can be used. This cannot be used in side-effect-free contexts such as initialize, queries, or update validators.

This is very commonly used to wait on a value to be set by a handler, e.g. ‘Temporalio::Workflow.wait_condition { @some_value }`. Special care was taken to only wake up a single wait condition when it evaluates to true. Therefore if multiple wait conditions are waiting on the same thing, only one is awoken at a time, which means the code immediately following that wait condition can change the variable before other wait conditions are evaluated. This is a useful property for building mutexes/semaphores.

Parameters:

  • cancellation (Cancellation, nil) (defaults to: Workflow.cancellation) —

    Cancellation to cancel the wait. This defaults to the workflow’s cancellation.

Yields:

  • Block that is run many times to test for truthiness.

Yield Returns:

  • (Object) —

    Value to check whether truthy or falsy.

Returns:

  • (Object) —

    Truthy value returned from the block.

Raises:



523
524
525
526
527
 
# File 'lib/temporalio/workflow.rb', line 523

def self.wait_condition(cancellation: Workflow.cancellation, &)
  raise 'Block required' unless block_given?

  _current.wait_condition(cancellation:, &)
end