From e447a902ea9db9894aee08f4a1fe9019861f1f31 Mon Sep 17 00:00:00 2001 From: Maxim Fateev Date: Tue, 30 Mar 2021 21:38:45 -0700 Subject: [PATCH 1/3] Fixed timeout property documentation --- .../io/temporal/activity/ActivityOptions.java | 40 ++++++++++++++----- .../io/temporal/client/WorkflowOptions.java | 9 ++++- 2 files changed, 38 insertions(+), 11 deletions(-) diff --git a/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java b/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java index 9cbc260af8..73b579f0ea 100644 --- a/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java +++ b/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java @@ -83,10 +83,14 @@ private Builder(ActivityOptions options) { } /** - * Overall timeout workflow is willing to wait for activity to complete. It includes time in a - * task queue (use {@link #setScheduleToStartTimeout(Duration)} to limit it) plus activity - * execution time (use {@link #setStartToCloseTimeout(Duration)} to limit it). Either this - * option or both schedule to start and start to close are required. + * Overall timeout workflow is willing to wait for activity to complete. + * + *

ScheduleToCloseTimeout limits total time of the activity execution including retries (use + * StartToCloseTimeout to limit a time of a single attempt). + * + *

Either this option or StartToClose are required. + * + *

Defaults to unlimited. */ public Builder setScheduleToCloseTimeout(Duration scheduleToCloseTimeout) { this.scheduleToCloseTimeout = scheduleToCloseTimeout; @@ -94,8 +98,15 @@ public Builder setScheduleToCloseTimeout(Duration scheduleToCloseTimeout) { } /** - * Time activity can stay in task queue before it is picked up by a worker. If schedule to close - * is not provided then both this and start to close are required. + * Time activity can stay in task queue before it is picked up by a worker. + * + *

Do not specify this timeout unless using host specific task queues for activity task + * routing. + * + *

ScheduleToStartTimeout is always non-retryable. Retrying after this timeout doesn't make + * sense as it would just put the activity task back into the same task queue. + * + *

Defaults to unlimited. */ public Builder setScheduleToStartTimeout(Duration scheduleToStartTimeout) { this.scheduleToStartTimeout = scheduleToStartTimeout; @@ -103,8 +114,17 @@ public Builder setScheduleToStartTimeout(Duration scheduleToStartTimeout) { } /** - * Maximum activity execution time after it was sent to a worker. If schedule to close is not - * provided then both this and schedule to start are required. + * Maximum time of a single activity execution attempt. + * + *

Note that Temporal doesn't detect worker process failures directly. It relies on this + * timeout to detect an activity that didn't complete on time. So this timeout should be as + * short as the longest possible execution of the activity body. Potentially long running + * activities must specify HeartbeatTimeout and call {@link + * ActivityExecutionContext#heartbeat(Object)} periodically for timely failure detection. + * + *

If schedule to close is not provided then this timeout is required. + * + *

Defaults to ScheduleToCloseTimeout. */ public Builder setStartToCloseTimeout(Duration startToCloseTimeout) { this.startToCloseTimeout = startToCloseTimeout; @@ -112,8 +132,8 @@ public Builder setStartToCloseTimeout(Duration startToCloseTimeout) { } /** - * Heartbeat interval. Activity must heartbeat before this interval passes after a last - * heartbeat or activity start. + * Heartbeat interval. Activity must call {@link ActivityExecutionContext#heartbeat(Object)} + * before this interval passes after a last heartbeat or activity start. */ public Builder setHeartbeatTimeout(Duration heartbeatTimeoutSeconds) { this.heartbeatTimeout = heartbeatTimeoutSeconds; diff --git a/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java b/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java index 8fda2f69ec..5bbfc34354 100644 --- a/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java +++ b/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java @@ -168,7 +168,14 @@ public Builder setWorkflowExecutionTimeout(Duration workflowExecutionTimeout) { return this; } - /** Maximum execution time of a single workflow task. Default is 10 seconds. */ + /** + * Maximum execution time of a single workflow task. In the majority of cases there is no need + * to change this timeout. Note that this timeout is not related to the overall workflow + * duration in any way. It defines for how long workflow can get blocked in case of a workflow + * worker crash. + * + *

Default is 10 seconds. Maximum value allowed by the service is 1 minute. + */ public Builder setWorkflowTaskTimeout(Duration workflowTaskTimeout) { this.workflowTaskTimeout = workflowTaskTimeout; return this; From 6ab43e6f7dacd9ae574f003e4ec10b147a3945ba Mon Sep 17 00:00:00 2001 From: Maxim Fateev Date: Wed, 31 Mar 2021 10:53:02 -0700 Subject: [PATCH 2/3] PR feedback --- .../io/temporal/activity/ActivityOptions.java | 16 ++++++++-------- .../java/io/temporal/client/WorkflowOptions.java | 10 +++++----- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java b/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java index 73b579f0ea..7bb0b0630f 100644 --- a/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java +++ b/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java @@ -114,17 +114,17 @@ public Builder setScheduleToStartTimeout(Duration scheduleToStartTimeout) { } /** - * Maximum time of a single activity execution attempt. + * Maximum time of a single Activity execution attempt. * - *

Note that Temporal doesn't detect worker process failures directly. It relies on this - * timeout to detect an activity that didn't complete on time. So this timeout should be as - * short as the longest possible execution of the activity body. Potentially long running - * activities must specify HeartbeatTimeout and call {@link + *

Note that the Temporal Server doesn't detect Worker process failures directly. It relies + * on this timeout to detect that an Activity that didn't complete on time. So this timeout + * should be as short as the longest possible execution of the Activity body. Potentially long + * running Activities must specify HeartbeatTimeout and call {@link * ActivityExecutionContext#heartbeat(Object)} periodically for timely failure detection. * - *

If schedule to close is not provided then this timeout is required. + *

If ScheduleToClose is not provided then this timeout is required. * - *

Defaults to ScheduleToCloseTimeout. + *

Defaults to the ScheduleToCloseTimeout value. */ public Builder setStartToCloseTimeout(Duration startToCloseTimeout) { this.startToCloseTimeout = startToCloseTimeout; @@ -133,7 +133,7 @@ public Builder setStartToCloseTimeout(Duration startToCloseTimeout) { /** * Heartbeat interval. Activity must call {@link ActivityExecutionContext#heartbeat(Object)} - * before this interval passes after a last heartbeat or activity start. + * before this interval passes after the last heartbeat or the Activity starts. */ public Builder setHeartbeatTimeout(Duration heartbeatTimeoutSeconds) { this.heartbeatTimeout = heartbeatTimeoutSeconds; diff --git a/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java b/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java index 5bbfc34354..9bb573ab53 100644 --- a/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java +++ b/temporal-sdk/src/main/java/io/temporal/client/WorkflowOptions.java @@ -169,12 +169,12 @@ public Builder setWorkflowExecutionTimeout(Duration workflowExecutionTimeout) { } /** - * Maximum execution time of a single workflow task. In the majority of cases there is no need - * to change this timeout. Note that this timeout is not related to the overall workflow - * duration in any way. It defines for how long workflow can get blocked in case of a workflow - * worker crash. + * Maximum execution time of a single Workflow Task. In the majority of cases there is no need + * to change this timeout. Note that this timeout is not related to the overall Workflow + * duration in any way. It defines for how long the Workflow can get blocked in the case of a + * Workflow Worker crash. * - *

Default is 10 seconds. Maximum value allowed by the service is 1 minute. + *

Default is 10 seconds. Maximum value allowed by the Temporal Server is 1 minute. */ public Builder setWorkflowTaskTimeout(Duration workflowTaskTimeout) { this.workflowTaskTimeout = workflowTaskTimeout; From 89096d998d700e0cd7ea7dc7736887e9944f944f Mon Sep 17 00:00:00 2001 From: Maxim Fateev Date: Mon, 5 Apr 2021 18:44:34 -0700 Subject: [PATCH 3/3] more PR comments --- .../io/temporal/activity/ActivityOptions.java | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java b/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java index 7bb0b0630f..fe1ea95b88 100644 --- a/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java +++ b/temporal-sdk/src/main/java/io/temporal/activity/ActivityOptions.java @@ -83,12 +83,12 @@ private Builder(ActivityOptions options) { } /** - * Overall timeout workflow is willing to wait for activity to complete. + * Total time that a workflow is willing to wait for Activity to complete. * - *

ScheduleToCloseTimeout limits total time of the activity execution including retries (use - * StartToCloseTimeout to limit a time of a single attempt). + *

ScheduleToCloseTimeout limits the total time of an Activity's execution including retries + * (use StartToCloseTimeout to limit the time of a single attempt). * - *

Either this option or StartToClose are required. + *

Either this option or StartToClose is required. * *

Defaults to unlimited. */ @@ -98,13 +98,12 @@ public Builder setScheduleToCloseTimeout(Duration scheduleToCloseTimeout) { } /** - * Time activity can stay in task queue before it is picked up by a worker. - * - *

Do not specify this timeout unless using host specific task queues for activity task - * routing. + * Time that the Activity Task can stay in the Task Queue before it is picked up by a Worker. Do + * not specify this timeout unless using host specific Task Queues for Activity Tasks are being + * used for routing. * *

ScheduleToStartTimeout is always non-retryable. Retrying after this timeout doesn't make - * sense as it would just put the activity task back into the same task queue. + * sense as it would just put the Activity Task back into the same Task Queue. * *

Defaults to unlimited. */