Added chapter 10 with documentation about multithreading

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@5621 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
author: Matthias Melcher <fltk@matthiasm.com> 2007-01-18 22:48:19 +0000
committer: Matthias Melcher <fltk@matthiasm.com> 2007-01-18 22:48:19 +0000
commit: 8e7e4167835186b2aab81c4e87153c574ff83466 (patch)
tree: ac7477a7e08300317717a84b94ac2527ec26c94e
parent: bb6f36cffe66509ebcc6da6d1a8d98cf48a0b749 (diff)
5 files changed, 108 insertions, 0 deletions
diff --git a/CHANGES b/CHANGES
index 2440e4bd7..44819a927 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,7 @@
 CHANGES IN FLTK 1.1.8
 
+	- Added chapter 10 about multithreading (STR #1532, 
+	  1533)
 	- OS X system menu bar itop level attribute support 
 	  improved (STR #1505)
 	- Fixed Quartz image drawing bug (STR #1438)
diff --git a/documentation/Fl.html b/documentation/Fl.html
index 8cd78507a..281ef7b8a 100644
--- a/documentation/Fl.html
+++ b/documentation/Fl.html
@@ -395,6 +395,13 @@ main thread, causing any pending <TT>wait()</TT> call to
 terminate so that the main thread can retrieve the message and
 any pending redraws can be processed.
 
+<P>Multiple calls to <TT>awake()</TT> will overwrite the same 
+message pointer. 
+<A HREF="#Fl.thread_message"><TT>thread_message()</TT></A> only returns 
+the last message stored by the last <TT>awake()</TT> call.
+
+<P>See also: <a href="advanced.html#multithreading">multithreading</a>
+
 <H4><A NAME="Fl.background2">void background2(uchar, uchar, uchar);</A></H4>
 
 <P>Changes the alternative background color. This color is used as a 
@@ -961,6 +968,8 @@ wait until all child threads have called <A
 HREF="#Fl.unlock"><TT>unlock()</TT></A> before processing
 additional data.
 
+<P>See also: <a href="advanced.html#multithreading">multithreading</a>
+
 <H4><A NAME="Fl.modal">Fl_Window* modal();</A></H4>
 
 <P>Returns the top-most <tt>modal()</tt> window currently shown.
@@ -1236,6 +1245,8 @@ Fl_Widget::test_shortcut()</tt></A>.
 that was sent from a child by the <A
 HREF="#Fl.awake"><TT>awake()</TT></A> method.
 
+<P>See also: <a href="advanced.html#multithreading">multithreading</a>
+
 <H4><A NAME="Fl.unlock">void unlock();</A></H4>
 
 <P>The <TT>unlock()</TT> method releases the lock that was set
@@ -1243,6 +1254,8 @@ using the <A HREF="#Fl.lock"><TT>lock()</TT></A> method. Child
 threads should call this method as soon as they are finished
 accessing FLTK.
 
+<P>See also: <a href="advanced.html#multithreading">multithreading</a>
+
 <H4><A NAME="Fl.version">double version();</A></H4>
 
 <P>Returns the compiled-in value of the FL_VERSION constant. This
diff --git a/documentation/Makefile b/documentation/Makefile
index f57e3aef7..8dcf9476b 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -54,6 +54,7 @@ HTMLFILES	= \
 		subclassing.html \
 		opengl.html \
 		fluid.html \
+		advanced.hml \
 		widgets.html \
 		Fl.html \
 		Fl_Adjuster.html \
diff --git a/documentation/advanced.html b/documentation/advanced.html
new file mode 100644
index 000000000..52c3009b6
--- /dev/null
+++ b/documentation/advanced.html
@@ -0,0 +1,89 @@
+<HTML>
+<HEAD>
+	<TITLE>10 - Advanced FLTK</TITLE>
+</HEAD>
+<BODY>
+
+<H1 ALIGN="RIGHT"><A NAME="advanced">10 - Advanced FLTK</A></H1>
+
+<P>This chapter explains advanced programming and design topics
+that will help you to get the most out of FLTK.</P>
+
+<H2><A NAME="multithreading">10.1 Multithreading</H2>
+
+<P>FLTK supports multithreaded application using a locking mechanism
+based on "pthreads". We do not provide a threading interface 
+as part of the library. However a simple example how threads can 
+be implemented for all supported platforms can be found in 
+<tt>test/threads.h</tt> and <tt>test/threads.cxx</tt>.
+
+<P>To use the locking mechanism, the command line version of FLTK
+must be compiled with <tt>--enable-threads</tt> set during the 
+<tt>configure</tt> process. IDE-based versions of FLTK are 
+automatically compiled with locking enabled if possible.
+
+<P>In <TT>main()</TT>, before calling <TT>Fl::run()</TT>, call 
+<TT>Fl::lock()</TT>. This will startup the runtime multithreading 
+support for your program. All callbacks and derived functions 
+like <tt>handle()</tt> and <tt>draw()</tt> will now be properly
+locked.
+
+<pre>
+  main() {
+    <a href="Fl.html#Fl.lock">Fl::lock()</a>;
+    /* run thread */
+    while(Fl::wait() > 0) {
+      if(<a href="Fl.html#Fl.thread_message">Fl::thread_message()</a>) {
+        /* process your data */
+      }
+    }
+  }
+
+</pre>
+
+<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
+in the following code:
+
+<pre>
+  <a href="Fl.html#Fl.lock">Fl::lock()</a>;      // avoid conflicting calls
+  ...              // your code here
+  <a href="Fl.html#Fl.unlock">Fl::unlock()</a>;    // allow other threads to access FLTK again
+  <a href="Fl.html#Fl.awake">Fl::awake(msg)</a>;  // tells FLTK that another thread has made changes
+
+</pre>
+
+<P>FLTK supports multiple platforms, some of them which do not 
+allow any other but the main thread to handle system events and
+open or close windows. The safe thing to do is to adhere to the 
+following rulesi for threads on all operating systems.
+
+<ul>
+
+<li>don't <tt>show()</tt> or <tt>hide()</tt>anything that contains 
+widgets derived from <tt>Fl_Window</tt>, including dialogs, file
+choosers, subwindows or <tt>Fl_GL_Window</tt>s</li>
+
+<li>don't call <tt>Fl::wait()</tt>, <tt>Fl::flush()</tt> or any 
+related methods that will handle system messages</li>
+
+<li>don't start or cancel timers</li>
+
+<li>don't change window decorations or titles</li>
+
+<li><tt>make_current()</tt> may or may not work well for regular
+windows, but should always work for <tt>Fl_GL_Window</tt>s to 
+allow for high speed rendering on graphics cards with multiple 
+pipelines</li>
+
+</ul>
+
+<P>See also: 
+<a href="Fl.html#Fl.lock">void lock()</A>, 
+<a href="Fl.html#Fl.unlock">void unlock()</A>, 
+<a href="Fl.html#Fl.awake">void awake(void *message)</A>, 
+<a href="Fl.html#Fl.thread_message">void *thread_message()</A>.
+
+
+</BODY>
+</HTML>
diff --git a/documentation/index.html b/documentation/index.html
index 001b9e627..5187f0789 100644
--- a/documentation/index.html
+++ b/documentation/index.html
@@ -73,6 +73,9 @@
 	<LI><A HREF="fluid.html#widget_attributes">Selecting Moving Widgets</A></LI>
 	<LI><A HREF="fluid.html#images">Image Labels</A></LI>
 	</UL>
+	<B><A HREF="advanced.html#advanced">10 - Advanced FLTK</A></B>
+	<BR>
+	<BR>
 	<B><A HREF="widgets.html#widgets">A - Class Reference</A></B>
 	<BR>
 	<BR>
author	Matthias Melcher <fltk@matthiasm.com>	2007-01-18 22:48:19 +0000
committer	Matthias Melcher <fltk@matthiasm.com>	2007-01-18 22:48:19 +0000
commit	8e7e4167835186b2aab81c4e87153c574ff83466 (patch)
tree	ac7477a7e08300317717a84b94ac2527ec26c94e
parent	bb6f36cffe66509ebcc6da6d1a8d98cf48a0b749 (diff)