time skipping fast forward by feiyang3cat · Pull Request #786 · temporalio/api

feiyang3cat · 2026-05-22T22:14:24Z

What changed?

Removed obsolete fields — safe to delete as this feature has not been released (disable compatibility checking temporarily)
Renamed bound to fast forward to define the concept from the perspective of users' behavior
Add disable_propagation_for_child to give users a way to stop propagation
Add update_time to UpdateWorkflowExecutionOptionsRequest

Why?

for 1) make the API cleaner
for 2) a neat name to reduce misunderstanding
for 3) a child workflow is a different execution and has its own virtual clock, and users may need an option to change the default propagation behavior
for 4) this can be used when SDK verify the time in TimeSkippingTransitionedEvent match the sleep duration

Breaking changes

removed the feature maxSkippedDuration-> the server has already implemented this feature need to delete the code first
restructured the maxElapsedDurationto fast_forward-> the server need to do renaming

Server PR
temporalio/temporal#10576

GregoryTravis · 2026-06-02T20:09:49Z

        }
      },
-      "description": "Configuration for time skipping during a workflow execution.\nWhen enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over.\nWhen time advances, it skips to the earlier of the next user timer or the configured bound, if either exists.\n\nPropagation behavior of time skipping:\nThe enabled flag, bound fields, and accumulated skipped duration are propagated to related executions as follows:\n(1) Child workflows and continue-as-new: both the configuration and the accumulated skipped duration are\n    inherited from the current execution. The configured bound is shared between the inherited skipped\n    duration and any additional duration skipped by the new run.\n(2) Retry and cron: the configuration and accumulated skipped duration are inherited as recorded when the\n    current workflow started; the accumulated skipped duration of the current run is not propagated.\n(3) Reset: the new run retains the time-skipping configuration of the current execution. Because reset replays\n    all events up to the reset point and re-applies any UpdateWorkflowExecutionOptions changes made after that\n    point, the resulting run ends up with the same final time-skipping configuration as the previous run."
+      "description": "The configuration for time skipping of a workflow execution (a chain of runs including retries, cron, continue-as-new).\nWhen time skipping is enabled, virtual time advances automatically whenever there is no in-flight work.\nIn-flight work includes activities, child workflows, Nexus operations, signal/cancel external workflow operations,\nand possibly other features added in the future.\nUser timers are not classified as in-flight work and will be skipped over; the virtual clock may also skip to the\ntime point of the registered sleep when there is no in-flight work.\n\nFor child workflows, by default, if the parent execution is skipping time, the child execution will also skip time,\nbut the parent's sleep won't affect the child execution. A flag is provided to disable propagation of the\n\"enabled\" flag to child workflows; regardless of that flag, a child workflow inherits the virtual time from the\nparent execution as its start time."


"to the time point of the registered sleep" -- does this mean to end point of the sleep period?

oh I see, this is better expression. yes. will change to "to the end point of the sleep period"

and I think I may need to add another thing is if the workflow execution (the whole chain of runs) completes before having a chance to skip time, the sleep may never take place -> check this example

GregoryTravis · 2026-06-02T20:12:53Z

