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

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


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

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

+----------------------------------------------------+----------------------------------------------------+
| "run()"                                            | 建立事件迴圈 (event loop)、執行一個協程            |
|                                                    | (coroutine)、關閉事件迴圈。                        |
+----------------------------------------------------+----------------------------------------------------+
| "Runner"                                           | A context manager that simplifies multiple async   |
|                                                    | function calls.                                    |
+----------------------------------------------------+----------------------------------------------------+
| "Task"                                             | Task 物件。                                        |
+----------------------------------------------------+----------------------------------------------------+
| "TaskGroup"                                        | A context manager that holds a group of tasks.     |
|                                                    | Provides a convenient and reliable way to wait for |
|                                                    | all tasks in the group to finish.                  |
+----------------------------------------------------+----------------------------------------------------+
| "create_task()"                                    | 啟動一個 asyncio 的 Task 物件，然後回傳它。        |
+----------------------------------------------------+----------------------------------------------------+
| "current_task()"                                   | 回傳目前 Task 物件。                               |
+----------------------------------------------------+----------------------------------------------------+
| "all_tasks()"                                      | 回傳事件迴圈中所有未完成的 task 物件。             |
+----------------------------------------------------+----------------------------------------------------+
| "await" "sleep()"                                  | 休眠數秒鐘。                                       |
+----------------------------------------------------+----------------------------------------------------+
| "await" "gather()"                                 | 並行 (concurrent) 地執行事件的排程與等待。         |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait_for()"                               | 有超時設置的執行。                                 |
+----------------------------------------------------+----------------------------------------------------+
| "await" "shield()"                                 | 屏蔽取消操作。                                     |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait()"                                   | 監控完成情況。                                     |
+----------------------------------------------------+----------------------------------------------------+
| "timeout()"                                        | Run with a timeout. Useful in cases when           |
|                                                    | "wait_for" is not suitable.                        |
+----------------------------------------------------+----------------------------------------------------+
| "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"                                 | 一個有界的旗號物件。                               |
+----------------------------------------------------+----------------------------------------------------+
| "Barrier"                                          | 一個屏障物件。                                     |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

* 使用 asyncio.Event。

* 使用 asyncio.Barrier。

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


例外
====

+----------------------------------------------------+----------------------------------------------------+
| "asyncio.CancelledError"                           | 當一 Task 物件被取消時被引發。請參閱               |
|                                                    | "Task.cancel()"。                                  |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.BrokenBarrierError"                       | 當一 Barrier 物件損壞時被引發。請參閱              |
|                                                    | "Barrier.wait()"。                                 |
+----------------------------------------------------+----------------------------------------------------+

-[ 範例 ]-

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

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