diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Fsched.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Fsched.html | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Fsched.html b/devdocs/python~3.12/library%2Fsched.html new file mode 100644 index 00000000..5f1ae2a6 --- /dev/null +++ b/devdocs/python~3.12/library%2Fsched.html @@ -0,0 +1,51 @@ + <span id="sched-event-scheduler"></span><h1>sched — Event scheduler</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/sched.py">Lib/sched.py</a></p> <p>The <a class="reference internal" href="#module-sched" title="sched: General purpose event scheduler."><code>sched</code></a> module defines a class which implements a general purpose event scheduler:</p> <dl class="py class"> <dt class="sig sig-object py" id="sched.scheduler"> +<code>class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)</code> </dt> <dd> +<p>The <a class="reference internal" href="#sched.scheduler" title="sched.scheduler"><code>scheduler</code></a> class defines a generic interface to scheduling events. It needs two functions to actually deal with the “outside world” — <em>timefunc</em> should be callable without arguments, and return a number (the “time”, in any units whatsoever). The <em>delayfunc</em> function should be callable with one argument, compatible with the output of <em>timefunc</em>, and should delay that many time units. <em>delayfunc</em> will also be called with the argument <code>0</code> after each event is run to allow other threads an opportunity to run in multi-threaded applications.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>timefunc</em> and <em>delayfunc</em> parameters are optional.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><a class="reference internal" href="#sched.scheduler" title="sched.scheduler"><code>scheduler</code></a> class can be safely used in multi-threaded environments.</p> </div> </dd> +</dl> <p>Example:</p> <pre data-language="python">>>> import sched, time +>>> s = sched.scheduler(time.monotonic, time.sleep) +>>> def print_time(a='default'): +... print("From print_time", time.time(), a) +... +>>> def print_some_times(): +... print(time.time()) +... s.enter(10, 1, print_time) +... s.enter(5, 2, print_time, argument=('positional',)) +... # despite having higher priority, 'keyword' runs after 'positional' as enter() is relative +... s.enter(5, 1, print_time, kwargs={'a': 'keyword'}) +... s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",)) +... s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",)) +... s.run() +... print(time.time()) +... +>>> print_some_times() +1652342830.3640375 +From print_time 1652342830.3642538 second enterabs +From print_time 1652342830.3643398 first enterabs +From print_time 1652342835.3694863 positional +From print_time 1652342835.3696074 keyword +From print_time 1652342840.369612 default +1652342840.3697174 +</pre> <section id="scheduler-objects"> <span id="id1"></span><h2>Scheduler Objects</h2> <p><a class="reference internal" href="#sched.scheduler" title="sched.scheduler"><code>scheduler</code></a> instances have the following methods and attributes:</p> <dl class="py method"> <dt class="sig sig-object py" id="sched.scheduler.enterabs"> +<code>scheduler.enterabs(time, priority, action, argument=(), kwargs={})</code> </dt> <dd> +<p>Schedule a new event. The <em>time</em> argument should be a numeric type compatible with the return value of the <em>timefunc</em> function passed to the constructor. Events scheduled for the same <em>time</em> will be executed in the order of their <em>priority</em>. A lower number represents a higher priority.</p> <p>Executing the event means executing <code>action(*argument, **kwargs)</code>. <em>argument</em> is a sequence holding the positional arguments for <em>action</em>. <em>kwargs</em> is a dictionary holding the keyword arguments for <em>action</em>.</p> <p>Return value is an event which may be used for later cancellation of the event (see <a class="reference internal" href="#sched.scheduler.cancel" title="sched.scheduler.cancel"><code>cancel()</code></a>).</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>argument</em> parameter is optional.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>kwargs</em> parameter was added.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="sched.scheduler.enter"> +<code>scheduler.enter(delay, priority, action, argument=(), kwargs={})</code> </dt> <dd> +<p>Schedule an event for <em>delay</em> more time units. Other than the relative time, the other arguments, the effect and the return value are the same as those for <a class="reference internal" href="#sched.scheduler.enterabs" title="sched.scheduler.enterabs"><code>enterabs()</code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>argument</em> parameter is optional.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>kwargs</em> parameter was added.</p> </div> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="sched.scheduler.cancel"> +<code>scheduler.cancel(event)</code> </dt> <dd> +<p>Remove the event from the queue. If <em>event</em> is not an event currently in the queue, this method will raise a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a>.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="sched.scheduler.empty"> +<code>scheduler.empty()</code> </dt> <dd> +<p>Return <code>True</code> if the event queue is empty.</p> </dd> +</dl> <dl class="py method"> <dt class="sig sig-object py" id="sched.scheduler.run"> +<code>scheduler.run(blocking=True)</code> </dt> <dd> +<p>Run all scheduled events. This method will wait (using the <em>delayfunc</em> function passed to the constructor) for the next event, then execute it and so on until there are no more scheduled events.</p> <p>If <em>blocking</em> is false executes the scheduled events due to expire soonest (if any) and then return the deadline of the next scheduled call in the scheduler (if any).</p> <p>Either <em>action</em> or <em>delayfunc</em> can raise an exception. In either case, the scheduler will maintain a consistent state and propagate the exception. If an exception is raised by <em>action</em>, the event will not be attempted in future calls to <a class="reference internal" href="#sched.scheduler.run" title="sched.scheduler.run"><code>run()</code></a>.</p> <p>If a sequence of events takes longer to run than the time available before the next event, the scheduler will simply fall behind. No events will be dropped; the calling code is responsible for canceling events which are no longer pertinent.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span><em>blocking</em> parameter was added.</p> </div> </dd> +</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="sched.scheduler.queue"> +<code>scheduler.queue</code> </dt> <dd> +<p>Read-only attribute returning a list of upcoming events in the order they will be run. Each event is shown as a <a class="reference internal" href="../glossary#term-named-tuple"><span class="xref std std-term">named tuple</span></a> with the following fields: time, priority, action, argument, kwargs.</p> </dd> +</dl> </section> <div class="_attribution"> + <p class="_attribution-p"> + © 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br> + <a href="https://docs.python.org/3.12/library/sched.html" class="_attribution-link">https://docs.python.org/3.12/library/sched.html</a> + </p> +</div> |