[PATCH sched_ext/for-7.1] sched_ext: Documentation: Add ops.dequeue() to task lifecycle

[PATCH sched_ext/for-7.1] sched_ext: Documentation: Add ops.dequeue() to task lifecycle

[Andrea Righi]

Document ops.dequeue() in the sched_ext task lifecycle now that its
semantics are well-defined.

Also update the pseudo-code to use task_is_runnable() consistently and
clarify the case where ops.dispatch() does not refill the time slice.

Fixes: ebf1ccff79c4 ("sched_ext: Fix ops.dequeue() semantics")
Signed-off-by: Andrea Righi <arighi@nvidia.com>
---
 Documentation/scheduler/sched-ext.rst | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
index 404b4e4c33f7e..9f03650abfeba 100644
--- a/Documentation/scheduler/sched-ext.rst
+++ b/Documentation/scheduler/sched-ext.rst
@@ -422,23 +422,29 @@ by a sched_ext scheduler:
 
         ops.runnable();         /* Task becomes ready to run */
 
-        while (task is runnable) {
+        while (task_is_runnable(task)) {
             if (task is not in a DSQ && task->scx.slice == 0) {
                 ops.enqueue();  /* Task can be added to a DSQ */
 
-                /* Any usable CPU becomes available */
+                /* Task property change (i.e., affinity, nice, etc.)? */
+                if (sched_change(task)) {
+                    ops.dequeue(); /* Exiting BPF scheduler custody */
+                    continue;
+                }
+            }
 
-                ops.dispatch(); /* Task is moved to a local DSQ */
+            /* Any usable CPU becomes available */
+
+            ops.dispatch();     /* Task is moved to a local DSQ */
+            ops.dequeue();      /* Exiting BPF scheduler custody */
 
-                ops.dequeue(); /* Exiting BPF scheduler */
-            }
             ops.running();      /* Task starts running on its assigned CPU */
 
-            while task_is_runnable(p) {
-                while (task->scx.slice > 0 && task_is_runnable(p))
-                    ops.tick();     /* Called every 1/HZ seconds */
+            while (task_is_runnable(task) && task->scx.slice > 0) {
+                ops.tick();     /* Called every 1/HZ seconds */
 
-                ops.dispatch();     /* task->scx.slice can be refilled */
+                if (task->scx.slice == 0)
+                    ops.dispatch(); /* task->scx.slice can be refilled */
             }
 
             ops.stopping();     /* Task stops running (time slice expires or wait) */
-- 
2.53.0

Re: [PATCH sched_ext/for-7.1] sched_ext: Documentation: Add ops.dequeue() to task lifecycle

[Emil Tsalapatis]

On Mon Apr 6, 2026 at 7:47 AM EDT, Andrea Righi wrote:
> Document ops.dequeue() in the sched_ext task lifecycle now that its
> semantics are well-defined.
>
> Also update the pseudo-code to use task_is_runnable() consistently and
> clarify the case where ops.dispatch() does not refill the time slice.
>
> Fixes: ebf1ccff79c4 ("sched_ext: Fix ops.dequeue() semantics")

Is the Fixes: tag appropriate here? It's not like the original patch
introduced a bug by fixing ops.dequeue().

Otherwise the state machine looks fine to me!

Reviewed-by: Emil Tsalapatis <emil@etsalapatis.com>

> Signed-off-by: Andrea Righi <arighi@nvidia.com>
> ---
>  Documentation/scheduler/sched-ext.rst | 24 +++++++++++++++---------
>  1 file changed, 15 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> index 404b4e4c33f7e..9f03650abfeba 100644
> --- a/Documentation/scheduler/sched-ext.rst
> +++ b/Documentation/scheduler/sched-ext.rst
> @@ -422,23 +422,29 @@ by a sched_ext scheduler:
>  
>          ops.runnable();         /* Task becomes ready to run */
>  
> -        while (task is runnable) {
> +        while (task_is_runnable(task)) {
>              if (task is not in a DSQ && task->scx.slice == 0) {
>                  ops.enqueue();  /* Task can be added to a DSQ */
>  
> -                /* Any usable CPU becomes available */
> +                /* Task property change (i.e., affinity, nice, etc.)? */
> +                if (sched_change(task)) {
> +                    ops.dequeue(); /* Exiting BPF scheduler custody */
> +                    continue;
> +                }
> +            }
>  
> -                ops.dispatch(); /* Task is moved to a local DSQ */
> +            /* Any usable CPU becomes available */
> +
> +            ops.dispatch();     /* Task is moved to a local DSQ */
> +            ops.dequeue();      /* Exiting BPF scheduler custody */
>  
> -                ops.dequeue(); /* Exiting BPF scheduler */
> -            }
>              ops.running();      /* Task starts running on its assigned CPU */
>  
> -            while task_is_runnable(p) {
> -                while (task->scx.slice > 0 && task_is_runnable(p))
> -                    ops.tick();     /* Called every 1/HZ seconds */
> +            while (task_is_runnable(task) && task->scx.slice > 0) {
> +                ops.tick();     /* Called every 1/HZ seconds */
>  
> -                ops.dispatch();     /* task->scx.slice can be refilled */
> +                if (task->scx.slice == 0)
> +                    ops.dispatch(); /* task->scx.slice can be refilled */
>              }
>  
>              ops.stopping();     /* Task stops running (time slice expires or wait) */

Re: [PATCH sched_ext/for-7.1] sched_ext: Documentation: Add ops.dequeue() to task lifecycle

[Andrea Righi]

Hi Emil,

On Mon, Apr 06, 2026 at 10:49:18AM -0400, Emil Tsalapatis wrote:
> On Mon Apr 6, 2026 at 7:47 AM EDT, Andrea Righi wrote:
> > Document ops.dequeue() in the sched_ext task lifecycle now that its
> > semantics are well-defined.
> >
> > Also update the pseudo-code to use task_is_runnable() consistently and
> > clarify the case where ops.dispatch() does not refill the time slice.
> >
> > Fixes: ebf1ccff79c4 ("sched_ext: Fix ops.dequeue() semantics")
> 
> Is the Fixes: tag appropriate here? It's not like the original patch
> introduced a bug by fixing ops.dequeue().

Yeah, the intent here was to make sure this commit isn't applied without
ebf1ccff79c4 (otherwise the state machine would be inaccurate), but that
shouldn't happen, so it's probably reasonable to drop the Fixes line.

Thanks,
-Andrea

> 
> Otherwise the state machine looks fine to me!
> 
> Reviewed-by: Emil Tsalapatis <emil@etsalapatis.com>
> 
> > Signed-off-by: Andrea Righi <arighi@nvidia.com>
> > ---
> >  Documentation/scheduler/sched-ext.rst | 24 +++++++++++++++---------
> >  1 file changed, 15 insertions(+), 9 deletions(-)
> >
> > diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> > index 404b4e4c33f7e..9f03650abfeba 100644
> > --- a/Documentation/scheduler/sched-ext.rst
> > +++ b/Documentation/scheduler/sched-ext.rst
> > @@ -422,23 +422,29 @@ by a sched_ext scheduler:
> >  
> >          ops.runnable();         /* Task becomes ready to run */
> >  
> > -        while (task is runnable) {
> > +        while (task_is_runnable(task)) {
> >              if (task is not in a DSQ && task->scx.slice == 0) {
> >                  ops.enqueue();  /* Task can be added to a DSQ */
> >  
> > -                /* Any usable CPU becomes available */
> > +                /* Task property change (i.e., affinity, nice, etc.)? */
> > +                if (sched_change(task)) {
> > +                    ops.dequeue(); /* Exiting BPF scheduler custody */
> > +                    continue;
> > +                }
> > +            }
> >  
> > -                ops.dispatch(); /* Task is moved to a local DSQ */
> > +            /* Any usable CPU becomes available */
> > +
> > +            ops.dispatch();     /* Task is moved to a local DSQ */
> > +            ops.dequeue();      /* Exiting BPF scheduler custody */
> >  
> > -                ops.dequeue(); /* Exiting BPF scheduler */
> > -            }
> >              ops.running();      /* Task starts running on its assigned CPU */
> >  
> > -            while task_is_runnable(p) {
> > -                while (task->scx.slice > 0 && task_is_runnable(p))
> > -                    ops.tick();     /* Called every 1/HZ seconds */
> > +            while (task_is_runnable(task) && task->scx.slice > 0) {
> > +                ops.tick();     /* Called every 1/HZ seconds */
> >  
> > -                ops.dispatch();     /* task->scx.slice can be refilled */
> > +                if (task->scx.slice == 0)
> > +                    ops.dispatch(); /* task->scx.slice can be refilled */
> >              }
> >  
> >              ops.stopping();     /* Task stops running (time slice expires or wait) */
> 

Re: [PATCH sched_ext/for-7.1] sched_ext: Documentation: Add ops.dequeue() to task lifecycle

[Tejun Heo]

> sched_ext: Documentation: Add ops.dequeue() to task lifecycle

Applied to sched_ext/for-7.1 with Emil's Reviewed-by added and the
Fixes: tag dropped per his comment.

Thanks.

--
tejun

Re: [PATCH sched_ext/for-7.1] sched_ext: Documentation: Add ops.dequeue() to task lifecycle

[Kuba Piecuch]

Hi Andrea,

On Mon Apr 6, 2026 at 11:47 AM UTC, Andrea Righi wrote:
> Document ops.dequeue() in the sched_ext task lifecycle now that its
> semantics are well-defined.
>
> Also update the pseudo-code to use task_is_runnable() consistently and
> clarify the case where ops.dispatch() does not refill the time slice.
>
> Fixes: ebf1ccff79c4 ("sched_ext: Fix ops.dequeue() semantics")
> Signed-off-by: Andrea Righi <arighi@nvidia.com>
> ---
>  Documentation/scheduler/sched-ext.rst | 24 +++++++++++++++---------
>  1 file changed, 15 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> index 404b4e4c33f7e..9f03650abfeba 100644
> --- a/Documentation/scheduler/sched-ext.rst
> +++ b/Documentation/scheduler/sched-ext.rst
> @@ -422,23 +422,29 @@ by a sched_ext scheduler:
>  
>          ops.runnable();         /* Task becomes ready to run */
>  
> -        while (task is runnable) {
> +        while (task_is_runnable(task)) {
>              if (task is not in a DSQ && task->scx.slice == 0) {
>                  ops.enqueue();  /* Task can be added to a DSQ */
>  
> -                /* Any usable CPU becomes available */
> +                /* Task property change (i.e., affinity, nice, etc.)? */
> +                if (sched_change(task)) {
> +                    ops.dequeue(); /* Exiting BPF scheduler custody */

Doesn't the task also go through quiescent -> runnable here? The full path
being dequeue -> quiescent -> (actual property change) -> runnable -> enqueue.

I guess we should be accurate here since quiescent and runnable are present
elsewhere in the pseudocode.

> +                    continue;
> +                }
> +            }
>  
> -                ops.dispatch(); /* Task is moved to a local DSQ */
> +            /* Any usable CPU becomes available */
> +
> +            ops.dispatch();     /* Task is moved to a local DSQ */

s/local/terminal/?

> +            ops.dequeue();      /* Exiting BPF scheduler custody */
>  
> -                ops.dequeue(); /* Exiting BPF scheduler */
> -            }
>              ops.running();      /* Task starts running on its assigned CPU */
>  
> -            while task_is_runnable(p) {
> -                while (task->scx.slice > 0 && task_is_runnable(p))
> -                    ops.tick();     /* Called every 1/HZ seconds */
> +            while (task_is_runnable(task) && task->scx.slice > 0) {
> +                ops.tick();     /* Called every 1/HZ seconds */
>  
> -                ops.dispatch();     /* task->scx.slice can be refilled */
> +                if (task->scx.slice == 0)
> +                    ops.dispatch(); /* task->scx.slice can be refilled */
>              }
>  
>              ops.stopping();     /* Task stops running (time slice expires or wait) */

Thanks,
Kuba

Re: [PATCH sched_ext/for-7.1] sched_ext: Documentation: Add ops.dequeue() to task lifecycle

[Andrea Righi]

Hi Kuba,

On Tue, Apr 07, 2026 at 09:54:22AM +0000, Kuba Piecuch wrote:
> Hi Andrea,
> 
> On Mon Apr 6, 2026 at 11:47 AM UTC, Andrea Righi wrote:
> > Document ops.dequeue() in the sched_ext task lifecycle now that its
> > semantics are well-defined.
> >
> > Also update the pseudo-code to use task_is_runnable() consistently and
> > clarify the case where ops.dispatch() does not refill the time slice.
> >
> > Fixes: ebf1ccff79c4 ("sched_ext: Fix ops.dequeue() semantics")
> > Signed-off-by: Andrea Righi <arighi@nvidia.com>
> > ---
> >  Documentation/scheduler/sched-ext.rst | 24 +++++++++++++++---------
> >  1 file changed, 15 insertions(+), 9 deletions(-)
> >
> > diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> > index 404b4e4c33f7e..9f03650abfeba 100644
> > --- a/Documentation/scheduler/sched-ext.rst
> > +++ b/Documentation/scheduler/sched-ext.rst
> > @@ -422,23 +422,29 @@ by a sched_ext scheduler:
> >  
> >          ops.runnable();         /* Task becomes ready to run */
> >  
> > -        while (task is runnable) {
> > +        while (task_is_runnable(task)) {
> >              if (task is not in a DSQ && task->scx.slice == 0) {
> >                  ops.enqueue();  /* Task can be added to a DSQ */
> >  
> > -                /* Any usable CPU becomes available */
> > +                /* Task property change (i.e., affinity, nice, etc.)? */
> > +                if (sched_change(task)) {
> > +                    ops.dequeue(); /* Exiting BPF scheduler custody */
> 
> Doesn't the task also go through quiescent -> runnable here? The full path
> being dequeue -> quiescent -> (actual property change) -> runnable -> enqueue.
> 
> I guess we should be accurate here since quiescent and runnable are present
> elsewhere in the pseudocode.

Ah yes, we need to add ops.quiescent() and ops.runnable() here. Tejun already
applied this patch to his branch, can you send another patch on top of this?

> 
> > +                    continue;
> > +                }
> > +            }
> >  
> > -                ops.dispatch(); /* Task is moved to a local DSQ */
> > +            /* Any usable CPU becomes available */
> > +
> > +            ops.dispatch();     /* Task is moved to a local DSQ */
> 
> s/local/terminal/?

Technically it'd be correct to say "terminal", but typically we use
scx_bpf_move_to_local() here, which moves the task to a local DSQ. Then it may
fallback into SCX_DSQ_GLOBAL if something goes wrong, but, from a logical
perspective, the intention is to move the task to local DSQ at this point.

So, I'm not sure if saying "terminal" here would be more confusing than
helpful... but I don't have a strong opinion on that.

Thanks,
-Andrea

> 
> > +            ops.dequeue();      /* Exiting BPF scheduler custody */
> >  
> > -                ops.dequeue(); /* Exiting BPF scheduler */
> > -            }
> >              ops.running();      /* Task starts running on its assigned CPU */
> >  
> > -            while task_is_runnable(p) {
> > -                while (task->scx.slice > 0 && task_is_runnable(p))
> > -                    ops.tick();     /* Called every 1/HZ seconds */
> > +            while (task_is_runnable(task) && task->scx.slice > 0) {
> > +                ops.tick();     /* Called every 1/HZ seconds */
> >  
> > -                ops.dispatch();     /* task->scx.slice can be refilled */
> > +                if (task->scx.slice == 0)
> > +                    ops.dispatch(); /* task->scx.slice can be refilled */
> >              }
> >  
> >              ops.stopping();     /* Task stops running (time slice expires or wait) */
> 
> Thanks,
> Kuba