Doc only: fix for "Fl::awake() and Fl::add_timeout()" (#524)

3 files changed, 14 insertions, 3 deletions

diff --git a/documentation/src/advanced.dox b/documentation/src/advanced.dox
index 7e8b3ca4d..7489a4698 100644
--- a/documentation/src/advanced.dox
+++ b/documentation/src/advanced.dox
@@ -398,7 +398,9 @@ threads on all operating systems:
     of Fl::awake(<thing>) mechanism and use that.
     (Intermixing calls to Fl::awake() should be safe with either however.)
 
-\li Don't start or cancel timers from a worker thread
+\li Starting with FLTK 1.4, it's possible to start (or cancel) a timer from a
+    worker thread under the condition that the call to Fl::add_timeout
+    (or Fl::remove_timeout) is wrapped in Fl::lock() and Fl::unlock().
 
 \li Don't change window decorations or titles from a worker thread
 
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) {