From a6dd0adac7078ea93955242ab4bad49c812c20a8 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Mon, 9 Jan 2023 15:07:46 +0100
Subject:  Doc only: fix for "Fl::awake() and Fl::add_timeout()" (#524)

---
 src/Fl.cxx      |  3 +++
 src/Fl_lock.cxx | 10 ++++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

(limited to 'src')

diff --git a/src/Fl.cxx b/src/Fl.cxx
index fa0620fa6..79956bfd7 100644
--- a/src/Fl.cxx
+++ b/src/Fl.cxx
@@ -258,6 +258,9 @@ int Fl::event_inside(const Fl_Widget *o) /*const*/ {
   If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to
   reschedule the subsequent timeouts. Please see Fl::repeat_timeout() for
   an example.
+ 
+  Since version 1.4, a timeout can be started from a child thread under the
+  condition that the call to Fl::add_timeout is wrapped in Fl::lock() and Fl::unlock().
 
   \param[in]  time    delta time in seconds until the timer expires
   \param[in]  cb      callback function
diff --git a/src/Fl_lock.cxx b/src/Fl_lock.cxx
index fdf045be9..d7bdf9c34 100644
--- a/src/Fl_lock.cxx
+++ b/src/Fl_lock.cxx
@@ -179,8 +179,14 @@ int Fl::awake(Fl_Awake_Handler func, void *data) {
     argument will trigger event loop handling in the main thread. Since
     it is not possible to call Fl::flush() from a subsidiary thread,
     Fl::awake() is the best (and only, really) substitute.
-
-    See also: \ref advanced_multithreading
+ 
+    It's \e not necessary to wrap calls to any form of Fl::awake() by Fl::lock() and Fl::unlock().
+    Nevertheless, the early, single call to Fl::lock() used to initialize threading support is necessary.
+ 
+    Function Fl::awake() in all its forms is typically called by worker threads, but it can be used safely
+    by the main thread too, as a means to break the event loop.
+
+    \see \ref advanced_multithreading
 */
 
 void Fl::awake(void *v) {
-- 
cgit v1.2.3