# 事件迴圈

原始碼： Lib/asyncio/events.py、Lib/asyncio/base_events.py

前言

事件迴圈是每個 asyncio 應用程式的核心。事件迴圈執行非同步任務和回呼、執行網路 IO 操作並啟動子行程。

應用程式開發人員通常應使用高階的 asyncio 函式，例如 `asyncio.run()`，並且很少需要參照事件迴圈物件或呼叫其方法。本節主要針對那些需要更細粒度控制事件迴圈行為的低階程式碼、函式庫和框架的作者。

取得事件迴圈

以下的低階函式可用於取得、設置或建立事件迴圈：

asyncio.get_running_loop()

  在目前作業系統執行緒中回傳正在運行的事件迴圈。

  如果沒有運行的事件迴圈，則引發 `RuntimeError`。

  此函式只能從協程或回呼函式中呼叫。

  在 3.7 版被加入.

asyncio.get_event_loop()

  取得目前的事件迴圈。

  當從協程或回呼函式呼叫此函式（例如，使用 call_soon 或類似的 API 於排程呼叫），此函式將永遠回傳正在運行的事件迴圈。

  如果沒有設定正在運行的事件迴圈，該函式將回傳 `get_event_loop_policy().get_event_loop()` 呼叫的結果。

  由於此函式具有相當複雜的行為（尤其是在使用自訂事件迴圈策略時），在協程和回呼函式中，建議使用 `get_running_loop()` 函式，而不是 `get_event_loop()`。

  如上所述，可以考慮使用高階的 `asyncio.run()` 函式，而不是使用這些較低階的函式手動建立和關閉事件迴圈。

  在 3.14 版的變更: 如果沒有目前的事件迴圈，則引發 `RuntimeError`。

  備註

  `asyncio` 的政策系統已被棄用，並將於 Python 3.16 中移除；此後，此函式將回傳目前執行中的事件迴圈（若存在），否則將回傳由 `set_event_loop()` 設定的迴圈。

asyncio.set_event_loop(loop)

  將 loop 設置為目前 OS 執行緒的目前事件迴圈。

asyncio.new_event_loop()

  建立並回傳新的事件迴圈物件。

請注意 `get_event_loop()`、`set_event_loop()` 和 `new_event_loop()` 函式的行為可以透過設定自訂事件迴圈策略進行調整。

目錄

本頁文件包含以下章節：

- 事件迴圈方法章節是事件迴圈 API 們的參照文件；

- 回呼處理章節記錄了從排程方法（如 `loop.call_soon()` 和 `loop.call_later()`）回傳的 `Handle` 和 `TimerHandle` 實例；

- Server 物件章節記錄了從事件迴圈方法（如 `loop.create_server()`）回傳的資料型別；

- 事件迴圈實作章節記錄了 `SelectorEventLoop` 和 `ProactorEventLoop` 類別；

- 範例章節展示了如何使用一些事件迴圈 API。

## 事件迴圈方法

事件迴圈提供以下低階 API：

### 啟動和停止迴圈

loop.run_until_complete(future)

  運行直到 future （一個 `Future` 實例）完成。

  如果引數是協程物件，則它將被隱式排程為 `asyncio.Task` 運行。

  回傳 Future 的結果或引發其例外。

loop.run_forever()

  運行事件迴圈直到 `stop()` 被呼叫。

  如果在呼叫 `run_forever()` 之前呼叫 `stop()`，則迴圈將使用超時為零的方式輪詢 I/O 選擇器，運行所有回應 I/O 事件（以及已經排程的事件）的回呼，然後退出。

  如果在 `run_forever()` 運行時呼叫 `stop()`，則迴圈將運行目前批次的回呼函式，然後退出。請注意，由回呼函式排程的新回呼在此情況下不會運行；而是在下次呼叫 `run_forever()` 或 `run_until_complete()` 時運行。

loop.stop()

  停止事件迴圈。

loop.is_running()

  如果事件迴圈目前正在運行，則回傳 `True`。

loop.is_closed()

  如果事件迴圈已關閉，則回傳 `True`。

loop.close()

  關閉事件迴圈。

  不得於迴圈運行中呼叫此函式。將丟棄任何待處理的回呼。

  此方法清除所有佇列並關閉執行器，但不等待執行器完成。

  此方法是冪等且不可逆的。在事件迴圈關閉後不應呼叫其他方法。

async loop.shutdown_asyncgens()

  排程所有目前打開的非同步產生器物件使用 `aclose()` 呼叫來關閉。呼叫此方法後，如果疊代新的非同步產生器，事件迴圈將發出警告。應該使用此方法可靠地完成所有已排程的非同步產生器。

  請注意，使用 `asyncio.run()` 時不需要呼叫此函式。

  範例：

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

  在 3.6 版被加入.

async loop.shutdown_default_executor(timeout=None)

  排程預設執行器的關閉，並等待它加入 `ThreadPoolExecutor` 中的所有執行緒。一旦呼叫了此方法，使用預設執行器與 `loop.run_in_executor()` 將引發 `RuntimeError`。

  timeout 參數指定執行器完成加入所需的時間（以 `float` 秒為單位）。預設情況下為 `None`，不會限制執行器所花費的時間。

  如果達到 timeout，將發出 `RuntimeWarning` 警告，預設執行器將立即終止，不等待其執行緒完成加入。

  備註

  使用 `asyncio.run()` 時請勿呼叫此方法，因為後者會自動處理預設執行器的關閉。

  在 3.9 版被加入.

  在 3.12 版的變更: 加入 timeout 參數。

### 排程回呼函式

loop.call_soon(callback, *args, context=None)

  在事件迴圈的下一次疊代中排程以 args 引數呼叫 callback callback。

  回傳 `asyncio.Handle` 的實例，稍後可以用於取消回呼函式。

  回呼函式按照其註冊的順序呼叫。每個回呼函式將被呼叫恰好一次。

  選用的僅限關鍵字引數 context 指定了要給 callback 執行的自訂 `contextvars.Context`。當未提供 context 時，回呼函式使用目前情境。

  與 `call_soon_threadsafe()` 不同，此方法不是執行緒安全的。

loop.call_soon_threadsafe(callback, *args, context=None)

  這是 `call_soon()` 的執行緒安全變體。當從另一個執行緒排程回呼函式時，必須使用此函式，因為 `call_soon()` 不是執行緒安全的。

  This function is safe to be called from a reentrant context or signal handler, however, it is not safe or fruitful to use the returned handle in such contexts.

  如果在已關閉的迴圈上呼叫，則引發 `RuntimeError`。在主應用程式關閉時，這可能發生在次要執行緒上。

  請參閱文件的並行和多執行緒部分。

  在 3.7 版的變更: 新增了 context 僅限關鍵字參數。詳細資訊請參閱 PEP 567。

備註

大多數 `asyncio` 排程函式不允許傳遞關鍵字引數。要傳遞關鍵字引數，請使用 `functools.partial()`：

    # 將會排程 "print("Hello", flush=True)"
    loop.call_soon(
        functools.partial(print, "Hello", flush=True))

