"concurrent.futures" --- 並列タスク実行
***************************************

Added in version 3.2.

**ソースコード:** Lib/concurrent/futures/thread.py、
Lib/concurrent/futures/process.py および
Lib/concurrent/futures/interpreter.py

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

"concurrent.futures" モジュールは、呼び出し可能オブジェクトを非同期に
実行するための高水準インターフェースを提供します。

非同期実行には、"ThreadPoolExecutor" または "InterpreterPoolExecutor"
によるスレッド、あるいは "ProcessPoolExecutor" による別プロセスを使え
ます。 いずれも、抽象クラス "Executor" で定義された同じインターフェー
スを実装しています。

"concurrent.futures.Future" と "asyncio.Future" を混同しないでください
。 後者は "asyncio" のタスクやコルーチンとともに使うよう設計されていま
す。 両者の詳しい比較は、asyncio の Future のドキュメントを参照してく
ださい。

利用可能な環境: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは
、WebAssembly プラットフォーム を見てください。


Executor オブジェクト
=====================

class concurrent.futures.Executor

   非同期呼び出しを実行するためのメソッドを提供する抽象クラスです。こ
   のクラスを直接使ってはならず、具象サブクラスを介して使います。

   submit(fn, /, *args, **kwargs)

      呼び出し可能オブジェクト *fn* を、 "fn(*args, **kwargs)" として
      実行するようにスケジュールし、呼び出し可能オブジェクトの実行を表
      現する "Future" オブジェクトを返します。

         with ThreadPoolExecutor(max_workers=1) as executor:
             future = executor.submit(pow, 323, 1235)
             print(future.result())

   map(fn, *iterables, timeout=None, chunksize=1, buffersize=None)

      "map(fn, *iterables)" と似ていますが、次の違いがあります:

      * 結果をまだ yield していない投入済みタスクの数を制限する
        *buffersize* が指定されていない限り、*iterables* の要素は遅延
        せず、直ちに収集されます。 バッファがいっぱいになると、バッフ
        ァから結果が yield されるまで *iterables* の反復処理は一時停止
        します。

      * *fn* は非同期に実行され、複数の *fn* の呼び出しが並行して行わ
        れる場合があります。

      もし "__next__()" が呼ばれその結果が元々の "Executor.map()" の呼
      び出しから *timeout* 秒経った後も利用できない場合、返されるイテ
      レータは "TimeoutError" を送出します。 *timeout* は整数または浮
      動小数点数です。 *timeout* を省略するか "None" を指定した場合、
      待ち時間に制限はありません。

      もし *fn* の呼び出しが例外を送出した場合、その例外はイテレータか
      ら値を受け取る時に送出されます。

      "ProcessPoolExecutor" を使う場合、このメソッドは *iterables* を
      複数のチャンクに分割し、それぞれを別々のタスクとしてプールに投入
      します。 *chunksize* を正の整数に設定すると、各チャンクのおおよ
      そのサイズを指定できます。 非常に長いイテラブルでは、*chunksize*
      に大きな値を使うと、デフォルトのサイズ 1 に比べて性能が大幅に向
      上する場合があります。 "ThreadPoolExecutor" と
      "InterpreterPoolExecutor" では、*chunksize* は効果がありません。

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

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

   shutdown(wait=True, *, cancel_futures=False)

      executor に対して、現在保留中のフューチャーが実行された後で、使
      用中のすべての資源を解放するように伝えます。シャットダウンにより
      後に "Executor.submit()" と "Executor.map()" を呼び出すと
      "RuntimeError" が送出されます。

      *wait* が "True" の場合、すべての未完了のフューチャの実行が完了
      して Executor に関連付けられたリソースが解放されるまで、このメソ
      ッドは返りません。 *wait* が "False" の場合、このメソッドはすぐ
      に返り、すべての未完了のフューチャの実行が完了したときに、
      Executor に関連付けられたリソースが解放されます。 *wait* の値に
      関係なく、すべての未完了のフューチャの実行が完了するまで Python
      プログラム全体は終了しません。

      *cancel_futures* が "True" の場合、このメソッドは executor がま
      だ実行を開始していない未完了のフューチャをすべてキャンセルします
      。 すでに完了したフューチャや実行中のフューチャは、
      *cancel_futures* の値にかかわらずキャンセルされません。

      *cancel_futures* と *wait* がともに "True" の場合、executor が実
      行を開始したフューチャはすべて、このメソッドが返る前に完了します
      。 残りのフューチャはキャンセルされます。

      "with" 文で executor を *コンテキストマネージャ* として使えば、
      このメソッドを明示的に呼び出す必要はありません。 "Executor" はシ
      ャットダウンされます (*wait* を "True" にして
      "Executor.shutdown()" を呼び出した場合と同様に待機します)。

         import shutil
         with ThreadPoolExecutor(max_workers=4) as e:
             e.submit(shutil.copy, 'src1.txt', 'dest1.txt')
             e.submit(shutil.copy, 'src2.txt', 'dest2.txt')
             e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
             e.submit(shutil.copy, 'src4.txt', 'dest4.txt')

      バージョン 3.9 で変更: *cancel_futures* パラメータが追加されまし
      た。


