18.5.1. 基底イベントループ
**************************

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

イベントループは "asyncio"  が提供する中心実行デバイスです。以下の多く
の機能を提供しています:

* 遅延呼び出しの登録、実行およびキャンセル (タイムアウト)。

* さまざまな種類の通信のためのクライアントおよびサーバー トランスポー
  ト の作成。

* 外部プログラムとの通信のためのサブプロセスおよび関連する トランスポ
  ート の起動。

* スレッドのプールへ呼び出す、コストの大きい関数の委譲。

class asyncio.BaseEventLoop

   このクラスは実装詳細です。 "AbstractEventLoop" のサブクラスであり、
   "asyncio" にあるイベントループを実装した具象クラスの基底クラスにな
   っていることがあります。このクラスは直接使うべきではありません。
   "AbstractEventLoop" を代わりに使用してください。サードパーティのコ
   ードで "BaseEventLoop" をサブクラス化すべきではありません。このクラ
   スの内部のインタフェースは安定していません。

class asyncio.AbstractEventLoop

   イベントループの抽象基底クラスです。

   このクラスは スレッド安全ではありません。


18.5.1.1. イベントループの実行
==============================

AbstractEventLoop.run_forever()

   "stop()" が呼ばれるまで実行します。もし "run_forever()" が呼ばれる
   前に "stop()" が呼ばれた場合、このメソッドは I/O セレクターをタイム
   アウト時間ゼロで一度ポーリングして、そこで検出された I/O イベントに
   応じて実行がスケジュールされたコールバックすべて (に加えて元々スケ
   ジュールされていたもの) を実行した後、終了します。もし
   "run_forever()" の実行中に "stop()" が呼ばれた場合、現在バッチ処理
   中のコールバックを実行した後に終了します。なお、この場合はコールバ
   ック内でスケジュールされたコールバックは実行されません。それらは次
   に "run_forever()" が呼ばれたときに実行されます。

   バージョン 3.5.1 で変更.

AbstractEventLoop.run_until_complete(future)

   "Future" が完了するまで実行します。

   引数が コルーチンオブジェクト の場合、"ensure_future()" でラップさ
   れます。

   Future の結果を返すか、例外を送出します。

AbstractEventLoop.is_running()

   イベントループの実行状態を返します。

AbstractEventLoop.stop()

   実行中のイベントループを停止します。

   これにより、 "run_forever()" は次の適当な時に終了します (詳細はそち
   らを参照してください)。

   バージョン 3.5.1 で変更.

AbstractEventLoop.is_closed()

   イベントループが閉じられていた場合 "True" を返します。

   バージョン 3.4.2 で追加.

AbstractEventLoop.close()

   イベントループを閉じます。ループは実行中ではいけません。保留中のコ
   ールバックは失われます。

   これはキューをクリアし実行者をシャットダウンしますが、実行者の終了
   を待ちません。

   これは冪等 (訳注： 何回行っても結果が同じ) であり取り消せません。こ
   の後他のメソッドを呼び出してはなりません。

coroutine AbstractEventLoop.shutdown_asyncgens()

   現在オープンの全ての *asynchronous generator* オブジェクトをスケジ
   ュールし、"aclose()" 呼び出しによりクローズするようにします。このメ
   ソッドの呼び出し後、イベントループは新しい非同期ジェネレータがイテ
   レートされると毎回警告を発します。全てのスケジュールされた非同期ジ
   ェネレータの終了処理を確実に行うために使用すべきです。以下に例を示
   します。

      try:
          loop.run_forever()
      finally:
          loop.run_until_complete(loop.shutdown_asyncgens())
          loop.close()

   バージョン 3.6 で追加.


18.5.1.2. 呼び出し (call)
=========================

"asyncio" 関数の大半はキーワードを受け付けません。 コールバックに引数
を渡したい場合は "functools.partial()" を使用してください。 例えば
"loop.call_soon(functools.partial(print, "Hello", flush=True))" は
"print("Hello", flush=True)" を呼び出します。

注釈:

  "lambda" 関数よりも "functools.partial()" を使用しましょう。
  "asyncio" はデバッグモードで引数を表示するよう "functools.partial()"
  オブジェクトを精査することが出来ますが、"lambda" 関数の表現は貧弱で
  す。

