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