Skip to content

sync vs async matching service #3487

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft
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
30 changes: 25 additions & 5 deletions docs/encyclopedia/temporal-service/temporal-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -152,24 +152,44 @@ Each History Shard maintains the Workflow Execution Event History, Workflow Exec
- Internal Visibility Task Queue: Pushes data to the [Advanced Visibility](/visibility#advanced-visibility) index.

## What is a Matching Service? {#matching-service}

The Matching Service is responsible for hosting user-facing [Task Queues](/task-queue) for Task dispatching.
The Matching Service is one of the four core services that make up the Temporal Server.
The Matching Service is responsible for maintaining the [Task Queues](/task-queue).
It is responsible for matching Workers to Tasks and routing new Tasks to the appropriate queue.
It also works closely with the History Service, which initiates Workflow and Activity Tasks.

<CaptionedImage
src="/diagrams/temporal-matching-service.svg"
title="Matching Service"
/>

It is responsible for matching Workers to Tasks and routing new Tasks to the appropriate queue.
This service can scale internally by having multiple instances.

It talks to the Frontend Service, History Service, and the database.

- It uses grpcPort 7235 to host the service handler.
- It uses port 6935 for membership related communication.

Ports are configurable in the Temporal Service configuration.

### Async and Sync Matching
In Temporal, sync matching and async matching refer to the two different ways that tasks are dispatched to workers in the Temporal system.

When the next step requires a Worker to execute code, the History Service calls the Matching Service, requesting it to add a Task to the appropriate Task Queue.

If there is already a Task scheduled when the Worker begins polling, the Matching Service loads the Task from the database, tells the History Service to mark the Task as Started, and provides it to the Frontend Service so it can be delivered to the Worker.
This is called **normal or asynchronous matching**.

If the History Service asks the Matching Service to add a Task while a Worker happens to be performing a long poll, the Task can be delivered to the Worker immediately.
This optimization, known as **sync matching**, improves performance by eliminating database operations associated with the Task Queue.
In other words, Sync matching (synchronous matching) occurs when a Worker polls for a Task and the Temporal Service can immediately match it with a Task that's ready to be executed, without having to persist the Task to the database first.
This is the more efficient method of Task delivery.


**Why Sync Matching is Important?**
The percentage of Tasks that involve sync matching is often used to evaluate whether an application has enough Workers.
When the number of Workers are in good balance with the number of Tasks, sync matching should account for 90% or more of all requests.
This percentage may naturally vary according to application load; for example, dropping slightly during a burst of activity.
If it remains low for an extended period of time, it can suggest the need to increase the number of Workers.


## What is a Worker Service? {#worker-service}

The Worker Service runs background processing for the replication queue, system Workflows, and (in versions older than 1.5.0) the Kafka visibility processor.
Expand Down