Timer type

Author: ivmarkov

Cargo.toml

@@ -12,7 +12,8 @@ categories = ["asynchronous", "network-programming", "MCU", "embedded"]
 exclude = ["/.*"]
 
 [features]
-default = ["futures-io", "futures-lite"]
+default = ["futures-io", "futures-lite", "embassy-time"]
+embassy-time = ["embassy-time-driver", "embassy-time-queue-driver", "dep:embassy-time"]
 
 [dependencies]
 libc = "0.2"
@@ -21,6 +22,8 @@ heapless = "0.8"
 log = { version = "0.4", default-features = false }
 futures-io = { version = "0.3", default-features = false, optional = true, features = ["std"] }
 futures-lite = { version = "1", default-features = false, optional = true }
+embassy-time-driver = { version = "0.1", optional = true }
+embassy-time-queue-driver = { version = "0.1", optional = true }
 embassy-time = { version = "0.3", optional = true }
 
 [dev-dependencies]
@@ -32,4 +35,8 @@ env_logger = "0.10"
 
 [[test]]
 name = "async"
-required-features = ["futures-io", "futures-lite"]
+required-features = ["futures-io", "futures-lite", "embassy-time"]
+
+[[test]]
+name = "timer"
+required-features = ["futures-lite", "embassy-time"]

README.md

@@ -11,7 +11,7 @@ This crate is an **experimental** fork of the splendid [`async-io`](https://gith
 
 ## How to use?
 
-`async-io-mini` is a drop-in, API-compatible replacement for the `Async` type from `async-io` (but does NOT have an equivalent of `Timer` - see why [below](#limitations)).
+`async-io-mini` is a drop-in, API-compatible replacement for the `Async` and `Timer` types from `async-io`.
 
 So either:
 * Just replace all `use async_io` occurances in your crate with `use async_io_mini`
@@ -37,26 +37,33 @@ Further, `async-io` has a non-trivial set of dependencies (again - for MCUs; for
 - `log` (might become optional);
 - `enumset` (not crucial, might remove).
 
-## Limitations
+## Enhancements
 
-### No timers
+The `Timer` type of `async_io_mini` is based on the `embassy-time` crate, and as such should offer a higher resolution on embedded operating systems like the ESP-IDF than what can be normally achieved by implementing timers using the `timeout` parameter of the `select` syscall. 
 
-`async-io-mini` does NOT have an equivalent of `async_io::Timer`. On ESP-IDF at least, timers based on OS systicks are often not very useful, as the OS systick is low-res (10ms).
+The reason for this is that on the ESP-IDF, the `timeout` parameter of `select` provides a minimum resolution of 10ms (one FreeRTOS sys-tick), while
+`embassy-time` is implemented using ESP-IDF Timer service, which provides resolutions up to 1 microsecond.
 
-Workaround: use the `Timer` struct from the [`embassy-time`](https://crates.io/crates/embassy-time) crate, which provides a very similar API and is highly optimized for embedded environments. On the ESP-IDF, the `embassy-time-driver` implementation is backed by the ESP-IDF Timer service, which runs off from a high priority thread by default and thus has good res.
+## Limitations
 
 ### No equivalent of `async_io::block_on`
 
 Implementing socket polling as a shared task between the hidden `async-io-mini` thread and the thread calling `async_io_mini::block_on` is not trivial and probably not worth it on MCUs. Just use `futures_lite::block_on` or the `block_on` equivalent for your OS (i.e. `esp_idf_svc::hal::task::block_on` for the ESP-IDF).
 
 ## Implementation
 
+### Async
+
 The first time `Async` is used, a thread named `async-io-mini` will be spawned.
 The purpose of this thread is to wait for I/O events reported by the operating system, and then
 wake appropriate futures blocked on I/O when they can be resumed.
 
 To wait for the next I/O event, the "async-io-mini" thread uses the [select](https://en.wikipedia.org/wiki/Select_(Unix)) syscall, and **is thus only useful for MCUs (might just be the ESP-IDF) where the number of file or socket handles is very small anyway**.
 
+### Timer
+
+As per above, the `Timer` type is a wrapper around the functionality provided by the `embassy-time` crate.
+
 ## Examples
 
 Connect to `example.com:80`.