Skip to content

Commit 6df7eb2

Browse files
ericallamericallam
authored
docs: new release concurrency system and run statuses (#2287)
* WIP new docs for the new release concurrency and run statuses * Fixed status description * Add the beta.24 changelog entry
1 parent 36ced50 commit 6df7eb2

File tree

1 file changed

+85
-25
lines changed

1 file changed

+85
-25
lines changed

‎docs/upgrade-to-v4.mdx

Lines changed: 85 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -749,40 +749,50 @@ await myTask.trigger({ foo: "bar" }); // Will use the queue defined on the task
749749
await myTask2.trigger({ foo: "bar" }); // Will use the queue defined on the task
750750
```
751751

752-
### Releasing concurrency on waits
752+
### Concurrency changes
753753

754-
We've changed the default behavior on how concurrency is released when a run is paused or resumed because of a wait. Previously, the concurrency would be released immediately when the run was first paused, no matter the settings on the queue.
754+
We've changed a few things around how concurrency is managed at the environment and queue level:
755755

756-
Now we will no longer release concurrency on a queue that has a specified `concurrencyLimit` when a run is paused. You can go back to the previous behavior by setting the `releaseConcurrencyOnWaitpoint` option to `true` on the queue:
756+
- Environment concurrency limits are now "burstable" above the base concurrency limit. The default burst factor is 2.0, meaning that the environment concurrency limit can be up to 2x the base concurrency limit. So if your base concurrency limit is 10, the environment concurrency limit can be up to 20.
757+
- Each individual queue has a maximum concurrency limit of the environment base concurrency limit, NOT the burstable limit. So if your base concurrency limit is 10, the queue concurrency limit can be up to 10. This means if you don't set the queue concurrency limit, it will default to the environment base concurrency limit.
758+
- The only time we "release" concurrency is when a run is checkpointed. This means that if you have a run that is waiting on a waitpoint, and the run is checkpointed, the concurrency will be released back into the queue, allowing other runs to execute/resume. We release the concurrency back to the queue and the environment.
757759

758-
```ts
759-
const myQueue = queue({
760-
name: "my-queue",
761-
concurrencyLimit: 10,
762-
releaseConcurrencyOnWaitpoint: true,
763-
});
764-
```
760+
This means that if you have a queue with a `concurrencyLimit` of 1, you can only have exactly 1 run executing at a time, but you may have more than 1 run in the `WAITING` state that belongs to that queue. Runs are only transitioned to the `WAITING` state when they are waiting on a waitpoint and have been checkpointed.
765761

766-
You can also now control whether concurrency is released when performing a wait:
762+
### New Run Statuses
767763

768-
```ts
769-
// This will prevent the run from being released back into the queue when the wait starts
770-
await wait.for({ seconds: 10, releaseConcurrency: false });
771-
```
764+
We've done some work cleaning up the run statuses. The new statuses are:
772765

773-
The new default behavior allows you to ensure that you can control the number of executing & waiting runs on a queue, and guarantee runs will resume once they are meant to be resumed.
766+
- `PENDING_VERSION`: Task is waiting for a version update because it cannot execute without additional information (task, queue, etc.).
767+
- `QUEUED`: Task is waiting to be executed by a worker.
768+
- `DEQUEUED`: Task has been dequeued and is being sent to a worker to start executing.
769+
- `EXECUTING`: Task is currently being executed by a worker.
770+
- `WAITING`: Task has been paused by the system, and will be resumed by the system.
771+
- `COMPLETED`: Task has been completed successfully.
772+
- `CANCELED`: Task has been canceled by the user.
773+
- `FAILED`: Task has failed to complete, due to an error in the task code.
774+
- `CRASHED`: Task has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage.
775+
- `SYSTEM_FAILURE`: Task has failed to complete, due to an error in the system
776+
- `DELAYED`: Task has been scheduled to run at a specific time.
777+
- `EXPIRED`: Task has expired and won't be executed,
778+
- `TIMED_OUT`: Task has reached its maxDuration and has been stopped.
774779

775-
<Note>
776-
If you do choose to release concurrency on waits, be aware that it's possible a resume is delayed
777-
if the concurrency that was released is not available at the time the wait completes. In this
778-
case, the run will go back into the queue and will resume once concurrency becomes available.
779-
</Note>
780+
We've removed the following statuses:
780781

781-
This new behavior effects all the wait functions:
782+
- `WAITING_FOR_DEPLOY`: This is no longer used, and is replaced by `PENDING_VERSION`
783+
- `FROZEN`: This is no longer used, and is replaced by `WAITING`
784+
- `INTERRUPTED`: This is no longer used
785+
- `REATTEMPTING`: This is no longer used, and is replaced by `EXECUTING`
782786

783-
- Wait for duration (e.g. `wait.for({ seconds: 10 })`)
784-
- Wait for a child task to complete (e.g. `myTask.triggerAndWait()`, `myTask.batchTriggerAndWait([...])`)
785-
- Wait for a token to complete (e.g. `wait.forToken(tokenId)`)
787+
We've also added "boolean" helpers to runs returned via the API and from Realtime:
788+
789+
- `isQueued`: Returns true when the status is `QUEUED`, `PENDING_VERSION`, or `DELAYED`
790+
- `isExecuting`: Returns true when the status is `EXECUTING`, `DEQUEUED`. These count against your concurrency limits.
791+
- `isWaiting`: Returns true when the status is `WAITING`. These do not count against your concurrency limits.
792+
- `isCompleted`: Returns true when the status is any of the completed statuses.
793+
- `isCanceled`: Returns true when the status is `CANCELED`
794+
- `isFailed`: Returns true when the status is any of the failed statuses.
795+
- `isSuccess`: Returns true when the status is `COMPLETED`
786796

787797
### Lifecycle hooks
788798

@@ -1115,3 +1125,53 @@ We recommend enabling this option and testing in a staging or preview environmen
11151125
- Fail fast in CI when running deploy with missing `TRIGGER_ACCESS_TOKEN` and add useful error message with link to docs ([#2258](https://github.com/triggerdotdev/trigger.dev/pull/2258))
11161126

11171127
</Update>
1128+
1129+
<Update label="July 22, 2025" description="v4.0.0-beta.24">
1130+
[Release
1131+
v4.0.0-beta.24](https://github.com/triggerdotdev/trigger.dev/releases/tag/trigger.dev%404.0.0-v4-beta.24).
1132+
1133+
- Removes the `releaseConcurrencyOnWaitpoint` option on queues and the `releaseConcurrency` option on various wait functions. Replaced with the following default behavior: ([#2284](https://github.com/triggerdotdev/trigger.dev/pull/2284))
1134+
1135+
- Concurrency is never released when a run is first blocked via a waitpoint, at either the env or queue level.
1136+
- Concurrency is always released when a run is checkpointed and shutdown, at both the env and queue level.
1137+
1138+
Additionally, environment concurrency limits now have a new "Burst Factor", defaulting to 2.0x. The "Burst Factor" allows the environment-wide concurrency limit to be higher than any individual queue's concurrency limit. For example, if you have an environment concurrency limit of 100, and a Burst Factor of 2.0x, then you can execute up to 200 runs concurrently, but any one task/queue can still only execute 100 runs concurrently.
1139+
1140+
We've done some work cleaning up the run statuses. The new statuses are:
1141+
1142+
- `PENDING_VERSION`: Task is waiting for a version update because it cannot execute without additional information (task, queue, etc.)
1143+
- `QUEUED`: Task is waiting to be executed by a worker
1144+
- `DEQUEUED`: Task has been dequeued and is being sent to a worker to start executing.
1145+
- `EXECUTING`: Task is currently being executed by a worker
1146+
- `WAITING`: Task has been paused by the system, and will be resumed by the system
1147+
- `COMPLETED`: Task has been completed successfully
1148+
- `CANCELED`: Task has been canceled by the user
1149+
- `FAILED`: Task has failed to complete, due to an error in the system
1150+
- `CRASHED`: Task has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage
1151+
- `SYSTEM_FAILURE`: Task has failed to complete, due to an error in the system
1152+
- `DELAYED`: Task has been scheduled to run at a specific time
1153+
- `EXPIRED`: Task has expired and won't be executed
1154+
- `TIMED_OUT`: Task has reached it's maxDuration and has been stopped
1155+
1156+
We've removed the following statuses:
1157+
1158+
- `WAITING_FOR_DEPLOY`: This is no longer used, and is replaced by `PENDING_VERSION`
1159+
- `FROZEN`: This is no longer used, and is replaced by `WAITING`
1160+
- `INTERRUPTED`: This is no longer used
1161+
- `REATTEMPTING`: This is no longer used, and is replaced by `EXECUTING`
1162+
1163+
We've also added "boolean" helpers to runs returned via the API and from Realtime:
1164+
1165+
- `isQueued`: Returns true when the status is `QUEUED`, `PENDING_VERSION`, or `DELAYED`
1166+
- `isExecuting`: Returns true when the status is `EXECUTING`, `DEQUEUED`. These count against your concurrency limits.
1167+
- `isWaiting`: Returns true when the status is `WAITING`. These do not count against your concurrency limits.
1168+
- `isCompleted`: Returns true when the status is any of the completed statuses.
1169+
- `isCanceled`: Returns true when the status is `CANCELED`
1170+
- `isFailed`: Returns true when the status is any of the failed statuses.
1171+
- `isSuccess`: Returns true when the status is `COMPLETED`
1172+
1173+
This change adds the ability to easily detect which runs are being counted against your concurrency limit by filtering for both `EXECUTING` or `DEQUEUED`.
1174+
1175+
- Added runs.list filtering for queue and machine ([#2277](https://github.com/triggerdotdev/trigger.dev/pull/2277))
1176+
1177+
</Update>

0 commit comments

Comments
 (0)