AbstractEventLoop.call_soon(callback, *args)

   コールバックをすぐに呼び出せるように準備します。 コールバックは
   "call_soon()" が返ると呼び出され、制御はイベントループに返されます
   。

   これは FIFO (first-in, first-out) キューのように処理され、コールバ
   ックは登録された順に呼び出されます。各コールバックは厳密に 1 回だけ
   呼び出されます。

   *callback* の後の位置引数 *args* は、コールバックが呼び出されたとき
   に渡されます。

   "asyncio.Handle" のインスタンスを返します。それを使用してコールバッ
   クをキャンセルすることが出来ます。

   コールバックに引数を渡すには functools.partial を使用してください。

AbstractEventLoop.call_soon_threadsafe(callback, *args)

   "call_soon()" に似ていますが、スレッドセーフです。

   このドキュメントの asyncio-multithreading 節を参照してください。


18.5.1.3. 遅延呼び出し
======================

イベントループはタイムアウトを計測するために自身に内部時計を持っていま
す。内部時計は (プラットフォーム固有の) イベントループの実装に依存した
ものが使用されます。理想的には、これは単調時計 (訳注: 巻き戻ることのな
い時計) です。これは通常 "time.time()" とは異なる時計です。

注釈:

  タイムアウト (相対値 *delay* または絶対値 *when*) は 1 日を超えては
  いけません。

AbstractEventLoop.call_later(delay, callback, *args)

   引数 *delay* 秒後に *callback* を呼び出す準備をします。*delay* は
   int または float です。

   "asyncio.Handle" のインスタンスを返します。それを使用してコールバッ
   クをキャンセルすることが出来ます。

   *callback* は "call_later()" を呼び出すたびに厳密に 1 度だけ呼び出
   されます。2 個のコールバックが完全に同じ時間にスケジュールされてい
   る場合、どちらが先に実行されるかは保証されません。

   コールバックが呼び出されたときに任意の位置引数 *args* が渡されます
   。名前付き引数をコールバックに渡したい場合、クロージャか
   "functools.partial()" を使用してください。

   コールバックに引数を渡すには functools.partial を使用してください。

AbstractEventLoop.call_at(when, callback, *args)

   絶対タイムスタンプ *when* (int または float) になったときに呼び出さ
   れる *callback* を準備します。 時刻は "AbstractEventLoop.time()" を
   参照します。

   このメソッドの振る舞いは "call_later()" と同じです。

   "asyncio.Handle" のインスタンスを返します。それを使用してコールバッ
   クをキャンセルすることが出来ます。

   コールバックに引数を渡すには functools.partial を使用してください。

AbstractEventLoop.time()

   現在の時刻を "float" 値で返します。時刻はイベントループの内部時計に
   従います。

参考: 関数 "asyncio.sleep()"。


18.5.1.4. Future
================

AbstractEventLoop.create_future()

   ループに付属した "asyncio.Future" オブジェクトを作成します。

   asyncio で Futures を作成するために推奨される方法です。イベントルー
   プを実装することにより、Futures クラスの(パフォーマンスや計測方法が
   優れた) 代替実装 が提供される場合があるためです。

   バージョン 3.5.2 で追加.


18.5.1.5. タスク
================

AbstractEventLoop.create_task(coro)

   コルーチンオブジェクト の実行をスケジュールします: このときフューチ
   ャにラップします。"Task" オブジェクトを返します。

   サードパーティのイベントループは相互運用のための自身の "Task" のサ
   ブクラスを使用できます。この場合、結果は "Task" のサブクラスになり
   ます。

   このメソッドは Python 3.4.2 で追加されました。Python の過去のバージ
   ョンもサポートするには "async()" 関数を使用してください。

   バージョン 3.4.2 で追加.

AbstractEventLoop.set_task_factory(factory)

   "AbstractEventLoop.create_task()" が使用するタスクファクトリーを設
   定します。

   *factory* が "None" の場合デフォルトのタスクファクトリーが設定され
   ます。

   *factory* が *呼び出し可能オブジェクト* の場合、 "(loop, coro)" に
   一致するシグニチャを持っていなければなりません。 *loop* は有効なイ
   ベントループへの参照で、 *coro* はコルーチンオブジェクトです。 呼び
   出し可能オブジェクトは "asyncio.Future" 互換のオブジェクトを返さな
   ければなりません。

   バージョン 3.4.4 で追加.

AbstractEventLoop.get_task_factory()

   タスクファクトリーを返します。デフォルトのものが使用された場合は
   "None" を返します。

   バージョン 3.4.4 で追加.


18.5.1.6. コネクションの作成
============================

