低階 API 索引
*************

本頁列出所有低階 asyncio APIs。


獲取事件迴圈
============

+----------------------------------------------------+----------------------------------------------------+
| "asyncio.get_running_loop()"                       | **推薦使用**於獲取當前運行事件迴圈 (event loop) 的 |
|                                                    | 函式。                                             |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.get_event_loop()"                         | 获取一个事件循环实例（正在运行的事件循环或通过当前 |
|                                                    | 策略确定的当前事件循 环）。                        |
+----------------------------------------------------+----------------------------------------------------+
| "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_sendall()"                      | 傳送資料到 "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.get_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()"                      | 在子行程退出後被呼叫。                             |
+----------------------------------------------------+----------------------------------------------------+


事件迴圈 Policies
=================

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

-[ 存取 Policy ]-

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