Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`sched` --- Event scheduler |
| 2 | ================================ |
| 3 | |
| 4 | .. module:: sched |
| 5 | :synopsis: General purpose event scheduler. |
| 6 | .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| 7 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. index:: single: event scheduling |
| 9 | |
Raymond Hettinger | 1048094 | 2011-01-10 03:26:08 +0000 | [diff] [blame] | 10 | **Source code:** :source:`Lib/sched.py` |
| 11 | |
Raymond Hettinger | 4f707fd | 2011-01-10 19:54:11 +0000 | [diff] [blame] | 12 | -------------- |
| 13 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | The :mod:`sched` module defines a class which implements a general purpose event |
| 15 | scheduler: |
| 16 | |
Terry Jan Reedy | adecf3f | 2013-03-09 02:14:27 -0500 | [diff] [blame] | 17 | .. class:: scheduler(timefunc=time.monotonic, delayfunc=time.sleep) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Terry Jan Reedy | adecf3f | 2013-03-09 02:14:27 -0500 | [diff] [blame] | 22 | units whatsoever). If time.monotonic is not available, the *timefunc* default |
| 23 | is time.time instead. The *delayfunc* function should be callable with one |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | argument, compatible with the output of *timefunc*, and should delay that many |
| 25 | time units. *delayfunc* will also be called with the argument ``0`` after each |
| 26 | event is run to allow other threads an opportunity to run in multi-threaded |
| 27 | applications. |
| 28 | |
Giampaolo Rodola' | be55d99 | 2011-11-22 13:33:34 +0100 | [diff] [blame] | 29 | .. versionchanged:: 3.3 |
| 30 | *timefunc* and *delayfunc* parameters are optional. |
Serhiy Storchaka | e912496 | 2012-12-29 20:57:52 +0200 | [diff] [blame] | 31 | |
Giampaolo Rodola' | 73520d5 | 2011-12-14 13:34:26 +0100 | [diff] [blame] | 32 | .. versionchanged:: 3.3 |
| 33 | :class:`scheduler` class can be safely used in multi-threaded |
| 34 | environments. |
Giampaolo Rodola' | be55d99 | 2011-11-22 13:33:34 +0100 | [diff] [blame] | 35 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | Example:: |
| 37 | |
| 38 | >>> import sched, time |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 39 | >>> s = sched.scheduler(time.time, time.sleep) |
Serhiy Storchaka | c04957b | 2012-12-29 21:13:45 +0200 | [diff] [blame] | 40 | >>> def print_time(a='default'): |
| 41 | ... print("From print_time", time.time(), a) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | ... |
| 43 | >>> def print_some_times(): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 44 | ... print(time.time()) |
Serhiy Storchaka | c04957b | 2012-12-29 21:13:45 +0200 | [diff] [blame] | 45 | ... s.enter(10, 1, print_time) |
| 46 | ... s.enter(5, 2, print_time, argument=('positional',)) |
| 47 | ... s.enter(5, 1, print_time, kwargs={'a': 'keyword'}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | ... s.run() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 49 | ... print(time.time()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | ... |
| 51 | >>> print_some_times() |
| 52 | 930343690.257 |
Serhiy Storchaka | c04957b | 2012-12-29 21:13:45 +0200 | [diff] [blame] | 53 | From print_time 930343695.274 positional |
| 54 | From print_time 930343695.275 keyword |
| 55 | From print_time 930343700.273 default |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | 930343700.276 |
| 57 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 58 | .. _scheduler-objects: |
| 59 | |
| 60 | Scheduler Objects |
| 61 | ----------------- |
| 62 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 63 | :class:`scheduler` instances have the following methods and attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
| 65 | |
Serhiy Storchaka | c04957b | 2012-12-29 21:13:45 +0200 | [diff] [blame] | 66 | .. method:: scheduler.enterabs(time, priority, action, argument=(), kwargs={}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 67 | |
| 68 | Schedule a new event. The *time* argument should be a numeric type compatible |
| 69 | with the return value of the *timefunc* function passed to the constructor. |
| 70 | Events scheduled for the same *time* will be executed in the order of their |
| 71 | *priority*. |
| 72 | |
Giampaolo Rodola' | be55d99 | 2011-11-22 13:33:34 +0100 | [diff] [blame] | 73 | Executing the event means executing ``action(*argument, **kwargs)``. |
Serhiy Storchaka | 75b936e | 2013-01-02 12:31:26 +0200 | [diff] [blame] | 74 | *argument* is a sequence holding the positional arguments for *action*. |
| 75 | *kwargs* is a dictionary holding the keyword arguments for *action*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
| 77 | Return value is an event which may be used for later cancellation of the event |
| 78 | (see :meth:`cancel`). |
| 79 | |
Giampaolo Rodola' | be55d99 | 2011-11-22 13:33:34 +0100 | [diff] [blame] | 80 | .. versionchanged:: 3.3 |
| 81 | *argument* parameter is optional. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 82 | |
Giampaolo Rodola' | be55d99 | 2011-11-22 13:33:34 +0100 | [diff] [blame] | 83 | .. versionadded:: 3.3 |
| 84 | *kwargs* parameter was added. |
| 85 | |
| 86 | |
Serhiy Storchaka | c04957b | 2012-12-29 21:13:45 +0200 | [diff] [blame] | 87 | .. method:: scheduler.enter(delay, priority, action, argument=(), kwargs={}) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
Ezio Melotti | d3cf0db | 2011-10-28 12:22:25 +0300 | [diff] [blame] | 89 | Schedule an event for *delay* more time units. Other than the relative time, the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | other arguments, the effect and the return value are the same as those for |
| 91 | :meth:`enterabs`. |
| 92 | |
Giampaolo Rodola' | be55d99 | 2011-11-22 13:33:34 +0100 | [diff] [blame] | 93 | .. versionchanged:: 3.3 |
| 94 | *argument* parameter is optional. |
| 95 | |
| 96 | .. versionadded:: 3.3 |
| 97 | *kwargs* parameter was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | |
| 99 | .. method:: scheduler.cancel(event) |
| 100 | |
| 101 | Remove the event from the queue. If *event* is not an event currently in the |
Georg Brandl | c38a000 | 2009-05-26 07:51:03 +0000 | [diff] [blame] | 102 | queue, this method will raise a :exc:`ValueError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
| 104 | |
| 105 | .. method:: scheduler.empty() |
| 106 | |
| 107 | Return true if the event queue is empty. |
| 108 | |
| 109 | |
Giampaolo Rodola' | 556ba04 | 2011-12-14 14:38:45 +0100 | [diff] [blame] | 110 | .. method:: scheduler.run(blocking=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | |
Giampaolo Rodola' | 556ba04 | 2011-12-14 14:38:45 +0100 | [diff] [blame] | 112 | Run all scheduled events. This method will wait (using the :func:`delayfunc` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | function passed to the constructor) for the next event, then execute it and so |
| 114 | on until there are no more scheduled events. |
| 115 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 116 | If *blocking* is false executes the scheduled events due to expire soonest |
Giampaolo Rodola' | a4e0188 | 2012-03-15 13:05:41 +0100 | [diff] [blame] | 117 | (if any) and then return the deadline of the next scheduled call in the |
| 118 | scheduler (if any). |
Giampaolo Rodola' | 556ba04 | 2011-12-14 14:38:45 +0100 | [diff] [blame] | 119 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Giampaolo Rodola' | 556ba04 | 2011-12-14 14:38:45 +0100 | [diff] [blame] | 130 | .. versionadded:: 3.3 |
| 131 | *blocking* parameter was added. |
| 132 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 133 | .. attribute:: scheduler.queue |
| 134 | |
| 135 | Read-only attribute returning a list of upcoming events in the order they |
| 136 | will be run. Each event is shown as a :term:`named tuple` with the |
Serhiy Storchaka | e912496 | 2012-12-29 20:57:52 +0200 | [diff] [blame] | 137 | following fields: time, priority, action, argument, kwargs. |