coroutine AbstractEventLoop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)

   インターネット *host* および *port* へのストリーミング転送コネクシ
   ョンを作成します: ソケットファミリ "AF_INET" または "AF_INET6" は
   *host* (または指定されていれば *family*) に依存し、ソケットタイプは
   "SOCK_STREAM" になります。*protocol_factory* は プロトコル のインス
   タンスを返す呼び出し可能オブジェクトでなければなりません。

   このメソッドはバックグラウンドでコネクションの確立を試みる コルーチ
   ン です。成功すると、コルーチンは "(トランスポート, プロトコル)" の
   ペアを返します。

   時系列での下層処理の概要は以下のとおりです:

   1. コネクションを確立し、それを表す トランスポート が作成される。

   2. *protocol_factory* が引数なしで呼び出され、プロトコル のインスタ
      ンスを返す。

   3. プロトコルインスタンスはトランスポートと紐付けられ、それの
      "connection_made()" メソッドが呼び出される。

   4. コルーチンは "(トランスポート, プロトコル)" のペアを返す。

   作成されたトランスポートは実装依存の双方向ストリームです。

   注釈:

     *protocol_factory* はクラスである必要はなく、あらゆる種類の呼び出
     し可能オブジェクトを使用可能です。例えば、あらかじめ作成しておい
     たプロコルインスタンスを使用したい場合、"lambda: my_protocol" を
     渡します。

   コネクションの作成方法を変更するオプションは以下の通りです:

   * *ssl*: 偽値以外が与えられた場合、SSL/TLS トランスポートが作成され
     ます (デフォルトではプレーン TCP トランスポートが作成されます)。
     *ssl* が "ssl.SSLContext" オブジェクトの場合、このコンテキストは
     トランスポートを作成するために使用されます; *ssl* が "True" の場
     合、いくつかの未定義のデフォルト値が使用されます。

     参考: SSL/TLS セキュリティについての考察

   * *server_hostname* は *ssl* 指定時のみ使用し、対象サーバーの証明書
     に一致するホスト名を設定またはオーバーライドします。デフォルトで
     は引数 *host* の値が使用されます。*host* が空の場合デフォルト値は
     なく、*server_hostname* に値を渡さなければなりません。
     *server_hostname* が空の場合、ホスト名のマッチングは無効になりま
     す (深刻なセキュリティリスクになり、中間者攻撃に対する脆弱性にな
     ります)。

   * *family*, *proto*, *flags* は任意のアドレスファミリであり、*host*
     解決のための getaddrinfo() 経由で渡されるプロトコルおよびフラグに
     なります。このオプションが与えられた場合、これらはすべて "socket"
     モジュール定数に従った整数でなければなりません。

   * *sock* を与える場合、トランスポートに使用される、既存の、すでに接
     続済の "socket.socket" オブジェクトを指定します。*sock* を指定す
     る場合、*host*、*port*、*family*、*proto*、*flags* および
     *local_addr* を指定してはなりません。

   * *local_addr* を与える場合、ソケットをローカルに束縛するために使用
     する "(local_host, local_port)" のタプルを指定します。
     *local_host* および *local_port* は *host* および *port* と同様に
     getaddrinfo() を使用してルックアップされます。

   バージョン 3.5 で変更: Windows の "ProactorEventLoop" で SSL/TLS が
   サポートされました。

   参考:

     関数 "open_connection()" はプロトコルではなく ("StreamReader",
     "StreamWriter") のペアの取得に使用できます。

