pw_thread: Extend docs and update duration/deadline terminology
Adds documentation covering thread identification, yielding,
sleeping, and portable thread creation.
The signatures, comments, and docs are updated to reflect the most
recent terminology for describing blocking APIs with timeouts and
deadlines.
Change-Id: I5d802335d3e52416131ad437ef8bfa19e04e637b
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/60042
Reviewed-by: Keir Mierle <keir@google.com>
Pigweed-Auto-Submit: Ewout van Bekkum <ewout@google.com>
Commit-Queue: Ewout van Bekkum <ewout@google.com>
diff --git a/pw_thread_threadx/sleep.cc b/pw_thread_threadx/sleep.cc
index 3de24c0..5bfb0ca 100644
--- a/pw_thread_threadx/sleep.cc
+++ b/pw_thread_threadx/sleep.cc
@@ -26,12 +26,12 @@
namespace pw::this_thread {
-void sleep_for(chrono::SystemClock::duration for_at_least) {
+void sleep_for(chrono::SystemClock::duration sleep_duration) {
// Ensure this is being called by a thread.
PW_DCHECK(get_id() != thread::Id());
// Yield for negative and zero length durations.
- if (for_at_least <= chrono::SystemClock::duration::zero()) {
+ if (sleep_duration <= chrono::SystemClock::duration::zero()) {
tx_thread_relinquish();
return;
}
@@ -43,16 +43,16 @@
// the loop must ensure that timeout + 1 is less than the max timeout.
constexpr SystemClock::duration kMaxTimeoutMinusOne =
pw::chrono::threadx::kMaxTimeout - SystemClock::duration(1);
- while (for_at_least > kMaxTimeoutMinusOne) {
+ while (sleep_duration > kMaxTimeoutMinusOne) {
const UINT result =
tx_thread_sleep(static_cast<ULONG>(kMaxTimeoutMinusOne.count()));
PW_CHECK_UINT_EQ(TX_SUCCESS, result);
- for_at_least -= kMaxTimeoutMinusOne;
+ sleep_duration -= kMaxTimeoutMinusOne;
}
// On a tick based kernel we cannot tell how far along we are on the current
// tick, ergo we add one whole tick to the final duration.
const UINT result =
- tx_thread_sleep(static_cast<ULONG>(for_at_least.count() + 1));
+ tx_thread_sleep(static_cast<ULONG>(sleep_duration.count() + 1));
PW_CHECK_UINT_EQ(TX_SUCCESS, result);
}