高层级 API 索引
***************

这个页面列举了所有能用于 async/wait 的高层级asyncio API 集。


任务
====

运行异步程序，创建Task对象，等待多件事运行超时的公共集。

+----------------------------------------------------+----------------------------------------------------+
| "run()"                                            | 创建事件循环，运行一个协程，关闭事件循环。         |
+----------------------------------------------------+----------------------------------------------------+
| "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()"                                    | Start an asyncio Task, then returns it.            |
+----------------------------------------------------+----------------------------------------------------+
| "current_task()"                                   | 返回当前Task对象                                   |
+----------------------------------------------------+----------------------------------------------------+
| "all_tasks()"                                      | Return all tasks that are not yet finished for an  |
|                                                    | event loop.                                        |
+----------------------------------------------------+----------------------------------------------------+
| "await" "sleep()"                                  | 休眠几秒。                                         |
+----------------------------------------------------+----------------------------------------------------+
| "await" "gather()"                                 | 并发执行所有事件的调度和等待。                     |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait_for()"                               | 有超时控制的运行。                                 |
+----------------------------------------------------+----------------------------------------------------+
| "await" "shield()"                                 | 屏蔽取消操作                                       |
+----------------------------------------------------+----------------------------------------------------+
| "await" "wait()"                                   | 完成情况的监控器                                   |
+----------------------------------------------------+----------------------------------------------------+
| "timeout()"                                        | Run with a timeout. Useful in cases when           |
|                                                    | "wait_for" is not suitable.                        |
+----------------------------------------------------+----------------------------------------------------+
| "to_thread()"                                      | 在不同的 OS 线程中异步地运行一个函数。             |
+----------------------------------------------------+----------------------------------------------------+
| "run_coroutine_threadsafe()"                       | 从其他OS线程中调度一个协程。                       |
+----------------------------------------------------+----------------------------------------------------+
| "for in" "as_completed()"                          | 用 "for" 循环监控完成情况。                        |
+----------------------------------------------------+----------------------------------------------------+

-[ 例子 ]-

* 使用 asyncio.gather() 并行运行.

* 使用 asyncio.wait_for() 强制超时.

* 撤销协程.

* asyncio.sleep() 的用法.

* 请主要参阅 协程与任务文档.


队列集
======

队列集被用于多个异步Task对象的运行调度，实现连接池以及发布/订阅模式。

+----------------------------------------------------+----------------------------------------------------+
| "Queue"                                            | 先进先出队列                                       |
+----------------------------------------------------+----------------------------------------------------+
| "PriorityQueue"                                    | 优先级队列。                                       |
+----------------------------------------------------+----------------------------------------------------+
| "LifoQueue"                                        | 后进先出队列。                                     |
+----------------------------------------------------+----------------------------------------------------+

-[ 例子 ]-

* 使用 asyncio.Queue 在多个并发任务间分配工作量.

* 请参阅 队列集文档.


子进程集
========

用于生成子进程和运行shell命令的工具包。

+----------------------------------------------------+----------------------------------------------------+
| "await" "create_subprocess_exec()"                 | 创建一个子进程。                                   |
+----------------------------------------------------+----------------------------------------------------+
| "await" "create_subprocess_shell()"                | 运行一个shell命令。                                |
+----------------------------------------------------+----------------------------------------------------+

-[ 例子 ]-

* 执行一个shell命令.

* 请参阅 子进程 APIs 相关文档.


流
==

用于网络IO处理的高级API集。

+----------------------------------------------------+----------------------------------------------------+
| "await" "open_connection()"                        | 建立一个TCP连接。                                  |
+----------------------------------------------------+----------------------------------------------------+
| "await" "open_unix_connection()"                   | 建立一个Unix socket连接。                          |
+----------------------------------------------------+----------------------------------------------------+
| "await" "start_server()"                           | 启动TCP服务。                                      |
+----------------------------------------------------+----------------------------------------------------+
| "await" "start_unix_server()"                      | 启动一个 Unix 套接字服务。                         |
+----------------------------------------------------+----------------------------------------------------+
| "StreamReader"                                     | 接收网络数据的高级async/await对象。                |
+----------------------------------------------------+----------------------------------------------------+
| "StreamWriter"                                     | 发送网络数据的高级async/await对象。                |
+----------------------------------------------------+----------------------------------------------------+

-[ 例子 ]-

* TCP 客户端样例.

* 请参阅 streams APIs 文档。


同步
====

能被用于Task对象集的，类似线程的同步基元组件。

+----------------------------------------------------+----------------------------------------------------+
| "Lock"                                             | 互斥锁。                                           |
+----------------------------------------------------+----------------------------------------------------+
| "Event"                                            | 事件对象。                                         |
+----------------------------------------------------+----------------------------------------------------+
| "Condition"                                        | 条件对象                                           |
+----------------------------------------------------+----------------------------------------------------+
| "Semaphore"                                        | 信号量                                             |
+----------------------------------------------------+----------------------------------------------------+
| "BoundedSemaphore"                                 | 有界的信号量。                                     |
+----------------------------------------------------+----------------------------------------------------+
| "Barrier"                                          | A barrier object.                                  |
+----------------------------------------------------+----------------------------------------------------+

-[ 例子 ]-

* asyncio.Event 的用法.

* Using asyncio.Barrier.

* 请参阅asyncio文档 synchronization primitives.


异常
====

+----------------------------------------------------+----------------------------------------------------+
| "asyncio.CancelledError"                           | 当一个Task对象被取消的时候被引发。请参阅           |
|                                                    | "Task.cancel()"。                                  |
+----------------------------------------------------+----------------------------------------------------+
| "asyncio.BrokenBarrierError"                       | Raised when a Barrier is broken. See also          |
|                                                    | "Barrier.wait()".                                  |
+----------------------------------------------------+----------------------------------------------------+

-[ 例子 ]-

* 在取消请求发生的运行代码中如何处理CancelledError异常.

* 请参阅完整的 asyncio 专用异常 列表.
