17.6. "sched" --- イベントスケジューラ
**************************************

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

======================================================================

"sched" モジュールは一般的な目的のためのイベントスケジューラを実装する
クラスを定義します:

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

   "scheduler" クラスはイベントをスケジュールするための一般的なインタ
   フェースを定義します。それは "外の世界" を実際に扱うための2つの関数
   を必要とします --- *timefunc* は引数なしで呼ばれて 1 つの数値を返す
   callable オブジェクトでなければなりません (戻り値は任意の単位で「時
   間」を表します)。 time.monotonic が利用出来ない場合、 *timefunc*
   のデフォルトには time.time が代わりに使われます。 *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',))
   ...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
   ...     s.run()
   ...     print(time.time())
   ...
   >>> print_some_times()
   930343690.257
   From print_time 930343695.274 positional
   From print_time 930343695.275 keyword
   From print_time 930343700.273 default
   930343700.276


17.6.1. スケジューラオブジェクト
================================

"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()" を使うことで行います。)

   *blocking* が False の場合、最も早く期限が来るスケジュールされたイ
   ベントを (存在する場合) 実行し、スケジューラ内で次にスケジュールさ
   れた呼び出しの期限を (存在する場合) 返します。

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

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

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

scheduler.queue

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