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

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
 

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

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.
+ 
+    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 also: \ref advanced_multithreading
+    \see \ref advanced_multithreading
 */
 
 void Fl::awake(void *v) {