coroutine AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)

   注釈:

     The parameter *reuse_address* is no longer supported, as using
     "SO_REUSEADDR" poses a significant security concern for UDP.
     Explicitly passing "reuse_address=True" will raise an
     exception.When multiple processes with differing UIDs assign
     sockets to an indentical UDP socket address with "SO_REUSEADDR",
     incoming packets can become randomly distributed among the
     sockets.For supported platforms, *reuse_port* can be used as a
     replacement for similar functionality. With *reuse_port*,
     "SO_REUSEPORT" is used instead, which specifically prevents
     processes with differing UIDs from assigning sockets to the same
     socket address.

   Create a datagram connection.

   データグラム接続を作成します: ソケットファミリー "AF_INET" または
   "AF_INET6" は *host* (または指定されていれば *family*) に依存し、ソ
   ケットタイプは "SOCK_DGRAM" です。 *protocol_factory* は プロトコル
   のインスタンスを返す呼び出し可能オブジェクトでなければなりません。

   このメソッドはバックグラウンドでコネクションの確立を試みる コルーチ
   ン です。成功すると、コルーチンは "(トランスポート, プロトコル)" の
   ペアを返します。

   コネクションの作成方法を変更するオプションは以下の通りです:

   * *local_addr* が指定される場合、"(local_host, local_port)" のタプ
     ルで、ソケットをローカルで束縛するために使用されます。
     *local_host* と *local_port* は "getaddrinfo()" を使用して検索さ
     れます。

   * *remote_addr* が指定される場合、"(remote_host, remote_por)" のタ
     プルで、ソケットをリモートアドレスに束縛するために使用されます。
     *remote_host* と *remote_port* は "getaddrinfo()" を使用して検索
     されます。

   * *family*, *proto*, *flags* は任意のアドレスファミリです。これらの
     ファミリ、プロトコル、フラグは、*host* 解決のため "getaddrinfo()"
     経由でオプションで渡されます。これらのオプションを指定する場合、
     すべて "socket" モジュール定数に従った整数でなければなりません。

   * *reuse_port* は、同じポートにバインドされた既存の端点すべてがこの
     フラグを設定して生成されている場合に限り、この端点を既存の端点と
     同じポートにバインドすることをカーネルに許可します（訳註: ソケッ
     トのオプション SO_REUSEPORT を使用します）。このオプションは、
     Windows やいくつかの UNIX システムではサポートされません。もし定
     数 "SO_REUSEPORT" が定義されていなければ、この機能はサポートされ
     ません。

   * *allow_broadcast* は、カーネルに、このエンドポイントがブロードキ
     ャストアドレスにメッセージを送信することを許可するように指示しま
     す。

   * オプションの *sock* を指定することで、既存の、すでに接続されてい
     る "socket.socket" をトランスポートで使用することができます。この
     オプションを使用する場合、*local_addr* と *remote_addr* は省略し
     てください ("None" でなければなりません)。

   Windows の "ProactorEventLoop" では、このメソッドはサポートされてい
   ません。

   UDP echo クライアントプロトコル および UDP echo サーバープロトコル
   の例を参照してください。

   バージョン 3.4.4 で変更: *family*, *proto*, *flags*,
   *reuse_address*, *reuse_port, *allow_broadcast*, *sock* パラメータ
   が追加されました。

   バージョン 3.6.10 で変更: The *reuse_address* parameter is no
   longer supporter due to security concerns

coroutine AbstractEventLoop.create_unix_connection(protocol_factory, path, *, ssl=None, sock=None, server_hostname=None)

   UNIX コネクションを作成します: ソケットファミリは "AF_UNIX"、ソケッ
   トタイプは "SOCK_STREAM" になります。"AF_UNIX" ソケットファミリは同
   一マシン上のプロセス間で効率的に通信するために使用されます。

   このメソッドはバックグラウンドでコネクションの確立を試みる コルーチ
   ン です。成功すると、コルーチンは "(トランスポート, プロトコル)" の
   ペアを返します。

   *path* は UNIX ドメインソケットの名前で、 *sock* パラメータが指定さ
   れない限り指定する必要があります。抽象化された UNIX ソケット、
   "str" 、そして "bytes" のパスを指定できます。

   引数については "AbstractEventLoop.create_connection()" メソッドを参
   照してください。

   利用できる環境: UNIX。


18.5.1.7. 待ち受けコネクションの作成
====================================