通常使用 partial 物件比使用 lambda 更方便，因為 asyncio 可以在除錯和錯誤訊息中更好地呈現 partial 物件。

### 排程延遲的回呼函式

事件迴圈提供為回呼函式排程在將來某個時間點才呼叫的機制。事件迴圈使用了單調時鐘來追蹤時間。

loop.call_later(delay, callback, *args, context=None)

  排程 callback 在給定的 delay 秒數後呼叫（可以是整數或浮點數）。

  回傳 `asyncio.TimerHandle` 的實例，可用於取消回呼函式。

  callback 將只被呼叫恰好一次。如果有兩個回呼函式被排程在完全相同的時間，則其呼叫順序是不定的。

  可選的位置引數 args 將在回呼函式被呼叫時傳遞給它。使用 `functools.partial()` 來傳遞關鍵字引數給 callback。

  可選的僅限關鍵字 context 引數允許為 callback 指定自訂的 `contextvars.Context` 以提供運行。當未提供 context 時，將使用目前情境。

  備註

  For performance, callbacks scheduled with `loop.call_later()` may run up to one clock-resolution early (see `time.get_clock_info('monotonic').resolution`).

  在 3.7 版的變更: 新增了 context 僅限關鍵字參數。詳細資訊請參閱 PEP 567。

  在 3.8 版的變更: 在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，delay 不能超過一天。這在 Python 3.8 中已經修復。

loop.call_at(when, callback, *args, context=None)

  排程 callback 在給定的絕對時間戳 when （整數或浮點數）處呼叫，使用與 `loop.time()` 相同的時間參照。

  此方法的行為與 `call_later()` 相同。

  回傳 `asyncio.TimerHandle` 的實例，可用於取消回呼函式。

  備註

  For performance, callbacks scheduled with `loop.call_at()` may run up to one clock-resolution early (see `time.get_clock_info('monotonic').resolution`).

  在 3.7 版的變更: 新增了 context 僅限關鍵字參數。詳細資訊請參閱 PEP 567。

  在 3.8 版的變更: 在 Python 3.7 及更早版本中，使用預設事件迴圈實作時，when 和目前時間之間的差值不能超過一天。這在 Python 3.8 中已經修復。

loop.time()

  根據事件迴圈的內部單調時鐘，回傳目前時間，以 `float` 值表示。

備註

在 3.8 版的變更: 在 Python 3.7 及更早版本中，超時（相對 delay 或絕對 when）不應超過一天。這在 Python 3.8 中已經修復。

也參考

函式 `asyncio.sleep()`。

### 建立 Futures 和 Tasks

loop.create_future()

  建立附加到事件迴圈的 `asyncio.Future` 物件。

  這是在 asyncio 中建立 Futures 的首選方式。這允許第三方事件迴圈提供 Future 物件的替代實作（具有更好的性能或儀器計測表現）。

  在 3.5.2 版被加入.

loop.create_task(coro, *, name=None, context=None, eager_start=None, **kwargs)

  排程執行協程 coro。回傳 `Task` 物件。

  第三方事件迴圈可以使用其自己的 `Task` 子類別以實現互操作性（interoperability）。在這種情況下，結果類型是 `Task` 的子類別。

  The full function signature is largely the same as that of the `Task` constructor (or factory) - all of the keyword arguments to this function are passed through to that interface.

  如果提供了 name 引數且不為 `None`，則將其設置為任務的名稱，使用 `Task.set_name()`。

  可選的僅限關鍵字 context 引數允許為 coro 指定自訂的 `contextvars.Context` 以提供運行。當未提供 context 時，將建立目前情境的副本。

  An optional keyword-only eager_start argument allows specifying if the task should execute eagerly during the call to create_task, or be scheduled later. If eager_start is not passed the mode set by `loop.set_task_factory()` will be used.

  在 3.8 版的變更: 加入 name 參數。

  在 3.11 版的變更: 加入 context 參數。

  在 3.13.3 版的變更: Added `kwargs` which passes on arbitrary extra parameters, including `name` and `context`.

  在 3.13.4 版的變更: Rolled back the change that passes on name and context (if it is None), while still passing on other arbitrary keyword arguments (to avoid breaking backwards compatibility with 3.13.3).

  在 3.14 版的變更: All kwargs are now passed on. The eager_start parameter works with eager task factories.

loop.set_task_factory(factory)

  設置將由 `loop.create_task()` 使用的任務工廠。

  如果 factory 為 `None`，將設置預設的任務工廠。否則，factory 必須是一個具有匹配簽名 `(loop, coro, **kwargs)` 的 callable，其中 loop 是有效事件迴圈的參照、coro 是一個協程物件。該可呼叫物件必須傳遞所有 kwargs 並回傳一個與 `asyncio.Task` 相容的物件。

  在 3.13.3 版的變更: Required that all kwargs are passed on to `asyncio.Task`.

  在 3.13.4 版的變更: name is no longer passed to task factories. context is no longer passed to task factories if it is `None`.

  在 3.14 版的變更: name and context are now unconditionally passed on to task factories again.

loop.get_task_factory()

  回傳任務工廠，如果使用預設任務工廠則回傳 `None`。

### 打開網路連線

