Removed the Fl::set_awake_cb API and documented the Fl::awake(function, data) API.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@5749 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
2007-03-20 10:41:14 +00:00 · 2007-03-20 10:41:14 +00:00 · 18f2016b1f
commit 18f2016b1f
parent 27568cfa1c
7 changed files with 36 additions and 43 deletions
--- a/6
+++ b/6
@ -4,9 +4,9 @@ CHANGES IN FLTK 1.1.8
 	  STR #1457, STR #1458, STR #1460, STR #1481, STR #1578)
 	- The sample RPM spec file now enables large file support
 	  and threading support (STR #1603)
-	- Changed minumu contrast between background and text to 
+	- Changed minimum contrast between background and text to 
 	  96 and added more weight to the blue component to improve
-	  readability (STR #1625)
+	  readability for certain color combinations (STR #1625)
 	- Fixed VCNet OpenGL project file (STR #1617)
 	- Fixed scrolling of clipped areas in MSWindows (STR
 	  #1601)
@ -16,7 +16,7 @@ CHANGES IN FLTK 1.1.8
 	  avoid data loss (STR #1609)
 	- The Fl_File_Chooser constructor now saves and restores the
 	  current group (STR #1611)
-	- Added Fl::set_awake_cb() to set a handler for thread
+	- Added Fl::awake(fn*,void*) to set a handler for thread
 	  messages (STR #1536)
 	- Added "mute sound" option to Sudoku game.
 	- Updated the bundled zlib to v1.2.3.
--- a/FL/Fl.H
+++ b/FL/Fl.H
@ -79,7 +79,6 @@ public: // should be private!
  static void damage(int d) {damage_ = d;}

  static void (*idle)();
-  static void (*awake_cb)(void *);
  static Fl_Awake_Handler *awake_ring_;
  static void **awake_data_;
  static int awake_ring_size_;
@ -277,7 +276,6 @@ public:
  static void unlock();
  static void awake(void* message = 0);
  static int awake(Fl_Awake_Handler cb, void* message = 0);
-  static void set_awake_cb(void (*cb)(void *)) { awake_cb = cb; }
  static void* thread_message();

  // Widget deletion:
--- a/documentation/Fl.html
+++ b/documentation/Fl.html
@ -126,7 +126,6 @@ state information and global methods for the current application.</P>
 	<LI><A HREF="#Fl.selection_owner">selection_owner</A></LI>
 	<LI><A HREF="#Fl.set_abort">set_abort</A></LI>
 	<LI><A HREF="#Fl.set_atclose">set_atclose</A></LI>
-	<LI><A HREF="#Fl.set_awake_cb">set_awake_cb</A></LI>
 	<LI><A HREF="#Fl.set_boxtype">set_boxtype</A></LI>
 	<LI><A HREF="#Fl.set_color">set_color</A></LI>
 	<LI><A HREF="#Fl.set_font">set_font</A></LI>
@ -391,9 +390,24 @@ argument on the command-line. You can change the message by setting the

 <H4><A NAME="Fl.awake">void awake(void *p);</A></H4>

-<P>The <TT>awake()</TT> method sends a message pointer to the main thread, causing any pending <A HREF="#Fl.wait"><TT>Fl::wait()</TT></A> call to terminate so that the main thread can retrieve the message and any pending redraws can be processed.
+<H4><A NAME="Fl.awake">int awake(void (*callback)(void*), void *userdata);</A></H4>

-<P>Multiple calls to <TT>Fl::awake()</TT> will queue multiple pointers for the main thread to process, up to a system-defined (typically several thousand) depth. The default message handler saves the last message which can be accessed using the <A HREF="#Fl.thread_message"><TT>Fl::thread_message()</TT></A> function. Use the <A HREF="#Fl.set_awake_cb"><TT>Fl::set_awake_cb()</TT></A> function to register your own thread message handler that is called for every message received by the main thread.
+<P>The <TT>awake()</TT> method sends a message pointer to the main thread, 
+causing any pending <A HREF="#Fl.wait"><TT>Fl::wait()</TT></A> call to 
+terminate so that the main thread can retrieve the message and any pending 
+redraws can be processed.
+
+<P>Multiple calls to <TT>Fl::awake()</TT> will queue multiple pointers 
+for the main thread to process, up to a system-defined (typically several 
+thousand) depth. The default message handler saves the last message which 
+can be accessed using the <A HREF="#Fl.thread_message">
+<TT>Fl::thread_message()</TT></A> function.
+
+<P>The second form of <TT>awake()</TT> registers a function that will be 
+called by the main thread during the next message handling cycle. 
+<TT>awake()</TT> will return 0 if the callback function was registered, 
+and -1 if registration failed. Over a thousand awake callbacks can be
+registered simultaneously.

 <P>See also: <a href="advanced.html#multithreading">multithreading</a>.

@ -1169,10 +1183,6 @@ of this.</I>

 <H4><A NAME="Fl.set_atclose">void set_atclose(void (*f)(Fl_Window*,void*));</A></H4>

-<H4><A NAME="Fl.set_awake_cb">void set_awake_cb(void (*cb)(void*));</A></H4>
-
-<P>Sets a function to handle thread messages sent via the <A HREF="#Fl.awake"><TT>Fl::awake()</TT></A> function.</P>
-
 <H4><A NAME="Fl.set_boxtype">void set_boxtype(Fl_Boxtype, Fl_Box_Draw_F*,uchar,uchar,uchar,uchar);<BR>
 void set_boxtype(Fl_Boxtype, Fl_Boxtype from);</A></H4>

--- a/documentation/advanced.html
+++ b/documentation/advanced.html
@ -31,7 +31,8 @@ that will help you to get the most out of FLTK.</P>

 <P>You can now start as many threads as you like. From within
 a thread (other than the main thread) FLTK calls must be wrapped
-with calls to <a href="Fl.html#Fl.lock"><tt>Fl::lock()</tt></a> and <a href="Fl.html#Fl.unlock"><tt>Fl::unlock()</tt></a>:
+with calls to <a href="Fl.html#Fl.lock"><tt>Fl::lock()</tt></a> 
+and <a href="Fl.html#Fl.unlock"><tt>Fl::unlock()</tt></a>:

 <pre>
    Fl::lock();      // avoid conflicting calls
@ -39,27 +40,28 @@ with calls to <a href="Fl.html#Fl.lock"><tt>Fl::lock()</tt></a> and <a href="Fl.
    Fl::unlock();    // allow other threads to access FLTK again
 </pre>

-<p>You can send messages from child threads to the main thread using <a href="Fl.html#Fl.awake"><tt>Fl::awake(msg)</tt></a>:</p>
+<p>You can send messages from child threads to the main thread 
+using <a href="Fl.html#Fl.awake"><tt>Fl::awake(msg)</tt></a>:</p>

 <pre>
    void *msg;       // "msg" is a pointer to your message
    Fl::awake(msg);  // send "msg" to main thread
 </pre>

-<p>These messages can be read by the main thread using <A HREF="Fl.html#Fl.thread_message"><TT>Fl::thread_message()</TT></A> or by registering a message callback with <A HREF="Fl.html#Fl.set_awake_cb"><TT>Fl::set_awake_cb()</TT></A>:</p>
+<p>You can also tell the main thread to call a function for you
+as soon as possible by using
+<a href="Fl.html#Fl.awake"><tt>Fl::awake(callback, userdata)</tt></a>:</p>

 <pre>
-    void message_cb(void *msg) {
-      ... do something with "msg" ...
+    void do_something(void *userdata) {
+      // running with the main thread
    }

-    int main() {
-      Fl::lock();
-      Fl::set_awake_cb(message_cb);
-      /* run thread */
-      return (Fl::run());
-    }
+    // running in another thread
+    void *data;       // "data" is a pointer to your user data
+    Fl::awake(do_something, data);  // call something in main thread
 </pre>
+
      
 <P>FLTK supports multiple platforms, some of them which do not 
 allow any other but the main thread to handle system events and
@ -86,7 +88,6 @@ related methods that will handle system messages</li>
 <P>See also: 
 <a href="Fl.html#Fl.awake">void awake(void *message)</A>, 
 <a href="Fl.html#Fl.lock">void lock()</A>, 
-<a href="Fl.html#Fl.set_awake_cb">void set_awake_cb(void (*cb)(void *)</A>, 
 <a href="Fl.html#Fl.thread_message">void *thread_message()</A>,
 <a href="Fl.html#Fl.unlock">void unlock()</A>.

--- a/src/Fl_lock.cxx
+++ b/src/Fl_lock.cxx
@ -58,9 +58,8 @@
   Fl::awake(void*) - Causes Fl::wait() to return (with the lock
   locked) even if there are no events ready.

-   Fl::set_awake_cb(void (*cb)(void *)) - Registers a function
-   to call for Fl::awake() messages that is called for each
-   message received.
+   Fl::awake(void (*cb)(void *), void*) - Call a function
+   in the main thread from within another thread of execution.

   Fl::thread_message() - returns an argument sent to an
   Fl::awake() call, or returns NULL if none.  WARNING: the
@ -68,8 +67,6 @@
   returns the most recent value!
 */

-void	(*Fl::awake_cb)(void *);
-
 Fl_Awake_Handler *Fl::awake_ring_;
 void **Fl::awake_data_;
 int Fl::awake_ring_size_;
@ -91,7 +88,7 @@ int Fl::add_awake_handler_(Fl_Awake_Handler func, void *data)
    awake_data_ = (void**)malloc(awake_ring_size_*sizeof(void*));
  }
  if (awake_ring_head_==awake_ring_tail_-1 || awake_ring_head_+1==awake_ring_tail_) {
-    // ring is full. Return -1 as ann error indicator.
+    // ring is full. Return -1 as an error indicator.
    ret = -1;
  } else {
    awake_ring_[awake_ring_head_] = func;
@ -278,7 +275,6 @@ void* Fl::thread_message() {

 static void thread_awake_cb(int fd, void*) {
  read(fd, &thread_message_, sizeof(void*));
-  if (Fl::awake_cb) (*Fl::awake_cb)(thread_message_);
  Fl_Awake_Handler func;
  void *data;
  while (Fl::get_awake_handler_(func, data)==0) {
--- a/src/Fl_win32.cxx
+++ b/src/Fl_win32.cxx
@ -299,7 +299,6 @@ int fl_wait(double time_to_wait) {
      if (fl_msg.message == fl_wake_msg) {
        // Used for awaking wait() from another thread
 	thread_message_ = (void*)fl_msg.wParam;
-        if (Fl::awake_cb) (*Fl::awake_cb)(thread_message_);
        Fl_Awake_Handler func;
        void *data;
        while (Fl::get_awake_handler_(func, data)==0) {
--- a/test/threads.cxx
+++ b/test/threads.cxx
@ -111,12 +111,6 @@ void* prime_func(void* p)
  return 0;
 }

-void message_cb(void *m) {
-  if (m == (void *)browser1) putchar('1');
-  else putchar('2');
-  fflush(stdout);
-}
-
 int main(int argc, char **argv)
 {
  Fl_Window* w = new Fl_Window(200, 200, "Single Thread");
@ -141,11 +135,6 @@ int main(int argc, char **argv)
  // when it is safe to do so...
  Fl::lock();

-  // Register a callback for Fl::awake() messages.  This allows
-  // you to get all thread messages even if you are in another
-  // run loop (say, with a modal dialog...)
-  Fl::set_awake_cb(message_cb);
-
  // Start threads...

  // One thread displaying in one browser