sched --- イベントスケジューラー

ソースコード: Lib/sched.py

The sched module defines a class which implements a general purpose event scheduler:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

scheduler クラスはイベントをスケジュールするための一般的なインターフェースを定義します。それは "外の世界" を実際に扱うための2つの関数を必要とします --- timefunc は引数なしで呼ばれて 1 つの数値を返す callable オブジェクトでなければなりません (戻り値は任意の単位で「時間」を表します)。 delayfunc は 1 つの引数を持つ callable オブジェクトでなければならず、その時間だけ遅延する必要があります (引数は timefunc の出力と互換)。 delayfunc は、各々のイベントが実行された後に引数 0 で呼ばれることがあります。これは、マルチスレッドアプリケーションの中で他のスレッドが実行する機会を与えるためです。

バージョン 3.3 で変更: timefunc と delayfunc がオプション引数になりました。

バージョン 3.3 で変更: scheduler クラスをマルチスレッド環境で安全に使用出来るようになりました。

以下はプログラム例です:

>>> import sched, time
>>> s = sched.scheduler(time.time, 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

スケジューラオブジェクト

scheduler インスタンスは以下のメソッドと属性を持っています:

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

新しいイベントをスケジュールします。 引数 time は、コンストラクタへ渡された timefunc の戻り値と互換な数値型でなければいけません。 同じ time によってスケジュールされたイベントは、それらの priority によって実行されます。 数値の小さい方が高い優先度となります。

イベントを実行することは、 action(*argument, **kwargs) を実行することを意味します。 argument は action のための位置引数を保持するシーケンスでなければいけません。 kwargs は action のためのキーワード引数を保持する辞書でなければいけません。

戻り値は、後にイベントをキャンセルする時に使われる可能性のあるイベントです (cancel() を参照)。

バージョン 3.3 で変更: argument 引数が任意になりました。

バージョン 3.3 で変更: kwargs 引数が追加されました。

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

時間単位以上の delay でイベントをスケジュールします。相対的時間以外の、引数、効果、戻り値は、 enterabs() に対するものと同じです。

バージョン 3.3 で変更: argument 引数が任意になりました。

バージョン 3.3 で変更: kwargs 引数が追加されました。

scheduler.cancel(event)

キューからイベントを消去します。もし event がキューにある現在のイベントでないならば、このメソッドは ValueError を送出します。

scheduler.empty()

もしイベントキューが空ならば、 True を返します。

scheduler.run(blocking=True)

すべてのスケジュールされたイベントを実行します。このメソッドは次のイベントを待ち、それを実行し、スケジュールされたイベントがなくなるまで同じことを繰り返します。(イベントの待機は、 コンストラクタへ渡された関数 delayfunc を使うことで行います。)

If blocking is false, immediately executes all events in the queue which have a time value less than or equal to the current timefunc value (if any) and returns the difference between the current timefunc value and the time value of the next scheduled event in the scheduler's event queue. If the queue is empty, returns None.

action あるいは delayfunc は例外を投げることができます。いずれの場合も、スケジューラは一貫した状態を維持し、例外を伝播するでしょう。例外が action によって投げられる場合、イベントは run() への呼出しを未来に行なわないでしょう。

イベントのシーケンスが、次イベントの前に、利用可能時間より実行時間が長いと、スケジューラは単に遅れることになるでしょう。イベントが落ちることはありません; 呼出しコードはもはや適切でないキャンセルイベントに対して責任があります。

バージョン 3.3 で変更: blocking 引数が追加されました。

scheduler.queue

読み出し専用の属性で、これから起こるイベントが実行される順序で格納されたリストを返します。各イベントは、次の属性 time, priority, action, argument, kwargs を持った named tuple の形式になります。