async loop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None, all_errors=False)

  打開以 host 和 port 指定之給定地址的串流傳輸連線。

  根據 host（或提供的 family 引數）的情況，socket 家族可以是 `AF_INET` 或 `AF_INET6`。

  Socket 類型將為 `SOCK_STREAM`。

  protocol_factory 必須是一個回傳 asyncio protocol 實作的可呼叫函式。

  此方法將嘗試在背景建立連線。成功時，它將回傳一對 `(transport, protocol)`。

  底層操作的時間軸簡介如下：

  1. 建立連線並為其建立傳輸。

  2. protocol_factory 在無引數的情況下被呼叫，並且預計回傳一個 協定 實例。

  3. 透過呼叫其 `connection_made()` 方法，將協定實例與傳輸連線在一起。

  4. 成功時回傳一個 `(transport, protocol)` 元組。

  建立的傳輸是一個依賴實作的雙向串流。

  其他引數：

  - 若有給定 ssl 且非 false，將建立 SSL/TLS 傳輸（預設建立普通 TCP 傳輸）。如果 ssl 為 `ssl.SSLContext` 物件，則使用該情境來建立傳輸；如果 ssl 為 `True`，則使用 `ssl.create_default_context()` 回傳的預設情境。

    也參考

    SSL/TLS 安全考量

  - server_hostname 設置或覆蓋目標伺服器憑證將匹配的主機名稱。僅在 ssl 不為 `None` 時傳遞。預設情況下，將使用 host 引數的值。如果 host 為空，則沒有預設值，必須傳遞 server_hostname 的值。若 server_hostname 為空字串，將停用主機名稱匹配（這是一個嚴重的安全風險，可能導致中間人攻擊）。

  - family、proto、flags 是可選的位址家族、協定和旗標，用於傳遞至 getaddrinfo() 進行 host 解析。若有給定這些應該都是相應 `socket` 模組常數的整數。

  - 若有給定，happy_eyeballs_delay 會啟用此連線的 Happy Eyeballs。它應該是一個浮點數，表示等待連線嘗試完成的秒數，然後在並行啟動下一次嘗試。這是 RFC 8305 中定義的「連線嘗試延遲」。RFC 建議的合理預設值為 `0.25` 秒（250 毫秒）。

  - interleave 控制主機名稱解析為多個 IP 位址時的地址重新排序。若為 `0` 或未指定，將不執行重排序，並按 `getaddrinfo()` 回傳的順序嘗試位址。如果指定正整數，則按地址家族交錯排列，給定的整數直譯為 RFC 8305 中定義的「首個地址家族計數」。如果未指定 happy_eyeballs_delay，則預設值為 `0`，如果指定則為 `1`。

  - 若有給定 sock 則其應為已存在且已連線的 `socket.socket` 物件，可供傳輸使用。如果提供了 sock，則不應指定 host、port、family、proto、flags、happy_eyeballs_delay、interleave 和 local_addr 中的任何一項。

    備註

    引數 sock 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 `close()` 方法。

  - 若有給定 local_addr 則其為一個 `(local_host, local_port)` 元組，用於在本地綁定 socket。將使用 `getaddrinfo()` 查找 local_host 和 local_port，方式類似於 host 和 port。

  - ssl_handshake_timeout （對於 TLS 連線）是等待 TLS 交握的時間，以秒為單位，在那之前若未完成則會中斷連線。如果為 `None` （預設值），則會等待 `60.0` 秒。

  - ssl_shutdown_timeout 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 `None` （預設值），則會等待 `30.0` 秒。

  - all_errors 決定在無法建立連線時會引發哪些例外。預設情況下，只會引發單一 `Exception`：如果只有一個例外或所有錯誤訊息相同，則引發第一個例外，否則引發包含所有錯誤訊息的單一 `OSError`。當 `all_errors` 為 `True` 時，將引發包含所有例外的 `ExceptionGroup` （即使只有一個例外）。

  在 3.5 版的變更: 新增 `ProactorEventLoop` 中的 SSL/TLS 支援。

  在 3.6 版的變更: 所有 TCP 連線都預設有 socket.TCP_NODELAY socket 選項。

  在 3.7 版的變更: 增加 ssl_handshake_timeout 參數。

  在 3.8 版的變更: 加入 happy_eyeballs_delay 和 interleave 參數。

  Happy Eyeballs 演算法：雙協定堆疊主機 (Dual-Stack Hosts) 的成功。當伺服器的 IPv4 路徑和協定運作正常，但伺服器的 IPv6 路徑和協定不運作時，雙棧用戶端應用程式會比僅具 IPv4 的用戶端體驗到顯著的連線延遲。這是不希望的，因為這會導致雙棧用戶端的使用者體驗變差。本文件具體說明了減少此用戶可見延遲的演算法要求並提供了一種演算法。

  更多資訊請見： https://datatracker.ietf.org/doc/html/rfc6555

  在 3.11 版的變更: 增加 ssl_shutdown_timeout 參數。

  在 3.12 版的變更: 已新增 all_errors。

  也參考

  函式 `open_connection()` 是高階的替代 API。它回傳一對 (`StreamReader`, `StreamWriter`) 可直接在 async/await 程式碼中使用。

async loop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_port=None, allow_broadcast=None, sock=None)

  建立一個資料報連線。

  Socket 家族可以是 `AF_INET`、`AF_INET6` 或 `AF_UNIX`，視乎 host（或提供的 family 引數）而定。

  Socket 類型將為 `SOCK_DGRAM`。

  protocol_factory 必須是可呼叫的函式，回傳 protocol 實作。

  成功時回傳 `(transport, protocol)` 元組。

  其他引數：

  - local_addr，如果提供，是一個 `(local_host, local_port)` 元組，用於在本地綁定 socket。local_host 和 local_port 使用 `getaddrinfo()` 來查找。

    備註

    On Windows, when using the proactor event loop with `local_addr=None`, an `OSError` with `errno.WSAEINVAL` will be raised when running it.

  - remote_addr，如果提供，是一個 `(remote_host, remote_port)` 元組，用於將 socket 連線到遠端位址。 remote_host 和 remote_port 使用 `getaddrinfo()` 來查找。

  - family、proto 和 flags 是用於傳遞給 `getaddrinfo()` 以解析 host 的可選地址家族、協定和旗標。如果提供，這些應該都是來自相應的 `socket` 模組常數的整數。

  - reuse_port 告訴核心允許將此端點綁定到與其他現有端點相同的埠，只要它們在建立時都設定了此旗標。此選項不受 Windows 和某些 Unix 系統支援。如果未定義 `socket.SO_REUSEPORT` 常數，則不支援此功能。

  - allow_broadcast 告訴核心允許此端點向廣播位址發送訊息。

  - sock 可以選擇性地指定，以使用預先存在且已連線的 `socket.socket` 物件供傳輸使用。如果指定，local_addr 和 remote_addr 應省略（必須是 `None`）。

    備註

    引數 sock 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 `close()` 方法。

  請參閱 UDP 回應用戶端協定 和 UDP 回應伺服器協定 範例。

  在 3.4.4 版的變更: 新增 family、proto、flags、reuse_address、reuse_port、allow_broadcast 和 sock 參數。

  在 3.8 版的變更: 新增對於 Windows 的支援。

  在 3.8.1 版的變更: 不再支援 reuse_address 參數，因為使用 `~socket.SO_REUSEADDR` 對於 UDP 存有重大的安全疑慮。明確傳遞 `reuse_address=True` 將引發例外。

  當具有不同 UID 的多個行程使用 `SO_REUSEADDR` 將 socket 分配給相同的 UDP socket 地址時，傳入的封包可能會在 socket 之間隨機分佈。

  對於有支援的平台，reuse_port 可以用作類似功能的替代方案。使用 reuse_port，將改為使用 `~socket.SO_REUSEPORT`，該選項明確禁止具有不同 UID 的行程將 socket 分配給相同的 socket 地址。

  在 3.11 版的變更: 自 Python 3.9.0、3.8.1、3.7.6 和 3.6.10 起，已完全移除 reuse_address 參數。

async loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

  建立一個 Unix 連線。

  Socket 家族將為 `AF_UNIX`；socket 類型將為 `SOCK_STREAM`。

  成功時回傳 `(transport, protocol)` 元組。

  path 是 Unix 域 socket 的名稱，除非指定 sock 參數，否則為必填。支援抽象 Unix sockets、`str`、`bytes` 和 `Path` 路徑。

  有關此方法的引數資訊，請參閱 `loop.create_connection()` 方法的文件。

  可用性: Unix.

  在 3.7 版的變更: 新增 ssl_handshake_timeout 參數。path 參數現在可以是 path-like object。

  在 3.11 版的變更: 增加 ssl_shutdown_timeout 參數。

### 建立網路伺服器

