Runners
*******

**ソースコード:** Lib/asyncio/runners.py

この節では、asyncio のコードを実行するための高レベルの asyncio のプリ
ミティブの概略を解説します。

これらは イベントループ の上に構築されており、一般的な広く普及している
シナリオでの非同期コードの使用を簡素化することを目的としています。

* 非同期プログラムの実行

* Runner context manager

* Handling Keyboard Interruption


非同期プログラムの実行
======================

asyncio.run(coro, *, debug=None, loop_factory=None)

   Execute *coro* in an asyncio event loop and return the result.

   The argument can be any awaitable object.

   This function runs the awaitable, taking care of managing the
   asyncio event loop, *finalizing asynchronous generators*, and
   closing the executor.

   この関数は、同じスレッドで他の非同期イベントループが実行中のときは
   呼び出せません。

   *debug* が "True" の場合、イベントループはデバッグモードで実行され
   ます。"False" は明示的にデバッグモードを無効化します。 グローバルな
   デバッグモード 設定を尊重するために "None" が使用されます。

   If *loop_factory* is not "None", it is used to create a new event
   loop; otherwise "asyncio.new_event_loop()" is used. The loop is
   closed at the end. This function should be used as a main entry
   point for asyncio programs, and should ideally only be called once.
   It is recommended to use *loop_factory* to configure the event loop
   instead of policies. Passing "asyncio.EventLoop" allows running
   asyncio without the policy system.

   The executor is given a timeout duration of 5 minutes to shutdown.
   If the executor hasn't finished within that duration, a warning is
   emitted and the executor is closed.

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

      async def main():
          await asyncio.sleep(1)
          print('hello')

      asyncio.run(main())

   Added in version 3.7.

   バージョン 3.9 で変更: "loop.shutdown_default_executor()" メソッド
   を使うように更新されました。

   バージョン 3.10 で変更: *debug* はグローバルなデバッグモード設定を
   尊重するためにデフォルトで "None" です。

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

   バージョン 3.14 で変更: *coro* can be any awaitable object.

   注釈:

     The "asyncio" policy system is deprecated and will be removed in
     Python 3.16; from there on, an explicit *loop_factory* is needed
     to configure the event loop.


Runner context manager
======================

class asyncio.Runner(*, debug=None, loop_factory=None)

   同じコンテキスト上での *複数* の非同期関数呼び出しをシンプルにする
   コンテキストマネージャ。

   Sometimes several top-level async functions should be called in the
   same event loop and "contextvars.Context".

   *debug* が "True" の場合、イベントループはデバッグモードで実行され
   ます。"False" は明示的にデバッグモードを無効化します。 グローバルな
   デバッグモード 設定を尊重するために "None" が使用されます。

   *loop_factory* could be used for overriding the loop creation. It
   is the responsibility of the *loop_factory* to set the created loop
   as the current one. By default "asyncio.new_event_loop()" is used
   and set as current event loop with "asyncio.set_event_loop()" if
   *loop_factory* is "None".

   Basically, "asyncio.run()" example can be rewritten with the runner
   usage:

      async def main():
          await asyncio.sleep(1)
          print('hello')

      with asyncio.Runner() as runner:
          runner.run(main())

   Added in version 3.11.

   run(coro, *, context=None)

      Execute *coro* in the embedded event loop.

      The argument can be any awaitable object.

      If the argument is a coroutine, it is wrapped in a Task.

      An optional keyword-only *context* argument allows specifying a
      custom "contextvars.Context" for the code to run in. The
      runner's default context is used if context is "None".

      Returns the awaitable's result or raises an exception.

      この関数は、同じスレッドで他の非同期イベントループが実行中のとき
      は呼び出せません。

      バージョン 3.14 で変更: *coro* can be any awaitable object.

   close()

      Close the runner.

      Finalize asynchronous generators, shutdown default executor,
      close the event loop and release embedded "contextvars.Context".

   get_loop()

      Return the event loop associated with the runner instance.

   注釈:

     "Runner" uses the lazy initialization strategy, its constructor
     doesn't initialize underlying low-level structures.Embedded
     *loop* and *context* are created at the "with" body entering or
     the first call of "run()" or "get_loop()".


Handling Keyboard Interruption
==============================

Added in version 3.11.

When "signal.SIGINT" is raised by "Ctrl"-"C", "KeyboardInterrupt"
exception is raised in the main thread by default. However this
doesn't work with "asyncio" because it can interrupt asyncio internals
and can hang the program from exiting.

To mitigate this issue, "asyncio" handles "signal.SIGINT" as follows:

1. "asyncio.Runner.run()" installs a custom "signal.SIGINT" handler
   before any user code is executed and removes it when exiting from
   the function.

2. The "Runner" creates the main task for the passed coroutine for its
   execution.

3. When "signal.SIGINT" is raised by "Ctrl"-"C", the custom signal
   handler cancels the main task by calling "asyncio.Task.cancel()"
   which raises "asyncio.CancelledError" inside the main task.  This
   causes the Python stack to unwind, "try/except" and "try/finally"
   blocks can be used for resource cleanup.  After the main task is
   cancelled, "asyncio.Runner.run()" raises "KeyboardInterrupt".

4. A user could write a tight loop which cannot be interrupted by
   "asyncio.Task.cancel()", in which case the second following
   "Ctrl"-"C" immediately raises the "KeyboardInterrupt" without
   cancelling the main task.
