| |
Author: matt
Date: 2007-03-20 05:41:14 -0500 (Tue, 20 Mar 2007)
New Revision: 5749
Log:
Removed the Fl::set_awake_cb API and documented the Fl::awake(function, data) API.
Modified:
branches/branch-1.1/CHANGES
branches/branch-1.1/FL/Fl.H
branches/branch-1.1/documentation/Fl.html
branches/branch-1.1/documentation/advanced.html
branches/branch-1.1/src/Fl_lock.cxx
branches/branch-1.1/src/Fl_win32.cxx
branches/branch-1.1/test/threads.cxx
Modified: branches/branch-1.1/CHANGES
===================================================================
--- branches/branch-1.1/CHANGES 2007-03-20 09:52:51 UTC (rev 5748)
+++ branches/branch-1.1/CHANGES 2007-03-20 10:41:14 UTC (rev 5749)
@@ -4,9 +4,9 @@
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 @@
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.
Modified: branches/branch-1.1/FL/Fl.H
===================================================================
--- branches/branch-1.1/FL/Fl.H 2007-03-20 09:52:51 UTC (rev 5748)
+++ branches/branch-1.1/FL/Fl.H 2007-03-20 10:41:14 UTC (rev 5749)
@@ -79,7 +79,6 @@
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 @@
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:
Modified: branches/branch-1.1/documentation/Fl.html
===================================================================
--- branches/branch-1.1/documentation/Fl.html 2007-03-20 09:52:51 UTC (rev 5748)
+++ branches/branch-1.1/documentation/Fl.html 2007-03-20 10:41:14 UTC (rev 5749)
@@ -126,7 +126,6 @@
<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,10 +390,25 @@
<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>.
<H4><A NAME="Fl.background2">void background2(uchar, uchar, uchar);</A></H4>
@@ -1169,10 +1183,6 @@
<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>
Modified: branches/branch-1.1/documentation/advanced.html
===================================================================
--- branches/branch-1.1/documentation/advanced.html 2007-03-20 09:52:51 UTC (rev 5748)
+++ branches/branch-1.1/documentation/advanced.html 2007-03-20 10:41:14 UTC (rev 5749)
@@ -31,7 +31,8 @@
<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 @@
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 @@
<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>.
Modified: branches/branch-1.1/src/Fl_lock.cxx
===================================================================
--- branches/branch-1.1/src/Fl_lock.cxx 2007-03-20 09:52:51 UTC (rev 5748)
+++ branches/branch-1.1/src/Fl_lock.cxx 2007-03-20 10:41:14 UTC (rev 5749)
@@ -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 @@
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 @@
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) {
Modified: branches/branch-1.1/src/Fl_win32.cxx
===================================================================
--- branches/branch-1.1/src/Fl_win32.cxx 2007-03-20 09:52:51 UTC (rev 5748)
+++ branches/branch-1.1/src/Fl_win32.cxx 2007-03-20 10:41:14 UTC (rev 5749)
@@ -299,7 +299,6 @@
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) {
Modified: branches/branch-1.1/test/threads.cxx
===================================================================
--- branches/branch-1.1/test/threads.cxx 2007-03-20 09:52:51 UTC (rev 5748)
+++ branches/branch-1.1/test/threads.cxx 2007-03-20 10:41:14 UTC (rev 5749)
@@ -111,12 +111,6 @@
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 @@
// 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
[ Direct Link to Message ] | |