+        "sleep": {
          "type": "string",
-          "description": "Maximum total virtual time that can be skipped."
+          "description": "Optionally register a sleep for the current workflow execution.\nWhen the sleep completes, time skipping is disabled and this action is recorded in\nthe WorkflowExecutionTimeSkippingTransitionedEvent, but it can be re-enabled by\nsetting `enabled` to true via UpdateWorkflowExecutionOptions.\nThe current workflow execution is a chain of runs (retries, cron, continue-as-new);\nchild workflows are separate executions, so this sleep won't affect them."


Is the implication here that the sleep will actually take place, and not be skipped?

yeah, totally, to be specific sleep counts both natural time passing and time skipping.

for example, the user calls sleep(1h) at 10am, and then the sleep is expected to take place in 11am if the workflow execution hasn't completed. And at 11am (virtual workflow time) the sleep takes place, but for the past 1hour the workflow may takes 30 minutes busy with activities (and this is real 30 minutes), and then waiting for some user timer/condition so we skip 30min(this is skipped) to fire the 1hour.

let me write some sleep examples

Sushisource · 2026-06-08T18:47:19Z

    google.protobuf.Timestamp target_time = 1;

-    // when true, time skipping was disabled automatically due to a bound being reached.
+    // When true, time skipping has been disabled automatically due to the fast_forward completing.


Suggested change

// When true, time skipping has been disabled automatically due to the fast_forward completing.

// When true, time skipping has been disabled automatically due to a call to fast_forward completing.

why do we need to add "a call" in this comment as there won't be any extra calls from the client side to disable it ?

Sushisource · 2026-06-08T18:50:17Z

+
+    // The Workflow Execution time when the options were updated. When time skipping is
+    // enabled, this is the workflow's virtual time rather than wall-clock time.
+    google.protobuf.Timestamp update_time = 2;


How does this get used? Does SDK need to use this?

I think so but it is just a refinement/enhancement that when SDK checks the time skipping event it can re-verifies the time is correct. this is only needed in edgy case:
-> the user set fast-forward 2hours using SDK and waiting on it (1)
-> and the user issues another request to change it to 4hours (2)
-> and when client (1) finds the time skipping transitioned event it has a way to know it is a correct time to return

Co-authored-by: Spencer Judge <spencer@temporal.io>

feiyang3cat requested review from a team May 22, 2026 22:14

feiyang3cat force-pushed the patch/ts branch 3 times, most recently from 64911c4 to f733324 Compare May 22, 2026 22:42

feiyang3cat force-pushed the patch/ts branch 2 times, most recently from 7431f2f to e24f538 Compare June 1, 2026 02:13

feiyang3cat changed the title ~~[don't merge] just for review~~ [don't merge] need review and server PR Jun 1, 2026

feiyang3cat force-pushed the patch/ts branch from e24f538 to 55a4896 Compare June 1, 2026 04:22

feiyang3cat changed the title ~~[don't merge] need review and server PR~~ [don't merge] time skipping sleep: need review and server PR Jun 1, 2026

feiyang3cat force-pushed the patch/ts branch 3 times, most recently from ae2e298 to a95915b Compare June 1, 2026 17:29

feiyang3cat commented Jun 2, 2026

View reviewed changes

Comment thread temporal/api/workflow/v1/message.proto Outdated

GregoryTravis reviewed Jun 2, 2026

View reviewed changes

JLDLaughlin reviewed Jun 2, 2026

View reviewed changes

Comment thread openapi/openapiv2.json Outdated

feiyang3cat force-pushed the patch/ts branch from a95915b to 708cc3a Compare June 5, 2026 19:45

feiyang3cat added 2 commits June 5, 2026 18:08

refactor time skipping config and event

eb6a515

change sleep to fast forward

2e87466

feiyang3cat force-pushed the patch/ts branch from 1592217 to 2e87466 Compare June 6, 2026 01:09

feiyang3cat mentioned this pull request Jun 6, 2026

Ts: api change to fast forward temporalio/temporal#10576

Open

5 tasks

feiyang3cat changed the title ~~[don't merge] time skipping sleep: need review and server PR~~ time skipping fast forward Jun 8, 2026

Sushisource reviewed Jun 8, 2026

View reviewed changes

Update temporal/api/workflow/v1/message.proto

5643734

Co-authored-by: Spencer Judge <spencer@temporal.io>

feiyang3cat force-pushed the patch/ts branch from 480478b to 5643734 Compare June 8, 2026 19:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

time skipping fast forward#786

time skipping fast forward#786
feiyang3cat wants to merge 3 commits into
mainfrom
patch/ts

feiyang3cat commented May 22, 2026 •

edited

Loading

Uh oh!

Uh oh!

GregoryTravis Jun 2, 2026

Uh oh!

feiyang3cat Jun 2, 2026

Uh oh!

GregoryTravis Jun 2, 2026

Uh oh!

feiyang3cat Jun 2, 2026

Uh oh!

feiyang3cat Jun 2, 2026

Uh oh!

Uh oh!

Sushisource Jun 8, 2026

Uh oh!

feiyang3cat Jun 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Sushisource Jun 8, 2026

Uh oh!

feiyang3cat Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	// When true, time skipping has been disabled automatically due to the fast_forward completing.
	// When true, time skipping has been disabled automatically due to a call to fast_forward completing.

Conversation

feiyang3cat commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

feiyang3cat Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feiyang3cat commented May 22, 2026 •

edited

Loading

feiyang3cat Jun 8, 2026 •

edited

Loading