Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

EDU-3430: breakout workflow message passing #3343

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/cli/batch.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The List Filter identifies the Workflow Executions in the Batch Job; the Batch t
There are three types of Batch Jobs:

- Cancel: cancels the Workflow Executions specified by the List Filter.
- Signal: sends a [Signal](/encyclopedia/workflow-message-passing#sending-signals) to the Workflow Executions specified by the List Filter.
- Signal: sends a [Signal](/sending-messages#sending-signals) to the Workflow Executions specified by the List Filter.
- Terminate: terminates the Workflow Executions specified by the List Filter.

Batch operations can affect multiple Workflows simultaneously.
Expand Down
2 changes: 1 addition & 1 deletion docs/cli/operator.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -967,7 +967,7 @@ Use the following options to change this command's behavior.

### list

The `temporal operator search-attribute list` command displays a list of all [Search Attributes](/visibility#search-attribute) that can be used in [Queries](/encyclopedia/workflow-message-passing#sending-queries).
The `temporal operator search-attribute list` command displays a list of all [Search Attributes](/visibility#search-attribute) that can be used in [Queries](/sending-messages#sending-queries).

`temporal workflow list --query`.

Expand Down
6 changes: 3 additions & 3 deletions docs/cli/workflow.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -372,7 +372,7 @@ Use the following command options to change the information returned by this com

## query

The `temporal workflow query` command sends a [Query](/encyclopedia/workflow-message-passing#sending-queries) to a [Workflow Execution](/workflows#workflow-execution).
The `temporal workflow query` command sends a [Query](/sending-messages#sending-queries) to a [Workflow Execution](/workflows#workflow-execution).

Queries can retrieve all or part of the Workflow state within given parameters.
Queries can also be used on completed [Workflows](/workflows#workflow-execution).
Expand Down Expand Up @@ -597,7 +597,7 @@ Use the following options to change the behavior of this command.

## signal

The `temporal workflow signal` command is used to send a [Signal](/encyclopedia/workflow-message-passing#sending-signals) to a [Workflow Execution](/workflows#workflow-execution) by [Workflow Id](/workflows#workflow-id) or [List Filter](/visibility#list-filter).
The `temporal workflow signal` command is used to send a [Signal](/sending-messages#sending-signals) to a [Workflow Execution](/workflows#workflow-execution) by [Workflow Id](/workflows#workflow-id) or [List Filter](/visibility#list-filter).

Use the following options to change the command's behavior.

Expand Down Expand Up @@ -647,7 +647,7 @@ Use the following options to change the command's behavior.

## stack

The `temporal workflow stack` command queries a [Workflow Execution](/workflows#workflow-execution) with `--stack-trace` as the [Query](/encyclopedia/workflow-message-passing#stack-trace-query) type.
The `temporal workflow stack` command queries a [Workflow Execution](/workflows#workflow-execution) with `--stack-trace` as the [Query](/sending-messages#stack-trace-query) type.
Returning the call stack of all the threads owned by a Workflow Execution can be great for troubleshooting in production.

Use the following options to change the command's behavior.
Expand Down
20 changes: 10 additions & 10 deletions docs/develop/dotnet/message-passing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Follow these guidelines when writing your message handlers:

### Query handlers {#queries}

A [Query](/encyclopedia/workflow-message-passing#sending-queries) is a synchronous operation that retrieves state from a Workflow Execution.
A [Query](/sending-messages#sending-queries) is a synchronous operation that retrieves state from a Workflow Execution.
Define as a method:

```csharp
Expand Down Expand Up @@ -101,7 +101,7 @@ public class GreetingWorkflow

### Signal handlers {#signals}

A [Signal](/encyclopedia/workflow-message-passing#sending-signals) is an asynchronous message sent to a running Workflow Execution to change its state and control its flow:
A [Signal](/sending-messages#sending-signals) is an asynchronous message sent to a running Workflow Execution to change its state and control its flow:

```csharp
[Workflow]
Expand Down Expand Up @@ -133,7 +133,7 @@ public class GreetingWorkflow

### Update handlers and validators {#updates}

An [Update](/encyclopedia/workflow-message-passing#sending-updates) is a trackable synchronous request sent to a running Workflow Execution.
An [Update](/sending-messages#sending-updates) is a trackable synchronous request sent to a running Workflow Execution.
It can change the Workflow state, control its flow, and return a result.
The sender must wait until the Worker accepts or rejects the Update.
The sender may wait further to receive a returned value or an exception if something goes wrong:
Expand Down Expand Up @@ -192,7 +192,7 @@ public class GreetingWorkflow
The caller receives an "Update failed" error.

- Use [`Workflow.CurrentUpdateInfo`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html#Temporalio_Workflows_Workflow_CurrentUpdateInfo) to obtain information about the current Update.
This includes the Update ID, which can be useful for deduplication when using Continue-As-New: see [Ensuring your messages are processed exactly once](/encyclopedia/workflow-message-passing#exactly-once-message-processing).
This includes the Update ID, which can be useful for deduplication when using Continue-As-New: see [Ensuring your messages are processed exactly once](/handling-messages#exactly-once-message-processing).
- Update (and Signal) handlers can be asynchronous and blocking.
This allows you to use Activities, Child Workflows, durable [`Workflow.DelayAsync`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html?#Temporalio_Workflows_Workflow_DelayAsync_System_Int32_System_Nullable_System_Threading_CancellationToken__) Timers, [`Workflow.WaitConditionAsync`](https://dotnet.temporal.io/api/Temporalio.Workflows.Workflow.html?#Temporalio_Workflows_Workflow_WaitConditionAsync_System_Func_System_Boolean__System_Int32_System_Nullable_System_Threading_CancellationToken__) conditions, and more.
See [Async handlers](#async-handlers) and [Workflow message passing](/encyclopedia/workflow-message-passing) for guidelines on safely using async Update and Signal handlers.
Expand Down Expand Up @@ -366,7 +366,7 @@ It doesn't apply to pure read operations, like Queries or Update Validators.

:::tip

For additional information, see [Inject work into the main Workflow](/encyclopedia/workflow-message-passing#injecting-work-into-main-workflow) and [Ensuring your messages are processed exactly once](/encyclopedia/workflow-message-passing#exactly-once-message-processing).
For additional information, see [Inject work into the main Workflow](/handling-messages#injecting-work-into-main-workflow) and [Ensuring your messages are processed exactly once](/handling-messages#exactly-once-message-processing).

:::

Expand Down Expand Up @@ -519,11 +519,11 @@ public async Task MyUpdateAsync()
// ...
```

See [Finishing handlers before the Workflow completes](/encyclopedia/workflow-message-passing#finishing-message-handlers) for more information.
See [Finishing handlers before the Workflow completes](/handling-messages#finishing-message-handlers) for more information.

### Use `[WorkflowInit]` to operate on Workflow input before any handler executes

The `[WorkflowInit]` attribute gives message handlers access to [Workflow input](/encyclopedia/workflow-message-passing#workflow-initializers).
The `[WorkflowInit]` attribute gives message handlers access to [Workflow input](/handling-messages#workflow-initializers).
When you use the `[WorkflowInit]` attribute on your constructor, you give the constructor the same Workflow parameters as your `[WorkflowRun]` method.
The SDK will then ensure that your constructor receives the Workflow input arguments that the [Client sent](/develop/dotnet/temporal-client#start-workflow).
The Workflow input arguments are also passed to your `[WorkflowRun]` method -- that always happens, whether or not you use the `[WorkflowInit]` attribute.
Expand Down Expand Up @@ -568,7 +568,7 @@ public class WorkflowInitWorkflow
### Use locks to prevent concurrent handler execution {#control-handler-concurrency}

Concurrent processes can interact in unpredictable ways.
Incorrectly written [concurrent message-passing](/encyclopedia/workflow-message-passing#message-handler-concurrency) code may not work correctly when multiple handler instances run simultaneously.
Incorrectly written [concurrent message-passing](/handling-messages#message-handler-concurrency) code may not work correctly when multiple handler instances run simultaneously.
Here's an example of a pathological case:

```csharp
Expand Down Expand Up @@ -639,7 +639,7 @@ When sending a Signal, Update, or Query to a Workflow, your Client might encount
- **The Workflow does not exist**:
You'll receive a [`Temporalio.Exceptions.RpcException`](https://dotnet.temporal.io/api/Temporalio.Exceptions.RpcException.html) exception whose `Code` property is [`RpcException.StatusCode`](https://dotnet.temporal.io/api/Temporalio.Exceptions.RpcException.StatusCode.html) with a status of `NotFound`.

See [Exceptions in message handlers](/encyclopedia/workflow-message-passing#exceptions) for a non–.NET-specific discussion of this topic.
See [Exceptions in message handlers](/handling-messages#exceptions) for a non–.NET-specific discussion of this topic.

### Problems when sending a Signal {#signal-problems}

Expand Down Expand Up @@ -687,7 +687,7 @@ When working with Updates, you may encounter these errors:

- The Workflow was canceled or failed.

- The Workflow completed normally or continued-as-new and the Workflow author did not [wait for handlers to be finished](/encyclopedia/workflow-message-passing#finishing-message-handlers).
- The Workflow completed normally or continued-as-new and the Workflow author did not [wait for handlers to be finished](/handling-messages#finishing-message-handlers).

### Problems when sending a Query {#query-problems}

Expand Down
2 changes: 1 addition & 1 deletion docs/develop/go/debugging.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -304,7 +304,7 @@ func (s *UnitTestSuite) Test_ProgressWorkflow() {

:::note

`RegisterDelayedCallback` can also be used to send [Signals](/encyclopedia/workflow-message-passing#sending-signals).
`RegisterDelayedCallback` can also be used to send [Signals](/sending-messages#sending-signals).
When using "Signal-With-Start", set the delay to `0`.
:::

Expand Down
22 changes: 11 additions & 11 deletions docs/develop/go/message-passing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Follow these guidelines when writing message handlers:

### Query handlers {#queries}

A [Query](/encyclopedia/workflow-message-passing#sending-queries) is a synchronous operation that retrieves state from a Workflow Execution:
A [Query](/sending-messages#sending-queries) is a synchronous operation that retrieves state from a Workflow Execution:

```go
type Language string
Expand Down Expand Up @@ -87,7 +87,7 @@ func GreetingWorkflow(ctx workflow.Context) (string, error) {

### Signal Channels {#signals}

A [Signal](/encyclopedia/workflow-message-passing#sending-signals) is an asynchronous message sent to a running Workflow Execution to change its state and control its flow.
A [Signal](/sending-messages#sending-signals) is an asynchronous message sent to a running Workflow Execution to change its state and control its flow.
Handle Signal messages by receiving them from their channel:

```go
Expand Down Expand Up @@ -154,7 +154,7 @@ for {

### Update handlers and validators {#updates}

An [Update](/encyclopedia/workflow-message-passing#sending-updates) is a trackable synchronous request sent to a running Workflow Execution.
An [Update](/sending-messages#sending-updates) is a trackable synchronous request sent to a running Workflow Execution.
It can change the Workflow state, control its flow, and return a result.
The sender must wait until the Worker accepts or rejects the Update.
The sender may wait further to receive a returned value or an exception if something goes wrong:
Expand Down Expand Up @@ -206,7 +206,7 @@ func GreetingWorkflow(ctx workflow.Context) error {
The caller receives an "Update failed" error.

- Use [`workflow.GetCurrentUpdateInfo`](https://pkg.go.dev/go.temporal.io/sdk/workflow#GetCurrentUpdateInfo) to obtain information about the current Update.
This includes the Update ID, which can be useful for deduplication when using Continue-As-New: see [Ensuring your messages are processed exactly once](/encyclopedia/workflow-message-passing#exactly-once-message-processing).
This includes the Update ID, which can be useful for deduplication when using Continue-As-New: see [Ensuring your messages are processed exactly once](/handling-messages#exactly-once-message-processing).
- Update handlers can use Activities, Child Workflows, durable [workflow.Sleep](https://pkg.go.dev/go.temporal.io/sdk/workflow#Sleep) Timers, [`workflow.Await`](https://pkg.go.dev/go.temporal.io/sdk/workflow#Await) conditions, and more.
See [Blocking handlers](#blocking-handlers) and [Workflow message passing](/encyclopedia/workflow-message-passing) for safe usage guidelines.
- Delay calling [`workflow.SetUpdateHandler`](https://pkg.go.dev/go.temporal.io/sdk/workflow#SetUpdateHandler) until the Workflow initialization needed by Update handlers is finished.
Expand Down Expand Up @@ -385,7 +385,7 @@ Minimum Temporal Server version [Temporal Server version 1.26](https://github.co

:::

[Update-with-Start](/encyclopedia/workflow-message-passing#update-with-start) lets you
[Update-with-Start](/sending-messages#update-with-start) lets you
[send an Update](/develop/go/message-passing#send-update-from-client) that checks whether an already-running Workflow with that ID exists:

- If the Workflow exists, the Update is processed.
Expand Down Expand Up @@ -464,7 +464,7 @@ It doesn't apply to pure read operations, like Queries or Update Validators.

:::tip

For additional information, see [Inject work into the main Workflow](/encyclopedia/workflow-message-passing#injecting-work-into-main-workflow), [Ensuring your messages are processed exactly once](/encyclopedia/workflow-message-passing#exactly-once-message-processing), and [this sample](https://github.com/temporalio/samples-typescript/blob/main/pdates-and-signals/safe-message-handlers/README.md) demonstrating safe blocking message handling.
For additional information, see [Inject work into the main Workflow](/handling-messages#injecting-work-into-main-workflow), [Ensuring your messages are processed exactly once](/handling-messages#exactly-once-message-processing), and [this sample](https://github.com/temporalio/samples-typescript/blob/main/pdates-and-signals/safe-message-handlers/README.md) demonstrating safe blocking message handling.

:::

Expand Down Expand Up @@ -557,14 +557,14 @@ err = workflow.SetUpdateHandlerWithOptions(ctx, UpdateHandlerName, UpdateFunc, w
})
```

See [Finishing handlers before the Workflow completes](/encyclopedia/workflow-message-passing#finishing-message-handlers) for more information.
See [Finishing handlers before the Workflow completes](/handling-messages#finishing-message-handlers) for more information.

#### Use `workflow.Mutex` to prevent concurrent handler execution {#control-handler-concurrency}

See [Message handler concurrency](/encyclopedia/workflow-message-passing#message-handler-concurrency).
See [Message handler concurrency](/handling-messages#message-handler-concurrency).

Concurrent processes can interact in unpredictable ways.
Incorrectly written [concurrent message-passing](/encyclopedia/workflow-message-passing#message-handler-concurrency) code may not work correctly when multiple handler instances run simultaneously.
Incorrectly written [concurrent message-passing](/handling-messages#message-handler-concurrency) code may not work correctly when multiple handler instances run simultaneously.
Here's an example of a pathological case:

```go
Expand Down Expand Up @@ -626,7 +626,7 @@ func YourWorkflowDefinition(ctx workflow.Context, param YourWorkflowParam) error

## Troubleshooting

See [Exceptions in message handlers](/encyclopedia/workflow-message-passing#exceptions) for a non–Go-specific discussion of this topic.
See [Exceptions in message handlers](/handling-messages#exceptions) for a non–Go-specific discussion of this topic.

When sending a Signal, Update, or Query to a Workflow, your Client might encounter the following errors:

Expand Down Expand Up @@ -667,7 +667,7 @@ If an issue occurs during the handler execution by the Worker, the Client may re

- The Workflow was canceled or failed.

- The Workflow completed normally or continued-as-new and the Workflow author did not [wait for handlers to be finished](/encyclopedia/workflow-message-passing#finishing-message-handlers).
- The Workflow completed normally or continued-as-new and the Workflow author did not [wait for handlers to be finished](/handling-messages#finishing-message-handlers).

### Problems when sending a Query

Expand Down
2 changes: 1 addition & 1 deletion docs/develop/go/test-suites.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -373,7 +373,7 @@ func (s *UnitTestSuite) Test_ProgressWorkflow() {

:::note

`RegisterDelayedCallback` can also be used to send [Signals](/encyclopedia/workflow-message-passing#sending-signals).
`RegisterDelayedCallback` can also be used to send [Signals](/sending-messages#sending-signals).
When using "Signal-With-Start", set the delay to `0`.
:::

Expand Down
Loading