1 :mod:`sched` --- Event scheduler 2 ================================ 3 4 .. module:: sched 5 :synopsis: General purpose event scheduler. 6 .. sectionauthor:: Moshe Zadka <moshez (a] zadka.site.co.il> 7 8 .. index:: single: event scheduling 9 10 **Source code:** :source:`Lib/sched.py` 11 12 -------------- 13 14 The :mod:`sched` module defines a class which implements a general purpose event 15 scheduler: 16 17 .. class:: scheduler(timefunc, delayfunc) 18 19 The :class:`scheduler` class defines a generic interface to scheduling events. 20 It needs two functions to actually deal with the "outside world" --- *timefunc* 21 should be callable without arguments, and return a number (the "time", in any 22 units whatsoever). The *delayfunc* function should be callable with one 23 argument, compatible with the output of *timefunc*, and should delay that many 24 time units. *delayfunc* will also be called with the argument ``0`` after each 25 event is run to allow other threads an opportunity to run in multi-threaded 26 applications. 27 28 Example:: 29 30 >>> import sched, time 31 >>> s = sched.scheduler(time.time, time.sleep) 32 >>> def print_time(): print "From print_time", time.time() 33 ... 34 >>> def print_some_times(): 35 ... print time.time() 36 ... s.enter(5, 1, print_time, ()) 37 ... s.enter(10, 1, print_time, ()) 38 ... s.run() 39 ... print time.time() 40 ... 41 >>> print_some_times() 42 930343690.257 43 From print_time 930343695.274 44 From print_time 930343700.273 45 930343700.276 46 47 In multi-threaded environments, the :class:`scheduler` class has limitations 48 with respect to thread-safety, inability to insert a new task before 49 the one currently pending in a running scheduler, and holding up the main 50 thread until the event queue is empty. Instead, the preferred approach 51 is to use the :class:`threading.Timer` class instead. 52 53 Example:: 54 55 >>> import time 56 >>> from threading import Timer 57 >>> def print_time(): 58 ... print "From print_time", time.time() 59 ... 60 >>> def print_some_times(): 61 ... print time.time() 62 ... Timer(5, print_time, ()).start() 63 ... Timer(10, print_time, ()).start() 64 ... time.sleep(11) # sleep while time-delay events execute 65 ... print time.time() 66 ... 67 >>> print_some_times() 68 930343690.257 69 From print_time 930343695.274 70 From print_time 930343700.273 71 930343701.301 72 73 74 .. _scheduler-objects: 75 76 Scheduler Objects 77 ----------------- 78 79 :class:`scheduler` instances have the following methods and attributes: 80 81 82 .. method:: scheduler.enterabs(time, priority, action, argument) 83 84 Schedule a new event. The *time* argument should be a numeric type compatible 85 with the return value of the *timefunc* function passed to the constructor. 86 Events scheduled for the same *time* will be executed in the order of their 87 *priority*. 88 89 Executing the event means executing ``action(*argument)``. *argument* must be a 90 sequence holding the parameters for *action*. 91 92 Return value is an event which may be used for later cancellation of the event 93 (see :meth:`cancel`). 94 95 96 .. method:: scheduler.enter(delay, priority, action, argument) 97 98 Schedule an event for *delay* more time units. Other than the relative time, the 99 other arguments, the effect and the return value are the same as those for 100 :meth:`enterabs`. 101 102 103 .. method:: scheduler.cancel(event) 104 105 Remove the event from the queue. If *event* is not an event currently in the 106 queue, this method will raise a :exc:`ValueError`. 107 108 109 .. method:: scheduler.empty() 110 111 Return true if the event queue is empty. 112 113 114 .. method:: scheduler.run() 115 116 Run all scheduled events. This function will wait (using the :func:`delayfunc` 117 function passed to the constructor) for the next event, then execute it and so 118 on until there are no more scheduled events. 119 120 Either *action* or *delayfunc* can raise an exception. In either case, the 121 scheduler will maintain a consistent state and propagate the exception. If an 122 exception is raised by *action*, the event will not be attempted in future calls 123 to :meth:`run`. 124 125 If a sequence of events takes longer to run than the time available before the 126 next event, the scheduler will simply fall behind. No events will be dropped; 127 the calling code is responsible for canceling events which are no longer 128 pertinent. 129 130 .. attribute:: scheduler.queue 131 132 Read-only attribute returning a list of upcoming events in the order they 133 will be run. Each event is shown as a :term:`named tuple` with the 134 following fields: time, priority, action, argument. 135 136 .. versionadded:: 2.6 137
