# 低階 API 索引

本頁列出所有低階 asyncio APIs。

## 獲取事件迴圈

`asyncio.get_running_loop()` | 推薦使用於獲取當前運行事件迴圈 (event loop) 的函式。
`asyncio.get_event_loop()` | 獲得一個（正在運行的或透過當前 policy 建立的）事件迴圈實例。
`asyncio.set_event_loop()` | 透過當前 policy 來設定當前事件迴圈。
`asyncio.new_event_loop()` | 建立一個新的事件迴圈。

範例

- 使用 asyncio.get_running_loop()。

## 事件迴圈方法

也請查閱文件中關於事件迴圈方法的主要段落。

生命週期

`loop.run_until_complete()` | 執行一個 Future/Task/awaitable（可等待物件）直到完成。
`loop.run_forever()` | 持續運行事件迴圈。
`loop.stop()` | 停止事件迴圈。
`loop.close()` | 關閉事件迴圈。
`loop.is_running()` | 如果事件迴圈正在執行則回傳 `True`。
`loop.is_closed()` | 如果事件迴圈已經被關閉則回傳 `True`。
`await` `loop.shutdown_asyncgens()` | 關閉非同步產生器 (asynchronous generators)。

除錯

`loop.set_debug()` | 開啟或禁用除錯模式。
`loop.get_debug()` | 獲取當前除錯模式。

為回呼函式排程

`loop.call_soon()` | 儘快調用回呼函式 (callback)。
`loop.call_soon_threadsafe()` | `loop.call_soon()` 方法之有支援執行緒安全 (thread-safe) 變體。
`loop.call_later()` | 在給定時間之後調用回呼函式。
`loop.call_at()` | 在給定時間當下調用回呼函式。

執行緒 (Thread)/行程池 (Process Pool)

`await` `loop.run_in_executor()` | 在 `concurrent.futures` 執行器 (excutor) 中執行一個 CPU 密集型 (CPU-bound) 或其它阻塞型式的函式。
`loop.set_default_executor()` | 為 `loop.run_in_executor()` 設定預設執行器。

Tasks 與 Futures

`loop.create_future()` | 建立一個 `Future` 物件。
`loop.create_task()` | 像是 `Task` 一樣，為協程 (coroutine) 排程。
`loop.set_task_factory()` | 設定被 `loop.create_task()` 用來建立 `Tasks` 的工廠函式 (factory)。
`loop.get_task_factory()` | 獲取被 `loop.create_task()` 用來建立 `Tasks` 的工廠函式。

DNS

`await` `loop.getaddrinfo()` | 非同步版本的 `socket.getaddrinfo()`。
`await` `loop.getnameinfo()` | 非同步版本的 `socket.getnameinfo()`。

網路和 IPC

`await` `loop.create_connection()` | 開啟一個 TCP 連線。
`await` `loop.create_server()` | 建立一個 TCP 伺服器。
`await` `loop.create_unix_connection()` | 開啟一個 Unix socket 連線。
`await` `loop.create_unix_server()` | 建立一個 Unix socket 伺服器。
`await` `loop.connect_accepted_socket()` | 將 `socket` 包裝成 `(transport, protocol)`。
`await` `loop.create_datagram_endpoint()` | 開啟一個資料單元 (datagram) (UDP) 連線。
`await` `loop.sendfile()` | 透過傳輸通道傳送一個檔案。
`await` `loop.start_tls()` | 將一個已存在的連線升級到 TLS。
`await` `loop.connect_read_pipe()` | 將 pipe（管道）讀取端包裝成 `(transport, protocol)`。
`await` `loop.connect_write_pipe()` | 將 pipe 寫入端包裝成 `(transport, protocol)`。

Sockets

`await` `loop.sock_recv()` | 從 `socket` 接收資料。
`await` `loop.sock_recv_into()` | 將從 `socket` 接收到的資料存放於一個緩衝區 (buffer) 中。
`await` `loop.sock_recvfrom()` | 從 `socket` 接收一個資料單元。
`await` `loop.sock_recvfrom_into()` | 將從 `socket` 接收到的資料單元存放於一個緩衝區中。
`await` `loop.sock_sendall()` | 傳送資料到 `socket`。
`await` `loop.sock_sendto()` | 透過 `socket` 將資料單元傳送至給定的地址。
`await` `loop.sock_connect()` | 連接 `socket`。
`await` `loop.sock_accept()` | 接受一個 `socket` 連線。
`await` `loop.sock_sendfile()` | 透過 `socket` 傳送一個檔案。
`loop.add_reader()` | 開始監控一個檔案描述器 (file descriptor) 的可讀取性。
`loop.remove_reader()` | 停止監控一個檔案描述器的可讀取性。
`loop.add_writer()` | 開始監控一個檔案描述器的可寫入性。
`loop.remove_writer()` | 停止監控一個檔案描述器的可寫入性。

Unix 信號

`loop.add_signal_handler()` | 為 `signal` 新增一個處理函式 (handler)。
`loop.remove_signal_handler()` | 刪除 `signal` 的處理函式。

子行程

`loop.subprocess_exec()` | 衍生 (spawn) 一個子行程 (subprocess)。
`loop.subprocess_shell()` | 從 shell 指令衍生一個子行程。

