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