[PATCH] sched_ext: Documentation: add note about multiple ops.enqueue() calls in a row

[PATCH] sched_ext: Documentation: add note about multiple ops.enqueue() calls in a row

[Kuba Piecuch]

Commit 84b1a0ea0b7c
("sched_ext: Implement scx_bpf_dsq_reenq() for user DSQs")
introduced the possibility of ops.enqueue() being called multiple times
in a row for the same task without intervening calls to ops.dequeue().
AFAIK this was not possible before that commit.
Document this behavior as it may be surprising to some.

Signed-off-by: Kuba Piecuch <jpiecuch@google.com>
---
 Documentation/scheduler/sched-ext.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
index 03d595d178ea..fba09aa1cd4e 100644
--- a/Documentation/scheduler/sched-ext.rst
+++ b/Documentation/scheduler/sched-ext.rst
@@ -339,6 +339,11 @@ The following briefly shows how a waking task is scheduled and executed.
      leaves (e.g., when ``ops.dispatch()`` moves it to a terminal DSQ, or
      on property change / sleep).
 
+   Note that ``ops.enqueue()`` can be called multiple times in a row without
+   an intervening call to ``ops.dequeue()``. This can happen, for example,
+   when a task on a user-created DSQ is re-enqueued using
+   ``scx_bpf_dsq_reenq()``. The task stays in BPF custody the entire time.
+
    When a task leaves BPF scheduler custody, ``ops.dequeue()`` is invoked.
    The dequeue can happen for different reasons, distinguished by flags:
 
-- 
2.54.0.rc1.555.g9c883467ad-goog

Re: [PATCH] sched_ext: Documentation: add note about multiple ops.enqueue() calls in a row

[Andrea Righi]

Hi Kuba,

On Mon, Apr 20, 2026 at 02:39:39PM +0000, Kuba Piecuch wrote:
> Commit 84b1a0ea0b7c
> ("sched_ext: Implement scx_bpf_dsq_reenq() for user DSQs")
> introduced the possibility of ops.enqueue() being called multiple times
> in a row for the same task without intervening calls to ops.dequeue().
> AFAIK this was not possible before that commit.
> Document this behavior as it may be surprising to some.
> 
> Signed-off-by: Kuba Piecuch <jpiecuch@google.com>

Looks good to me and I think it's good to document this special case.

Acked-by: Andrea Righi <arighi@nvidia.com>

Thanks,
-Andrea

> ---
>  Documentation/scheduler/sched-ext.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> index 03d595d178ea..fba09aa1cd4e 100644
> --- a/Documentation/scheduler/sched-ext.rst
> +++ b/Documentation/scheduler/sched-ext.rst
> @@ -339,6 +339,11 @@ The following briefly shows how a waking task is scheduled and executed.
>       leaves (e.g., when ``ops.dispatch()`` moves it to a terminal DSQ, or
>       on property change / sleep).
>  
> +   Note that ``ops.enqueue()`` can be called multiple times in a row without
> +   an intervening call to ``ops.dequeue()``. This can happen, for example,
> +   when a task on a user-created DSQ is re-enqueued using
> +   ``scx_bpf_dsq_reenq()``. The task stays in BPF custody the entire time.
> +
>     When a task leaves BPF scheduler custody, ``ops.dequeue()`` is invoked.
>     The dequeue can happen for different reasons, distinguished by flags:
>  
> -- 
> 2.54.0.rc1.555.g9c883467ad-goog
> 

Re: [PATCH] sched_ext: Documentation: add note about multiple ops.enqueue() calls in a row

[Cheng-Yang Chou]

Hi Kuba,

On Mon, Apr 20, 2026 at 02:39:39PM +0000, Kuba Piecuch wrote:
> Commit 84b1a0ea0b7c
> ("sched_ext: Implement scx_bpf_dsq_reenq() for user DSQs")
> introduced the possibility of ops.enqueue() being called multiple times
> in a row for the same task without intervening calls to ops.dequeue().
> AFAIK this was not possible before that commit.
  ^^^^^
Nit: Do we really need this line in the commit message?
Perhaps we can just drop this?

> Document this behavior as it may be surprising to some.
> 
> Signed-off-by: Kuba Piecuch <jpiecuch@google.com>
> ---
>  Documentation/scheduler/sched-ext.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> index 03d595d178ea..fba09aa1cd4e 100644
> --- a/Documentation/scheduler/sched-ext.rst
> +++ b/Documentation/scheduler/sched-ext.rst
> @@ -339,6 +339,11 @@ The following briefly shows how a waking task is scheduled and executed.
>       leaves (e.g., when ``ops.dispatch()`` moves it to a terminal DSQ, or
>       on property change / sleep).
>  
> +   Note that ``ops.enqueue()`` can be called multiple times in a row without
> +   an intervening call to ``ops.dequeue()``. This can happen, for example,
> +   when a task on a user-created DSQ is re-enqueued using
> +   ``scx_bpf_dsq_reenq()``. The task stays in BPF custody the entire time.
> +

Thanks for adding and clarifying this. ^v^

Acked-by: Cheng-Yang Chou <yphbchou0911@gmail.com>