async loop.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, keep_alive=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)

  建立一個 TCP 伺服器（socket 類型 `SOCK_STREAM`），監聽 host 位址的 port。

  回傳一個 `Server` 物件。

  引數：

  - protocol_factory 必須是可呼叫的函式，回傳 protocol 實作。

  - 可以將 host 參數設為幾種類型，以確定伺服器將監聽的位置：

    - 如果 host 是字串，則 TCP 伺服器綁定到由 host 指定的單個網路介面。

    - 如果 host 是字串序列，則 TCP 伺服器綁定到序列指定的所有網路介面。

    - 若 host 是空字串或 `None`，則所有介面都被假定並回傳多個 socket 的清單（可能一個用於 IPv4，另一個用於 IPv6）。

  - 可以設定 port 參數以指定伺服器應該監聽的埠。如果是 `0` 或 `None`（預設值），將隨機選擇一個未使用的埠（請注意，如果 host 解析為多個網路介面，將為每個介面隨機選擇不同的隨機埠）。

  - family 可以設定為 `socket.AF_INET` 或 `AF_INET6` 以強制使用 IPv4 或 IPv6。如果未設定，family 將從主機名稱決定（預設為 `AF_UNSPEC`）。

  - flags 是 `getaddrinfo()` 的位元遮罩。

  - 可以可選地指定 sock 以使用現有的 socket 物件。如果指定了，host 和 port 不能指定。

    備註

    sock 引數將 socket 的所有權轉移給建立的伺服器。要關閉 socket，請呼叫伺服器的 `close()` 方法。

  - backlog 是傳遞給 `listen()` 的最大佇列連線數（預設為 100）。

  - ssl 可以設定為 `SSLContext` 實例以在接受的連線上啟用 TLS。

  - reuse_address 告訴內核重用 `TIME_WAIT` 狀態下的本地 socket，而不等待其自然超時過期。如果未指定，在 Unix 上將自動設置為 `True`。

  - reuse_port 告訴內核允許此端點繫結到與其他現有端點繫結的相同埠，只要它們在建立時都設置了此旗標。此選項在旗標 Windows 上不受支援。

  - 將 keep_alive 設為 `True` 透過啟用定期的訊息傳輸來保持連線活躍。

  在 3.13 版的變更: 加入 keep_alive 參數。

  - （對於 TLS 伺服器）ssl_handshake_timeout 是在中斷連線之前等待 TLS 握手完成的時間（以秒為單位）。如果為 `None`（預設），則為 `60.0` 秒。

  - ssl_shutdown_timeout 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 `None` （預設值），則會等待 `30.0` 秒。

  - 將 start_serving 設置為 `True`（預設）將使建立的伺服器立即開始接受連接。當設置為 `False` 時，用戶應該等待 `Server.start_serving()` 或 `Server.serve_forever()` 來使伺服器開始接受連線。

  在 3.5 版的變更: 新增 `ProactorEventLoop` 中的 SSL/TLS 支援。

  在 3.5.1 版的變更: host 參數可以是字串序列。

  在 3.6 版的變更: 新增 ssl_handshake_timeout 與 start_serving 參數。所有 TCP 連線都預設有 socket.TCP_NODELAY socket 選項。

  在 3.11 版的變更: 增加 ssl_shutdown_timeout 參數。

  也參考

  `start_server()` 函式是一個更高階的替代 API，它回傳一對 `StreamReader` 和 `StreamWriter`，可以在 async/await 程式碼中使用。

async loop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True, cleanup_socket=True)

  類似 `loop.create_server()`，但適用於 `AF_UNIX` socket 家族。

  path 是 Unix 域 socket 的名稱，除非提供了 sock 引數，否則必須給定。支援抽象 Unix sockets、`str`、`bytes` 和 `Path` 路徑。

  如果 cleanup_socket 為真，則 Unix socket 將在伺服器關閉時自動從檔案系統中刪除，除非在建立伺服器後替換了 socket。

  有關此方法的引數資訊，請參閱 `loop.create_server()` 方法的文件。

  可用性: Unix.

  在 3.7 版的變更: 新增 ssl_handshake_timeout 與 start_serving 參數。path 參數現在可為一個 `Path` 物件。

  在 3.11 版的變更: 增加 ssl_shutdown_timeout 參數。

  在 3.13 版的變更: 加入 cleanup_socket 參數。