coroutine AbstractEventLoop.create_server(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None)

   *host* および *port* に束縛された TCP サーバー (ソケットタイプ
   "SOCK_STREAM") を作成します。

   "Server" オブジェクトを返します。これの "sockets" 属性には作成され
   たソケットが含まれています。サーバーを停止するには "Server.close()"
   メソッドを使用します: 待受中のソケットを閉じます。

   引数:

   * *host* 引数には文字列を渡すことが出来ます。 その場合、TCP サーバ
     は *host* と *port* に束縛されます。 *host* 引数には文字列のシー
     ケンスを渡すことも出来ます。 その場合 TCP サーバはシーケンスの全
     ホストに束縛されます。 *host* が空の文字列や "None" の場合、全イ
     ンターフェイスが想定され、複数のソケットからなるリストを返します
     (最も近いのは IPv4 や IPv6 のものです)。

   * *family* には "socket.AF_INET" または "AF_INET6" を指定し、ソケッ
     トで IPv4 を使用するか IPv6 を使用するか強制的に設定できます。設
     定されない場合ホストから決定されます ("socket.AF_UNSPEC" がデフォ
     ルトになります)。

   * *flags* は "getaddrinfo()" のためのビットマスクになります。

   * 任意の引数 *sock* には、既存のソケットオブジェクトの使用順を指定
     できます。指定した場合、*host* および *port* を指定してはなりませ
     ん ("None" でなければなりません)。

   * *backlog* は "listen()" に渡される、キューに入るコネクションの最
     大数になります (デフォルトは 100)。

   * *ssl* には "SSLContext" を指定できます。指定すると、受け付けたコ
     ネクション上での SSL を有効にします。

   * *reuse_address* は、 TIME_WAIT 状態にあるローカルソケットを、その
     状態が自然にタイムアウトするのを待つことなく再利用するようカーネ
     ルに指示します（訳註: ソケットのオプション SO_REUSEADDR を使用し
     ます）。指定しない場合、UNIX では自動的に "True" が設定されます。

   * *reuse_port* は、同じポートにバインドされた既存の端点すべてがこの
     フラグを設定して生成されている場合に限り、この端点を既存の端点と
     同じポートにバインドすることを許可するよう、カーネルに指示します
     （訳註: ソケットのオプション SO_REUSEPORT を使用します）。このオ
     プションは、Windows ではサポートされていません。

   このメソッドは コルーチン です。

   バージョン 3.5 で変更: Windows の "ProactorEventLoop" で SSL/TLS が
   サポートされました。

   参考:

     関数 "start_server()" は ("StreamReader", "StreamWriter") のペア
     を作成し、このペアで関数を再度呼び出します。

   バージョン 3.5.1 で変更: *host* 引数に文字列のシーケンスを与えられ
   るようになりました。

coroutine AbstractEventLoop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None)

   "AbstractEventLoop.create_server()" と似ていますが、ソケットファミ
   リー "AF_UNIX" 固有です。

   このメソッドは コルーチン です。

   利用できる環境: UNIX。

coroutine BaseEventLoop.connect_accepted_socket(protocol_factory, sock, *, ssl=None)

   受け付けられた接続を扱います。

   asyncio の範囲外で接続を受け付けるが、asyncio を使用してそれらを扱
   うサーバにより使用されます。

   引数:

   * *sock* は、 "accept" 呼び出しが返す既存のソケットオブジェクトです
     。

   * *ssl* には "SSLContext" を指定できます。指定すると、受け付けたコ
     ネクション上での SSL を有効にします。

   このメソッドは coroutine です。完了すると、このコルーチンは
   "(transport, protocol)" のペアを返します。

   バージョン 3.5.3 で追加.


18.5.1.8. ファイル記述子の監視
==============================

Windows の "SelectorEventLoop" では、ソケットの扱いのみサポートされて
います (例えばパイプのファイル記述子はサポートされません)。

Wndows の "ProactorEventLoop" では、これらのメソッドはサポートされませ
ん。

AbstractEventLoop.add_reader(fd, callback, *args)

   読み込み可能なファイル記述子の監視を開始し、指定された引数で
   *callback* を呼び出します。

   コールバックに引数を渡すには functools.partial を使用してください。

AbstractEventLoop.remove_reader(fd)

   読み込み可能なファイル記述子の監視を停止します。

AbstractEventLoop.add_writer(fd, callback, *args)

   書き込み可能なファイル記述子の監視を開始し、指定された引数で
   *callback* を呼び出します。

   コールバックに引数を渡すには functools.partial を使用してください。

AbstractEventLoop.remove_writer(fd)

   書き込み可能なファイル記述子の監視を停止します。

読み込みイベント用のファイル記述子の監視 の例では、ソケットのファイル
記述子を登録するのに低水準の "AbstractEventLoop.add_reader()" メソッド
を使用しています。


18.5.1.9. 低水準のソケット操作
==============================

coroutine AbstractEventLoop.sock_recv(sock, nbytes)

   ソケットからデータを受け取ります。 "socket.socket.recv()" メソッド
   のブロックをモデルにしています。

   受け取ったデータを表す bytes オブジェクトを返します。 一度に受け取
   るデータの最大量を *nbytes* で指定します。

   "SelectorEventLoop" イベントループの場合、ソケット *sock* は非ブロ
   ックでなければなりません。

   このメソッドは コルーチン です。

