From 907edf10a3526a3ca861fd1c61b5a65d58a777e5 Mon Sep 17 00:00:00 2001 From: Ryan Pavlik Date: Fri, 20 May 2022 14:37:50 -0500 Subject: [PATCH] a/os: Add more docs for correct use of condition variables --- src/xrt/auxiliary/os/os_threading.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/src/xrt/auxiliary/os/os_threading.h b/src/xrt/auxiliary/os/os_threading.h index cea0fb946..8c80a077b 100644 --- a/src/xrt/auxiliary/os/os_threading.h +++ b/src/xrt/auxiliary/os/os_threading.h @@ -169,6 +169,16 @@ os_cond_signal(struct os_cond *oc) /*! * Wait. * + * Be sure to call this in a loop, testing some other condition that you + * are actually waiting for, as condition variable waits are subject to + * spurious wakeups. + * + * Must be called with the mutex @p om locked. + * + * Once the wait begins, the mutex @p om is unlocked, to allow another + * thread access to change the thing you're monitoring. By the time this + * returns, you once again own the lock. + * * @public @memberof os_cond */ static inline void @@ -590,8 +600,16 @@ os_thread_helper_is_running_locked(struct os_thread_helper *oth) /*! * Wait for a signal. * + * Be sure to call this in a loop, testing some other condition that you + * are actually waiting for, as this is backed by a condition variable + * wait and is thus subject to spurious wakeups. + * * Must be called with the helper locked. * + * As this wraps a cond-var wait, once the wait begins, the helper is + * unlocked, to allow another thread access to change the thing you're + * monitoring. By the time this returns, you once again own the lock. + * * @public @memberof os_thread_helper */ static inline void