ThreadPoolExecutor
==================

"ThreadPoolExecutor" はスレッドのプールを使用して非同期に呼び出しを行
う、 "Executor" のサブクラスです。

"Future" に関連づけられた呼び出し可能オブジェクトが、別の "Future" の
結果を待つ時にデッドロックすることがあります。例:

   import time
   def wait_on_b():
       time.sleep(5)
       print(b.result())  # b は a を待っているため完了しない
       return 5

   def wait_on_a():
       time.sleep(5)
       print(a.result())  # a は b を待っているため完了しない
       return 6


   executor = ThreadPoolExecutor(max_workers=2)
   a = executor.submit(wait_on_b)
   b = executor.submit(wait_on_a)

以下でも同様です:

   def wait_on_future():
       f = executor.submit(pow, 5, 2)
       # ワーカースレッドは一つしかなく、この関数を実行しているため
       # この処理は完了しない
       print(f.result())

   executor = ThreadPoolExecutor(max_workers=1)
   future = executor.submit(wait_on_future)
   # 注意: future.result() を呼び出してもデッドロックが起こる。

   # 唯一のワーカースレッドはすでに wait_on_future() の終了を待っているためである

class concurrent.futures.ThreadPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=(), **ctxkwargs)

   最大で *max_workers* 個のスレッドを非同期実行に使う "Executor" のサ
   ブクラスです。

   "ThreadPoolExecutor" に登録されたすべてのスレッドは、インタープリタ
   の終了前に join されます。 この処理を行う終了ハンドラは、"atexit"
   で追加した終了ハンドラよりも *前に* 実行されることに注意してくださ
   い。 そのため、スレッドに正常終了を指示できるように、メインスレッド
   の例外を捕捉して処理しなければなりません。 この理由から、長時間実行
   するタスクには "ThreadPoolExecutor" を使わないことを推奨します。

   *initializer* は省略可能な呼び出し可能オブジェクトで、各ワーカース
   レッドの開始時に呼び出されます。 *initargs* は、この初期化処理に渡
   す引数のタプルです。 *initializer* が例外を送出した場合、現在未完了
   のジョブはすべて "BrokenThreadPool" を送出し、プールへの新たなジョ
   ブの投入も同じ例外を送出します。

   *ctxkwargs* は、"prepare_context()" に渡す追加のキーワード引数のマ
   ッピングで、ワーカーの実行コンテキストをカスタマイズできます。

   classmethod prepare_context(initializer, initargs)

      プールを使う executor でワーカーインスタンスを作成するために必要
      なコンテキストを設定します (例えば、スレッドやインタープリタによ
      る並行実行環境で使います)。

      Added in version 3.14.

   バージョン 3.5 で変更: *max_workers* が "None" か指定されない場合の
   デフォルト値はマシンのプロセッサの数に 5 を掛けたものになります。こ
   れは、 "ThreadPoolExecutor" は CPU の処理ではなく I/O をオーバーラ
   ップするのによく使用されるため、 "ProcessPoolExecutor" のワーカーの
   数よりもこのワーカーの数を増やすべきであるという想定に基づいていま
   す。

   バージョン 3.6 で変更: *thread_name_prefix* 引数が追加され、デバッ
   グしやすくなるようにプールから作られたワーカスレッド
   "threading.Thread" の名前を管理できるようになりました。

   バージョン 3.7 で変更: *initializer* と *initargs* 引数が追加されま
   した。

   バージョン 3.8 で変更: *max_workers* のデフォルト値が "min(32,
   os.cpu_count() + 4)" に変更されました。 このデフォルト値により、I/O
   バウンドのタスクには少なくとも 5 個のワーカーが確保されます。 GIL
   を解放する CPU バウンドのタスクには最大 32 個の CPU コアを利用しま
   す。 また、多数のコアを持つマシンで暗黙に大量のリソースを使うことを
   避けられます。ThreadPoolExecutor は、*max_workers* 個のワーカースレ
   ッドを起動する前に、待機中のワーカースレッドを再利用するようにもな
   りました。

   バージョン 3.13 で変更: *max_workers* のデフォルト値が "min(32,
   (os.process_cpu_count() or 1) + 4)" に変更されました。

   バージョン 3.14 で変更: "prepare_context()" クラスメソッドに追加の
   引数を渡すための *ctxkwargs* が追加されました。


