diff --git a/README.md b/README.md new file mode 100644 index 0000000..f177d15 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +# QuecPython Software Watchdog + +[中文](README_ZH.md) | English + +## Overview + +asyncio is a library to write **concurrent** code using the **async/await** syntax. + +asyncio is used as a foundation for multiple Python asynchronous frameworks that provide high-performance network and web-servers, database connection libraries, distributed task queues, etc. + +asyncio is often a perfect fit for IO-bound and high-level **structured** network code. + +## Usage + +- [API Reference Manual](./docs/en/API_Reference.md) +- [Example Code](./code/demo.py) + +## Contribution + +We welcome contributions to improve this project! Please follow these steps to contribute: + +1. Fork the repository. +2. Create a new branch (`git checkout -b feature/your-feature`). +3. Commit your changes (`git commit -m 'Add your feature'`). +4. Push to the branch (`git push origin feature/your-feature`). +5. Open a Pull Request. + +## License + +This project is licensed under the Apache License. See the [LICENSE](LICENSE) file for details. + +## Support + +If you have any questions or need support, please refer to the [QuecPython documentation](https://python.quectel.com/doc/en) or open an issue in this repository. \ No newline at end of file diff --git a/README_ZH.md b/README_ZH.md new file mode 100644 index 0000000..3358f65 --- /dev/null +++ b/README_ZH.md @@ -0,0 +1,30 @@ +# 异步 I/O 调度器 —— uasyncio + +中文 | [English](README.md) + +## 概述 + +uasyncio 是用来编写 **并发** 代码的库,使用 **async/await** 语法。uasyncio 被用作多个提供高性能异步框架的基础,包括网络和网站服务,数据库连接库,分布式任务队列等等。uasyncio 往往是构建 IO 密集型和高层级 **结构化** 网络代码的最佳选择。 + +## 用法 + +- [API 参考手册](./docs/zh/API参考手册.md) +- [示例代码](./code/demo.py) + +## 贡献 + +我们欢迎对本项目的改进做出贡献!请按照以下步骤进行贡献: + +1. Fork 此仓库。 +2. 创建一个新分支(`git checkout -b feature/your-feature`)。 +3. 提交您的更改(`git commit -m 'Add your feature'`)。 +4. 推送到分支(`git push origin feature/your-feature`)。 +5. 打开一个 Pull Request。 + +## 许可证 + +本项目使用 Apache 许可证。详细信息请参阅 [LICENSE](LICENSE) 文件。 + +## 支持 + +如果您有任何问题或需要支持,请参阅 [QuecPython 文档](https://python.quectel.com/doc) 或在本仓库中打开一个 issue。 \ No newline at end of file diff --git a/code/demo.py b/code/demo.py new file mode 100644 index 0000000..8012c2e --- /dev/null +++ b/code/demo.py @@ -0,0 +1,28 @@ +from usr.uasyncio.core import create_task, sleep, sleep_ms, run +from machine import Pin + + +async def blink(led, period_ms, name=''): + while True: + led.write(1) + print('led on: {}'.format(name)) + await sleep_ms(period_ms) + led.write(0) + print('led off: {}'.format(name)) + await sleep_ms(period_ms) + + +async def main(led1, led2): + create_task(blink(led1, 700, 'led1')) + create_task(blink(led2, 400, 'led2')) + sleep(10) + + +if __name__ == '__main__': + # Running + run( + main( + Pin(Pin.GPIO1, Pin.OUT, Pin.PULL_DISABLE, 0), # led1 + Pin(Pin.GPIO2, Pin.OUT, Pin.PULL_DISABLE, 0) # led2 + ) + ) diff --git a/docs/en/API_Reference.md b/docs/en/API_Reference.md new file mode 100644 index 0000000..8dc31d3 --- /dev/null +++ b/docs/en/API_Reference.md @@ -0,0 +1,105 @@ +# Asynchronous I/O -- uasyncio + +asyncio is a library to write **concurrent** code using the **async/await** syntax. + +asyncio is used as a foundation for multiple Python asynchronous frameworks that provide high-performance network and web-servers, database connection libraries, distributed task queues, etc. + +asyncio is often a perfect fit for IO-bound and high-level **structured** network code. + +## Primary Functions + +### `uasyncio.create_task(coro)` + +> Create a new task from the given protocol and schedule it to run. + +**Params** + +- `core`: Coroutine object + +**Return value**: Task object + +### `uasyncio.run(coro) ` + +> Create a new task from the given coroutine and run it until it is completed. + +**Params** + +- `coro`: Coroutine object + +**Return value**: the value of `coro` returns. + +### `uasyncio.sleep(t) ` + +> Sleep for t seconds (can be a floating-point number). This is a Coroutine. + +### `uasyncio.sleep_ms(t)` + +> Sleep for t milliseconds. This is a Coroutine. + +## Additional Functions + +### `uasyncio.wait_for(awaitable, timeout)` + +> Wait for `awaitable` to complete, but if it requires a longer timeout seconds, please cancel it. If awaitable is not a task, then a task will be created from it. +> +> If a timeout occurs, it will cancel the task and trigger ` asyncio.TimeoutError`: This should be captured by the caller. +> +> This is a Coroutine. + +**Params**: + +- `awaitable`:awaitable object. +- `timeout`:timeout seconds + +**Return value**:the value of `awaitable` returns. + +### `uasyncio.wait_for_ms(awaitable, timeout)` + +> like `wait_for` but the timeout unit is milliseconds. +> +> This is a Coroutine. + +**Params**: + +- `awaitable`:awaitable object. +- `timeout`:timeout milliseconds + +**Return value**:the value of `awaitable` returns. + +### `uasyncio.gather(awaitables, return_exceptions=False)` + +> Run all waits simultaneously. Any waiting item that is not a task is elevated to a task. +> +> This is a Coroutine. + +**Params**: + +- `awaitable`:awaitable object. +- `return_exceptions`: if the exception object returned flag. + +**Return value**:the value of `awaitable` returns. + +## Event + +### `uasyncio.Event` + +> Create a new event that can be used to synchronize tasks. The event starts with a clear state. + +### `Event.is_set()` + +> `True` returns if an event is set, otherwise `False` returns. + +### `Event.set()` + +> Set events. Any task waiting for an event will be scheduled to run. + +### `Event.clear()` + +> clear event. + +### `Event.wait()` + +> Wait for the event to be set. If the event has already been set, it will immediately return. +> +> This is a Coroutine. + diff --git "a/docs/zh/API\345\217\202\350\200\203\346\211\213\345\206\214.md" "b/docs/zh/API\345\217\202\350\200\203\346\211\213\345\206\214.md" new file mode 100644 index 0000000..6f4789e --- /dev/null +++ "b/docs/zh/API\345\217\202\350\200\203\346\211\213\345\206\214.md" @@ -0,0 +1,104 @@ +# 异步 I/O 调度器 —— uasyncio + +uasyncio 是用来编写 **并发** 代码的库,使用 **async/await** 语法。uasyncio 被用作多个提供高性能异步框架的基础,包括网络和网站服务,数据库连接库,分布式任务队列等等。uasyncio 往往是构建 IO 密集型和高层级 **结构化** 网络代码的最佳选择。 + +## 核心功能 + +### `uasyncio.create_task(coro)` + +> 从给定的协程创建一个新任务并安排它运行。 + +**参数** + +- `core`:协程对象 + +**返回值**:相应的`Task`对象 + +### `uasyncio.run(coro) ` + +> 从给定的协程创建一个新任务并运行它直到完成 + +**参数** + +- `coro`:协程对象 + +**返回值**: 返回coro返回的值。 + +### `uasyncio.sleep(t) ` + +> 睡眠t秒(可以是浮点数)。 这是一个协程。 + +### `uasyncio.sleep_ms(t)` + +> 休眠t毫秒。 这是一个协程。 + +## 附加功能 + +### `uasyncio.wait_for(awaitable, timeout)` + +> 等待awaitable完成,但如果它需要更长的超时秒数,请取消它。如果awaitable不是任务,那么将从它创建一个任务。 +> +> 如果发生超时,它会取消任务并引发`asyncio.TimeoutError`: :这应该被调用者捕获。 +> +> 返回awaitable的返回值。 +> +> 这是一个协程。 + +**参数**: + +- `awaitable`:可等待对象。 +- `timeout`:超时时间 + +**返回值**:返回`awaitable`返回的值。 + +### `uasyncio.wait_for_ms(awaitable, timeout)` + +> 类似于`wait_for`但超时是以毫秒为单位的整数。 +> +> 这是一个协程。 + +**参数**: + +- `awaitable`:可等待对象 +- `timeout`:超时时间 + +**返回值**:返回`awaitable`返回值。 + +### `uasyncio.gather(awaitables, return_exceptions=False)` + +> 同时运行所有等待。任何不是任务的等待项都被提升为任务。 +> +> 返回所有awaitables的返回值列表。 +> +> 这是一个协程。 + +**参数**: + +- `awaitable`:可等待对象 +- `return_exceptions`:是否返回异常对象标志。 + +**返回值**:返回`awaitable`返回值。 + +## 协程事件 + +### `uasyncio.Event` + +> 创建一个可用于同步任务的新事件。事件以清除状态开始。 + +### `Event.is_set()` + +> `True`如果设置了事件,则返回,`False`否则返回。 + +### `Event.set()` + +> 设置事件。任何等待事件的任务都将被安排运行。 + +### `Event.clear()` + +> 清除事件。 + +### `Event.wait()` + +> 等待事件被设置。如果事件已经设置,那么它会立即返回。 +> +> 这是一个协程。 \ No newline at end of file