coroutine AbstractEventLoop.sock_sendall(sock, data)

   ソケットにデータを送ります。 "socket.socket.sendall()" メソッドのブ
   ロックをモデルにいています。

   ソケットはリモートソケットに接続されていなければなりません。 このメ
   ソッドは全データを送信するかエラーが発生するまで、 *data* からのデ
   ータを送信し続けます。 正常終了すると "None" を返します。 エラー発
   生時は例外を送出しますが、正常に処理されたデータ量を確認する手段は
   ありません。 たとえあったとしても、接続の終了を受信するまではできま
   せん。

   "SelectorEventLoop" イベントループの場合、ソケット *sock* は非ブロ
   ックでなければなりません。

   このメソッドは コルーチン です。

coroutine AbstractEventLoop.sock_connect(sock, address)

   *address* のソケットに接続します。 "socket.socket.connect()" メソッ
   ドのブロックをモデルにしています。

   "SelectorEventLoop" イベントループの場合、ソケット *sock* は非ブロ
   ックでなければなりません。

   このメソッドは コルーチン です。

   バージョン 3.5.2 で変更: "address" を解決する必要はなくなりました。
   "sock_connect" は "socket.inet_pton()" の呼び出しで *address* が既
   に解決されているかチェックしようとします。 解決されていない場合
   "AbstractEventLoop.getaddrinfo()" を使用して *address* を解決します
   。

   参考:

     "AbstractEventLoop.create_connection()" および
     "asyncio.open_connection()"。

coroutine AbstractEventLoop.sock_accept(sock)

   接続を受け付けます。 "socket.socket.accept()" のブロック をモデルに
   しています。

   ソケットはアドレスに束縛済みで、接続を listen 中である必要がありま
   す。戻り値は "(conn, address)" のペアで、*conn* は接続を通じてデー
   タの送受信を行うための *新しい* ソケットオブジェクト、*address* は
   接続先の端点でソケットに束縛されているアドレスを示します。

   ソケット *sock* は非ブロックでなければなりません。

   このメソッドは コルーチン です。

   参考: "AbstractEventLoop.create_server()" および "start_server()"。


18.5.1.10. ホスト名の解決
=========================

coroutine AbstractEventLoop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0)

   このメソッドは コルーチン で、"socket.getaddrinfo()" 関数に似ていま
   すが、ブロックされません。

coroutine AbstractEventLoop.getnameinfo(sockaddr, flags=0)

   このメソッドは コルーチン で、"socket.getnameinfo()" 関数に似ていま
   すが、ブロックされません。


18.5.1.11. パイプの接続
=======================

Windows の "SelectorEventLoop" では、これらメソッドはサポートされてい
ません。Windows でパイプをサポートするには、"ProactorEventLoop" を使用
してください。

coroutine AbstractEventLoop.connect_read_pipe(protocol_factory, pipe)

   イベントループ内で読み込みパイプを登録します。

   *protocol_factory* は "Protocol" インターフェースを持つオブジェクト
   のインスタンスを作成しなければなりません。 *pipe* は *ファイルライ
   クオブジェクト* です。 "(トランスポート, プロトコル)" のペアを返し
   、 *トランスポート* は "ReadTransport" インターフェースをサポートし
   ます。

   "SelectorEventLoop" イベントループの場合、*pipe* は非ブロックモード
   に設定されていなければなりません。

   このメソッドは コルーチン です。

coroutine AbstractEventLoop.connect_write_pipe(protocol_factory, pipe)

   イベントループ内の書き込みパイプを登録します。

   *protocol_factory* は "BaseProtocol" で作成されたインスタンスオブジ
   ェクトでなければなりません。*pipe* は *ファイルライクオブジェクト*
   です。"(transport, protocol)" のペアを返します。*transport* は
   "WriteTransport" インターフェースをサポートしています。

   "SelectorEventLoop" イベントループの場合、*pipe* は非ブロックモード
   に設定されていなければなりません。

   このメソッドは コルーチン です。

参考:

  "AbstractEventLoop.subprocess_exec()" メソッドおよび
  "AbstractEventLoop.subprocess_shell()" メソッド。


18.5.1.12. UNIX シグナル
========================

利用できる環境: UNIX のみ。

AbstractEventLoop.add_signal_handler(signum, callback, *args)

   シグナル用のハンドラーを追加します。

   シグナルナンバーが誤っているか捕捉不可能な場合 "ValueError" が送出
   されます。ハンドラーの設定に問題があった場合 "RuntimeError" が送出
   されます。

   コールバックに引数を渡すには functools.partial を使用してください。

