sched — Event scheduler

Source code:Lib/sched.py

Thesched module defines a class which implements a general purpose eventscheduler:

classsched.scheduler(timefunc=time.monotonic,delayfunc=time.sleep)

Thescheduler class defines a generic interface to scheduling events.It needs two functions to actually deal with the “outside world” —timefuncshould be callable without arguments, and return a number (the “time”, in anyunits whatsoever). Thedelayfunc function should be callable with oneargument, compatible with the output oftimefunc, and should delay that manytime units.delayfunc will also be called with the argument0 after eachevent is run to allow other threads an opportunity to run in multi-threadedapplications.

Changed in version 3.3:timefunc anddelayfunc parameters are optional.

Changed in version 3.3:scheduler class can be safely used in multi-threadedenvironments.

Example:

>>>importsched,time>>>s=sched.scheduler(time.time,time.sleep)>>>defprint_time(a='default'):...print("From print_time",time.time(),a)...>>>defprint_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.3640375From print_time 1652342830.3642538 second enterabsFrom print_time 1652342830.3643398 first enterabsFrom print_time 1652342835.3694863 positionalFrom print_time 1652342835.3696074 keywordFrom print_time 1652342840.369612 default1652342840.3697174

Scheduler Objects

scheduler instances have the following methods and attributes:

scheduler.enterabs(time,priority,action,argument=(),kwargs={})

Schedule a new event. Thetime argument should be a numeric type compatiblewith the return value of thetimefunc function passed to the constructor.Events scheduled for the sametime will be executed in the order of theirpriority. A lower number represents a higher priority.

Executing the event means executingaction(*argument,**kwargs).argument is a sequence holding the positional arguments foraction.kwargs is a dictionary holding the keyword arguments foraction.

Return value is an event which may be used for later cancellation of the event(seecancel()).

Changed in version 3.3:argument parameter is optional.

Changed in version 3.3:kwargs parameter was added.

scheduler.enter(delay,priority,action,argument=(),kwargs={})

Schedule an event fordelay more time units. Other than the relative time, theother arguments, the effect and the return value are the same as those forenterabs().

Changed in version 3.3:argument parameter is optional.

Changed in version 3.3:kwargs parameter was added.

scheduler.cancel(event)

Remove the event from the queue. Ifevent is not an event currently in thequeue, this method will raise aValueError.

scheduler.empty()

ReturnTrue if the event queue is empty.

scheduler.run(blocking=True)

Run all scheduled events. This method will wait (using thedelayfuncfunction passed to the constructor) for the next event, then execute it and soon until there are no more scheduled events.

Ifblocking is false executes the scheduled events due to expire soonest(if any) and then return the deadline of the next scheduled call in thescheduler (if any).

Eitheraction ordelayfunc can raise an exception. In either case, thescheduler will maintain a consistent state and propagate the exception. If anexception is raised byaction, the event will not be attempted in future callstorun().

If a sequence of events takes longer to run than the time available before thenext event, the scheduler will simply fall behind. No events will be dropped;the calling code is responsible for canceling events which are no longerpertinent.

Changed in version 3.3:blocking parameter was added.

scheduler.queue

Read-only attribute returning a list of upcoming events in the order theywill be run. Each event is shown as anamed tuple with thefollowing fields: time, priority, action, argument, kwargs.