ThreadPoolExecutor の例
-----------------------

   import concurrent.futures
   import urllib.request

   URLS = ['http://www.foxnews.com/',
           'http://www.cnn.com/',
           'http://europe.wsj.com/',
           'http://www.bbc.co.uk/',
           'http://nonexistent-subdomain.python.org/']

   # 一つのページを取得し、URL と内容を報告する
   def load_url(url, timeout):
       with urllib.request.urlopen(url, timeout=timeout) as conn:
           return conn.read()

   # with 文を使えばスレッドを速やかに後始末できる
   with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor:
       # 読み込みを開始し、各フューチャに URL を対応付ける
       future_to_url = {executor.submit(load_url, url, 60): url for url in URLS}
       for future in concurrent.futures.as_completed(future_to_url):
           url = future_to_url[future]
           try:
               data = future.result()
           except Exception as exc:
               print('%r generated an exception: %s' % (url, exc))
           else:
               print('%r page is %d bytes' % (url, len(data)))


InterpreterPoolExecutor
=======================

Added in version 3.14.

"InterpreterPoolExecutor" クラスは、インタープリタのプールを使って呼び
出しを非同期に実行します。 "ThreadPoolExecutor" のサブクラスなので、各
ワーカーはそれぞれのスレッドで動作します。 異なる点は、各ワーカーが専
用のインタープリタを持ち、それを使って各タスクを実行することです。

スレッドだけを使う代わりにインタープリタを使う最大の利点は、複数のコア
で真に並列実行できることです。 各インタープリタはそれぞれの *グローバ
ルインタープリタロック* を持ちます。 そのため、一つのインタープリタの
コードをある CPU コアで実行しながら、別のインタープリタのコードを他の
コアで、妨げられることなく実行できます。

その代わり、複数のインタープリタを使う並行コードの作成には、追加の手間
がかかる場合があります。 しかしこれは、インタープリタがいつ、どのよう
にやり取りするかを慎重に考え、共有するデータを明示する必要があるためで
す。 このことは、複数コアでの真の並列実行をはじめ、追加の手間に見合う
いくつかの利点につながります。 例えば、このように書かれたコードでは、
並行処理の振る舞いを考えやすくなる場合があります。 競合状態など、スレ
ッドを使う際の大きな問題のいくつかに対処せずに済むことも、大きな利点で
す。

各ワーカーのインタープリタは、他のすべてのインタープリタから分離されて
います。 「分離されている」とは、各インタープリタが独自の実行時の状態
を持ち、完全に独立して動作することです。 例えば、一つのインタープリタ
で "sys.stdout" をリダイレクトしても、他のインタープリタでは自動的にリ
ダイレクトされません。 一つのインタープリタでモジュールをインポートし
ても、他のインタープリタでは自動的にインポートされません。 そのモジュ
ールを必要とするインタープリタごとに、個別にインポートする必要がありま
す。 実際、あるインタープリタでインポートしたモジュールは、別のインタ
ープリタの同じモジュールとは完全に別のオブジェクトです。 これは "sys"
、"builtins"、さらには "__main__" にも当てはまります。

分離されているため、ミュータブルなオブジェクトやその他のデータを、複数
のインタープリタで同時に使うことはできません。 実質的に、インタープリ
タ間でそのようなオブジェクトやデータを共有することはできないということ
です。 各インタープリタはそれぞれのコピーを持たなければならず、コピー
間の変更は手動で同期する必要があります。 組み込みのシングルトン、文字
列、イミュータブルなオブジェクトからなるタプルなど、イミュータブルなオ
ブジェクトやデータにはこの制約がありません。

