You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refactor Priority & Fairness walkthrough into tabbed demo
- Replace inline MDX with a tabbed PriorityFairnessWalkthrough component (Overview, Try It, How It Works, SDK Examples)
- Move Interactive Demos sidebar section after glossary; restore activity-retry-simulator to standalone position in Develop
- Remove unicode symbols from simulator buttons
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
title: Task Queue Priority and Fairness — Interactive Demo
4
-
sidebar_label: Priority and Fairness (Interactive)
5
-
description: Interactively explore how Task Queue Priority and Fairness control dispatch order. Load a preset scenario, step through dispatches, and see exactly which task gets picked next — and why.
6
-
toc_max_heading_level: 3
3
+
title: Task Queue Priority and Fairness - Interactive Walkthrough
4
+
sidebar_label: Priority and Fairness
5
+
description: Interactively explore how Task Queue Priority and Fairness control dispatch order. Step through scenarios, see which task gets picked next and why, then grab the SDK code.
When multiple workloads compete for Workers, Task Queue Priority determines which tasks get picked first, while Task Queue Fairness ensures no single workload can crowd out the rest.
Every task carries a `priorityKey` from `1` (critical) to `5` (batch), with `3` as the default. When a Worker polls, it always picks the lowest-numbered task first regardless of arrival time. This lets you share a single Worker pool across very different workloads and guarantee that time-sensitive work never waits behind low-urgency jobs.
Without Fairness, tasks at the same priority dispatch strictly FIFO, so a backlog-heavy tenant can block everyone else at that level indefinitely. Fairness groups tasks by `fairnessKey` and dispatches proportionally by `fairnessWeight`. A key with weight `5` gets roughly 5x more dispatches than a key with weight `1`, but no key is ever completely locked out.
48
-
49
-
</div>
50
-
51
-
</div>
52
-
53
-
Use both together when you need SLA ordering across workload types and fair distribution across tenants within each tier.
Load a preset or build your own queue. Use **Step ->** to dispatch one task at a time and watch which task gets picked next, or **Dispatch All** to see the full order at once.
66
-
67
-
<PriorityFairnessSimulator />
68
-
69
-
---
70
-
71
-
## How it works
72
-
73
-
When a Worker polls for the next task, Temporal applies two rules in sequence:
74
-
75
-
1.**Priority first** - the task with the lowest `priorityKey` wins. If there are tasks at priority `1`, none of the `2`s will dispatch until all `1`s are gone.
76
-
2.**Fairness within a tier** - when multiple tasks share the same priority level but carry different `fairnessKey` values, Temporal tracks how many tasks each key has received relative to its weight and dispatches from the key that is furthest behind its expected share.
77
-
78
-
If no `fairnessKey` is set, tasks within a priority level dispatch in FIFO order.
79
-
80
-
### When to use Priority vs Fairness
81
-
82
-
| Scenario | Use |
83
-
|---|---|
84
-
| Payments should never wait behind inventory syncs |**Priority**|
85
-
| Premium users shouldn't be blocked by a single large tenant |**Fairness**|
86
-
| SLAs differ across customer tiers and tenants vary in volume |**Both**|
87
-
88
-
---
89
-
90
-
## Setup
91
-
92
-
Priority and Fairness are enabled automatically - no configuration required. Just set `priorityKey`, `fairnessKey`, or both when starting Workflows or Activities.
93
-
94
-
For self-hosted Temporal, set `matching.useNewMatcher` to `true` in dynamic config. To enable Fairness, also set `matching.enableFairness: true`.
body: 'When a Worker is ready, it sends a poll request to the Task Queue. Temporal evaluates all waiting tasks and applies Priority and Fairness rules to decide which one to return.',
8
+
},
9
+
{
10
+
title: 'Priority tier is selected first',
11
+
body: 'Temporal finds the lowest priorityKey among all waiting tasks. Every task at priority 1 will be dispatched before any task at priority 2 moves, and so on. Tasks at the same level compete under Fairness rules.',
12
+
},
13
+
{
14
+
title: 'Fairness distributes capacity within the tier',
15
+
body: 'Within a priority tier, Temporal tracks how many tasks each fairnessKey has received relative to its fairnessWeight. The key that is furthest behind its expected share gets the next dispatch. This prevents any single tenant from consuming disproportionate capacity, even if they have a deep backlog.',
16
+
},
17
+
{
18
+
title: 'No fairnessKey means strict FIFO within the tier',
19
+
body: 'If you set priorityKey but omit fairnessKey, tasks at the same priority level are dispatched in arrival order. Fairness only applies when at least one task in the tier carries a fairnessKey.',
20
+
},
21
+
{
22
+
title: 'Priority and Fairness are per Task Queue',
23
+
body: 'The rules apply independently per Task Queue. Workers on the same Task Queue share the same dispatch ordering. Workers on separate Task Queues are unaffected by each other.',
24
+
},
25
+
];
26
+
27
+
constWHEN_ROWS=[
28
+
{scenario: 'Payments should never wait behind inventory syncs',use: 'Priority',badge: 'badgePriority'},
29
+
{scenario: 'Premium users should not be blocked by a large free-tier tenant',use: 'Fairness',badge: 'badgeFairness'},
30
+
{scenario: 'SLAs differ across customer tiers and tenants vary in volume',use: 'Both',badge: 'badgeBoth'},
31
+
];
32
+
33
+
exportdefaultfunctionHowItWorks({ onNext }){
34
+
return(
35
+
<divclassName={styles.section}>
36
+
<pclassName={styles.lead}>
37
+
When a Worker polls for the next task, Temporal applies two rules in sequence: Priority
38
+
determines which tier goes first, and Fairness distributes capacity among tenants within
39
+
each tier.
40
+
</p>
41
+
42
+
<divclassName={styles.stepList}>
43
+
{STEPS.map((step,i)=>(
44
+
<divkey={i}className={styles.step}>
45
+
<divclassName={styles.stepNum}>{i+1}</div>
46
+
<divclassName={styles.stepContent}>
47
+
<pclassName={styles.stepTitle}>{step.title}</p>
48
+
<pclassName={styles.stepBody}>{step.body}</p>
49
+
</div>
50
+
</div>
51
+
))}
52
+
</div>
53
+
54
+
<h3className={styles.sectionHeading}>When to use Priority vs Fairness</h3>
0 commit comments