Improve README with extra info about concurrency #520
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add two notes on README about conurrency controls and how blocked jobs are unblocked and for how long can they be blocked.
cedricpim
force-pushed
the
add-notes-on-concurrency
branch
from
a2727ad to
25b58e1
Compare
rosa
reviewed
Feb 24, 2025
README.md
Outdated
| @@ -426,7 +426,7 @@ class MyJob < ApplicationJob | |||
|
|
|||
| When a job includes these controls, we'll ensure that, at most, the number of jobs (indicated as `to`) that yield the same `key` will be performed concurrently, and this guarantee will last for `duration` for each job enqueued. Note that there's no guarantee about _the order of execution_, only about jobs being performed at the same time (overlapping). | |||
|
|
|||
| The concurrency limits use the concept of semaphores when enqueuing, and work as follows: when a job is enqueued, we check if it specifies concurrency controls. If it does, we check the semaphore for the computed concurrency key. If the semaphore is open, we claim it and we set the job as _ready_. Ready means it can be picked up by workers for execution. When the job finishes executing (be it successfully or unsuccessfully, resulting in a failed execution), we signal the semaphore and try to unblock the next job with the same key, if any. Unblocking the next job doesn't mean running that job right away, but moving it from _blocked_ to _ready_. Since something can happen that prevents the first job from releasing the semaphore and unblocking the next job (for example, someone pulling a plug in the machine where the worker is running), we have the `duration` as a failsafe. Jobs that have been blocked for more than duration are candidates to be released, but only as many of them as the concurrency rules allow, as each one would need to go through the semaphore dance check. This means that the `duration` is not really about the job that's enqueued or being run, it's about the jobs that are blocked waiting. | |||
| The concurrency limits use the concept of semaphores when enqueuing, and work as follows: when a job is enqueued, we check if it specifies concurrency controls. If it does, we check the semaphore for the computed concurrency key. If the semaphore is open, we claim it and we set the job as _ready_. Ready means it can be picked up by workers for execution. When the job finishes executing (be it successfully or unsuccessfully, resulting in a failed execution), we signal the semaphore and try to unblock the next job with the same key, if any. Unblocking the next job doesn't mean running that job right away, but moving it from _blocked_ to _ready_. Since something can happen that prevents the first job from releasing the semaphore and unblocking the next job (for example, someone pulling a plug in the machine where the worker is running), we have the `duration` as a failsafe. Jobs that have been blocked for more than duration are candidates to be released, but only as many of them as the concurrency rules allow, as each one would need to go through the semaphore dance check. This means that the `duration` is not really about the job that's enqueued or being run, it's about the jobs that are blocked waiting. When there are multiple jobs unblocked, it is important to note that, as a job finishes and the next jobs are unblocked, the `duration` timer for the still blocked jobs is reset (this happens indirectly via the expiration time of the semaphore). | |||
There was a problem hiding this comment.
I'd rephrase this, as it's not really necessary that there are multiple jobs unblocked (because concurrency limit > 1). The behaviour is always the same.
Instead of:
When there are multiple jobs unblocked, it is important to note that, as a job finishes and the next jobs are unblocked, the
durationtimer for the still blocked jobs is reset (this happens indirectly via the expiration time of the semaphore).
I'd write this as:
It's important to note that after one or more candidate jobs are unblocked (either because a job finishes or because
durationexpires and a semaphore is released), thedurationtimer for the still blocked jobs is reset. This happens indirectly via the expiration time of the semaphore, which is updated.
|
Thanks a lot @cedricpim! I just left a small comment about one of the changes 🙏 |
|
@rosa sorry for the delay on this. Just updated the PR. |
|
Nice, thanks a lot! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add two notes on README about conurrency controls and how blocked jobs are unblocked and for how long can they be blocked.
Related to what was discussed in #502