インタープリタ間の通信や同期には、**PEP 734** で提案されたような専用の
ツールを使うのが最も効率的です。 効率は劣りますが、"pickle" でシリアラ
イズしてから、共有の "ソケット" や "パイプ" を介してバイト列を送る方法
もあります。

class concurrent.futures.InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())

   最大 *max_workers* 個のスレッドからなるプールを使い、呼び出しを非同
   期に実行する "ThreadPoolExecutor" のサブクラスです。 各スレッドは専
   用のインタープリタでタスクを実行します。 ワーカーのインタープリタは
   互いに分離されているため、それぞれが独自の実行時の状態を持ち、ミュ
   ータブルなオブジェクトやその他のデータを共有できません。 各インター
   プリタはそれぞれの *グローバルインタープリタロック* を持つため、こ
   の executor で実行するコードは複数のコアで真に並列実行できます。

   省略可能な *initializer* と *initargs* 引数の意味は
   "ThreadPoolExecutor" と同じです。 初期化処理は各ワーカーの作成時に
   実行されますが、この場合はワーカーのインタープリタ内で実行されます
   。 executor は、*initializer* と *initargs* をワーカーのインタープ
   リタに送る際に "pickle" でシリアライズします。

   注釈:

     executor は、*initializer* で捕捉されなかった例外を
     "ExecutionFailed" に置き換える場合があります。

   親クラス "ThreadPoolExecutor" のその他の注意事項も当てはまります。

"submit()" と "map()" は通常どおり動作しますが、ワーカーが呼び出し可能
オブジェクトと引数を自分のインタープリタに送る際に "pickle" でシリアラ
イズする点が異なります。 戻り値を送り返す際にも、同様にシリアライズし
ます。

ワーカーが実行中のタスクで捕捉されない例外が発生すると、ワーカーは常に
その例外をそのまま保持しようとします。 保持できた場合は、元の例外の要
約を含む、対応する "ExecutionFailed" インスタンスを "__cause__" にも設
定します。 まれに元の例外をそのまま保持できない場合は、対応する
"ExecutionFailed" インスタンスを直接保持します。


ProcessPoolExecutor
===================

"ProcessPoolExecutor"  はプロセスプールを使って非同期呼び出しを実施す
る "Executor" のサブクラスです。"ProcessPoolExecutor" は
"multiprocessing" モジュールを利用します。このため *Global Interpreter
Lock* を回避することができますが、pickle 化できるオブジェクトしか実行
したり返したりすることができません。

"__main__" モジュールはワーカサブプロセスでインポート可能でなければな
りません。 すなわち、 "ProcessPoolExecutor" は対話的インタープリタでは
動きません。

"ProcessPoolExecutor" に渡された呼び出し可能オブジェクトから
"Executor" や "Future" メソッドを呼ぶとデッドロックに陥ります。

"ProcessPoolExecutor" の "submit()" と "map()" を使う際には、
"multiprocessing.Process" と同様に、関数と引数が pickle 化可能でなけれ
ばならないという制約があることに注意してください。 REPL で定義した関数
や lambda が動作することは期待できません。

