Mercurial > cpython-lru_cache-weakref

annotate Lib/sched.py @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 86e3943d0d5b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11708
4a23cc49e2b0 Actually, the previous batch's comment should have been different;
Guido van Rossum <guido@python.org>
parents: 11063
diff changeset
1 """A generally useful event scheduler class.
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
2
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
3 Each instance of this class manages its own queue.
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
4 No multi-threading is implied; you are supposed to hack that
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
5 yourself, or use a single instance per application.
195
45f43f755e5c Initial revision
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
7 Each instance is parametrized with two functions, one that is
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
8 supposed to return the current time, one that is supposed to
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
9 implement a delay. You can implement real-time scheduling by
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
10 substituting time and sleep from built-in module time, or you can
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
11 implement simulated time by writing your own functions. This can
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
12 also be used to integrate scheduling with STDWIN events; the delay
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
13 function is allowed to modify the queue. Time can be expressed as
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
14 integers or floating point numbers, as long as it is consistent.
195
45f43f755e5c Initial revision
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
16 Events are specified by tuples (time, priority, action, argument).
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
17 As in UNIX, lower priority numbers mean higher priority; in this
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
18 way the queue can be maintained as a priority queue. Execution of the
43493
9e6020bb2352 Update docstring of sched, also remove an unused assignment.
Georg Brandl <georg@python.org>
parents: 41073
diff changeset
19 event means calling the action function, passing it the argument
9e6020bb2352 Update docstring of sched, also remove an unused assignment.
Georg Brandl <georg@python.org>
parents: 41073
diff changeset
20 sequence in "argument" (remember that in Python, multiple function
9e6020bb2352 Update docstring of sched, also remove an unused assignment.
Georg Brandl <georg@python.org>
parents: 41073
diff changeset
21 arguments are be packed in a sequence).
9e6020bb2352 Update docstring of sched, also remove an unused assignment.
Georg Brandl <georg@python.org>
parents: 41073
diff changeset
22 The action function may be an instance method so it
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
23 has another way to reference private data (besides global variables).
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
24 """
195
45f43f755e5c Initial revision
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
429
bb308e7b0039 Added a comment about a possible interface change.
Guido van Rossum <guido@python.org>
parents: 218
diff changeset
26 # XXX The timefunc and delayfunc should have been defined as methods
bb308e7b0039 Added a comment about a possible interface change.
Guido van Rossum <guido@python.org>
parents: 218
diff changeset
27 # XXX so you can define new kinds of schedulers using subclassing
bb308e7b0039 Added a comment about a possible interface change.
Guido van Rossum <guido@python.org>
parents: 218
diff changeset
28 # XXX instead of having to define a module or class just to hold
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
29 # XXX the global state of your particular time and delay functions.
429
bb308e7b0039 Added a comment about a possible interface change.
Guido van Rossum <guido@python.org>
parents: 218
diff changeset
30
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
31 import heapq
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
32 from collections import namedtuple
1006
903071377d29 Added a _v21 def to FL.py and added two new input field types
Guido van Rossum <guido@python.org>
parents: 559
diff changeset
33
16613
f68dbffff927 bunch more __all__ lists
Skip Montanaro <skip@pobox.com>
parents: 15872
diff changeset
34 __all__ = ["scheduler"]
f68dbffff927 bunch more __all__ lists
Skip Montanaro <skip@pobox.com>
parents: 15872
diff changeset
35
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
36 Event = namedtuple('Event', 'time, priority, action, argument')
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
37
531
8331076cfe15 New class syntax.
Guido van Rossum <guido@python.org>
parents: 429
diff changeset
38 class scheduler:
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
39 def __init__(self, timefunc, delayfunc):
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
40 """Initialize a new instance, passing the time and delay
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
41 functions"""
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
42 self._queue = []
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
43 self.timefunc = timefunc
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
44 self.delayfunc = delayfunc
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
45
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
46 def enterabs(self, time, priority, action, argument):
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
47 """Enter a new event in the queue at an absolute time.
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
48
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
49 Returns an ID for the event which can be used to remove it,
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
50 if necessary.
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
51
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
52 """
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
53 event = Event(time, priority, action, argument)
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
54 heapq.heappush(self._queue, event)
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
55 return event # The ID
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
56
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
57 def enter(self, delay, priority, action, argument):
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
58 """A variant that specifies the time as a relative time.
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
59
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
60 This is actually the more commonly used interface.
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
61
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
62 """
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
63 time = self.timefunc() + delay
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
64 return self.enterabs(time, priority, action, argument)
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
65
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
66 def cancel(self, event):
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
67 """Remove an event from the queue.
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
68
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
69 This must be presented the ID as returned by enter().
54346
3b612569d536 Merged revisions 72932 via svnmerge from
Georg Brandl <georg@python.org>
parents: 46891
diff changeset
70 If the event is not in the queue, this raises ValueError.
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
71
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
72 """
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
73 self._queue.remove(event)
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
74 heapq.heapify(self._queue)
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
75
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
76 def empty(self):
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
77 """Check whether the queue is empty."""
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
78 return not self._queue
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
79
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
80 def run(self):
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
81 """Execute events until the queue is empty.
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
82
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
83 When there is a positive delay until the first event, the
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
84 delay function is called and the event is left in the queue;
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
85 otherwise, the event is removed from the queue and executed
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
86 (its action function is called, passing it the argument). If
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
87 the delay function returns prematurely, it is simply
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
88 restarted.
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
89
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
90 It is legal for both the delay function and the action
72984
86e3943d0d5b Remove duplication.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68255
diff changeset
91 function to modify the queue or to raise an exception;
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
92 exceptions are not caught but the scheduler's state remains
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
93 well-defined so run() may be called again.
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
94
43493
9e6020bb2352 Update docstring of sched, also remove an unused assignment.
Georg Brandl <georg@python.org>
parents: 41073
diff changeset
95 A questionable hack is added to allow other threads to run:
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
96 just after an event is executed, a delay of 0 is executed, to
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
97 avoid monopolizing the CPU when other threads are also
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
98 runnable.
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
99
15872
3685ef2a55a4 Whitespace normalization.
Tim Peters <tim.peters@gmail.com>
parents: 11708
diff changeset
100 """
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
101 # localize variable access to minimize overhead
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
102 # and to improve thread safety
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
103 q = self._queue
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
104 delayfunc = self.delayfunc
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
105 timefunc = self.timefunc
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
106 pop = heapq.heappop
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
107 while q:
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
108 time, priority, action, argument = checked_event = q[0]
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
109 now = timefunc()
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
110 if now < time:
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
111 delayfunc(time - now)
11063
7ed6fba8265c While we're at it, convert to docstrings and set the indentation level
Fred Drake <fdrake@acm.org>
parents: 1746
diff changeset
112 else:
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
113 event = pop(q)
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
114 # Verify that the event was not removed or altered
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
115 # by another thread after we last looked at q[0].
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
116 if event is checked_event:
43493
9e6020bb2352 Update docstring of sched, also remove an unused assignment.
Georg Brandl <georg@python.org>
parents: 41073
diff changeset
117 action(*argument)
34176
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
118 delayfunc(0) # Let other threads run
05bc8acaf0bb Refactor:
Raymond Hettinger <python@rcn.com>
parents: 28089
diff changeset
119 else:
46892
49ff1fc00c6c #2803: fix heappush invocation (backport).
Georg Brandl <georg@python.org>
parents: 41073
diff changeset
120 heapq.heappush(q, event)
44727
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
121
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
122 @property
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
123 def queue(self):
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
124 """An ordered list of upcoming events.
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
125
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
126 Events are named tuples with fields for:
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
127 time, priority, action, arguments
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
128
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
129 """
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
130 # Use heapq to sort the queue rather than using 'sorted(self._queue)'.
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
131 # With heapq, two events scheduled at the same time will show in
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
132 # the actual order they would be retrieved.
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
133 events = self._queue[:]
222b918ce092 Issue #1861: Add read-only attribute listing upcoming events in the order they will be run.
Raymond Hettinger <python@rcn.com>
parents: 43493
diff changeset
134 return map(heapq.heappop, [events]*len(events))