blob: 29ccc2add3a8fb1fcaf349a9f789a697e7db3260 [file] [log] [blame]
Guido van Rossum2d844d11991-04-07 13:41:50 +00001# Module sched -- a generally useful event scheduler class
2
3# Each instance of this class manages its own queue.
4# No multi-threading is implied; you are supposed to hack that
5# yourself, or use a single instance per application.
6#
7# Each instance is parametrized with two functions, one that is
8# supposed to return the current time, one that is supposed to
9# implement a delay. You can implement fine- or course-grained
10# real-time scheduling by substituting time and sleep or millitimer
11# and millisleep from the built-in module time, or you can implement
12# simulated time by writing your own functions. This can also be
13# used to integrate scheduling with STDWIN events; the delay function
Guido van Rossuma31b9cc1991-04-21 19:33:53 +000014# is allowed to modify the queue. Time can be expressed as
15# integers or floating point numbers, as long as it is consistent.
Guido van Rossum2d844d11991-04-07 13:41:50 +000016
17# Events are specified by tuples (time, priority, action, argument).
18# As in UNIX, lower priority numbers mean higher priority; in this
19# way the queue can be maintained fully sorted. Execution of the
20# event means calling the action function, passing it the argument.
21# Remember that in Python, multiple function arguments can be packed
22# in a tuple. The action function may be an instance method so it
23# has another way to reference private data (besides global variables).
24# Parameterless functions or methods cannot be used, however.
25
Guido van Rossum5478cc61991-11-12 15:37:53 +000026# XXX The timefunc and delayfunc should have been defined as methods
27# XXX so you can define new kinds of schedulers using subclassing
28# XXX instead of having to define a module or class just to hold
29# XXX the global state of your particular time and delay functtions.
30
Guido van Rossum4e160981992-09-02 20:43:20 +000031import bisect
32
Guido van Rossumce084481991-12-26 13:06:29 +000033class scheduler:
Guido van Rossum2d844d11991-04-07 13:41:50 +000034 #
35 # Initialize a new instance, passing the time and delay functions
36 #
Guido van Rossum89a78691992-12-14 12:57:56 +000037 def init(self, timefunc, delayfunc):
Guido van Rossum2d844d11991-04-07 13:41:50 +000038 self.queue = []
39 self.timefunc = timefunc
40 self.delayfunc = delayfunc
41 return self
42 #
43 # Enter a new event in the queue at an absolute time.
44 # Returns an ID for the event which can be used
45 # to remove it, if necessary.
46 #
Guido van Rossum89a78691992-12-14 12:57:56 +000047 def enterabs(self, time, priority, action, argument):
48 event = time, priority, action, argument
Guido van Rossum4e160981992-09-02 20:43:20 +000049 bisect.insort(self.queue, event)
Guido van Rossum2d844d11991-04-07 13:41:50 +000050 return event # The ID
51 #
52 # A variant that specifies the time as a relative time.
53 # This is actually the more commonly used interface.
54 #
Guido van Rossum89a78691992-12-14 12:57:56 +000055 def enter(self, delay, priority, action, argument):
Guido van Rossum2d844d11991-04-07 13:41:50 +000056 time = self.timefunc() + delay
57 return self.enterabs(time, priority, action, argument)
58 #
59 # Remove an event from the queue.
60 # This must be presented the ID as returned by enter().
61 # If the event is not in the queue, this raises RuntimeError.
62 #
63 def cancel(self, event):
64 self.queue.remove(event)
65 #
66 # Check whether the queue is empty.
67 #
68 def empty(self):
Guido van Rossumbdfcfcc1992-01-01 19:35:13 +000069 return len(self.queue) == 0
Guido van Rossum2d844d11991-04-07 13:41:50 +000070 #
71 # Run: execute events until the queue is empty.
72 #
73 # When there is a positive delay until the first event, the
74 # delay function is called and the event is left in the queue;
75 # otherwise, the event is removed from the queue and executed
76 # (its action function is called, passing it the argument).
77 # If the delay function returns prematurely, it is simply
78 # restarted.
79 #
80 # It is legal for both the delay function and the action
81 # function to to modify the queue or to raise an exception;
82 # exceptions are not caught but the scheduler's state
83 # remains well-defined so run() may be called again.
84 #
Guido van Rossuma31b9cc1991-04-21 19:33:53 +000085 # A questionably hack is added to allow other threads to run:
86 # just after an event is executed, a delay of 0 is executed,
87 # to avoid monopolizing the CPU when other threads are also
88 # runnable.
89 #
Guido van Rossum2d844d11991-04-07 13:41:50 +000090 def run(self):
91 q = self.queue
92 while q:
93 time, priority, action, argument = q[0]
94 now = self.timefunc()
95 if now < time:
96 self.delayfunc(time - now)
97 else:
98 del q[0]
Guido van Rossum89a78691992-12-14 12:57:56 +000099 void = apply(action, argument)
Guido van Rossuma31b9cc1991-04-21 19:33:53 +0000100 self.delayfunc(0) # Let other threads run
Guido van Rossum2d844d11991-04-07 13:41:50 +0000101 #