From b536e50d2e2585ea3857f2de7e9f775718ed17fa Mon Sep 17 00:00:00 2001 From: Eric Allam Date: Thu, 17 Jul 2025 18:36:12 +0100 Subject: [PATCH 1/3] WIP new docs for the new release concurrency and run statuses --- docs/upgrade-to-v4.mdx | 78 ++++++++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 34 deletions(-) diff --git a/docs/upgrade-to-v4.mdx b/docs/upgrade-to-v4.mdx index 35c0e11228..3b108be22c 100644 --- a/docs/upgrade-to-v4.mdx +++ b/docs/upgrade-to-v4.mdx @@ -749,40 +749,50 @@ await myTask.trigger({ foo: "bar" }); // Will use the queue defined on the task await myTask2.trigger({ foo: "bar" }); // Will use the queue defined on the task ``` -### Releasing concurrency on waits - -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. - -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: - -```ts -const myQueue = queue({ - name: "my-queue", - concurrencyLimit: 10, - releaseConcurrencyOnWaitpoint: true, -}); -``` - -You can also now control whether concurrency is released when performing a wait: - -```ts -// This will prevent the run from being released back into the queue when the wait starts -await wait.for({ seconds: 10, releaseConcurrency: false }); -``` - -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. - - - If you do choose to release concurrency on waits, be aware that it's possible a resume is delayed - if the concurrency that was released is not available at the time the wait completes. In this - case, the run will go back into the queue and will resume once concurrency becomes available. - - -This new behavior effects all the wait functions: - -- Wait for duration (e.g. `wait.for({ seconds: 10 })`) -- Wait for a child task to complete (e.g. `myTask.triggerAndWait()`, `myTask.batchTriggerAndWait([...])`) -- Wait for a token to complete (e.g. `wait.forToken(tokenId)`) +### Concurrency changes + +We've changed a few things around how concurrency is managed at the environment and queue level: + +- 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. +- 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. +- 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. + +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. + +### New Run Statuses + +We've done some work cleaning up the run statuses. The new statuses are: + +- `PENDING_VERSION`: Task is waiting for a version update because it cannot execute without additional information (task, queue, etc.) +- `QUEUED`: Task is waiting to be executed by a worker +- `DEQUEUED`: Task has been dequeued and is being sent to a worker to start executing. +- `EXECUTING`: Task is currently being executed by a worker +- `WAITING`: Task has been paused by the system, and will be resumed by the system +- `COMPLETED`: Task has been completed successfully +- `CANCELED`: Task has been canceled by the user +- `FAILED`: Task has failed to complete, due to an error in the system +- `CRASHED`: Task has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage +- `SYSTEM_FAILURE`: Task has failed to complete, due to an error in the system +- `DELAYED`: Task has been scheduled to run at a specific time +- `EXPIRED`: Task has expired and won't be executed +- `TIMED_OUT`: Task has reached it's maxDuration and has been stopped + +We've removed the following statuses: + +- `WAITING_FOR_DEPLOY`: This is no longer used, and is replaced by `PENDING_VERSION` +- `FROZEN`: This is no longer used, and is replaced by `WAITING` +- `INTERRUPTED`: This is no longer used +- `REATTEMPTING`: This is no longer used, and is replaced by `EXECUTING` + +We've also added "boolean" helpers to runs returned via the API and from Realtime: + +- `isQueued`: Returns true when the status is `QUEUED`, `PENDING_VERSION`, or `DELAYED` +- `isExecuting`: Returns true when the status is `EXECUTING`, `DEQUEUED`. These count against your concurrency limits. +- `isWaiting`: Returns true when the status is `WAITING`. These do not count against your concurrency limits. +- `isCompleted`: Returns true when the status is any of the completed statuses. +- `isCanceled`: Returns true when the status is `CANCELED` +- `isFailed`: Returns true when the status is any of the failed statuses. +- `isSuccess`: Returns true when the status is `COMPLETED` ### Lifecycle hooks From 66b161221812d11af49f109653db90ce45ac13c6 Mon Sep 17 00:00:00 2001 From: Eric Allam Date: Mon, 21 Jul 2025 14:36:16 +0100 Subject: [PATCH 2/3] Fixed status description --- docs/upgrade-to-v4.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/upgrade-to-v4.mdx b/docs/upgrade-to-v4.mdx index 3b108be22c..d324582c8a 100644 --- a/docs/upgrade-to-v4.mdx +++ b/docs/upgrade-to-v4.mdx @@ -763,19 +763,19 @@ This means that if you have a queue with a `concurrencyLimit` of 1, you can only We've done some work cleaning up the run statuses. The new statuses are: -- `PENDING_VERSION`: Task is waiting for a version update because it cannot execute without additional information (task, queue, etc.) -- `QUEUED`: Task is waiting to be executed by a worker +- `PENDING_VERSION`: Task is waiting for a version update because it cannot execute without additional information (task, queue, etc.). +- `QUEUED`: Task is waiting to be executed by a worker. - `DEQUEUED`: Task has been dequeued and is being sent to a worker to start executing. -- `EXECUTING`: Task is currently being executed by a worker -- `WAITING`: Task has been paused by the system, and will be resumed by the system -- `COMPLETED`: Task has been completed successfully -- `CANCELED`: Task has been canceled by the user -- `FAILED`: Task has failed to complete, due to an error in the system -- `CRASHED`: Task has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage +- `EXECUTING`: Task is currently being executed by a worker. +- `WAITING`: Task has been paused by the system, and will be resumed by the system. +- `COMPLETED`: Task has been completed successfully. +- `CANCELED`: Task has been canceled by the user. +- `FAILED`: Task has failed to complete, due to an error in the task code. +- `CRASHED`: Task has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage. - `SYSTEM_FAILURE`: Task has failed to complete, due to an error in the system -- `DELAYED`: Task has been scheduled to run at a specific time -- `EXPIRED`: Task has expired and won't be executed -- `TIMED_OUT`: Task has reached it's maxDuration and has been stopped +- `DELAYED`: Task has been scheduled to run at a specific time. +- `EXPIRED`: Task has expired and won't be executed, +- `TIMED_OUT`: Task has reached its maxDuration and has been stopped. We've removed the following statuses: From c590e26de4435f1b9a1d4ee13edffe0b377a5bf6 Mon Sep 17 00:00:00 2001 From: Eric Allam Date: Tue, 22 Jul 2025 11:28:57 +0100 Subject: [PATCH 3/3] Add the beta.24 changelog entry --- docs/upgrade-to-v4.mdx | 50 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/upgrade-to-v4.mdx b/docs/upgrade-to-v4.mdx index d324582c8a..528888b6f9 100644 --- a/docs/upgrade-to-v4.mdx +++ b/docs/upgrade-to-v4.mdx @@ -1125,3 +1125,53 @@ We recommend enabling this option and testing in a staging or preview environmen - 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)) + + + [Release + v4.0.0-beta.24](https://github.com/triggerdotdev/trigger.dev/releases/tag/trigger.dev%404.0.0-v4-beta.24). + +- 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)) + + - Concurrency is never released when a run is first blocked via a waitpoint, at either the env or queue level. + - Concurrency is always released when a run is checkpointed and shutdown, at both the env and queue level. + + 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. + + We've done some work cleaning up the run statuses. The new statuses are: + + - `PENDING_VERSION`: Task is waiting for a version update because it cannot execute without additional information (task, queue, etc.) + - `QUEUED`: Task is waiting to be executed by a worker + - `DEQUEUED`: Task has been dequeued and is being sent to a worker to start executing. + - `EXECUTING`: Task is currently being executed by a worker + - `WAITING`: Task has been paused by the system, and will be resumed by the system + - `COMPLETED`: Task has been completed successfully + - `CANCELED`: Task has been canceled by the user + - `FAILED`: Task has failed to complete, due to an error in the system + - `CRASHED`: Task has crashed and won't be retried, most likely the worker ran out of resources, e.g. memory or storage + - `SYSTEM_FAILURE`: Task has failed to complete, due to an error in the system + - `DELAYED`: Task has been scheduled to run at a specific time + - `EXPIRED`: Task has expired and won't be executed + - `TIMED_OUT`: Task has reached it's maxDuration and has been stopped + + We've removed the following statuses: + + - `WAITING_FOR_DEPLOY`: This is no longer used, and is replaced by `PENDING_VERSION` + - `FROZEN`: This is no longer used, and is replaced by `WAITING` + - `INTERRUPTED`: This is no longer used + - `REATTEMPTING`: This is no longer used, and is replaced by `EXECUTING` + + We've also added "boolean" helpers to runs returned via the API and from Realtime: + + - `isQueued`: Returns true when the status is `QUEUED`, `PENDING_VERSION`, or `DELAYED` + - `isExecuting`: Returns true when the status is `EXECUTING`, `DEQUEUED`. These count against your concurrency limits. + - `isWaiting`: Returns true when the status is `WAITING`. These do not count against your concurrency limits. + - `isCompleted`: Returns true when the status is any of the completed statuses. + - `isCanceled`: Returns true when the status is `CANCELED` + - `isFailed`: Returns true when the status is any of the failed statuses. + - `isSuccess`: Returns true when the status is `COMPLETED` + + This change adds the ability to easily detect which runs are being counted against your concurrency limit by filtering for both `EXECUTING` or `DEQUEUED`. + +- Added runs.list filtering for queue and machine ([#2277](https://github.com/triggerdotdev/trigger.dev/pull/2277)) + +