AbstractEventLoop.remove_signal_handler(sig)

   シグナル用のハンドラーを削除します。

   シグナルハンドラーが削除されると "True" が、されなければ "False" を
   返します。

参考: "signal" モジュール。


18.5.1.13. 実行者
=================

"Executor" (スレッドプールまたはプロセスプール) 内の関数を呼び出します
。デフォルトでは、一つのイベントループは一つのスレッドプール実行者
("ThreadPoolExecutor") を使用します。

coroutine AbstractEventLoop.run_in_executor(executor, func, *args)

   特定の実行者で *func* を呼び出す準備をします。

   引数 *executor* は "Executor" のインスタンスでなければなりません。
   *executor* が "None" のときデフォルトの実行者が使用されます。

   *func* にキーワードを渡すには、functools.partial を使用します。

   このメソッドは コルーチン です。

   バージョン 3.5.3 で変更: "BaseEventLoop.run_in_executor()" は、作成
   するスレッドプール実行者の "max_workers" を作成しなくなり、代わりに
   スレッドプール実行者 ("ThreadPoolExecutor") にデフォルトを設定させ
   るようになりました。

AbstractEventLoop.set_default_executor(executor)

   "run_in_executor()" で使用される実行者を設定します。


18.5.1.14. エラーハンドリング API
=================================

イベントループ内での例外の扱い方をカスタマイズできます。

AbstractEventLoop.set_exception_handler(handler)

   *handler* を新しいイベントループ例外ハンドラーとして設定します。

   *handler* が "None" の場合、デフォルトの例外ハンドラーが設定されま
   す。

   *handler* が呼び出し可能オブジェクトの場合、"(loop, context)" に一
   致するシグニチャを持っていなければなりません。 "loop" は有効なイベ
   ントループへの参照で、"context" は "dict" オブジェクトです (コンテ
   キストの詳細については "call_exception_handler()" ドキュメントを参
   照してください)。

AbstractEventLoop.get_exception_handler()

   例外ハンドラを返します。デフォルトのものが使用されている場合は
   "None" を返します。

   バージョン 3.5.2 で追加.

AbstractEventLoop.default_exception_handler(context)

   デフォルトの例外ハンドラーです。

   これは例外が発生したときおよび例外ハンドラーが設定されていないとき
   に呼び出され、デフォルトとは振る舞いの異なるカスタム例外ハンドラー
   を呼び出すこともできます。

   引数 *context* の意味は "call_exception_handler()" と同じです。

AbstractEventLoop.call_exception_handler(context)

   現在のイベントループ例外ハンドラーを呼び出します。

   *context* は以下のキーを含む "dict" オブジェクトです (新しいキーは
   後で導入されます):

   * 'message': エラーメッセージ;

   * 'exception' (任意): 例外オブジェクト;

   * 'future' (任意): "asyncio.Future" インスタンス;

   * 'handle' (任意): "asyncio.Handle" インスタンス;

   * 'protocol' (任意): プロトコル インスタンス;

   * 'transport' (任意): トランスポート インスタンス;

   * 'socket' (任意): "socket.socket" インスタンス;

   注釈:

     注意: このメソッドはサブクラス化されたイベントループ内でオーバー
     ロードされてはなりません。あらゆるカスタム例外ハンドリングには、
     "set_exception_handler()" メソッドを使用してください。


18.5.1.15. デバッグモード
=========================

AbstractEventLoop.get_debug()

   イベントループのデバッグモード ("bool") を取得します。

   環境変数 "PYTHONASYNCIODEBUG" に空でない文字列が設定されている場合
   のデフォルト値は "True"、そうでない場合は "False" になります。

   バージョン 3.4.2 で追加.

AbstractEventLoop.set_debug(enabled: bool)

   イベントループのデバッグモードを設定します。

   バージョン 3.4.2 で追加.

参考: asyncio のデバッグモード。


18.5.1.16. サーバー
===================

class asyncio.Server

   ソケット上で待機しているサーバーです。

   "AbstractEventLoop.create_server()" メソッドおよび "start_server()"
   関数によって作成されたオブジェクトです。クラスから直接インスタンス
   を作成しないでください。

   close()

      サーバーを停止します: 待機しているソケットをクローズし "sockets"
      属性に "None" を設定します。

      既存の受信中のクライアントとの接続を表すソケットはオープンのまま
      です。

      サーバーは非同期に停止されます。サーバーの停止を待ちたい場合は
      "wait_closed()" コルーチンを使用します。

   coroutine wait_closed()

      "close()" メソッドが完了するまで待ちます。

      このメソッドは コルーチン です。

   sockets

      サーバーが待機している "socket.socket" オブジェクトのリストです
      。サーバーが停止しているときは "None" になります。