>     When a task leaves BPF scheduler custody, ``ops.dequeue()`` is invoked.
>     The dequeue can happen for different reasons, distinguished by flags:
>  
> -- 
> 2.54.0.rc1.555.g9c883467ad-goog
> 

-- 
Cheers,
Cheng-Yang

Re: [PATCH] sched_ext: Documentation: add note about multiple ops.enqueue() calls in a row

[Kuba Piecuch]

Hi Cheng-Yang,

On Mon Apr 20, 2026 at 3:12 PM UTC, Cheng-Yang Chou wrote:
> Hi Kuba,
>
> On Mon, Apr 20, 2026 at 02:39:39PM +0000, Kuba Piecuch wrote:
>> Commit 84b1a0ea0b7c
>> ("sched_ext: Implement scx_bpf_dsq_reenq() for user DSQs")
>> introduced the possibility of ops.enqueue() being called multiple times
>> in a row for the same task without intervening calls to ops.dequeue().
>> AFAIK this was not possible before that commit.
>   ^^^^^
> Nit: Do we really need this line in the commit message?
> Perhaps we can just drop this?

I put it there just in case someone was actually aware of a scenario before
that commit where we can have multiple ops.enqueue() calls in a row.

Regarding removing the line: yeah, I guess it's a bit redundant.
I'll send a v2.

>
>> Document this behavior as it may be surprising to some.
>> 
>> Signed-off-by: Kuba Piecuch <jpiecuch@google.com>
>> ---
>>  Documentation/scheduler/sched-ext.rst | 5 +++++
>>  1 file changed, 5 insertions(+)
>> 
>> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
>> index 03d595d178ea..fba09aa1cd4e 100644
>> --- a/Documentation/scheduler/sched-ext.rst
>> +++ b/Documentation/scheduler/sched-ext.rst
>> @@ -339,6 +339,11 @@ The following briefly shows how a waking task is scheduled and executed.
>>       leaves (e.g., when ``ops.dispatch()`` moves it to a terminal DSQ, or
>>       on property change / sleep).
>>  
>> +   Note that ``ops.enqueue()`` can be called multiple times in a row without
>> +   an intervening call to ``ops.dequeue()``. This can happen, for example,
>> +   when a task on a user-created DSQ is re-enqueued using
>> +   ``scx_bpf_dsq_reenq()``. The task stays in BPF custody the entire time.
>> +
>
> Thanks for adding and clarifying this. ^v^
>
> Acked-by: Cheng-Yang Chou <yphbchou0911@gmail.com>
>

Thanks,
Kuba

Re: [PATCH] sched_ext: Documentation: add note about multiple ops.enqueue() calls in a row

[Cheng-Yang Chou]

Hi Kuba,

On Mon, Apr 20, 2026 at 03:21:59PM +0000, Kuba Piecuch wrote:
> Hi Cheng-Yang,
> 
> On Mon Apr 20, 2026 at 3:12 PM UTC, Cheng-Yang Chou wrote:
> > Hi Kuba,
> >
> > On Mon, Apr 20, 2026 at 02:39:39PM +0000, Kuba Piecuch wrote:
> >> Commit 84b1a0ea0b7c
> >> ("sched_ext: Implement scx_bpf_dsq_reenq() for user DSQs")
> >> introduced the possibility of ops.enqueue() being called multiple times
> >> in a row for the same task without intervening calls to ops.dequeue().
> >> AFAIK this was not possible before that commit.
> >   ^^^^^
> > Nit: Do we really need this line in the commit message?
> > Perhaps we can just drop this?
> 
> I put it there just in case someone was actually aware of a scenario before
> that commit where we can have multiple ops.enqueue() calls in a row.

I see, thanks!

> 
> Regarding removing the line: yeah, I guess it's a bit redundant.
> I'll send a v2.
> 
> >
> >> Document this behavior as it may be surprising to some.
> >> 
> >> Signed-off-by: Kuba Piecuch <jpiecuch@google.com>
> >> ---
> >>  Documentation/scheduler/sched-ext.rst | 5 +++++
> >>  1 file changed, 5 insertions(+)
> >> 
> >> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> >> index 03d595d178ea..fba09aa1cd4e 100644
> >> --- a/Documentation/scheduler/sched-ext.rst
> >> +++ b/Documentation/scheduler/sched-ext.rst
> >> @@ -339,6 +339,11 @@ The following briefly shows how a waking task is scheduled and executed.
> >>       leaves (e.g., when ``ops.dispatch()`` moves it to a terminal DSQ, or
> >>       on property change / sleep).
> >>  
> >> +   Note that ``ops.enqueue()`` can be called multiple times in a row without
> >> +   an intervening call to ``ops.dequeue()``. This can happen, for example,
> >> +   when a task on a user-created DSQ is re-enqueued using
> >> +   ``scx_bpf_dsq_reenq()``. The task stays in BPF custody the entire time.
> >> +
> >
> > Thanks for adding and clarifying this. ^v^
> >
> > Acked-by: Cheng-Yang Chou <yphbchou0911@gmail.com>
> >
> 
> Thanks,
> Kuba

-- 
Cheers,
Cheng-Yang