錯誤處理

`loop.call_exception_handler()` | 呼叫例外處理函式。
`loop.set_exception_handler()` | 設定一個新的例外處理函式。
`loop.get_exception_handler()` | 獲取當前例外處理函式。
`loop.default_exception_handler()` | 預設例外處理函式實作。

範例

- 使用 asyncio.new_event_loop() 和 loop.run_forever()。

- 使用 loop.call_later()。

- 使用 `loop.create_connection()` 以實作一個 echo 客戶端。

- 使用 `loop.create_connection()` 來連接 socket。

- 使用 add_reader() 監控 FD 的讀取事件。

- 使用 loop.add_signal_handler()。

- 使用 loop.add_signal_handler()。

## 傳輸

所有傳輸方式都有實作以下方法：

`transport.close()` | 關閉傳輸。
`transport.is_closing()` | 如果傳輸正在關閉或已經關閉則回傳 `True`。
`transport.get_extra_info()` | 請求傳輸的相關資訊。
`transport.set_protocol()` | 設定一個新協定。
`transport.get_protocol()` | 回傳當前協定。

可以接收資料（TCP 和 Unix 連線、pipe 等）的傳輸。它由 `loop.create_connection()`、`loop.create_unix_connection()`、`loop.connect_read_pipe()` 等方法回傳：

讀取傳輸

`transport.is_reading()` | 如果傳輸正在接收則回傳 `True`。
`transport.pause_reading()` | 暫停接收。
`transport.resume_reading()` | 繼續接收。

可以傳送資料（TCP 和 Unix 連線、pipe 等）的傳輸。它由 `loop.create_connection()`、`loop.create_unix_connection()`、`loop.connect_write_pipe()` 等方法回傳：

寫入傳輸

`transport.write()` | 將資料寫入傳輸。
`transport.writelines()` | 將緩衝區資料寫入傳輸。
`transport.can_write_eof()` | 如果傳輸支援傳送 EOF 則回傳 `True`。
`transport.write_eof()` | 在清除 (flush) 已緩衝的資料後關閉傳輸並傳送 EOF。
`transport.abort()` | 立即關閉傳輸。
`transport.get_write_buffer_size()` | 回傳當前輸出緩衝區的大小。
`transport.get_write_buffer_limits()` | 回傳用於寫入流量控制 (write flow control) 的高低標記位 (high and low water marks)。
`transport.set_write_buffer_limits()` | 為寫入流量控制設定高低標記位。

由 `loop.create_datagram_endpoint()` 回傳的傳輸：

資料單元傳輸

`transport.sendto()` | 傳送資料到連線遠端。
`transport.abort()` | 立即關閉傳輸。

基於子行程的低階傳輸抽象，它會由 `loop.subprocess_exec()` 和 `loop.subprocess_shell()` 所回傳：

子行程傳輸

`transport.get_pid()` | 回傳子行程的行程 id。
`transport.get_pipe_transport()` | 回傳被請求用於通訊 pipe （stdin、stdout 或 stderr）的傳輸。
`transport.get_returncode()` | 回傳子行程的回傳代號 (return code)。
`transport.kill()` | 殺死子行程。
`transport.send_signal()` | 傳送一個訊號到子行程。
`transport.terminate()` | 停止子行程。
`transport.close()` | 殺死子行程並關閉所有 pipes。

## 協定

協定類別可以實作以下回呼方法：

`callback` `connection_made()` | 在連線建立時被呼叫。
`callback` `connection_lost()` | 在失去連線或連線關閉時被呼叫。
`callback` `pause_writing()` | 在傳輸緩衝區超過高標記位時被呼叫。
`callback` `resume_writing()` | 在傳輸緩衝區低於低標記位時被呼叫。

串流協定 (TCP, Unix socket, Pipes)

`callback` `data_received()` | 在接收到資料時被呼叫。
`callback` `eof_received()` | 在接收到 EOF 時被呼叫。

緩衝串流協定

`callback` `get_buffer()` | 呼叫後會分配新的接收緩衝區。
`callback` `buffer_updated()` | 在以接收到的資料更新緩衝區時被呼叫。
`callback` `eof_received()` | 在接收到 EOF 時被呼叫。

資料單元協定

`callback` `datagram_received()` | 在接收到資料單元時被呼叫。
`callback` `error_received()` | 在前一個傳送或接收操作引發 `OSError` 時被呼叫。

子行程協定

`callback` `pipe_data_received()` | 在子行程向 stdout 或 stderr pipe 寫入資料時被呼叫。
`callback` `pipe_connection_lost()` | 在與子行程通訊的其中一個 pipes 關閉時被呼叫。
`callback` `process_exited()` | 在子行程退出時呼叫。它可以在 `pipe_data_received()` 和 `pipe_connection_lost()` 方法之前呼叫。

## 事件迴圈 Policies

Policy 是改變 `asyncio.get_event_loop()` 這類函式行為的一個低階機制。更多細節請見 Policy 相關段落。

存取 Policy

`asyncio.get_event_loop_policy()` | 回傳當前整個行程中的 Policy。
`asyncio.set_event_loop_policy()` | 設定整個行程中的一個新 Policy。
`AbstractEventLoopPolicy` | Policy 物件的基礎類別。