interface/thread.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        thread.h
   3 // Purpose:     interface of wxCondition
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCondition
  11     @wxheader{thread.h}
  12
  13     wxCondition variables correspond to pthread conditions or to Win32 event
  14     objects. They may be used in a multithreaded application to wait until the
  15     given condition becomes @true which happens when the condition becomes signaled.
  16
  17     For example, if a worker thread is doing some long task and another thread has
  18     to wait until it is finished, the latter thread will wait on the condition
  19     object and the worker thread will signal it on exit (this example is not
  20     perfect because in this particular case it would be much better to just
  21     wxThread::Wait for the worker thread, but if there are several
  22     worker threads it already makes much more sense).
  23
  24     Note that a call to wxCondition::Signal may happen before the
  25     other thread calls wxCondition::Wait and, just as with the
  26     pthread conditions, the signal is then lost and so if you want to be sure that
  27     you don't miss it you must keep the mutex associated with the condition
  28     initially locked and lock it again before calling
  29     wxCondition::Signal. Of course, this means that this call is
  30     going to block until wxCondition::Wait is called by another
  31     thread.
  32
  33     @library{wxbase}
  34     @category{threading}
  35
  36     @see wxThread, wxMutex
  37 */
  38 class wxCondition
  39 {
  40 public:
  41     /**
  42         Default and only constructor. The @a mutex must be locked by the caller
  43         before calling Wait() function.
  44         Use IsOk() to check if the object was successfully
  45         initialized.
  46     */
  47     wxCondition(wxMutex& mutex);
  48
  49     /**
  50         Destroys the wxCondition object. The destructor is not virtual so this class
  51         should not be used polymorphically.
  52     */
  53     ~wxCondition();
  54
  55     /**
  56         Broadcasts to all waiting threads, waking all of them up. Note that this method
  57         may be called whether the mutex associated with this condition is locked or
  58         not.
  59
  60         @see Signal()
  61     */
  62     void Broadcast();
  63
  64     /**
  65         Returns @true if the object had been initialized successfully, @false
  66         if an error occurred.
  67     */
  68     bool IsOk() const;
  69
  70     /**
  71         Signals the object waking up at most one thread. If several threads are waiting
  72         on the same condition, the exact thread which is woken up is undefined. If no
  73         threads are waiting, the signal is lost and the condition would have to be
  74         signalled again to wake up any thread which may start waiting on it later.
  75         Note that this method may be called whether the mutex associated with this
  76         condition is locked or not.
  77
  78         @see Broadcast()
  79     */
  80     void Signal();
  81
  82     /**
  83         Waits until the condition is signalled.
  84         This method atomically releases the lock on the mutex associated with this
  85         condition (this is why it must be locked prior to calling Wait) and puts the
  86         thread to sleep until Signal() or
  87         Broadcast() is called. It then locks the mutex
  88         again and returns.
  89         Note that even if Signal() had been called before
  90         Wait without waking up any thread, the thread would still wait for another one
  91         and so it is important to ensure that the condition will be signalled after
  92         Wait or the thread may sleep forever.
  93
  94         @return Returns wxCOND_NO_ERROR on success, another value if an error
  95                  occurred.
  96
  97         @see WaitTimeout()
  98     */
  99     wxCondError Wait();
 100
 101     /**
 102         Waits until the condition is signalled or the timeout has elapsed.
 103         This method is identical to Wait() except that it
 104         returns, with the return code of @c wxCOND_TIMEOUT as soon as the given
 105         timeout expires.
 106
 107         @param milliseconds
 108             Timeout in milliseconds
 109     */
 110     wxCondError WaitTimeout(unsigned long milliseconds);
 111 };
 112
 113
 114
 115 /**
 116     @class wxCriticalSectionLocker
 117     @wxheader{thread.h}
 118
 119     This is a small helper class to be used with wxCriticalSection
 120     objects. A wxCriticalSectionLocker enters the critical section in the
 121     constructor and leaves it in the destructor making it much more difficult to
 122     forget to leave a critical section (which, in general, will lead to serious
 123     and difficult to debug problems).
 124
 125     Example of using it:
 126
 127     @code
 128     void Set Foo()
 129     {
 130         // gs_critSect is some (global) critical section guarding access to the
 131         // object "foo"
 132         wxCriticalSectionLocker locker(gs_critSect);
 133
 134         if ( ... )
 135         {
 136             // do something
 137             ...
 138
 139             return;
 140         }
 141
 142         // do something else
 143         ...
 144
 145         return;
 146     }
 147     @endcode
 148
 149     Without wxCriticalSectionLocker, you would need to remember to manually leave
 150     the critical section before each @c return.
 151
 152     @library{wxbase}
 153     @category{threading}
 154
 155     @see wxCriticalSection, wxMutexLocker
 156 */
 157 class wxCriticalSectionLocker
 158 {
 159 public:
 160     /**
 161         Constructs a wxCriticalSectionLocker object associated with given
 162         @a criticalsection and enters it.
 163     */
 164     wxCriticalSectionLocker(wxCriticalSection& criticalsection);
 165
 166     /**
 167         Destructor leaves the critical section.
 168     */
 169     ~wxCriticalSectionLocker();
 170 };
 171
 172
 173
 174 /**
 175     @class wxThreadHelper
 176     @wxheader{thread.h}
 177
 178     The wxThreadHelper class is a mix-in class that manages a single background
 179     thread.  By deriving from wxThreadHelper, a class can implement the thread
 180     code in its own wxThreadHelper::Entry method
 181     and easily share data and synchronization objects between the main thread
 182     and the worker thread.  Doing this prevents the awkward passing of pointers
 183     that is needed when the original object in the main thread needs to
 184     synchronize with its worker thread in its own wxThread derived object.
 185
 186     For example, wxFrame may need to make some calculations
 187     in a background thread and then display the results of those calculations in
 188     the main window.
 189
 190     Ordinarily, a wxThread derived object would be created
 191     with the calculation code implemented in
 192     wxThread::Entry.  To access the inputs to the
 193     calculation, the frame object would often to pass a pointer to itself to the
 194     thread object.  Similarly, the frame object would hold a pointer to the
 195     thread object.  Shared data and synchronization objects could be stored in
 196     either object though the object without the data would have to access the
 197     data through a pointer.
 198
 199     However, with wxThreadHelper, the frame object and the thread object are
 200     treated as the same object.  Shared data and synchronization variables are
 201     stored in the single object, eliminating a layer of indirection and the
 202     associated pointers.
 203
 204     @library{wxbase}
 205     @category{threading}
 206
 207     @see wxThread
 208 */
 209 class wxThreadHelper
 210 {
 211 public:
 212     /**
 213         This constructor simply initializes a member variable.
 214     */
 215     wxThreadHelper();
 216
 217     /**
 218         The destructor frees the resources associated with the thread.
 219     */
 220     ~wxThreadHelper();
 221
 222     /**
 223         Creates a new thread. The thread object is created in the suspended state, and
 224         you
 225         should call @ref wxThread::Run GetThread()-Run to start running
 226         it.  You may optionally specify the stack size to be allocated to it (Ignored on
 227         platforms that don't support setting it explicitly, eg. Unix).
 228
 229         @return One of:
 230     */
 231     wxThreadError Create(unsigned int stackSize = 0);
 232
 233     /**
 234         This is the entry point of the thread. This function is pure virtual and must
 235         be implemented by any derived class. The thread execution will start here.
 236         The returned value is the thread exit code which is only useful for
 237         joinable threads and is the value returned by
 238         @ref wxThread::Wait GetThread()-Wait.
 239         This function is called by wxWidgets itself and should never be called
 240         directly.
 241     */
 242     virtual ExitCode Entry();
 243
 244     /**
 245         This is a public function that returns the wxThread object
 246         associated with the thread.
 247     */
 248     wxThread* GetThread();
 249
 250     /**
 251         wxThread * m_thread
 252         the actual wxThread object.
 253     */
 254 };
 255
 256
 257
 258 /**
 259     @class wxCriticalSection
 260     @wxheader{thread.h}
 261
 262     A critical section object is used for exactly the same purpose as
 263     mutexes(). The only difference is that under Windows platform
 264     critical sections are only visible inside one process, while mutexes may be
 265     shared among processes, so using critical sections is slightly more
 266     efficient. The terminology is also slightly different: mutex may be locked (or
 267     acquired) and unlocked (or released) while critical section is entered and left
 268     by the program.
 269
 270     Finally, you should try to use
 271     wxCriticalSectionLocker class whenever
 272     possible instead of directly using wxCriticalSection for the same reasons
 273     wxMutexLocker is preferrable to
 274     wxMutex - please see wxMutex for an example.
 275
 276     @library{wxbase}
 277     @category{threading}
 278
 279     @see wxThread, wxCondition, wxCriticalSectionLocker
 280 */
 281 class wxCriticalSection
 282 {
 283 public:
 284     /**
 285         Default constructor initializes critical section object.
 286     */
 287     wxCriticalSection();
 288
 289     /**
 290         Destructor frees the resources.
 291     */
 292     ~wxCriticalSection();
 293
 294     /**
 295         Enter the critical section (same as locking a mutex). There is no error return
 296         for this function. After entering the critical section protecting some global
 297         data the thread running in critical section may safely use/modify it.
 298     */
 299     void Enter();
 300
 301     /**
 302         Leave the critical section allowing other threads use the global data protected
 303         by it. There is no error return for this function.
 304     */
 305     void Leave();
 306 };
 307
 308
 309
 310 /**
 311     @class wxThread
 312     @wxheader{thread.h}
 313
 314     A thread is basically a path of execution through a program. Threads are
 315     sometimes called @e light-weight processes, but the fundamental difference
 316     between threads and processes is that memory spaces of different processes are
 317     separated while all threads share the same address space.
 318
 319     While it makes it much easier to share common data between several threads, it
 320     also makes it much easier to shoot oneself in the foot, so careful use of
 321     synchronization objects such as mutexes() or @ref wxCriticalSection
 322     "critical sections" is recommended. In addition, don't create global thread
 323     objects because they allocate memory in their constructor, which will cause
 324     problems for the memory checking system.
 325
 326     @section overview_typeswxthread Types of wxThreads
 327         There are two types of threads in wxWidgets: @e detached and @e joinable,
 328         modeled after the the POSIX thread API. This is different from the Win32 API
 329         where all threads are joinable.
 330
 331         By default wxThreads in wxWidgets use the detached behavior. Detached threads
 332         delete themselves once they have completed, either by themselves when they
 333         complete processing or through a call to Delete(), and thus
 334         must be created on the heap (through the new operator, for example).
 335         Conversely, joinable threads do not delete themselves when they are done
 336         processing and as such are safe to create on the stack. Joinable threads
 337         also provide the ability for one to get value it returned from Entry()
 338         through Wait().
 339
 340         You shouldn't hurry to create all the threads joinable, however, because this
 341         has a disadvantage as well: you @b must Wait() for a joinable thread or the
 342         system resources used by it will never be freed, and you also must delete the
 343         corresponding wxThread object yourself if you did not create it on the stack.
 344         In contrast, detached threads are of the "fire-and-forget" kind: you only have to
 345         start a detached thread and it will terminate and destroy itself.
 346
 347     @section overview_deletionwxthread wxThread Deletion
 348         Regardless of whether it has terminated or not, you should call
 349         Wait() on a joinable thread to release its memory, as outlined in
 350         @ref overview_typeswxthread "Types of wxThreads". If you created
 351         a joinable thread on the heap, remember to delete it manually with the delete
 352         operator or similar means as only detached threads handle this type of memory
 353         management.
 354
 355         Since detached threads delete themselves when they are finished processing,
 356         you should take care when calling a routine on one. If you are certain the
 357         thread is still running and would like to end it, you may call Delete()
 358         to gracefully end it (which implies that the thread will be deleted after
 359         that call to Delete()). It should be implied that you should never attempt
 360         to delete a detached thread with the delete operator or similar means.
 361         As mentioned, Wait() or Delete() attempts to gracefully terminate a
 362         joinable and detached thread, respectively. It does this by waiting until
 363         the thread in question calls TestDestroy() or ends processing (returns
 364         from wxThread::Entry).
 365
 366         Obviously, if the thread does call TestDestroy() and does not end the calling
 367         thread will come to halt. This is why it is important to call TestDestroy() in
 368         the Entry() routine of your threads as often as possible.
 369         As a last resort you can end the thread immediately through Kill(). It is
 370         strongly recommended that you do not do this, however, as it does not free
 371         the resources associated with the object (although the wxThread object of
 372         detached threads will still be deleted) and could leave the C runtime
 373         library in an undefined state.
 374
 375     @section overview_secondarythreads wxWidgets Calls in Secondary Threads
 376         All threads other than the "main application thread" (the one
 377         wxApp::OnInit or your main function runs in, for example) are considered
 378         "secondary threads". These include all threads created by Create() or the
 379         corresponding constructors.
 380
 381         GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe
 382         at all in secondary threads and could end your application prematurely.
 383         This is due to several reasons, including the underlying native API and
 384         the fact that wxThread does not run a GUI event loop similar to other APIs
 385         as MFC.
 386
 387         A workaround for some wxWidgets ports is calling wxMutexGUIEnter()
 388         before any GUI calls and then calling wxMutexGUILeave() afterwords. However,
 389         the recommended way is to simply process the GUI calls in the main thread
 390         through an event that is posted by either wxQueueEvent().
 391         This does not imply that calls to these classes are thread-safe, however,
 392         as most wxWidgets classes are not thread-safe, including wxString.
 393
 394     @section overview_pollwxThread Don't Poll a wxThread
 395         A common problem users experience with wxThread is that in their main thread
 396         they will check the thread every now and then to see if it has ended through
 397         IsRunning(), only to find that their application has run into problems
 398         because the thread is using the default behavior and has already deleted
 399         itself. Naturally, they instead attempt to use joinable threads in place
 400         of the previous behavior. However, polling a wxThread for when it has ended
 401         is in general a bad idea - in fact calling a routine on any running wxThread
 402         should be avoided if possible. Instead, find a way to notify yourself when
 403         the thread has ended.
 404
 405         Usually you only need to notify the main thread, in which case you can
 406         post an event to it via wxPostEvent() or wxEvtHandler::AddPendingEvent.
 407         In the case of secondary threads you can call a routine of another class
 408         when the thread is about to complete processing and/or set the value of
 409         a variable, possibly using mutexes() and/or other synchronization means
 410         if necessary.
 411
 412     @library{wxbase}
 413     @category{threading}
 414     @see wxMutex, wxCondition, wxCriticalSection
 415 */
 416 class wxThread
 417 {
 418 public:
 419     /**
 420         This constructor creates a new detached (default) or joinable C++
 421         thread object. It does not create or start execution of the real thread --
 422         for this you should use the Create() and Run() methods.
 423
 424         The possible values for @a kind parameters are:
 425           - @b wxTHREAD_DETACHED - Creates a detached thread.
 426           - @b wxTHREAD_JOINABLE - Creates a joinable thread.
 427     */
 428     wxThread(wxThreadKind kind = wxTHREAD_DETACHED);
 429
 430     /**
 431         The destructor frees the resources associated with the thread. Notice that you
 432         should never delete a detached thread -- you may only call
 433         Delete() on it or wait until it terminates (and auto
 434         destructs) itself. Because the detached threads delete themselves, they can
 435         only be allocated on the heap.
 436         Joinable threads should be deleted explicitly. The Delete() and Kill() functions
 437         will not delete the C++ thread object. It is also safe to allocate them on
 438         stack.
 439     */
 440     ~wxThread();
 441
 442     /**
 443         Creates a new thread. The thread object is created in the suspended state,
 444         and you should call Run() to start running it.  You may optionally
 445         specify the stack size to be allocated to it (Ignored on platforms that don't
 446         support setting it explicitly, eg. Unix system without
 447         @c pthread_attr_setstacksize). If you do not specify the stack size,
 448         the system's default value is used.
 449         @b Warning: It is a good idea to explicitly specify a value as systems'
 450         default values vary from just a couple of KB on some systems (BSD and
 451         OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you
 452         have a thread that requires more than just a few KB of memory, you will
 453         have mysterious problems on some platforms but not on the common ones. On the
 454         other hand, just indicating a large stack size by default will give you
 455         performance issues on those systems with small default stack since those
 456         typically use fully committed memory for the stack. On the contrary, if
 457         use a lot of threads (say several hundred), virtual adress space can get tight
 458         unless you explicitly specify a smaller amount of thread stack space for each
 459         thread.
 460
 461         @return One of:
 462           - @b wxTHREAD_NO_ERROR - No error.
 463           - @b wxTHREAD_NO_RESOURCE - There were insufficient resources to create the thread.
 464           - @b wxTHREAD_NO_RUNNING - The thread is already running
 465     */
 466     wxThreadError Create(unsigned int stackSize = 0);
 467
 468     /**
 469         Calling Delete() gracefully terminates a
 470         detached thread, either when the thread calls TestDestroy() or finished
 471         processing.
 472         (Note that while this could work on a joinable thread you simply should not
 473         call this routine on one as afterwards you may not be able to call
 474         Wait() to free the memory of that thread).
 475         See @ref overview_deletionwxthread "wxThread deletion" for a broader
 476         explanation of this routine.
 477     */
 478     wxThreadError Delete();
 479
 480     /**
 481         This is the entry point of the thread. This function is pure virtual and must
 482         be implemented by any derived class. The thread execution will start here.
 483         The returned value is the thread exit code which is only useful for
 484         joinable threads and is the value returned by Wait().
 485         This function is called by wxWidgets itself and should never be called
 486         directly.
 487     */
 488     virtual ExitCode Entry();
 489
 490     /**
 491         This is a protected function of the wxThread class and thus can only be called
 492         from a derived class. It also can only be called in the context of this
 493         thread, i.e. a thread can only exit from itself, not from another thread.
 494         This function will terminate the OS thread (i.e. stop the associated path of
 495         execution) and also delete the associated C++ object for detached threads.
 496         OnExit() will be called just before exiting.
 497     */
 498     void Exit(ExitCode exitcode = 0);
 499
 500     /**
 501         Returns the number of system CPUs or -1 if the value is unknown.
 502
 503         @see SetConcurrency()
 504     */
 505     static int GetCPUCount();
 506
 507     /**
 508         Returns the platform specific thread ID of the current thread as a
 509         long.  This can be used to uniquely identify threads, even if they are
 510         not wxThreads.
 511     */
 512     static unsigned long GetCurrentId();
 513
 514     /**
 515         Gets the thread identifier: this is a platform dependent number that uniquely
 516         identifies the
 517         thread throughout the system during its existence (i.e. the thread identifiers
 518         may be reused).
 519     */
 520     unsigned long GetId() const;
 521
 522     /**
 523         Gets the priority of the thread, between zero and 100.
 524
 525         The following priorities are defined:
 526           - @b WXTHREAD_MIN_PRIORITY: 0
 527           - @b WXTHREAD_DEFAULT_PRIORITY: 50
 528           - @b WXTHREAD_MAX_PRIORITY: 100
 529     */
 530     int GetPriority() const;
 531
 532     /**
 533         Returns @true if the thread is alive (i.e. started and not terminating).
 534         Note that this function can only safely be used with joinable threads, not
 535         detached ones as the latter delete themselves and so when the real thread is
 536         no longer alive, it is not possible to call this function because
 537         the wxThread object no longer exists.
 538     */
 539     bool IsAlive() const;
 540
 541     /**
 542         Returns @true if the thread is of the detached kind, @false if it is a
 543         joinable
 544         one.
 545     */
 546     bool IsDetached() const;
 547
 548     /**
 549         Returns @true if the calling thread is the main application thread.
 550     */
 551     static bool IsMain();
 552
 553     /**
 554         Returns @true if the thread is paused.
 555     */
 556     bool IsPaused() const;
 557
 558     /**
 559         Returns @true if the thread is running.
 560         This method may only be safely used for joinable threads, see the remark in
 561         IsAlive().
 562     */
 563     bool IsRunning() const;
 564
 565     /**
 566         Immediately terminates the target thread. @b This function is dangerous and
 567         should
 568         be used with extreme care (and not used at all whenever possible)! The resources
 569         allocated to the thread will not be freed and the state of the C runtime library
 570         may become inconsistent. Use Delete() for detached
 571         threads or Wait() for joinable threads instead.
 572         For detached threads Kill() will also delete the associated C++ object.
 573         However this will not happen for joinable threads and this means that you will
 574         still have to delete the wxThread object yourself to avoid memory leaks.
 575         In neither case OnExit() of the dying thread will be
 576         called, so no thread-specific cleanup will be performed.
 577         This function can only be called from another thread context, i.e. a thread
 578         cannot kill itself.
 579         It is also an error to call this function for a thread which is not running or
 580         paused (in the latter case, the thread will be resumed first) -- if you do it,
 581         a @b wxTHREAD_NOT_RUNNING error will be returned.
 582     */
 583     wxThreadError Kill();
 584
 585     /**
 586         Called when the thread exits. This function is called in the context of the
 587         thread associated with the wxThread object, not in the context of the main
 588         thread. This function will not be called if the thread was
 589         @ref Kill() killed.
 590         This function should never be called directly.
 591     */
 592     void OnExit();
 593
 594     /**
 595         Suspends the thread. Under some implementations (Win32), the thread is
 596         suspended immediately, under others it will only be suspended when it calls
 597         TestDestroy() for the next time (hence, if the
 598         thread doesn't call it at all, it won't be suspended).
 599         This function can only be called from another thread context.
 600     */
 601     wxThreadError Pause();
 602
 603     /**
 604         Resumes a thread suspended by the call to Pause().
 605         This function can only be called from another thread context.
 606     */
 607     wxThreadError Resume();
 608
 609     /**
 610         Starts the thread execution. Should be called after
 611         Create().
 612         This function can only be called from another thread context.
 613     */
 614     wxThreadError Run();
 615
 616     /**
 617         Sets the thread concurrency level for this process. This is, roughly, the
 618         number of threads that the system tries to schedule to run in parallel.
 619         The value of 0 for @a level may be used to set the default one.
 620         Returns @true on success or @false otherwise (for example, if this function is
 621         not implemented for this platform -- currently everything except Solaris).
 622     */
 623     static bool SetConcurrency(size_t level);
 624
 625     /**
 626         Sets the priority of the thread, between 0 and 100. It can only be set
 627         after calling Create() but before calling
 628         Run().
 629
 630         The following priorities are defined:
 631           - @b WXTHREAD_MIN_PRIORITY: 0
 632           - @b WXTHREAD_DEFAULT_PRIORITY: 50
 633           - @b WXTHREAD_MAX_PRIORITY: 100
 634     */
 635     void SetPriority(int priority);
 636
 637     /**
 638         Pauses the thread execution for the given amount of time.
 639
 640         This is the same as wxMilliSleep().
 641     */
 642     static void Sleep(unsigned long milliseconds);
 643
 644     /**
 645         This function should be called periodically by the thread to ensure that
 646         calls to Pause() and Delete() will work. If it returns @true, the thread
 647         should exit as soon as possible. Notice that under some platforms (POSIX),
 648         implementation of Pause() also relies on this function being called, so
 649         not calling it would prevent both stopping and suspending thread from working.
 650     */
 651     virtual bool TestDestroy();
 652
 653     /**
 654         Return the thread object for the calling thread. @NULL is returned if
 655         the calling thread is the main (GUI) thread, but IsMain() should be used
 656         to test whether the thread is really the main one because @NULL may also
 657         be returned for the thread not created with wxThread class. Generally
 658         speaking, the return value for such a thread is undefined.
 659     */
 660     static wxThread* This();
 661
 662     /**
 663         Waits for a joinable thread to terminate and returns the value the thread
 664         returned from Entry() or @c (ExitCode)-1 on error. Notice that, unlike
 665         Delete() doesn't cancel the thread in any way so the caller waits for as
 666         long as it takes to the thread to exit.
 667         You can only Wait() for joinable (not detached) threads.
 668         This function can only be called from another thread context.
 669         See @ref overview_deletionwxthread "wxThread deletion" for a broader
 670         explanation of this routine.
 671     */
 672     ExitCode Wait() const;
 673
 674     /**
 675         Give the rest of the thread time slice to the system allowing the other
 676         threads to run.
 677         Note that using this function is @b strongly discouraged, since in
 678         many cases it indicates a design weakness of your threading model (as
 679         does using Sleep functions).
 680         Threads should use the CPU in an efficient manner, i.e. they should
 681         do their current work efficiently, then as soon as the work is done block
 682         on a wakeup event (wxCondition, wxMutex, select(), poll(), ...)
 683         which will get signalled e.g. by other threads or a user device once further
 684         thread work is available. Using Yield or Sleep
 685         indicates polling-type behaviour, since we're fuzzily giving up our timeslice
 686         and wait until sometime later we'll get reactivated, at which time we
 687         realize that there isn't really much to do and Yield again...
 688         The most critical characteristic of Yield is that it's operating system
 689         specific: there may be scheduler changes which cause your thread to not
 690         wake up relatively soon again, but instead many seconds later,
 691         causing huge performance issues for your application. @b with a
 692         well-behaving, CPU-efficient thread the operating system is likely to properly
 693         care for its reactivation the moment it needs it, whereas with
 694         non-deterministic, Yield-using threads all bets are off and the system
 695         scheduler is free to penalize drastically, and this effect gets worse
 696         with increasing system load due to less free CPU resources available.
 697         You may refer to various Linux kernel sched_yield discussions for more
 698         information.
 699         See also Sleep().
 700     */
 701     void Yield();
 702 };
 703
 704 /**
 705     @class wxSemaphore
 706     @wxheader{thread.h}
 707
 708     wxSemaphore is a counter limiting the number of threads concurrently accessing
 709     a shared resource. This counter is always between 0 and the maximum value
 710     specified during the semaphore creation. When the counter is strictly greater
 711     than 0, a call to wxSemaphore::Wait returns immediately and
 712     decrements the counter. As soon as it reaches 0, any subsequent calls to
 713     wxSemaphore::Wait block and only return when the semaphore
 714     counter becomes strictly positive again as the result of calling
 715     wxSemaphore::Post which increments the counter.
 716
 717     In general, semaphores are useful to restrict access to a shared resource
 718     which can only be accessed by some fixed number of clients at the same time. For
 719     example, when modeling a hotel reservation system a semaphore with the counter
 720     equal to the total number of available rooms could be created. Each time a room
 721     is reserved, the semaphore should be acquired by calling
 722     wxSemaphore::Wait and each time a room is freed it should be
 723     released by calling wxSemaphore::Post.
 724
 725     @library{wxbase}
 726     @category{threading}
 727 */
 728 class wxSemaphore
 729 {
 730 public:
 731     /**
 732         Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if
 733         there is no upper limit. If maxcount is 1, the semaphore behaves almost as a
 734         mutex (but unlike a mutex it can be released by a thread different from the one
 735         which acquired it).
 736         @a initialcount is the initial value of the semaphore which must be between
 737         0 and @a maxcount (if it is not set to 0).
 738     */
 739     wxSemaphore(int initialcount = 0, int maxcount = 0);
 740
 741     /**
 742         Destructor is not virtual, don't use this class polymorphically.
 743     */
 744     ~wxSemaphore();
 745
 746     /**
 747         Increments the semaphore count and signals one of the waiting
 748         threads in an atomic way. Returns wxSEMA_OVERFLOW if the count
 749         would increase the counter past the maximum.
 750
 751         @return One of:
 752     */
 753     wxSemaError Post();
 754
 755     /**
 756         Same as Wait(), but returns immediately.
 757
 758         @return One of:
 759     */
 760     wxSemaError TryWait();
 761
 762     /**
 763         Wait indefinitely until the semaphore count becomes strictly positive
 764         and then decrement it and return.
 765
 766         @return One of:
 767     */
 768     wxSemaError Wait();
 769 };
 770
 771
 772
 773 /**
 774     @class wxMutexLocker
 775     @wxheader{thread.h}
 776
 777     This is a small helper class to be used with wxMutex
 778     objects. A wxMutexLocker acquires a mutex lock in the constructor and releases
 779     (or unlocks) the mutex in the destructor making it much more difficult to
 780     forget to release a mutex (which, in general, will promptly lead to serious
 781     problems). See wxMutex for an example of wxMutexLocker
 782     usage.
 783
 784     @library{wxbase}
 785     @category{threading}
 786
 787     @see wxMutex, wxCriticalSectionLocker
 788 */
 789 class wxMutexLocker
 790 {
 791 public:
 792     /**
 793         Constructs a wxMutexLocker object associated with mutex and locks it.
 794         Call @ref IsOk() IsLocked to check if the mutex was
 795         successfully locked.
 796     */
 797     wxMutexLocker(wxMutex& mutex);
 798
 799     /**
 800         Destructor releases the mutex if it was successfully acquired in the ctor.
 801     */
 802     ~wxMutexLocker();
 803
 804     /**
 805         Returns @true if mutex was acquired in the constructor, @false otherwise.
 806     */
 807     bool IsOk() const;
 808 };
 809
 810
 811
 812 /**
 813     @class wxMutex
 814     @wxheader{thread.h}
 815
 816     A mutex object is a synchronization object whose state is set to signaled when
 817     it is not owned by any thread, and nonsignaled when it is owned. Its name comes
 818     from its usefulness in coordinating mutually-exclusive access to a shared
 819     resource as only one thread at a time can own a mutex object.
 820
 821     Mutexes may be recursive in the sense that a thread can lock a mutex which it
 822     had already locked before (instead of dead locking the entire process in this
 823     situation by starting to wait on a mutex which will never be released while the
 824     thread is waiting) but using them is not recommended under Unix and they are
 825     @b not recursive there by default. The reason for this is that recursive
 826     mutexes are not supported by all Unix flavours and, worse, they cannot be used
 827     with wxCondition. On the other hand, Win32 mutexes are
 828     always recursive.
 829
 830     For example, when several threads use the data stored in the linked list,
 831     modifications to the list should only be allowed to one thread at a time
 832     because during a new node addition the list integrity is temporarily broken
 833     (this is also called @e program invariant).
 834
 835     @library{wxbase}
 836     @category{threading}
 837
 838     @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection
 839 */
 840 class wxMutex
 841 {
 842 public:
 843     /**
 844         Default constructor.
 845     */
 846     wxMutex(wxMutexType type = wxMUTEX_DEFAULT);
 847
 848     /**
 849         Destroys the wxMutex object.
 850     */
 851     ~wxMutex();
 852
 853     /**
 854         Locks the mutex object. This is equivalent to
 855         LockTimeout() with infinite timeout.
 856
 857         @return One of:
 858     */
 859     wxMutexError Lock();
 860
 861     /**
 862         Try to lock the mutex object during the specified time interval.
 863
 864         @return One of:
 865     */
 866     wxMutexError LockTimeout(unsigned long msec);
 867
 868     /**
 869         Tries to lock the mutex object. If it can't, returns immediately with an error.
 870
 871         @return One of:
 872     */
 873     wxMutexError TryLock();
 874
 875     /**
 876         Unlocks the mutex object.
 877
 878         @return One of:
 879     */
 880     wxMutexError Unlock();
 881 };
 882
 883
 884
 885 // ============================================================================
 886 // Global functions/macros
 887 // ============================================================================
 888
 889 /** @ingroup group_funcmacro_thread */
 890 //@{
 891
 892 /**
 893     This macro declares a (static) critical section object named @a cs if
 894     @c wxUSE_THREADS is 1 and does nothing if it is 0.
 895
 896     @header{wx/thread.h}
 897 */
 898 #define wxCRIT_SECT_DECLARE(cs)
 899
 900 /**
 901     This macro declares a critical section object named @a cs if
 902     @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include
 903     the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to
 904     declare a class or struct member which explains its name.
 905
 906     @header{wx/thread.h}
 907 */
 908 #define wxCRIT_SECT_DECLARE_MEMBER(cs)
 909
 910 /**
 911     This macro creates a wxCriticalSectionLocker named @a name and associated
 912     with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing
 913     if it is 0.
 914
 915     @header{wx/thread.h}
 916 */
 917 #define wxCRIT_SECT_LOCKER(name, cs)
 918
 919 /**
 920     This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it
 921     creates a static critical section object and also the lock object
 922     associated with it. Because of this, it can be only used inside a function,
 923     not at global scope. For example:
 924
 925     @code
 926     int IncCount()
 927     {
 928         static int s_counter = 0;
 929
 930         wxCRITICAL_SECTION(counter);
 931
 932         return ++s_counter;
 933     }
 934     @endcode
 935
 936     Note that this example assumes that the function is called the first time
 937     from the main thread so that the critical section object is initialized
 938     correctly by the time other threads start calling it, if this is not the
 939     case this approach can @b not be used and the critical section must be made
 940     a global instead.
 941
 942     @header{wx/thread.h}
 943 */
 944 #define wxCRITICAL_SECTION(name)
 945
 946 /**
 947     This macro is equivalent to
 948     @ref wxCriticalSection::Leave "critical_section.Leave()" if
 949     @c wxUSE_THREADS is 1 and does nothing if it is 0.
 950
 951     @header{wx/thread.h}
 952 */
 953 #define wxLEAVE_CRIT_SECT(critical_section)
 954
 955 /**
 956     This macro is equivalent to
 957     @ref wxCriticalSection::Enter "critical_section.Enter()" if
 958     @c wxUSE_THREADS is 1 and does nothing if it is 0.
 959
 960     @header{wx/thread.h}
 961 */
 962 #define wxENTER_CRIT_SECT(critical_section)
 963
 964 /**
 965     Returns @true if this thread is the main one. Always returns @true if
 966     @c wxUSE_THREADS is 0.
 967
 968     @header{wx/thread.h}
 969 */
 970 bool wxIsMainThread();
 971
 972 /**
 973     This function must be called when any thread other than the main GUI thread
 974     wants to get access to the GUI library. This function will block the
 975     execution of the calling thread until the main thread (or any other thread
 976     holding the main GUI lock) leaves the GUI library and no other thread will
 977     enter the GUI library until the calling thread calls wxMutexGuiLeave().
 978
 979     Typically, these functions are used like this:
 980
 981     @code
 982     void MyThread::Foo(void)
 983     {
 984         // before doing any GUI calls we must ensure that
 985         // this thread is the only one doing it!
 986
 987         wxMutexGuiEnter();
 988
 989         // Call GUI here:
 990         my_window-DrawSomething();
 991
 992         wxMutexGuiLeave();
 993     }
 994     @endcode
 995
 996     This function is only defined on platforms which support preemptive
 997     threads.
 998
 999     @note Under GTK, no creation of top-level windows is allowed in any thread
1000           but the main one.
1001
1002     @header{wx/thread.h}
1003 */
1004 void wxMutexGuiEnter();
1005
1006 /**
1007     This function is only defined on platforms which support preemptive
1008     threads.
1009
1010     @see wxMutexGuiEnter()
1011
1012     @header{wx/thread.h}
1013 */
1014 void wxMutexGuiLeave();
1015
1016 //@}
1017