X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b67a86d57493137cb1f7cce8ca8daf0b7120207e..78cb09ec439962b53ba75fef814b9a3871412287:/docs/latex/wx/thread.tex

diff --git a/docs/latex/wx/thread.tex b/docs/latex/wx/thread.tex
index 7a8c8ee32c..a0b29545c4 100644
--- a/docs/latex/wx/thread.tex
+++ b/docs/latex/wx/thread.tex
@@ -19,6 +19,10 @@ None.
 
 <wx/thread.h>
 
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
 \wxheading{See also}
 
 \helpref{wxMutex}{wxmutex}, \helpref{wxCondition}{wxcondition}, \helpref{wxCriticalSection}{wxcriticalsection}
@@ -454,6 +458,27 @@ is undefined.
 \func{void}{Yield}{\void}
 
 Give the rest of the thread time slice to the system allowing the other threads to run.
+Note that using this function is {\bf strongly discouraged}, since in
+many cases it indicates a design weakness of your threading model (as
+does using Sleep functions).
+Threads should use the CPU in an efficient manner, i.e. they should
+do their current work efficiently, then as soon as the work is done block
+on a wakeup event (wxCondition, wxMutex, select(), poll(), ...)
+which will get signalled e.g. by other threads or a user device once further
+thread work is available. Using Yield or Sleep
+indicates polling-type behaviour, since we're fuzzily giving up our timeslice
+and wait until sometime later we'll get reactivated, at which time we
+realize that there isn't really much to do and Yield again...
+The most critical characteristic of Yield is that it's operating system
+specific: there may be scheduler changes which cause your thread to not
+wake up relatively soon again, but instead many seconds later,
+causing huge performance issues for your application. {\bf with a
+well-behaving, CPU-efficient thread the operating system is likely to properly
+care for its reactivation the moment it needs it, whereas with
+non-deterministic, Yield-using threads all bets are off and the system
+scheduler is free to penalize drastically}, and this effect gets worse
+with increasing system load due to less free CPU resources available.
+You may refer to various Linux kernel sched\_yield discussions for more information.
 See also \helpref{Sleep()}{wxthreadsleep}.
 
 
@@ -461,10 +486,11 @@ See also \helpref{Sleep()}{wxthreadsleep}.
 
 \constfunc{ExitCode}{Wait}{\void}
 
-Gracefully terminates a joinable thread, either when the thread calls 
-\helpref{TestDestroy}{wxthreadtestdestroy} or finished processing, and 
-returns the value the thread returned from 
-\helpref{wxThread::Entry}{wxthreadentry} or {\tt (ExitCode)-1} on error. 
+Waits for a joinable thread to terminate and returns the value the thread
+returned from \helpref{wxThread::Entry}{wxthreadentry} or {\tt (ExitCode)-1} on
+error. Notice that, unlike \helpref{Delete}{wxthreaddelete} doesn't cancel the
+thread in any way so the caller waits for as long as it takes to the thread to
+exit.
 
 You can only Wait() for joinable (not detached) threads.