kern/turnstile: improve comments

2 files changed, 11 insertions, 9 deletions

diff --git a/kern/rtmutex.c b/kern/rtmutex.c
index 10482d54..fa0419be 100644
--- a/kern/rtmutex.c
+++ b/kern/rtmutex.c
@@ -136,8 +136,9 @@ rtmutex_lock_slow_common(struct rtmutex *rtmutex, bool timed, uint64_t ticks)
         /*
          * Keep in mind more than one thread may have timed out on waiting.
          * These threads aren't considered waiters, making the turnstile
-         * empty. The first to reacquire the turnstile clears the contention
-         * bits, allowing the owner to unlock through the fast path.
+         * potentially empty. The first to reacquire the turnstile clears
+         * the contention bits, allowing the owner to unlock through the
+         * fast path.
          */
         if (turnstile_empty(turnstile)) {
             owner = atomic_load(&rtmutex->owner, ATOMIC_RELAXED);
diff --git a/kern/turnstile.h b/kern/turnstile.h
index 76b80301..929bdd50 100644
--- a/kern/turnstile.h
+++ b/kern/turnstile.h
@@ -152,11 +152,11 @@ bool turnstile_empty(const struct turnstile *turnstile);
  * The turnstile must be lent when calling this function. It is
  * released and later reacquired before returning from this function.
  *
- * The calling thread is considered a waiter as long as it didn't
- * reacquire the turnstile. This means that signalling a turnstile
- * has no visible effect on the number of waiters until the turnstile
- * is released, e.g. if a single thread is waiting and another signals
- * the turnstile, the turnstile is not immediately considered empty.
+ * Unless a timeout occurs, the calling thread is considered a waiter
+ * as long as it didn't reacquire the turnstile. This means that signalling
+ * a turnstile has no immediate visible effect on the number of waiters,
+ * e.g. if a single thread is waiting and another signals the turnstile,
+ * the turnstile is not immediately considered empty.
  *
  * If owner isn't NULL, it must refer to the thread currently owning
  * the associated synchronization object. The priority of the caller
@@ -166,8 +166,9 @@ bool turnstile_empty(const struct turnstile *turnstile);
  * When bounding the duration of the wait, the caller must pass an absolute
  * time in ticks, and ETIMEDOUT is returned if that time is reached before
  * the turnstile is signalled. In addition, if a timeout occurs, the calling
- * thread temporarily releases the turnstile before returning, causing other
- * threads to consider the turnstile as empty.
+ * thread isn't considered a waiter any more. Other threads may be able to
+ * acquire the turnstile and consider it empty, despite the fact that threads
+ * may not have returned from this function yet.
  */
 void turnstile_wait(struct turnstile *turnstile, const char *wchan,
                     struct thread *owner);