class concurrent.futures.ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)

   最大 *max_workers* 個のプロセスからなるプールを使い、呼び出しを非同
   期に実行する "Executor" のサブクラスです。 *max_workers* が "None"
   または省略された場合、デフォルトで "os.process_cpu_count()" が使わ
   れます。 *max_workers* が "0" 以下の場合は "ValueError" を送出しま
   す。 Windows では、*max_workers* は "61" 以下でなければなりません。
   そうでない場合は "ValueError" を送出します。 *max_workers* が
   "None" の場合、利用可能なプロセッサ数がそれより多くても、デフォルト
   で選択される値は最大 "61" です。 *mp_context* には
   "multiprocessing" のコンテキストまたは "None" を指定でき、ワーカー
   の起動に使われます。 *mp_context* が "None" または省略された場合、
   デフォルトの "multiprocessing" コンテキストが使われます。 コンテキ
   ストと開始方式 を参照してください。

   *initializer* は省略可能な呼び出し可能オブジェクトで、各ワーカープ
   ロセスの開始時に呼び出されます。 *initargs* は、この初期化処理に渡
   す引数のタプルです。 *initializer* が例外を送出した場合、現在未完了
   のジョブはすべて "BrokenProcessPool" を送出し、プールへの新たなジョ
   ブの投入も同じ例外を送出します。

   *max_tasks_per_child* は省略可能な引数で、一つのプロセスが終了して
   新しいワーカープロセスに置き換わるまでに実行できるタスクの最大数を
   指定します。 デフォルトの *max_tasks_per_child* は "None" で、ワー
   カープロセスはプールが存在する限り存続します。 最大数を指定し、
   *mp_context* パラメータを指定しなかった場合、デフォルトでは
   multiprocessing の開始方式に "spawn" が使われます。 この機能は
   "fork" 開始方式とは併用できません。

   バージョン 3.3 で変更: ワーカプロセスの1つが突然終了した場合、
   "BrokenProcessPool" エラーが送出されるようになりました。 以前は挙動
   は未定義でしたが、 executor や  futures がフリーズしたりデッドロッ
   クを起こすことがしばしばでした。

   バージョン 3.7 で変更: プールが作成するワーカープロセスの開始方式を
   利用者が制御できるよう、*mp_context* 引数が追加されました。
   *initializer* と *initargs* 引数が追加されました。

   バージョン 3.11 で変更: プール内のワーカーの存続期間を利用者が制御
   できるよう、*max_tasks_per_child* 引数が追加されました。

   バージョン 3.12 で変更: POSIX システムで、アプリケーションが複数の
   スレッドを持ち、"multiprocessing" コンテキストが ""fork"" 開始方式
   を使う場合、ワーカーを起動するために内部で呼び出す "os.fork()" 関数
   が "DeprecationWarning" を送出することがあります。 別の開始方式を使
   うように設定した *mp_context* を渡してください。 詳しくは
   "os.fork()" のドキュメントを参照してください。

   バージョン 3.13 で変更: *max_workers* のデフォルトで、
   "os.cpu_count()" の代わりに "os.process_cpu_count()" を使うようにな
   りました。

   バージョン 3.14 で変更: プロセスのデフォルトの開始方式 (コンテキス
   トと開始方式 を参照) が *fork* 以外に変更されました。
   "ProcessPoolExecutor" で *fork* 開始方式が必要な場合は、
   "mp_context=multiprocessing.get_context("fork")" を明示的に渡さなけ
   ればなりません。

   バージョン 3.15 で変更: キューにタスクが残っている間にワーカープロ
   セスが *max_tasks_per_child* の上限に達して終了すると、executor が
   停止したままになることがあるデッドロック (gh-115634) を修正しました
   。

   terminate_workers()

      存続中のすべてのワーカープロセスについて "Process.terminate" を
      呼び出し、直ちに終了させようとします。 executor に関連するその他
      のリソースをすべて解放するため、内部では "Executor.shutdown()"
      も呼び出します。

      このメソッドを呼び出した後は、executor にタスクを投入しないでく
      ださい。

      Added in version 3.14.

   kill_workers()

      存続中のすべてのワーカープロセスについて "Process.kill" を呼び出
      し、直ちに強制終了させようとします。 executor に関連するその他の
      リソースをすべて解放するため、内部では "Executor.shutdown()" も
      呼び出します。

      このメソッドを呼び出した後は、executor にタスクを投入しないでく
      ださい。

      Added in version 3.14.


ProcessPoolExecutor の例
------------------------

   import concurrent.futures
   import math

   PRIMES = [
       112272535095293,
       112582705942171,
       112272535095293,
       115280095190773,
       115797848077099,
       1099726899285419]

   def is_prime(n):
       if n < 2:
           return False
       if n == 2:
           return True
       if n % 2 == 0:
           return False

       sqrt_n = int(math.floor(math.sqrt(n)))
       for i in range(3, sqrt_n + 1, 2):
           if n % i == 0:
               return False
       return True

   def main():
       with concurrent.futures.ProcessPoolExecutor() as executor:
           for number, prime in zip(PRIMES, executor.map(is_prime, PRIMES)):
               print('%d is prime: %s' % (number, prime))

   if __name__ == '__main__':
       main()


Future オブジェクト
===================

"Future" クラスは呼び出し可能オブジェクトの非同期実行をカプセル化しま
す。 "Future" のインスタンスは "Executor.submit()" によって生成されま
す。

