"asyncio" --- 非同步 I/O
************************

======================================================================


Hello World!
^^^^^^^^^^^^

   import asyncio

   async def main():
       print('Hello ...')
       await asyncio.sleep(1)
       print('... World!')

   asyncio.run(main())

asyncio 是讓使用者以 **async/await** 語法來編寫*並行 (concurrent)* 程
式碼的函式庫 (library)。

asyncio 作為多個 Python 非同步框架的基礎，在高效能網路與網頁伺服器、資
料庫連線函式庫、分散式任務佇列等服務都可以看得到它。

asyncio 往往是個建構 IO 密集型與高階層**結構化**網路程式碼的完美選擇。

也參考:

  A conceptual overview of asyncio
     asyncio 的基本原理說明。

asyncio 提供了一系列**高階** API：

* 並行地運行 Python 協程 (coroutine) 並擁有完整控制權；

* 執行網路 IO 與 IPC；

* 控制子行程 (subprocess)；

* 透過佇列 (queue) 分配任務；

* 同步並行程式碼；

此外，還有一些給*函式庫與框架 (framework) 開發者*的**低階** API：

* 建立與管理 event loops（事件迴圈），它提供了能被用於網路、執行子行程
  、處理作業系統訊號等任務的非同步 API；

* 使用 transports（asyncio 底層傳輸相關類別）來實作高效能協定；

* 透過 async/await 語法來橋接基於回呼 (callback-based) 的函式庫與程式
  碼。

可用性: not WASI.

此模組在 WebAssembly 平台上不起作用或無法使用。更多資訊請參閱
WebAssembly 平台。

-[ asyncio REPL ]-

你能在 *REPL* 中對一個 "asyncio" 的並行情境 (context) 進行實驗：

   $ python -m asyncio
   asyncio REPL ...
   Use "await" directly instead of "asyncio.run()".
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import asyncio
   >>> await asyncio.sleep(10, result='hello')
   'hello'

This REPL provides limited compatibility with "PYTHON_BASIC_REPL". It
is recommended that the default REPL is used for full functionality
and the latest features.

產生一個 稽核事件 "cpython.run_stdin" 且沒有引數。

在 3.12.5 版的變更: (也包括 3.11.10、3.10.15、3.9.20 及 3.8.20）發出稽
核事件。

在 3.13 版的變更: 可能的話使用 PyREPL，在這種情況下 "PYTHONSTARTUP" 也
會被執行。發出稽核事件。

-[ 參閱 ]-


高階 API
^^^^^^^^

* Runners (執行器)

* 協程與任務

* 串流

* 同步原語 (Synchronization Primitives)

* 子行程

* 佇列 (Queues)

* 例外

* 呼叫圖內省（Call Graph Introspection）


低階 API
^^^^^^^^

* 事件迴圈

* Futures

* 傳輸與協定

* Policies

* 平臺支援

* 擴充


指南與教學
^^^^^^^^^^

* 高階 API 索引

* 低階 API 索引

* 使用 asyncio 開發

備註:

  asyncio 的原始碼可以在 Lib/asyncio/ 中找到。
