API convention for blocking-, timeout-, and/or deadline-related functions · Issue #46316 · rust-lang/rust (original) (raw)
The standard library currently exposes several blocking- and/or timeout-related functions:
| Function \ Versions | Blocking | Timeout (ms) | Timeout |
|---|---|---|---|
| std::sync::Condvar::wait* | wait | wait_timeout_ms | wait_timeout |
| std::sync::mpsc::Receiver::recv* | recv | none | recv_timeout |
| std::thread::park* | park | park_timeout_ms | park_timeout |
| std::thread::sleep* | none | sleep_ms | sleep |
The timeout versions taking a u32 in milliseconds are actually deprecated for the version taking a Duration since 1.6.0.
This issue tracks the possibility to extend these APIs and provide a convention for blocking-, timeout-, and/or deadline-related functions. The current suggestion is:
| Function \ Versions | Blocking | Timeout | Deadline |
|---|---|---|---|
| std::sync::Condvar::wait* | wait | wait_timeout | wait_deadline |
| std::sync::mpsc::Receiver::recv* | recv | recv_timeout | recv_deadline |
| std::thread::park* | park | park_timeout | park_deadline |
| std::thread::sleep* | none | sleep_for | sleep_until |
The blocking versions do not take any extra argument and are not suffixed. The timeout versions take a timeout as a Duration and return if this timeout is reached (the timeout starts when the function is called with best-effort precision). They are suffixed by _timeout. The deadline versions take a deadline as an Instant and return if this deadline is reached (the deadline precision is best-effort). They are suffixed by _deadline.
For functions that do not have a meaningful blocking version (like sleep which would essentially block until the program ends), the timeout version would be suffixed by _for and the deadline version would be suffixed by _until. We don't have enough data-points to see if this rule is actually applicable. In a first iteration, we could leave aside those functions that do not have a meaningful blocking version.