async loop.connect_accepted_socket(protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

  將已接受的連線包裝成傳輸層/協定對。

  此方法可以由在 asyncio 外接受連線但使用 asyncio 處理連線的伺服器使用。

  參數：

  - protocol_factory 必須是可呼叫的函式，回傳 protocol 實作。

  - sock 是從 `socket.accept` 回傳的預先存在的 socket 物件。

    備註

    引數 sock 將 socket 所有權轉移給所建立的傳輸 socket，請呼叫傳輸的 `close()` 方法。

  - ssl 可以設置為 `SSLContext` 以在已接受的連線上啟用 SSL。

  - （對於 SSL 連線）ssl_handshake_timeout 是在中斷連線之前等待 SSL 握手完成的時間（以秒為單位）。如果為 `None`（預設），則為 `60.0` 秒。

  - ssl_shutdown_timeout 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 `None` （預設值），則會等待 `30.0` 秒。

  回傳 `(transport, protocol)` 對。

  在 3.5.3 版被加入.

  在 3.7 版的變更: 增加 ssl_handshake_timeout 參數。

  在 3.11 版的變更: 增加 ssl_shutdown_timeout 參數。

### 傳輸檔案

async loop.sendfile(transport, file, offset=0, count=None, *, fallback=True)

  透過 transport 發送 file。回傳發送的總位元組數。

  如果可用，該方法使用高性能 `os.sendfile()`。

  file 必須是以二進位模式打開的常規檔案物件。

  offset 告訴從哪裡開始讀取檔案。如果指定了，count 是要傳輸的總位元組數，而不是發送檔案直到達到 EOF。即使此方法引發錯誤時，檔案位置也始終更新，可以使用 `file.tell()` 取得實際發送的位元組數。

  將 fallback 設置為 `True` 會使 asyncio 在平台不支援 sendfile 系統呼叫時（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。

  如果系統不支援 sendfile 系統呼叫且 fallback 為 `False`，則引發 `SendfileNotAvailableError`。

  在 3.7 版被加入.

### TLS 升級

async loop.start_tls(transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)

  將基於傳輸的現有連線升級到 TLS。

  建立 TLS 編解碼器實例並在 transport 和 protocol 之間插入它。編解碼器既實作了對於 transport 的協定，也實作了對於 protocol 的傳輸。

  回傳建立的雙介面實例。在 await 後，protocol 必須停止使用原始的 transport，僅與回傳的物件通信，因為編碼器快取了 protocol 端的資料，並且與 transport 間歇性地交換額外的 TLS session 封包。

  在某些情況下（例如傳入的傳輸已經關閉），此函式可能回傳 `None`。

  參數：

  - transport 和 protocol 實例，由像 `create_server()` 和 `create_connection()` 等方法回傳。

  - sslcontext：配置好的 `SSLContext` 實例。

  - 當升級伺服器端連線時（像由 `create_server()` 建立的那樣）傳遞 `True`。

  - server_hostname：設置或覆蓋將用於匹配目標伺服器憑證的主機名。

  - ssl_handshake_timeout （對於 TLS 連線）是等待 TLS 交握的時間，以秒為單位，在那之前若未完成則會中斷連線。如果為 `None` （預設值），則會等待 `60.0` 秒。

  - ssl_shutdown_timeout 是等待 SSL 關閉完成以前中斷連線的時間，以秒為單位。如果為 `None` （預設值），則會等待 `30.0` 秒。

  在 3.7 版被加入.

  在 3.11 版的變更: 增加 ssl_shutdown_timeout 參數。

### 監視檔案描述器

loop.add_reader(fd, callback, *args)

  開始監視 fd 檔案描述器的讀取可用性，一但 fd 可讀取，使用指定引數叫用 callback。

  任何預先存在、為 fd 註冊的回呼函式將被取消並替換為 callback。

loop.remove_reader(fd)

  停止監視 fd 檔案描述器的讀取可用性。如果 fd 之前正在監視讀取，則回傳 `True`。

loop.add_writer(fd, callback, *args)

  開始監視 fd 檔案描述器的寫入可用性，一旦 fd 可寫入，使用指定引數 args 叫用 callback。

  任何預先存在、為 fd 註冊的回呼函式將被取消並替換為 callback。

  使用 `functools.partial()` 向 callback 傳送關鍵字引數。

loop.remove_writer(fd)

  停止監視 fd 檔案描述器的寫入可用性。如果 fd 之前正在監視寫入，則回傳 `True`。

另請參閱平台支援部分以了解這些方法的一些限制。

### 直接使用 socket 物件

一般情況下，使用基於傳輸的 API（如 `loop.create_connection()` 和 `loop.create_server()`）的協定實作比直接使用 socket 的實作更快。然而在某些情況下性能不是關鍵，直接使用 `socket` 物件更方便。

async loop.sock_recv(sock, nbytes)

  從 sock 接收最多 nbytes。`socket.recv()` 的非同步版本。

  將接收到的資料作為 bytes 物件回傳。

  sock 必須是非阻塞 socket。

  在 3.7 版的變更: 儘管此方法一直記錄為協程方法，但 Python 3.7 之前的版本回傳 `Future`。自 Python 3.7 起，這是 `async def` 方法。

async loop.sock_recv_into(sock, buf)

  從 sock 接收資料到 buf 緩衝區。仿照阻塞 `socket.recv_into()` 方法。

  回傳寫入緩衝區位元組的數目。

  sock 必須是非阻塞 socket。

  在 3.7 版被加入.

async loop.sock_recvfrom(sock, bufsize)

  從 sock 接收最多 bufsize 大小的資料單元。`socket.recvfrom()` 的非同步版本。

  回傳一個元組 (received data, remote address)。

  sock 必須是非阻塞 socket。

  在 3.11 版被加入.

async loop.sock_recvfrom_into(sock, buf, nbytes=0)

  從 sock 接收最多 nbytes 大小的資料單元到 buf。`socket.recvfrom_into()` 的非同步版本。

  回傳一個元組 (number of bytes received, remote address)。

  sock 必須是非阻塞 socket。

  在 3.11 版被加入.

async loop.sock_sendall(sock, data)

  將 data 發送到 sock socket。`socket.sendall()` 的非同步版本。

  此方法將繼續發送到 socket，直到 data 中的所有資料都已發送或發生錯誤。成功時回傳 `None`。錯誤時引發例外。此外，沒有辦法確定接收端成功處理了多少資料（如果有的話）。

  sock 必須是非阻塞 socket。

  在 3.7 版的變更: 儘管該方法一直被記錄為協程方法，但在 Python 3.7 之前它回傳 `Future`。從 Python 3.7 開始，這是一個 `async def` 方法。

async loop.sock_sendto(sock, data, address)

  從 sock 向 address 發送一個資料單元。`socket.sendto()` 的非同步版本。

  回傳發送的位元組數。

  sock 必須是非阻塞 socket。

  在 3.11 版被加入.

async loop.sock_connect(sock, address)

  將 sock 連線到位於 address 的遠端 socket。

  `socket.connect()` 的非同步版本。

  sock 必須是非阻塞 socket。

  在 3.5.2 版的變更: 不再需要解析 `address`。`sock_connect` 將嘗試透過呼叫 `socket.inet_pton()` 檢查 address 是否已解析。如果沒有，將使用 `loop.getaddrinfo()` 解析 address。

  也參考

  `loop.create_connection()` 和 `asyncio.open_connection()`。

async loop.sock_accept(sock)

  接受一個連線。模擬阻塞的 `socket.accept()` 方法。

  Socket 必須繫結到一個地址並偵聽連線。回傳值是一個 `(conn, address)` 對，其中 conn 是一個 新 socket 物件，可在連線上發送和接收資料，address 是連接另一端對應的 socket 地址。

  sock 必須是非阻塞 socket。

  在 3.7 版的變更: 儘管該方法一直被記錄為協程方法，但在 Python 3.7 之前它回傳 `Future`。從 Python 3.7 開始，這是一個 `async def` 方法。

  也參考

  `loop.create_server()` 和 `start_server()`。

async loop.sock_sendfile(sock, file, offset=0, count=None, *, fallback=True)

  如果可行，使用高性能 `os.sendfile` 發送檔案。回傳發送的總位元組數。

  `socket.sendfile()` 的非同步版本。

  sock 必須是非阻塞的 `socket.SOCK_STREAM` `socket`。

  file 必須是以二進位模式打開的常規檔案物件。

  offset 告訴從哪裡開始讀取檔案。如果指定了，count 是要傳輸的總位元組數，而不是發送檔案直到達到 EOF。即使此方法引發錯誤時，檔案位置也始終更新，可以使用 `file.tell()` 取得實際發送的位元組數。

  當設置為 `True` 時，fallback 使 asyncio 在平台不支援 sendfile 系統呼叫時（例如 Windows 或 Unix 上的 SSL socket）手動讀取和發送檔案。

  如果系統不支援 sendfile 系統呼叫且 fallback 為 `False`，引發 `SendfileNotAvailableError`。

  sock 必須是非阻塞 socket。

  在 3.7 版被加入.

### DNS

async loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0)

  `socket.getaddrinfo()` 的非同步版本。

async loop.getnameinfo(sockaddr, flags=0)

  `socket.getnameinfo()` 的非同步版本。

備註

Both getaddrinfo and getnameinfo internally utilize their synchronous versions through the loop's default thread pool executor. When this executor is saturated, these methods may experience delays, which higher-level networking libraries may report as increased timeouts. To mitigate this, consider using a custom executor for other user tasks, or setting a default executor with a larger number of workers.

在 3.7 版的變更: getaddrinfo 和 getnameinfo 方法一直被記錄為回傳協程，但在 Python 3.7 之前它們實際上回傳 `asyncio.Future` 物件。從 Python 3.7 開始，兩個方法都是協程。

