[doc] sched.enter priority has no impact on execution

[altairmn]

BPO	33590
Nosy	@rhettinger, @ronaldoussoren, @bitdancer, @altairmn
Files	sched.enter.bug.py: Contains example code demonstrating bug. Priority order not followed in sched event execution.

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-05-21.05:43:33.136>
labels = ['easy', '3.11', '3.9', '3.10', 'docs']
title = '[doc] sched.enter priority has no impact on execution'
updated_at = <Date 2021-11-23.08:19:25.859>
user = 'https://github.com/altairmn'

bugs.python.org fields:

activity = <Date 2021-11-23.08:19:25.859>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-05-21.05:43:33.136>
creator = 'sahilmn'
dependencies = []
files = ['47609']
hgrepos = []
issue_num = 33590
keywords = ['easy']
message_count = 7.0
messages = ['317215', '317218', '317249', '317251', '317260', '317304', '318213']
nosy_count = 6.0
nosy_names = ['rhettinger', 'ronaldoussoren', 'r.david.murray', 'docs@python', 'sahilmn', 'mfisher']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue33590'
versions = ['Python 3.6', 'Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• [3.10] gh-77771: Add enterabs example in sched (GH-92716) #100490
• [3.11] gh-77771: Add enterabs example in sched (GH-92716) #100491

[altairmn]

sched.enter doesn't work as expected. If two events are scheduled with the same delay, then their order of execution seems to be dictated by the order of enter statements for the events instead of the priority order.

Ref attached file with example code. sched.enterabs works as expected.

[ronaldoussoren]

I don't think there's a bug here: sched.enter schedules an event some time after the current time. The two calls to sched.enter are not at the same time, hence the priority is not used because the events are scheduled at different times.

[altairmn]

The task schedule is executed when s.run() is called. There should be a
delay = 5 from the time the scheduling statement is executed.

If your claim is true, the priority argument is useless since it has no
impact on the execution order when delay values are equal. Clearly, this
is not the case since the example for enter at
https://docs.python.org/3/library/sched.html aims to demonstrate the use of
priority argument.

On Mon, May 21, 2018 at 4:14 AM, Ronald Oussoren <report@bugs.python.org>
wrote:

Ronald Oussoren <ronaldoussoren@mac.com> added the comment:

I don't think there's a bug here: sched.enter schedules an event some
time after the current time. The two calls to sched.enter are not at the
same time, hence the priority is not used because the events are scheduled
at different times.

----------
nosy: +ronaldoussoren

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue33590\>

---

[bitdancer]

I think Ronald is correct.

The priority argument for enter would apply if you called enter twice with two different delays, but they happen to end up pointing to the same moment in time from the scheduler's point of view.

How would the computer know that two calls to enter with the same delay are supposed to point to the same moment in time?

But you are correct, it looks like the example would make more sense if it used enterabs, not enter.

You can test our theory by writing time and delay functions with a course enough resolution that two sequential calls to delay will end up pointing to the time time unit. (Or we could look at the code :)

[ronaldoussoren]

I did look at the code :-)

The enter() method just calls enterabs() with an absolute time calculated from the current time (using the timefunc for the scheduler) and the passed relative time. Two calls of enter() with the same relative time will therefore use different absolute times unless you're using custom time function with a lower resolution.

Prorities are only used when who events are scheduled for the same absolute time, which is easy to arrange for using enterabs() but less so using enter() but still can happen when using calculated timeout values.

I don't agree about the example in the documentation, it is a clear demonstration about how to use the API in general and AFAIK is not intended to show how priorities work.

[rhettinger]

It would be nice to either modify the example or add another example to show the use of enterabs() and of the priority field being used as a tie breaker for two events scheduled at the same time.

[mfisher]

I did look at the code :-)

I also looked at the code. I had to do so to understand why the example output was not "as expected." ;)

I don't agree about the example in the documentation, it is a clear
demonstration about how to use the API in general and AFAIK is not
intended to show how priorities work.

Although I came to the same conclusion as you regarding both the fact and the reason the output was correct, I respectfully disagree that the example is clear. It is not. Yes, the example, as written, is intended to demonstrate the API -- which consists of several functionalities *including priority*. If this were not so, the example would not be passing different priority values with the same delay value.

I suggest re-opening this issue as a documentation bug and modifying the example to use enterabs instead of enter.

Respectfully,
M Fisher