class concurrent.futures.Future

   呼び出し可能オブジェクトの非同期実行をカプセル化します。 "Future"
   インスタンスは "Executor.submit()" で生成され、テストを除いて直接生
   成すべきではありません。

   cancel()

      呼び出しのキャンセルを試みます。 呼び出しがすでに実行中または実
      行済みで、キャンセルできない場合は "False" を返します。 それ以外
      の場合は呼び出しをキャンセルして "True" を返します。

   cancelled()

      呼び出しが正常にキャンセルされた場合 "True" を返します。

   running()

      現在呼び出しが実行中でキャンセルできない場合 "True" を返します。

   done()

      呼び出しが正常にキャンセルされたか終了した場合 "True" を返します
      。

   result(timeout=None)

      呼び出しによって返された値を返します。もし呼び出しがまだ完了して
      いなければ、このメソッドは *timeout* 秒の間、待機します。もし呼
      び出しが *timeout* 秒間の間に完了しなければ、 "TimeoutError" が
      送出されます。 *timeout* はintかfloatを指定できます。もし
      *timeout* が指定されていないか、 "None" であれば、待機時間に制限
      はありません。

      future が完了する前にキャンセルされた場合 "CancelledError" が送
      出されます。

      呼び出しが例外を送出した場合、このメソッドも同じ例外を送出します
      。

   exception(timeout=None)

      呼び出しによって送出された例外を返します。もし呼び出しがまだ完了
      されていなければ、このメソッドは *timeout* 秒だけ待機します。も
      し呼び出しが *timeout* 秒の間に完了しなければ、 "TimeoutError"
      が送出されます。 *timeout* にはintかfloatを指定できます。
      *timeout* が指定されていないか、 "None" であれば、待機時間に制限
      はありません。

      future が完了する前にキャンセルされた場合 "CancelledError" が送
      出されます。

      呼び出しが例外を送出することなく完了した場合、"None" を返します
      。

   add_done_callback(fn)

      呼び出し可能な *fn* オブジェクトを future にアタッチします。
      futureがキャンセルされたか、実行を終了した際に、future をそのた
      だ一つの引数として *fn* が呼び出されます。

      追加された呼び出し可能オブジェクトは、追加された順番で呼びだされ
      、追加を行ったプロセスに属するスレッド中で呼び出されます。もし呼
      び出し可能オブジェクトが "Exception" のサブクラスを送出した場合
      、それはログに記録され無視されます。呼び出し可能オブジェクトが
      "BaseException" のサブクラスを送出した場合の動作は未定義です。

      もしfutureがすでに完了しているか、キャンセル済みであれば、*fn*
      は即座に実行されます。

   以下の "Future" メソッドは、ユニットテストでの使用と "Executor" を
   実装することを意図しています。

   set_running_or_notify_cancel()

      このメソッドを呼び出してよいのは、"Future" に関連付けられた処理
      を実行する前の "Executor" の実装と、ユニットテストだけです。

      このメソッドが "False" を返す場合、 "Future" はキャンセルされて
      います。つまり、 "Future.cancel()" が呼び出されて "True" が返っ
      ています。"Future" の完了を  ("as_completed()" または "wait()"
      により)  待機するすべてのスレッドが起動します。

      このメソッドが "True" を返す場合、 "Future" はキャンセルされてお
      らず、実行状態に移行しています。 つまり、 "Future.running()" を
      呼び出すと "True" が返ります。

      このメソッドは一度だけ呼び出すことができ、"Future.set_result()"
      または "Future.set_exception()" が呼び出された後には呼び出すこと
      ができません。

   set_result(result)

      "Future" に関連付けられたワークの結果を *result* に設定します。

      このメソッドは、 "Executor" の実装またはユニットテストによっての
      み使用してください。

      バージョン 3.8 で変更: "Future" がすでに完了している場合、このメ
      ソッドは "concurrent.futures.InvalidStateError" を送出します。

   set_exception(exception)

      "Future" に関連付けられたワークの結果を "Exception" *exception*
      に設定します。

      このメソッドは、 "Executor" の実装またはユニットテストによっての
      み使用してください。

      バージョン 3.8 で変更: "Future" がすでに完了している場合、このメ
      ソッドは "concurrent.futures.InvalidStateError" を送出します。


モジュール関数
==============