### 使用管道

async loop.connect_read_pipe(protocol_factory, pipe)

  在事件迴圈中註冊 pipe 的讀取端。

  protocol_factory 必須是一個回傳 asyncio protocol 實作的可呼叫函式。

  pipe 是 類檔案物件。

  回傳 `(transport, protocol)` 對，其中 transport 支援 `ReadTransport` 介面，protocol 是由 protocol_factory 實例化的物件。

  使用 `SelectorEventLoop` 事件迴圈時，pipe 設置為非阻塞模式。

async loop.connect_write_pipe(protocol_factory, pipe)

  在事件迴圈中註冊 pipe 的寫入端。

  protocol_factory 必須是一個回傳 asyncio protocol 實作的可呼叫函式。

  pipe 是 file-like object。

  回傳 `(transport, protocol)` 對，其中 transport 支援 `WriteTransport` 介面，protocol 是由 protocol_factory 實例化的物件。

  使用 `SelectorEventLoop` 事件迴圈時，pipe 設置為非阻塞模式。

備註

`SelectorEventLoop` 在 Windows 上不支援上述方法。對於 Windows 請使用 `ProactorEventLoop`。

也參考

`loop.subprocess_exec()` 和 `loop.subprocess_shell()` 方法。

### Unix 訊號

loop.add_signal_handler(signum, callback, *args)

  將 callback 設置為 signum 訊號的處理程式，並將 args 作為位置引數傳遞。

  該回呼將由 loop 叫用，與該事件迴圈的其他排隊回呼和可運行的協程一起。與使用 `signal.signal()` 註冊的訊號處理程式不同，使用此函式註冊的回呼允許與事件迴圈進行互動。

  如果訊號號無效或不可捕獲，引發 `ValueError`。如果設定處理程序有問題，拋出 `RuntimeError`。

  使用 `functools.partial()` 向 callback 傳送關鍵字引數。

  像 `signal.signal()` 一樣，此函式必須在主執行緒中叫用。

loop.remove_signal_handler(sig)

  移除 sig 訊號的處理程式。

  如果訊號處理程式被移除，回傳 `True`；如果給定訊號沒有設置處理程式，回傳 `False`。

  可用性: Unix.

也參考

`signal` 模組。

### 在執行緒池或行程池中執行程式碼

awaitable loop.run_in_executor(executor, func, *args)

  安排在指定的執行器中呼叫 func，並將 args 作為位置引數傳遞。

  The executor argument should be an `concurrent.futures.Executor` instance. The default executor is used if executor is `None`. The default executor can be set by `loop.set_default_executor()`, otherwise, a `concurrent.futures.ThreadPoolExecutor` will be lazy-initialized and used by `run_in_executor()` if needed.

  範例：

      import asyncio
      import concurrent.futures

      def blocking_io():
          # File operations (such as logging) can block the
          # event loop: run them in a thread pool.
          with open('/dev/urandom', 'rb') as f:
              return f.read(100)

      def cpu_bound():
          # CPU-bound operations will block the event loop:
          # in general it is preferable to run them in a
          # process pool.
          return sum(i * i for i in range(10 ** 7))

      async def main():
          loop = asyncio.get_running_loop()

          ## Options:

          # 1. Run in the default loop's executor:
          result = await loop.run_in_executor(
              None, blocking_io)
          print('default thread pool', result)

          # 2. Run in a custom thread pool:
          with concurrent.futures.ThreadPoolExecutor() as pool:
              result = await loop.run_in_executor(
                  pool, blocking_io)
              print('custom thread pool', result)

          # 3. Run in a custom process pool:
          with concurrent.futures.ProcessPoolExecutor() as pool:
              result = await loop.run_in_executor(
                  pool, cpu_bound)
              print('custom process pool', result)

          # 4. Run in a custom interpreter pool:
          with concurrent.futures.InterpreterPoolExecutor() as pool:
              result = await loop.run_in_executor(
                  pool, cpu_bound)
              print('custom interpreter pool', result)

      if __name__ == '__main__':
          asyncio.run(main())

  請注意，由於 `multiprocessing`（由 `ProcessPoolExecutor` 使用）的特殊性，選項 3 需要進入點保護（`if __name__ == '__main__'`）。請參閱主模組的安全引入。

  此方法回傳 `asyncio.Future` 物件。

  使用 `functools.partial()` 將來關鍵字引數傳遞給 func。

  在 3.5.3 版的變更: `loop.run_in_executor()` 不再配置它建立的執行緒池執行器的 `max_workers`，而是讓執行緒池執行器（`ThreadPoolExecutor`）設定預設值。

loop.set_default_executor(executor)

  將 executor 設置為 `run_in_executor()` 使用的預設執行器。executor 必須是 `ThreadPoolExecutor`（也包含 `InterpreterPoolExecutor`）的實例。

  在 3.11 版的變更: executor 必須是 `ThreadPoolExecutor` 的實例。

### 錯誤處理 API

允許自訂事件迴圈中的例外處理方式。

loop.set_exception_handler(handler)

  將 handler 設定為新的事件迴圈例外處理程式。

  如果 handler 是 `None`，則將設置預設例外處理程式。否則，handler 必須是一個可呼叫物件，簽名匹配 `(loop, context)`，其中 `loop` 是參照活躍事件迴圈的，`context` 是包含例外詳細資訊的 `dict` 物件（有關情境的詳細資訊，請參閱 `call_exception_handler()` 文件）。

  如果代表 `Task` 或 `Handle` 呼叫處理程式，它將在該任務或回呼處理程式的 `contextvars.Context` 中運行。

  在 3.12 版的變更: 處理程式可能在引發例外的任務或處理程式的 `Context` 中被呼叫。

loop.get_exception_handler()

  回傳目前的例外處理程式，如果未設置自訂例外處理程式，則回傳 `None`。

  在 3.5.2 版被加入.

loop.default_exception_handler(context)

  預設例外處理程式。

  當發生例外且未設置例外處理程式時呼叫此函式。自訂例外處理程式可以呼叫此函式以轉由預設處理程式處理。

  context 參數與 `call_exception_handler()` 中的意思相同。

loop.call_exception_handler(context)

  呼叫目前事件迴圈例外處理程式。

  context 是一個包含以下鍵的 `dict` 物件（未來的 Python 版本中可能會引入新的鍵）:

  - 'message'：錯誤訊息；

  - 'exception'（可選）：例外物件；

  - 'future'（可選）： `asyncio.Future` 實例；

  - 'task'（可選）： `asyncio.Task` 實例；

  - 'handle'（可選）： `asyncio.Handle` 實例；

  - 'protocol'（可選）： Protocol 實例；

  - 'transport'（可選）： Transport 實例；

  - 'socket'（可選）： `socket.socket` 實例；

  - 'source_traceback' (optional): Traceback of the source;

  - 'handle_traceback' (optional): Traceback of the handle;

  - 'asyncgen'(可選)： 非同步產生器引發

      例外。

  備註

  此方法不應在子類別事件迴圈中被覆寫。為了自訂例外處理，請使用 `set_exception_handler()` 方法。

