低階 API 索引

本頁列出所有低階 asyncio APIs。

獲取事件迴圈

asyncio.get_running_loop()

推薦使用於獲取當前運行事件迴圈 (event loop) 的函式。

asyncio.get_event_loop()

獲得一個(正在運行的或透過當前 policy 建立的)事件迴圈實例。

asyncio.set_event_loop()

透過當前 policy 來設定當前事件迴圈。

asyncio.new_event_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()

預設例外處理函式實作。

範例

傳輸

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

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 (stdinstdoutstderr)的傳輸。

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()

在子行程向 stdoutstderr 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 物件的基礎類別。