concurrent.futures.wait(fs, timeout=None, return_when=ALL_COMPLETED)

   *fs* で指定された "Future" インスタンス (異なる "Executor" インスタ
   ンスで作成されたものでも可) が完了するまで待機します。 *fs* に重複
   して指定されたフューチャは一つにまとめられ、一度だけ返されます。 集
   合を要素とする、要素数 2 の名前付きタプルを返します。 最初の集合
   "done" には、待機が終わるまでに完了したフューチャ (実行済みまたはキ
   ャンセル済みのフューチャ) が含まれます。 二つ目の集合 "not_done" に
   は、完了していないフューチャ (保留中または実行中のフューチャ) が含
   まれます。

   *timeout* で結果を返すまで待機する最大秒数を指定できます。*timeout*
   は整数か浮動小数点数をとります。*timeout* が指定されないか "None"
   の場合、無期限に待機します。

   *return_when* でこの関数がいつ結果を返すか指定します。指定できる値
   は以下の 定数のどれか一つです:

   +----------------------------------------------------+----------------------------------------------------+
   | 定数                                               | 説明                                               |
   |====================================================|====================================================|
   | concurrent.futures.FIRST_COMPLETED                 | いずれかのフューチャが終了したかキャンセルされたと |
   |                                                    | きに返します。                                     |
   +----------------------------------------------------+----------------------------------------------------+
   | concurrent.futures.FIRST_EXCEPTION                 | いずれかのフューチャが例外を送出して終了すると、こ |
   |                                                    | の関数は返ります 。 例外を送出するフューチャがない |
   |                                                    | 場合は、"ALL_COMPLETED" と等価です 。              |
   +----------------------------------------------------+----------------------------------------------------+
   | concurrent.futures.ALL_COMPLETED                   | すべてのフューチャが終了したかキャンセルされたとき |
   |                                                    | に返します。                                       |
   +----------------------------------------------------+----------------------------------------------------+

concurrent.futures.as_completed(fs, timeout=None)

   *fs* で指定された "Future" インスタンス (異なる "Executor" インスタ
   ンスで作成されたものでも可) を、完了するたびに (実行済みまたはキャ
   ンセル済みになった順に) yield するイテレータを返します。 *fs* に重
   複して指定されたフューチャは、一度だけ返されます。 "as_completed()"
   の呼び出し前に完了していたフューチャが、最初に yield されます。 返
   されたイテレータの "__next__()" が呼び出された際、最初の
   "as_completed()" の呼び出しから *timeout* 秒が経過しても結果を取得
   できなければ、"TimeoutError" を送出します。 *timeout* には整数また
   は浮動小数点数を指定できます。 *timeout* が省略された場合や "None"
   の場合は、待ち時間に制限はありません。

参考:

  **PEP 3148** -- futures - execute computations asynchronously
     この機能を Python 標準ライブラリに含めることを述べた提案です。


例外クラス
==========

exception concurrent.futures.CancelledError

   future がキャンセルされたときに送出されます。

exception concurrent.futures.TimeoutError

   "TimeoutError" の非推奨のエイリアスです。 フューチャの操作が指定さ
   れたタイムアウトを超えた場合に送出されます。

   バージョン 3.11 で変更: このクラスは "TimeoutError" のエイリアスに
   なりました。

exception concurrent.futures.BrokenExecutor

   "RuntimeError" の派生クラスです。 何らかの理由で executor が壊れて
   、新しいタスクの投入や実行に使えなくなった場合に送出されます。

   Added in version 3.7.

exception concurrent.futures.InvalidStateError

   フューチャに対して、現在の状態では許可されていない操作を行った場合
   に送出されます。

   Added in version 3.8.

exception concurrent.futures.thread.BrokenThreadPool

   "BrokenExecutor" の派生クラスです。 "ThreadPoolExecutor" のワーカー
   のいずれかで初期化に失敗した場合に送出されます。

   Added in version 3.7.

exception concurrent.futures.interpreter.BrokenInterpreterPool

   "BrokenThreadPool" の派生クラスです。 "InterpreterPoolExecutor" の
   ワーカーのいずれかで初期化に失敗した場合に送出されます。

   Added in version 3.14.

exception concurrent.futures.process.BrokenProcessPool

   "BrokenExecutor" (以前は "RuntimeError") の派生クラスです。
   "ProcessPoolExecutor" のワーカーのいずれかが正常でない形で終了した
   場合 (例えば、外部から強制終了された場合) に送出されます。

   Added in version 3.3.