18.5.1.17. ハンドル
===================

class asyncio.Handle

   "AbstractEventLoop.call_soon()",
   "AbstractEventLoop.call_soon_threadsafe()",
   "AbstractEventLoop.call_later()", および
   "AbstractEventLoop.call_at()" が返すコールバックラッパです。

   cancel()

      呼び出しをキャンセルします。コールバックが既にキャンセルされてい
      たり実行されていた場合、このメソッドの影響はありません。


18.5.1.18. イベントループの例
=============================


18.5.1.18.1. call_soon() を使った Hello World
---------------------------------------------

"AbstractEventLoop.call_soon()" メソッドを使用してコールバックをスケジ
ュールする例です。 コールバックは ""Hello World"" を表示してイベントル
ープを停止します:

   import asyncio

   def hello_world(loop):
       print('Hello World')
       loop.stop()

   loop = asyncio.get_event_loop()

   # Schedule a call to hello_world()
   loop.call_soon(hello_world, loop)

   # Blocking call interrupted by loop.stop()
   loop.run_forever()
   loop.close()

参考: コルーチンを使った Hello World の例では コルーチン を使用しています
    。


18.5.1.18.2. call_later() で現在の日時を表示する
------------------------------------------------

現在の日時を毎秒表示するコールバックの例です。コールバックは
"AbstractEventLoop.call_later()" を使用して 5 秒間自身を再スケジュール
し、イベントループを停止します。

   import asyncio
   import datetime

   def display_date(end_time, loop):
       print(datetime.datetime.now())
       if (loop.time() + 1.0) < end_time:
           loop.call_later(1, display_date, end_time, loop)
       else:
           loop.stop()

   loop = asyncio.get_event_loop()

   # Schedule the first call to display_date()
   end_time = loop.time() + 5.0
   loop.call_soon(display_date, end_time, loop)

   # Blocking call interrupted by loop.stop()
   loop.run_forever()
   loop.close()

参考: 現在の日時を表示するコルーチン の例は コルーチン を使用しています。


18.5.1.18.3. 読み込みイベント用ファイル記述子の監視
---------------------------------------------------

ファイル記述子が "AbstractEventLoop.add_reader()" を使用してデータを受
信するまで待機し、その後イベントループを閉じます。

   import asyncio
   try:
       from socket import socketpair
   except ImportError:
       from asyncio.windows_utils import socketpair

   # Create a pair of connected file descriptors
   rsock, wsock = socketpair()
   loop = asyncio.get_event_loop()

   def reader():
       data = rsock.recv(100)
       print("Received:", data.decode())
       # We are done: unregister the file descriptor
       loop.remove_reader(rsock)
       # Stop the event loop
       loop.stop()

   # Register the file descriptor for read event
   loop.add_reader(rsock, reader)

   # Simulate the reception of data from the network
   loop.call_soon(wsock.send, 'abc'.encode())

   # Run the event loop
   loop.run_forever()

   # We are done, close sockets and the event loop
   rsock.close()
   wsock.close()
   loop.close()

参考:

  プロトコルを使ってデータを待つオープンソケットの登録 の例では
  "AbstractEventLoop.create_connection()" メソッドによって作成された低
  レベルプロトコルを使用しています。

  ストリームを使ってデータを待つオープンソケットの登録 の例ではコルー
  チンの "open_connection()" 関数によって作成された高水準ストリームを
  使用しています。


18.5.1.18.4. SIGINT および SIGTERM 用のシグナルハンドラーの設定
---------------------------------------------------------------

"AbstractEventLoop.add_signal_handler()" メソッドを使用した、シグナル
"SIGINT" および "SIGTERM" 用のハンドラを登録します。

   import asyncio
   import functools
   import os
   import signal

   def ask_exit(signame):
       print("got signal %s: exit" % signame)
       loop.stop()

   loop = asyncio.get_event_loop()
   for signame in ('SIGINT', 'SIGTERM'):
       loop.add_signal_handler(getattr(signal, signame),
                               functools.partial(ask_exit, signame))

   print("Event loop running forever, press Ctrl+C to interrupt.")
   print("pid %s: send SIGINT or SIGTERM to exit." % os.getpid())
   try:
       loop.run_forever()
   finally:
       loop.close()

この例は UNIX でのみ動きます。
