# 高階 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 專用例外完整列表。