高階 API 索引
*************

這個頁面列出了所有能使用 async/wait 的高階 asyncio API。


任務 (Tasks)
============

用於執行非同步程式、建立 Task 物件、帶有超時 (timeout) 設定地等待多個
事件的工具程式。

+----------------------------------------------------+----------------------------------------------------+
| "run()"                                            | 建立事件迴圈 (event loop)、執行一個協程            |
|                                                    | (coroutine)、關閉事件迴圈。                        |
+----------------------------------------------------+----------------------------------------------------+
| "create_task()"                                    | 啟動一個 asyncio 的 Task 物件。                    |
+----------------------------------------------------+----------------------------------------------------+
| "await" "sleep()"                                  | 休眠數秒鐘。                                       |
+----------------------------------------------------+----------------------------------------------------+
| "await" "gather()"                                 | 並行 (concurrent) 地執行事件的排程與等待。         |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait_for()"                               | 有超時設置的執行。                                 |
+----------------------------------------------------+----------------------------------------------------+
| "await" "shield()"                                 | 屏蔽取消操作。                                     |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait()"                                   | 監控完成情況。                                     |
+----------------------------------------------------+----------------------------------------------------+
| "current_task()"                                   | 回傳當前 Task 物件。                               |
+----------------------------------------------------+----------------------------------------------------+
| "all_tasks()"                                      | 回傳事件迴圈中所有的 task 物件。                   |
+----------------------------------------------------+----------------------------------------------------+
| "Task"                                             | Task 物件。                                        |
+----------------------------------------------------+----------------------------------------------------+
| "to_thread()"                                      | 在不同的 OS 執行緒 (thread) 中非同步地執行一個函式 |
|                                                    | 。                                                 |
+----------------------------------------------------+----------------------------------------------------+
| "run_coroutine_threadsafe()"                       | 從其他 OS 執行緒中為一個協程排程。                 |
+----------------------------------------------------+----------------------------------------------------+
| "for in" "as_completed()"                          | 用 "for" 迴圈來監控完成情況。                      |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

* 使用 asyncio.gather() 平行 (parallel) 執行。

* 使用 asyncio.wait_for() 強制設置超時。

* 取消任務。

* 使用 asyncio.sleep()。

* 請參閱 Tasks 文件頁面。


佇列 (Queues)
=============

佇列應被用於為多個 asyncio Task 物件分配工作、實作 connection pools（
連線池）以及 pub/sub（發行/訂閱）模式。

+----------------------------------------------------+----------------------------------------------------+
| "Queue"                                            | 一個先進先出 (FIFO) 佇列。                         |
+----------------------------------------------------+----------------------------------------------------+
| "PriorityQueue"                                    | 一個優先佇列 (priority queue)。                    |
+----------------------------------------------------+----------------------------------------------------+
| "LifoQueue"                                        | 一個後進先出 (LIFO) 佇列。                         |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

* 使用 asyncio.Queue 為多個 Task 分配工作。

* 請參閱佇列文件頁面。


子行程 (Subprocesses)
=====================

用於衍生（spawn）子行程和執行 shell 指令的工具程式。

+----------------------------------------------------+----------------------------------------------------+
| "await" "create_subprocess_exec()"                 | 建立一個子行程。                                   |
+----------------------------------------------------+----------------------------------------------------+
| "await" "create_subprocess_shell()"                | 執行一個 shell 命令。                              |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

* 執行一個 shell 指令。

* 請參閱子行程 APIs 相關文件。


串流 (Streams)
==============

用於網路 IO 處理的高階 API。

+----------------------------------------------------+----------------------------------------------------+
| "await" "open_connection()"                        | 建立一個 TCP 連線。                                |
+----------------------------------------------------+----------------------------------------------------+
| "await" "open_unix_connection()"                   | 建立一個 Unix socket 連線。                        |
+----------------------------------------------------+----------------------------------------------------+
| "await" "start_server()"                           | 啟動一個 TCP 伺服器。                              |
+----------------------------------------------------+----------------------------------------------------+
| "await" "start_unix_server()"                      | 啟動一個 Unix socket 伺服器。                      |
+----------------------------------------------------+----------------------------------------------------+
| "StreamReader"                                     | 接收網路資料的高階 async/await 物件。              |
+----------------------------------------------------+----------------------------------------------------+
| "StreamWriter"                                     | 傳送網路資料的高階 async/await 物件。              |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

* TCP 客戶端範例。

* 請參閱串流 APIs 文件。


同步化 (Synchronization)
========================

類似執行緒且能被用於 Task 中的同步化原始物件 (primitive)。

+----------------------------------------------------+----------------------------------------------------+
| "Lock"                                             | 一個互斥鎖 (mutex lock)。                          |
+----------------------------------------------------+----------------------------------------------------+
| "Event"                                            | 一個事件物件。                                     |
+----------------------------------------------------+----------------------------------------------------+
| "Condition"                                        | 一個條件物件。                                     |
+----------------------------------------------------+----------------------------------------------------+
| "Semaphore"                                        | 一個旗號 (semaphore) 物件。                        |
+----------------------------------------------------+----------------------------------------------------+
| "BoundedSemaphore"                                 | 一個有界的旗號物件。                               |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

* 使用 asyncio.Event。

* 請參閱 asyncio 關於同步化原始物件的文件。


例外
====

+----------------------------------------------------+----------------------------------------------------+
| "asyncio.TimeoutError"                             | 在像是 "wait_for()" 等函式超時的時候被引發。請注意 |
|                                                    | "asyncio.TimeoutError" 與內建例外 "TimeoutError"   |
|                                                    | **無關**。                                         |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.CancelledError"                           | 當一 Task 物件被取消時被引發。請參閱               |
|                                                    | "Task.cancel()"。                                  |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

* 在取消請求發生的程式中處理 CancelledError 例外。

* 請參閱 asyncio 專用例外完整列表。