### 啟用除錯模式

loop.get_debug()

  取得事件迴圈的除錯模式（`bool`）。

  如果環境變數 `PYTHONASYNCIODEBUG` 被設定為非空字串，則預設值為 `True`，否則為 `False`。

loop.set_debug(enabled: bool)

  設定事件迴圈的除錯模式。

  在 3.7 版的變更: 現在也可以使用新的 Python 開發模式 啟用除錯模式。

loop.slow_callback_duration

  此屬性可用於設定被視為"慢"的最短執行時間（以秒為單位）。啟用偵錯模式後，"慢"回呼將被記錄。

  預設值為 100 毫秒

也參考

asyncio 的除錯模式。

### 運行子行程

本小節描述的方法是低階的。在常規的 async/await 程式碼中，請考慮使用高階 `asyncio.create_subprocess_shell()` 和 `asyncio.create_subprocess_exec()` 輔助功能而不是。

備註

在 Windows 上，預設事件迴圈 `ProactorEventLoop` 支援子行程，而 `SelectorEventLoop` 不支援。詳細資訊請參見 Windows 上對於子行程的支援。

async loop.subprocess_exec(protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

  從 args 指定的一個或多個字串引數建立子行程。

  args 必須是由以下項表示的字串串列：

  - `str`；

  - 或 `bytes`，編碼為 檔案系統編碼。

  第一個字串指定程序可執行檔案，其餘字串指定引數。字串引數一起組成程序的 `argv`。

  這與標準函式庫 `subprocess.Popen` 類似，使用 `shell=False` 呼叫並將字串串列作為第一個引數傳遞；然而，`Popen` 接受單個字串串列引數，subprocess_exec 接受多個字串引數。

  protocol_factory 必須是回傳 `asyncio.SubprocessProtocol` 子類別的可呼叫物件。

  其他參數：

  - stdin 可以是以下任意一個：

    - 類檔案物件

    - 現有的檔案描述器（正整數），例如用 `os.pipe()` 建立的

    - `subprocess.PIPE` 常數（預設），它將建立一個新的管道並連線，

    - 值 `None` 將使子行程從此行程繼承檔案描述器

    - `subprocess.DEVNULL` 常數，表示將使用特殊的 `os.devnull` 檔案

  - stdout 可以是以下任意一個：

    - 類檔案物件

    - `subprocess.PIPE` 常數（預設），它將建立一個新的管道並連線，

    - 值 `None` 將使子行程從此行程繼承檔案描述器

    - `subprocess.DEVNULL` 常數，表示將使用特殊的 `os.devnull` 檔案

  - stderr 可以是以下任意一個：

    - 類檔案物件

    - `subprocess.PIPE` 常數（預設），它將建立一個新的管道並連線，

    - 值 `None` 將使子行程從此行程繼承檔案描述器

    - `subprocess.DEVNULL` 常數，表示將使用特殊的 `os.devnull` 檔案

    - `subprocess.STDOUT` 常數，它將標準錯誤串流連線到行程的標準輸出串流

  - 所有其他關鍵字引數都會傳遞給 `subprocess.Popen` 而不進行直譯，但 bufsize、universal_newlines、shell、text、encoding 和 errors 除外，這些不應該指定。

    `asyncio` 子行程 API 不支援將串流解碼為文本。可以使用 `bytes.decode()` 將從串流回傳的位元組轉換為文本。

  如果傳遞給 stdin、stdout 或 stderr 的類檔案物件表示管道，則該管道的另一端應該使用 `connect_write_pipe()` 或 `connect_read_pipe()` 註冊到事件迴圈中。

  有關其他引數的文件，請參閱 `subprocess.Popen` 類別的建構函式。

  回傳 `(transport, protocol)` 對，其中 transport 符合 `asyncio.SubprocessTransport` 基底類別，protocol 是由 protocol_factory 實例化的物件。

  If the transport is closed or is garbage collected, the child process is killed if it is still running.

async loop.subprocess_shell(protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs)

  使用平台的 "shell" 語法從 cmd 建立子行程，cmd 可以是 `str` 或編碼為 檔案系統編碼 的 `bytes` 字串。

  這類似於標準函式庫中的 `subprocess.Popen` 類別，使用 `shell=True` 呼叫。

  protocol_factory 必須是回傳 `SubprocessProtocol` 子類別的可呼叫物件。

  有關其餘引數的更多詳細資訊，請參閱 `subprocess_exec()`。

  回傳一對 `(transport, protocol)`，其中 transport 符合 `SubprocessTransport` 基底類別，而 protocol 是由 protocol_factory 實例化的物件。

  If the transport is closed or is garbage collected, the child process is killed if it is still running.

備註

由應用程式負責確保適當引用所有空白和特殊字元，以避免 shell 注入風險。可以使用 `shlex.quote()` 函式來正確跳脫用於構建 shell 命令的字串中的空白和特殊字元。

## 回呼處理

class asyncio.Handle

  由 `loop.call_soon()` 和 `loop.call_soon_threadsafe()` 回傳的回呼包裝器。

  get_context()

    回傳與處理相關聯的 `contextvars.Context` 物件。

    在 3.12 版被加入.

  cancel()

    取消回呼。如果回呼已被取消或執行，此方法將不起作用。

  cancelled()

    如果回呼已被取消，回傳 `True`。

    在 3.7 版被加入.

class asyncio.TimerHandle

  由 `loop.call_later()` 和 `loop.call_at()` 回傳的回呼包裝器。

  這個類別是 `Handle` 的子類別。

  when()

    回傳預定的回呼時間，以 `float` 秒為單位。

    時間是一個絕對的時間戳，使用與 `loop.time()` 相同的時間參照。

    在 3.7 版被加入.

## Server 物件

Server 物件是由 `loop.create_server()`、`loop.create_unix_server()`、`start_server()` 和 `start_unix_server()` 函式所建立。

請勿直接實例化 `Server` 類別。

class asyncio.Server

  Server 物件是非同步情境管理器。當在 `async with` 陳述中使用時，可以保證在完成 `async with` 陳述時，Server 物件將會關閉並停止接受新的連線：

      srv = await loop.create_server(...)

      async with srv:
          # 一些程式碼

      # 此時 srv 已關閉，不再接受新的連線。

  在 3.7 版的變更: 自 Python 3.7 起，Server 物件是非同步情境管理器。

  在 3.11 版的變更: 此類別在 Python 3.9.11、3.10.3 和 3.11 中以 `asyncio.Server` 的形式被公開。

  close()

    停止服務：關閉監聽的 sockets 並將 `sockets` 屬性設為 `None`。

    代表現有傳入用戶端連線的 sockets 仍然保持開啟。

    伺服器以非同步方式關閉；使用 `wait_closed()` 協程等待伺服器關閉（不再有活躍連線）。

  close_clients()

    關閉所有現有的傳入用戶端連線。

    在所有關聯的傳輸上呼叫 `close()`。

    `close()` should be called before `close_clients()` when closing the server to avoid races with new clients connecting.

    在 3.13 版被加入.

  abort_clients()

    立即關閉所有現有的傳入用戶端連線，而不等待待定操作完成。

    在所有關聯的傳輸上呼叫 `abort()`。

    `close()` should be called before `abort_clients()` when closing the server to avoid races with new clients connecting.

    在 3.13 版被加入.

  get_loop()

    回傳與伺服器物件關聯的事件迴圈。

    在 3.7 版被加入.

  async start_serving()

    開始接受連線。

    此方法是幂等的，因此可以在伺服器已經運行時呼叫。

    start_serving 僅限關鍵字參數只能在 `loop.create_server()` 和 `asyncio.start_server()` 中使用，允許建立一個最初不接受連線的 Server 物件。在這種情況下，可以使用 `Server.start_serving()` 或 `Server.serve_forever()` 來使 Server 開始接受連線。

    在 3.7 版被加入.

  async serve_forever()

    開始接受連線，直到協程被取消。取消 `serve_forever` 任務會導致伺服器關閉。

    如果伺服器已經接受連線，則可以呼叫此方法。每個 Server 物件只能存在一個 `serve_forever` 任務。

    範例：

        async def client_connected(reader, writer):
            # 透過讀取器/寫入器串流
            # 與用戶端溝通。例如：
            await reader.readline()

        async def main(host, port):
            srv = await asyncio.start_server(
                client_connected, host, port)
            await srv.serve_forever()

        asyncio.run(main('127.0.0.1', 0))

    在 3.7 版被加入.

  is_serving()

    如果伺服器正在接受新連線，則回傳 `True`。

    在 3.7 版被加入.

  async wait_closed()

    等待 `close()` 方法完成且所有活動連線都已結束。

  sockets

    伺服器正在監聽的類似 socket 的物件串列，`asyncio.trsock.TransportSocket`。

    在 3.7 版的變更: 在 Python 3.7 之前，`Server.sockets` 曾經直接回傳內部伺服器 sockets 的串列。在 3.7 中回傳了該串列的副本。

## 事件迴圈實作

asyncio 內附兩個不同的事件迴圈實作：`SelectorEventLoop` 和 `ProactorEventLoop`。

預設情況下，asyncio 被配置為要使用 `EventLoop`。

class asyncio.SelectorEventLoop

  基於 `selectors` 模組的一個 `AbstractEventLoop` 子類別。

  使用特定平台上最有效的 selector。也可以手動配置要使用的確切 selector 實作：

      import asyncio
      import selectors

      async def main():
         ...

      loop_factory = lambda: asyncio.SelectorEventLoop(selectors.SelectSelector())
      asyncio.run(main(), loop_factory=loop_factory)

  可用性: Unix, Windows.

class asyncio.ProactorEventLoop

  用於 Windows 的 `AbstractEventLoop` 子類別，使用「I/O 完成埠 (IOCP, I/O Completion Ports)」。

  可用性: Windows.

  也參考

  I/O 完成埠的 MSDN 文件。

class asyncio.EventLoop

  > An alias to the most efficient available subclass of `AbstractEventLoop` for the given platform.

  > 在 Unix 上是 `SelectorEventLoop` 的別名，在 Windows 上是 `ProactorEventLoop` 的別名。

  在 3.13 版被加入.

class asyncio.AbstractEventLoop

  為符合 asyncio 標準的事件迴圈的抽象基礎類別。

  事件迴圈方法 部分列出了替代 `AbstractEventLoop` 實作應該定義的所有方法。

## 範例

請注意，本節中的所有範例都 故意 展示如何使用低階事件迴圈 API，如 `loop.run_forever()` 和 `loop.call_soon()`。現代 asyncio 應用程式很少需要這種方式撰寫；請考慮使用高階的函式，如 `asyncio.run()`。

### 使用 call_soon() 的 Hello World 範例

使用 `loop.call_soon()` 方法排程回呼的範例。回呼會顯示 `"Hello World"`，然後停止事件迴圈：

    import asyncio

    def hello_world(loop):
        """列印 'Hello World' 並停止事件迴圈的回呼"""
        print('Hello World')
        loop.stop()

    loop = asyncio.new_event_loop()

    # 排程對 hello_world() 的呼叫
    loop.call_soon(hello_world, loop)

    # 阻塞呼叫被 loop.stop() 中斷
    try:
        loop.run_forever()
    finally:
        loop.close()

也參考

使用協程和 `run()` 函式建立的類似 Hello World 範例。

### 使用 call_later() 顯示目前日期

一個回呼的範例，每秒顯示目前日期。回呼使用 `loop.call_later()` 方法在 5 秒後重新排程自己，然後停止事件迴圈：

    import asyncio
    import datetime as dt

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

    loop = asyncio.new_event_loop()

    # 排程 display_date() 的第一次呼叫
    end_time = loop.time() + 5.0
    loop.call_soon(display_date, end_time, loop)

    # 阻塞呼叫被 loop.stop() 中斷
    try:
        loop.run_forever()
    finally:
        loop.close()

也參考

使用協程和 `run()` 函式建立的類似 current date 範例。

### 監聽檔案描述器以進行讀取事件

使用 `loop.add_reader()` 方法等待檔案描述器接收到某些資料，然後關閉事件迴圈：

    import asyncio
    from socket import socketpair

    # 建立一對連接的檔案描述器
    rsock, wsock = socketpair()

    loop = asyncio.new_event_loop()

    def reader():
        data = rsock.recv(100)
        print("Received:", data.decode())

        # 我們完成了：註銷檔案描述器
        loop.remove_reader(rsock)

        # 停止事件迴圈
        loop.stop()

    # 為讀取事件註冊檔案描述器
    loop.add_reader(rsock, reader)

    # 模擬從網路接收資料
    loop.call_soon(wsock.send, 'abc'.encode())

    try:
        # 運行事件迴圈
        loop.run_forever()
    finally:
        # 我們完成了。關閉 socket 和事件迴圈。
        rsock.close()
        wsock.close()
        loop.close()

也參考

- 使用傳輸、協定和 `loop.create_connection()` 方法的類似 範例。

- 另一個使用高階 `asyncio.open_connection()` 函式和串流的類似 範例。

### 設定 SIGINT 和 SIGTERM 的訊號處理程式

（此 `signal` 範例僅在 Unix 上運作。）

使用 `loop.add_signal_handler()` 方法註冊訊號 `SIGINT` 和 `SIGTERM` 的處理程式：

    import asyncio
    import functools
    import os
    import signal

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

    async def main():
        loop = asyncio.get_running_loop()

        for signame in {'SIGINT', 'SIGTERM'}:
            loop.add_signal_handler(
                getattr(signal, signame),
                functools.partial(ask_exit, signame, loop))

        await asyncio.sleep(3600)

    print("Event loop running for 1 hour, press Ctrl+C to interrupt.")
    print(f"pid {os.getpid()}: send SIGINT or SIGTERM to exit.")

    asyncio.run(main())