1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: thread.h 3 // Purpose: interface of all thread-related wxWidgets classes 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 9 /** See wxCondition. */ 10 enum wxCondError 11 { 12 wxCOND_NO_ERROR = 0, 13 wxCOND_INVALID, 14 wxCOND_TIMEOUT, //!< WaitTimeout() has timed out 15 wxCOND_MISC_ERROR 16 }; 17 18 19 /** 20 @class wxCondition 21 22 wxCondition variables correspond to pthread conditions or to Win32 event objects. 23 They may be used in a multithreaded application to wait until the given condition 24 becomes @true which happens when the condition becomes signaled. 25 26 For example, if a worker thread is doing some long task and another thread has 27 to wait until it is finished, the latter thread will wait on the condition 28 object and the worker thread will signal it on exit (this example is not 29 perfect because in this particular case it would be much better to just 30 wxThread::Wait for the worker thread, but if there are several worker threads 31 it already makes much more sense). 32 33 Note that a call to wxCondition::Signal may happen before the other thread calls 34 wxCondition::Wait and, just as with the pthread conditions, the signal is then 35 lost and so if you want to be sure that you don't miss it you must keep the 36 mutex associated with the condition initially locked and lock it again before calling 37 wxCondition::Signal. Of course, this means that this call is going to block 38 until wxCondition::Wait is called by another thread. 39 40 @section condition_example Example 41 42 This example shows how a main thread may launch a worker thread which starts 43 running and then waits until the main thread signals it to continue: 44 45 @code 46 class MySignallingThread : public wxThread 47 { 48 public: 49 MySignallingThread(wxMutex *mutex, wxCondition *condition) 50 { 51 m_mutex = mutex; 52 m_condition = condition; 53 } 54 55 virtual ExitCode Entry() 56 { 57 ... do our job ... 58 59 // tell the other(s) thread(s) that we're about to terminate: we must 60 // lock the mutex first or we might signal the condition before the 61 // waiting threads start waiting on it! 62 wxMutexLocker lock(*m_mutex); 63 m_condition->Broadcast(); // same as Signal() here -- one waiter only 64 65 return 0; 66 } 67 68 private: 69 wxCondition *m_condition; 70 wxMutex *m_mutex; 71 }; 72 73 int main() 74 { 75 wxMutex mutex; 76 wxCondition condition(mutex); 77 78 // the mutex should be initially locked 79 mutex.Lock(); 80 81 // create and run the thread but notice that it won't be able to 82 // exit (and signal its exit) before we unlock the mutex below 83 MySignallingThread *thread = new MySignallingThread(&mutex, &condition); 84 85 thread->Run(); 86 87 // wait for the thread termination: Wait() atomically unlocks the mutex 88 // which allows the thread to continue and starts waiting 89 condition.Wait(); 90 91 // now we can exit 92 return 0; 93 } 94 @endcode 95 96 Of course, here it would be much better to simply use a joinable thread and 97 call wxThread::Wait on it, but this example does illustrate the importance of 98 properly locking the mutex when using wxCondition. 99 100 @library{wxbase} 101 @category{threading} 102 103 @see wxThread, wxMutex 104 */ 105 class wxCondition 106 { 107 public: 108 /** 109 Default and only constructor. 110 The @a mutex must be locked by the caller before calling Wait() function. 111 Use IsOk() to check if the object was successfully initialized. 112 */ 113 wxCondition(wxMutex& mutex); 114 115 /** 116 Destroys the wxCondition object. 117 118 The destructor is not virtual so this class should not be used polymorphically. 119 */ 120 ~wxCondition(); 121 122 /** 123 Broadcasts to all waiting threads, waking all of them up. 124 125 Note that this method may be called whether the mutex associated with 126 this condition is locked or not. 127 128 @see Signal() 129 */ 130 wxCondError Broadcast(); 131 132 /** 133 Returns @true if the object had been initialized successfully, @false 134 if an error occurred. 135 */ 136 bool IsOk() const; 137 138 /** 139 Signals the object waking up at most one thread. 140 141 If several threads are waiting on the same condition, the exact thread 142 which is woken up is undefined. If no threads are waiting, the signal is 143 lost and the condition would have to be signalled again to wake up any 144 thread which may start waiting on it later. 145 146 Note that this method may be called whether the mutex associated with this 147 condition is locked or not. 148 149 @see Broadcast() 150 */ 151 wxCondError Signal(); 152 153 /** 154 Waits until the condition is signalled. 155 156 This method atomically releases the lock on the mutex associated with this 157 condition (this is why it must be locked prior to calling Wait()) and puts the 158 thread to sleep until Signal() or Broadcast() is called. 159 It then locks the mutex again and returns. 160 161 Note that even if Signal() had been called before Wait() without waking 162 up any thread, the thread would still wait for another one and so it is 163 important to ensure that the condition will be signalled after 164 Wait() or the thread may sleep forever. 165 166 @return Returns wxCOND_NO_ERROR on success, another value if an error occurred. 167 168 @see WaitTimeout() 169 */ 170 wxCondError Wait(); 171 172 /** 173 Waits until the condition is signalled and the associated condition true. 174 175 This is a convenience overload that may be used to ignore spurious 176 awakenings while waiting for a specific condition to become true. 177 178 Equivalent to 179 @code 180 while ( !predicate() ) 181 { 182 wxCondError e = Wait(); 183 if ( e != wxCOND_NO_ERROR ) 184 return e; 185 } 186 return wxCOND_NO_ERROR; 187 @endcode 188 189 The predicate would typically be a C++11 lambda: 190 @code 191 condvar.Wait([]{return value == 1;}); 192 @endcode 193 194 @since 3.0 195 */ 196 template<typename Functor> 197 wxCondError Wait(const Functor& predicate); 198 199 /** 200 Waits until the condition is signalled or the timeout has elapsed. 201 202 This method is identical to Wait() except that it returns, with the 203 return code of @c wxCOND_TIMEOUT as soon as the given timeout expires. 204 205 @param milliseconds 206 Timeout in milliseconds 207 208 @return Returns wxCOND_NO_ERROR if the condition was signalled, 209 wxCOND_TIMEOUT if the timeout elapsed before this happened or 210 another error code from wxCondError enum. 211 */ 212 wxCondError WaitTimeout(unsigned long milliseconds); 213 }; 214 215 216 /** 217 @class wxCriticalSectionLocker 218 219 This is a small helper class to be used with wxCriticalSection objects. 220 221 A wxCriticalSectionLocker enters the critical section in the constructor and 222 leaves it in the destructor making it much more difficult to forget to leave 223 a critical section (which, in general, will lead to serious and difficult 224 to debug problems). 225 226 Example of using it: 227 228 @code 229 void Set Foo() 230 { 231 // gs_critSect is some (global) critical section guarding access to the 232 // object "foo" 233 wxCriticalSectionLocker locker(gs_critSect); 234 235 if ( ... ) 236 { 237 // do something 238 ... 239 240 return; 241 } 242 243 // do something else 244 ... 245 246 return; 247 } 248 @endcode 249 250 Without wxCriticalSectionLocker, you would need to remember to manually leave 251 the critical section before each @c return. 252 253 @library{wxbase} 254 @category{threading} 255 256 @see wxCriticalSection, wxMutexLocker 257 */ 258 class wxCriticalSectionLocker 259 { 260 public: 261 /** 262 Constructs a wxCriticalSectionLocker object associated with given 263 @a criticalsection and enters it. 264 */ 265 wxCriticalSectionLocker(wxCriticalSection& criticalsection); 266 267 /** 268 Destructor leaves the critical section. 269 */ 270 ~wxCriticalSectionLocker(); 271 }; 272 273 274 275 /** 276 @class wxThreadHelper 277 278 The wxThreadHelper class is a mix-in class that manages a single background 279 thread, either detached or joinable (see wxThread for the differences). 280 By deriving from wxThreadHelper, a class can implement the thread 281 code in its own wxThreadHelper::Entry() method and easily share data and 282 synchronization objects between the main thread and the worker thread. 283 284 Doing this prevents the awkward passing of pointers that is needed when the 285 original object in the main thread needs to synchronize with its worker thread 286 in its own wxThread derived object. 287 288 For example, wxFrame may need to make some calculations in a background thread 289 and then display the results of those calculations in the main window. 290 291 Ordinarily, a wxThread derived object would be created with the calculation 292 code implemented in wxThread::Entry. To access the inputs to the calculation, 293 the frame object would often need to pass a pointer to itself to the thread object. 294 Similarly, the frame object would hold a pointer to the thread object. 295 296 Shared data and synchronization objects could be stored in either object 297 though the object without the data would have to access the data through 298 a pointer. 299 However with wxThreadHelper the frame object and the thread object are 300 treated as the same object. Shared data and synchronization variables are 301 stored in the single object, eliminating a layer of indirection and the 302 associated pointers. 303 304 Example: 305 @code 306 wxDECLARE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent); 307 308 class MyFrame : public wxFrame, public wxThreadHelper 309 { 310 public: 311 MyFrame(...) { ... } 312 ~MyFrame() 313 { 314 // it's better to do any thread cleanup in the OnClose() 315 // event handler, rather than in the destructor. 316 // This is because the event loop for a top-level window is not 317 // active anymore when its destructor is called and if the thread 318 // sends events when ending, they won't be processed unless 319 // you ended the thread from OnClose. 320 // See @ref overview_windowdeletion for more info. 321 } 322 323 ... 324 void DoStartALongTask(); 325 void OnThreadUpdate(wxThreadEvent& evt); 326 void OnClose(wxCloseEvent& evt); 327 ... 328 329 protected: 330 virtual wxThread::ExitCode Entry(); 331 332 // the output data of the Entry() routine: 333 char m_data[1024]; 334 wxCriticalSection m_dataCS; // protects field above 335 336 wxDECLARE_EVENT_TABLE(); 337 }; 338 339 wxDEFINE_EVENT(myEVT_THREAD_UPDATE, wxThreadEvent) 340 wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) 341 EVT_THREAD(wxID_ANY, myEVT_THREAD_UPDATE, MyFrame::OnThreadUpdate) 342 EVT_CLOSE(MyFrame::OnClose) 343 wxEND_EVENT_TABLE() 344 345 void MyFrame::DoStartALongTask() 346 { 347 // we want to start a long task, but we don't want our GUI to block 348 // while it's executed, so we use a thread to do it. 349 if (CreateThread(wxTHREAD_JOINABLE) != wxTHREAD_NO_ERROR) 350 { 351 wxLogError("Could not create the worker thread!"); 352 return; 353 } 354 355 // go! 356 if (GetThread()->Run() != wxTHREAD_NO_ERROR) 357 { 358 wxLogError("Could not run the worker thread!"); 359 return; 360 } 361 } 362 363 wxThread::ExitCode MyFrame::Entry() 364 { 365 // IMPORTANT: 366 // this function gets executed in the secondary thread context! 367 368 int offset = 0; 369 370 // here we do our long task, periodically calling TestDestroy(): 371 while (!GetThread()->TestDestroy()) 372 { 373 // since this Entry() is implemented in MyFrame context we don't 374 // need any pointer to access the m_data, m_processedData, m_dataCS 375 // variables... very nice! 376 377 // this is an example of the generic structure of a download thread: 378 char buffer[1024]; 379 download_chunk(buffer, 1024); // this takes time... 380 381 { 382 // ensure no one reads m_data while we write it 383 wxCriticalSectionLocker lock(m_dataCS); 384 memcpy(m_data+offset, buffer, 1024); 385 offset += 1024; 386 } 387 388 389 // VERY IMPORTANT: do not call any GUI function inside this 390 // function; rather use wxQueueEvent(): 391 wxQueueEvent(this, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE)); 392 // we used pointer 'this' assuming it's safe; see OnClose() 393 } 394 395 // TestDestroy() returned true (which means the main thread asked us 396 // to terminate as soon as possible) or we ended the long task... 397 return (wxThread::ExitCode)0; 398 } 399 400 void MyFrame::OnClose(wxCloseEvent&) 401 { 402 // important: before terminating, we _must_ wait for our joinable 403 // thread to end, if it's running; in fact it uses variables of this 404 // instance and posts events to *this event handler 405 406 if (GetThread() && // DoStartALongTask() may have not been called 407 GetThread()->IsRunning()) 408 GetThread()->Wait(); 409 410 Destroy(); 411 } 412 413 void MyFrame::OnThreadUpdate(wxThreadEvent& evt) 414 { 415 // ...do something... e.g. m_pGauge->Pulse(); 416 417 // read some parts of m_data just for fun: 418 wxCriticalSectionLocker lock(m_dataCS); 419 wxPrintf("%c", m_data[100]); 420 } 421 @endcode 422 423 @library{wxbase} 424 @category{threading} 425 426 @see wxThread, wxThreadEvent 427 */ 428 class wxThreadHelper 429 { 430 public: 431 /** 432 This constructor simply initializes internal member variables and tells 433 wxThreadHelper which type the thread internally managed should be. 434 */ 435 wxThreadHelper(wxThreadKind kind = wxTHREAD_JOINABLE); 436 437 /** 438 The destructor frees the resources associated with the thread, forcing 439 it to terminate (it uses wxThread::Kill function). 440 441 Because of the wxThread::Kill unsafety, you should always wait 442 (with wxThread::Wait) for joinable threads to end or call wxThread::Delete 443 on detached threads, instead of relying on this destructor for stopping 444 the thread. 445 */ 446 virtual ~wxThreadHelper(); 447 448 /** 449 This is the entry point of the thread. 450 451 This function is pure virtual and must be implemented by any derived class. 452 The thread execution will start here. 453 454 You'll typically want your Entry() to look like: 455 @code 456 wxThread::ExitCode Entry() 457 { 458 while (!GetThread()->TestDestroy()) 459 { 460 // ... do some work ... 461 462 if (IsWorkCompleted) 463 break; 464 465 if (HappenedStoppingError) 466 return (wxThread::ExitCode)1; // failure 467 } 468 469 return (wxThread::ExitCode)0; // success 470 } 471 @endcode 472 473 The returned value is the thread exit code which is only useful for 474 joinable threads and is the value returned by @c "GetThread()->Wait()". 475 476 This function is called by wxWidgets itself and should never be called 477 directly. 478 */ 479 virtual ExitCode Entry() = 0; 480 481 /** 482 Callback called by Delete() before actually deleting the thread. 483 484 This function can be overridden by the derived class to perform some 485 specific task when the thread is gracefully destroyed. Notice that it 486 will be executed in the context of the thread that called Delete() and 487 <b>not</b> in this thread's context. 488 489 TestDestroy() will be true for the thread before OnDelete() gets 490 executed. 491 492 @since 2.9.2 493 494 @see OnKill() 495 */ 496 virtual void OnDelete(); 497 498 /** 499 Callback called by Kill() before actually killing the thread. 500 501 This function can be overridden by the derived class to perform some 502 specific task when the thread is terminated. Notice that it will be 503 executed in the context of the thread that called Kill() and <b>not</b> 504 in this thread's context. 505 506 @since 2.9.2 507 508 @see OnDelete() 509 */ 510 virtual void OnKill(); 511 512 /** 513 @deprecated 514 Use CreateThread() instead. 515 */ 516 wxThreadError Create(unsigned int stackSize = 0); 517 518 /** 519 Creates a new thread of the given @a kind. 520 521 The thread object is created in the suspended state, and you 522 should call @ref wxThread::Run "GetThread()->Run()" to start running it. 523 524 You may optionally specify the stack size to be allocated to it (ignored 525 on platforms that don't support setting it explicitly, e.g. Unix). 526 527 @return One of the ::wxThreadError enum values. 528 */ 529 wxThreadError CreateThread(wxThreadKind kind = wxTHREAD_JOINABLE, 530 unsigned int stackSize = 0); 531 532 /** 533 This is a public function that returns the wxThread object associated with 534 the thread. 535 */ 536 wxThread* GetThread() const; 537 538 /** 539 Returns the last type of thread given to the CreateThread() function 540 or to the constructor. 541 */ 542 wxThreadKind GetThreadKind() const; 543 }; 544 545 /** 546 Possible critical section types 547 */ 548 549 enum wxCriticalSectionType 550 { 551 wxCRITSEC_DEFAULT, 552 /** Recursive critical section under both Windows and Unix */ 553 554 wxCRITSEC_NON_RECURSIVE 555 /** Non-recursive critical section under Unix, recursive under Windows */ 556 }; 557 558 /** 559 @class wxCriticalSection 560 561 A critical section object is used for exactly the same purpose as a wxMutex. 562 The only difference is that under Windows platform critical sections are only 563 visible inside one process, while mutexes may be shared among processes, 564 so using critical sections is slightly more efficient. 565 566 The terminology is also slightly different: mutex may be locked (or acquired) 567 and unlocked (or released) while critical section is entered and left by the program. 568 569 Finally, you should try to use wxCriticalSectionLocker class whenever 570 possible instead of directly using wxCriticalSection for the same reasons 571 wxMutexLocker is preferable to wxMutex - please see wxMutex for an example. 572 573 @library{wxbase} 574 @category{threading} 575 576 @note Critical sections can be used before the wxWidgets library is fully 577 initialized. In particular, it's safe to create global 578 wxCriticalSection instances. 579 580 @see wxThread, wxCondition, wxCriticalSectionLocker 581 */ 582 class wxCriticalSection 583 { 584 public: 585 /** 586 Default constructor initializes critical section object. 587 By default critical sections are recursive under Unix and Windows. 588 */ 589 wxCriticalSection( wxCriticalSectionType critSecType = wxCRITSEC_DEFAULT ); 590 591 /** 592 Destructor frees the resources. 593 */ 594 ~wxCriticalSection(); 595 596 /** 597 Enter the critical section (same as locking a mutex): if another thread 598 has already entered it, this call will block until the other thread 599 calls Leave(). 600 There is no error return for this function. 601 602 After entering the critical section protecting a data variable, 603 the thread running inside the critical section may safely use/modify it. 604 605 Note that entering the same critical section twice or more from the same 606 thread doesn't result in a deadlock; in this case in fact this function will 607 immediately return. 608 */ 609 void Enter(); 610 611 /** 612 Try to enter the critical section (same as trying to lock a mutex). 613 If it can't, immediately returns false. 614 615 @since 2.9.3 616 */ 617 bool TryEnter(); 618 619 /** 620 Leave the critical section allowing other threads use the global data 621 protected by it. There is no error return for this function. 622 */ 623 void Leave(); 624 }; 625 626 /** 627 The possible thread wait types. 628 629 @since 2.9.2 630 */ 631 enum wxThreadWait 632 { 633 /** 634 No events are processed while waiting. 635 636 This is the default under all platforms except for wxMSW. 637 */ 638 wxTHREAD_WAIT_BLOCK, 639 640 /** 641 Yield for event dispatching while waiting. 642 643 This flag is dangerous as it exposes the program using it to unexpected 644 reentrancies in the same way as calling wxYield() function does so you 645 are strongly advised to avoid its use and not wait for the thread 646 termination from the main (GUI) thread at all to avoid making your 647 application unresponsive. 648 649 Also notice that this flag is not portable as it is only implemented in 650 wxMSW and simply ignored under the other platforms. 651 */ 652 wxTHREAD_WAIT_YIELD, 653 654 /** 655 Default wait mode for wxThread::Wait() and wxThread::Delete(). 656 657 For compatibility reasons, the default wait mode is currently 658 wxTHREAD_WAIT_YIELD if WXWIN_COMPATIBILITY_2_8 is defined (and it is 659 by default). However, as mentioned above, you're strongly encouraged to 660 not use wxTHREAD_WAIT_YIELD and pass wxTHREAD_WAIT_BLOCK to wxThread 661 method explicitly. 662 */ 663 wxTHREAD_WAIT_DEFAULT = wxTHREAD_WAIT_YIELD 664 }; 665 666 /** 667 The possible thread kinds. 668 */ 669 enum wxThreadKind 670 { 671 /** Detached thread */ 672 wxTHREAD_DETACHED, 673 674 /** Joinable thread */ 675 wxTHREAD_JOINABLE 676 }; 677 678 /** 679 The possible thread errors. 680 */ 681 enum wxThreadError 682 { 683 /** No error */ 684 wxTHREAD_NO_ERROR = 0, 685 686 /** No resource left to create a new thread. */ 687 wxTHREAD_NO_RESOURCE, 688 689 /** The thread is already running. */ 690 wxTHREAD_RUNNING, 691 692 /** The thread isn't running. */ 693 wxTHREAD_NOT_RUNNING, 694 695 /** Thread we waited for had to be killed. */ 696 wxTHREAD_KILLED, 697 698 /** Some other error */ 699 wxTHREAD_MISC_ERROR 700 }; 701 702 /** 703 @class wxThread 704 705 A thread is basically a path of execution through a program. 706 Threads are sometimes called @e light-weight processes, but the fundamental difference 707 between threads and processes is that memory spaces of different processes are 708 separated while all threads share the same address space. 709 710 While it makes it much easier to share common data between several threads, it 711 also makes it much easier to shoot oneself in the foot, so careful use of 712 synchronization objects such as mutexes (see wxMutex) or critical sections 713 (see wxCriticalSection) is recommended. 714 In addition, don't create global thread objects because they allocate memory 715 in their constructor, which will cause problems for the memory checking system. 716 717 718 @section thread_types Types of wxThreads 719 720 There are two types of threads in wxWidgets: @e detached and @e joinable, 721 modeled after the POSIX thread API. This is different from the Win32 API 722 where all threads are joinable. 723 724 By default wxThreads in wxWidgets use the @b detached behaviour. 725 Detached threads delete themselves once they have completed, either by themselves 726 when they complete processing or through a call to Delete(), and thus 727 @b must be created on the heap (through the new operator, for example). 728 729 Typically you'll want to store the instances of the detached wxThreads you 730 allocate, so that you can call functions on them. 731 Because of their nature however you'll need to always use a critical section 732 when accessing them: 733 734 @code 735 // declare a new type of event, to be used by our MyThread class: 736 wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent); 737 wxDECLARE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent); 738 class MyFrame; 739 740 class MyThread : public wxThread 741 { 742 public: 743 MyThread(MyFrame *handler) 744 : wxThread(wxTHREAD_DETACHED) 745 { m_pHandler = handler } 746 ~MyThread(); 747 748 protected: 749 virtual ExitCode Entry(); 750 MyFrame *m_pHandler; 751 }; 752 753 class MyFrame : public wxFrame 754 { 755 public: 756 ... 757 ~MyFrame() 758 { 759 // it's better to do any thread cleanup in the OnClose() 760 // event handler, rather than in the destructor. 761 // This is because the event loop for a top-level window is not 762 // active anymore when its destructor is called and if the thread 763 // sends events when ending, they won't be processed unless 764 // you ended the thread from OnClose. 765 // See @ref overview_windowdeletion for more info. 766 } 767 ... 768 void DoStartThread(); 769 void DoPauseThread(); 770 771 // a resume routine would be nearly identic to DoPauseThread() 772 void DoResumeThread() { ... } 773 774 void OnThreadUpdate(wxThreadEvent&); 775 void OnThreadCompletion(wxThreadEvent&); 776 void OnClose(wxCloseEvent&); 777 778 protected: 779 MyThread *m_pThread; 780 wxCriticalSection m_pThreadCS; // protects the m_pThread pointer 781 782 wxDECLARE_EVENT_TABLE(); 783 }; 784 785 wxBEGIN_EVENT_TABLE(MyFrame, wxFrame) 786 EVT_CLOSE(MyFrame::OnClose) 787 EVT_MENU(Minimal_Start, MyFrame::DoStartThread) 788 EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_UPDATE, MyFrame::OnThreadUpdate) 789 EVT_COMMAND(wxID_ANY, wxEVT_COMMAND_MYTHREAD_COMPLETED, MyFrame::OnThreadCompletion) 790 wxEND_EVENT_TABLE() 791 792 wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_COMPLETED, wxThreadEvent) 793 wxDEFINE_EVENT(wxEVT_COMMAND_MYTHREAD_UPDATE, wxThreadEvent) 794 795 void MyFrame::DoStartThread() 796 { 797 m_pThread = new MyThread(this); 798 799 if ( m_pThread->Run() != wxTHREAD_NO_ERROR ) 800 { 801 wxLogError("Can't create the thread!"); 802 delete m_pThread; 803 m_pThread = NULL; 804 } 805 806 // after the call to wxThread::Run(), the m_pThread pointer is "unsafe": 807 // at any moment the thread may cease to exist (because it completes its work). 808 // To avoid dangling pointers OnThreadExit() will set m_pThread 809 // to NULL when the thread dies. 810 } 811 812 wxThread::ExitCode MyThread::Entry() 813 { 814 while (!TestDestroy()) 815 { 816 // ... do a bit of work... 817 818 wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_UPDATE)); 819 } 820 821 // signal the event handler that this thread is going to be destroyed 822 // NOTE: here we assume that using the m_pHandler pointer is safe, 823 // (in this case this is assured by the MyFrame destructor) 824 wxQueueEvent(m_pHandler, new wxThreadEvent(wxEVT_COMMAND_MYTHREAD_COMPLETED)); 825 826 return (wxThread::ExitCode)0; // success 827 } 828 829 MyThread::~MyThread() 830 { 831 wxCriticalSectionLocker enter(m_pHandler->m_pThreadCS); 832 833 // the thread is being destroyed; make sure not to leave dangling pointers around 834 m_pHandler->m_pThread = NULL; 835 } 836 837 void MyFrame::OnThreadCompletion(wxThreadEvent&) 838 { 839 wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n"); 840 } 841 842 void MyFrame::OnThreadUpdate(wxThreadEvent&) 843 { 844 wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n"); 845 } 846 847 void MyFrame::DoPauseThread() 848 { 849 // anytime we access the m_pThread pointer we must ensure that it won't 850 // be modified in the meanwhile; since only a single thread may be 851 // inside a given critical section at a given time, the following code 852 // is safe: 853 wxCriticalSectionLocker enter(m_pThreadCS); 854 855 if (m_pThread) // does the thread still exist? 856 { 857 // without a critical section, once reached this point it may happen 858 // that the OS scheduler gives control to the MyThread::Entry() function, 859 // which in turn may return (because it completes its work) making 860 // invalid the m_pThread pointer 861 862 if (m_pThread->Pause() != wxTHREAD_NO_ERROR ) 863 wxLogError("Can't pause the thread!"); 864 } 865 } 866 867 void MyFrame::OnClose(wxCloseEvent&) 868 { 869 { 870 wxCriticalSectionLocker enter(m_pThreadCS); 871 872 if (m_pThread) // does the thread still exist? 873 { 874 wxMessageOutputDebug().Printf("MYFRAME: deleting thread"); 875 876 if (m_pThread->Delete() != wxTHREAD_NO_ERROR ) 877 wxLogError("Can't delete the thread!"); 878 } 879 } // exit from the critical section to give the thread 880 // the possibility to enter its destructor 881 // (which is guarded with m_pThreadCS critical section!) 882 883 while (1) 884 { 885 { // was the ~MyThread() function executed? 886 wxCriticalSectionLocker enter(m_pThreadCS); 887 if (!m_pThread) break; 888 } 889 890 // wait for thread completion 891 wxThread::This()->Sleep(1); 892 } 893 894 Destroy(); 895 } 896 @endcode 897 898 For a more detailed and comprehensive example, see @sample{thread}. 899 For a simpler way to share data and synchronization objects between 900 the main and the secondary thread see wxThreadHelper. 901 902 Conversely, @b joinable threads do not delete themselves when they are done 903 processing and as such are safe to create on the stack. Joinable threads 904 also provide the ability for one to get value it returned from Entry() 905 through Wait(). 906 You shouldn't hurry to create all the threads joinable, however, because this 907 has a disadvantage as well: you @b must Wait() for a joinable thread or the 908 system resources used by it will never be freed, and you also must delete the 909 corresponding wxThread object yourself if you did not create it on the stack. 910 In contrast, detached threads are of the "fire-and-forget" kind: you only have 911 to start a detached thread and it will terminate and destroy itself. 912 913 914 @section thread_deletion wxThread Deletion 915 916 Regardless of whether it has terminated or not, you should call Wait() on a 917 @b joinable thread to release its memory, as outlined in @ref thread_types. 918 If you created a joinable thread on the heap, remember to delete it manually 919 with the @c delete operator or similar means as only detached threads handle 920 this type of memory management. 921 922 Since @b detached threads delete themselves when they are finished processing, 923 you should take care when calling a routine on one. If you are certain the 924 thread is still running and would like to end it, you may call Delete() 925 to gracefully end it (which implies that the thread will be deleted after 926 that call to Delete()). It should be implied that you should @b never attempt 927 to delete a detached thread with the @c delete operator or similar means. 928 929 As mentioned, Wait() or Delete() functions attempt to gracefully terminate a 930 joinable and a detached thread, respectively. They do this by waiting until 931 the thread in question calls TestDestroy() or ends processing (i.e. returns 932 from wxThread::Entry). 933 934 Obviously, if the thread does call TestDestroy() and does not end, the 935 thread which called Wait() or Delete() will come to halt. 936 This is why it's important to call TestDestroy() in the Entry() routine of 937 your threads as often as possible and immediately exit when it returns @true. 938 939 As a last resort you can end the thread immediately through Kill(). It is 940 strongly recommended that you do not do this, however, as it does not free 941 the resources associated with the object (although the wxThread object of 942 detached threads will still be deleted) and could leave the C runtime 943 library in an undefined state. 944 945 946 @section thread_secondary wxWidgets Calls in Secondary Threads 947 948 All threads other than the "main application thread" (the one running 949 wxApp::OnInit() or the one your main function runs in, for example) are 950 considered "secondary threads". 951 952 GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe 953 at all in secondary threads and could end your application prematurely. 954 This is due to several reasons, including the underlying native API and 955 the fact that wxThread does not run a GUI event loop similar to other APIs 956 as MFC. 957 958 A workaround for some wxWidgets ports is calling wxMutexGUIEnter() 959 before any GUI calls and then calling wxMutexGUILeave() afterwords. 960 However, the recommended way is to simply process the GUI calls in the main 961 thread through an event that is posted by wxQueueEvent(). 962 This does not imply that calls to these classes are thread-safe, however, 963 as most wxWidgets classes are not thread-safe, including wxString. 964 965 966 @section thread_poll Don't Poll a wxThread 967 968 A common problem users experience with wxThread is that in their main thread 969 they will check the thread every now and then to see if it has ended through 970 IsRunning(), only to find that their application has run into problems 971 because the thread is using the default behaviour (i.e. it's @b detached) and 972 has already deleted itself. 973 Naturally, they instead attempt to use joinable threads in place of the previous 974 behaviour. However, polling a wxThread for when it has ended is in general a 975 bad idea - in fact calling a routine on any running wxThread should be avoided 976 if possible. Instead, find a way to notify yourself when the thread has ended. 977 978 Usually you only need to notify the main thread, in which case you can 979 post an event to it via wxQueueEvent(). 980 In the case of secondary threads you can call a routine of another class 981 when the thread is about to complete processing and/or set the value of 982 a variable, possibly using mutexes (see wxMutex) and/or other synchronization 983 means if necessary. 984 985 @library{wxbase} 986 @category{threading} 987 988 @see wxThreadHelper, wxMutex, wxCondition, wxCriticalSection, 989 @ref overview_thread 990 */ 991 class wxThread 992 { 993 public: 994 /** 995 The return type for the thread functions. 996 */ 997 typedef void* ExitCode; 998 999 /** 1000 This constructor creates a new detached (default) or joinable C++ 1001 thread object. It does not create or start execution of the real thread - 1002 for this you should use the Run() method. 1003 1004 The possible values for @a kind parameters are: 1005 - @b wxTHREAD_DETACHED - Creates a detached thread. 1006 - @b wxTHREAD_JOINABLE - Creates a joinable thread. 1007 */ 1008 wxThread(wxThreadKind kind = wxTHREAD_DETACHED); 1009 1010 /** 1011 The destructor frees the resources associated with the thread. 1012 Notice that you should never delete a detached thread -- you may only call 1013 Delete() on it or wait until it terminates (and auto destructs) itself. 1014 1015 Because the detached threads delete themselves, they can only be allocated on the heap. 1016 Joinable threads should be deleted explicitly. The Delete() and Kill() functions 1017 will not delete the C++ thread object. It is also safe to allocate them on stack. 1018 */ 1019 virtual ~wxThread(); 1020 1021 /** 1022 Creates a new thread. 1023 1024 The thread object is created in the suspended state, and you should call Run() 1025 to start running it. You may optionally specify the stack size to be allocated 1026 to it (Ignored on platforms that don't support setting it explicitly, 1027 eg. Unix system without @c pthread_attr_setstacksize). 1028 1029 If you do not specify the stack size, the system's default value is used. 1030 1031 @note 1032 It is not necessary to call this method since 2.9.5, Run() will create 1033 the thread internally. You only need to call Create() if you need to do 1034 something with the thread (e.g. pass its ID to an external library) 1035 before it starts. 1036 1037 @warning 1038 It is a good idea to explicitly specify a value as systems' 1039 default values vary from just a couple of KB on some systems (BSD and 1040 OS/2 systems) to one or several MB (Windows, Solaris, Linux). 1041 So, if you have a thread that requires more than just a few KB of memory, you 1042 will have mysterious problems on some platforms but not on the common ones. 1043 On the other hand, just indicating a large stack size by default will give you 1044 performance issues on those systems with small default stack since those 1045 typically use fully committed memory for the stack. 1046 On the contrary, if you use a lot of threads (say several hundred), 1047 virtual address space can get tight unless you explicitly specify a 1048 smaller amount of thread stack space for each thread. 1049 1050 @return One of: 1051 - @b wxTHREAD_NO_ERROR - No error. 1052 - @b wxTHREAD_NO_RESOURCE - There were insufficient resources to create the thread. 1053 - @b wxTHREAD_NO_RUNNING - The thread is already running 1054 */ 1055 wxThreadError Create(unsigned int stackSize = 0); 1056 1057 /** 1058 Calling Delete() gracefully terminates a @b detached thread, either when 1059 the thread calls TestDestroy() or when it finishes processing. 1060 1061 @param rc 1062 The thread exit code, if rc is not NULL. 1063 1064 @param waitMode 1065 As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK 1066 should be used as the wait mode even although currently 1067 wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is 1068 new in wxWidgets 2.9.2. 1069 1070 @note 1071 This function works on a joinable thread but in that case makes 1072 the TestDestroy() function of the thread return @true and then 1073 waits for its completion (i.e. it differs from Wait() because 1074 it asks the thread to terminate before waiting). 1075 1076 See @ref thread_deletion for a broader explanation of this routine. 1077 */ 1078 wxThreadError Delete(ExitCode *rc = NULL, 1079 wxThreadWait waitMode = wxTHREAD_WAIT_DEFAULT); 1080 1081 /** 1082 Returns the number of system CPUs or -1 if the value is unknown. 1083 1084 For multi-core systems the returned value is typically the total number 1085 of @e cores, since the OS usually abstract a single N-core CPU 1086 as N different cores. 1087 1088 @see SetConcurrency() 1089 */ 1090 static int GetCPUCount(); 1091 1092 /** 1093 Returns the platform specific thread ID of the current thread as a long. 1094 1095 This can be used to uniquely identify threads, even if they are not wxThreads. 1096 1097 @see GetMainId() 1098 */ 1099 static wxThreadIdType GetCurrentId(); 1100 1101 /** 1102 Gets the thread identifier: this is a platform dependent number that uniquely 1103 identifies the thread throughout the system during its existence 1104 (i.e.\ the thread identifiers may be reused). 1105 */ 1106 wxThreadIdType GetId() const; 1107 1108 /** 1109 Returns the thread kind as it was given in the ctor. 1110 1111 @since 2.9.0 1112 */ 1113 wxThreadKind GetKind() const; 1114 1115 /** 1116 Returns the thread ID of the main thread. 1117 1118 @see IsMain() 1119 1120 @since 2.9.1 1121 */ 1122 static wxThreadIdType GetMainId(); 1123 1124 /** 1125 Gets the priority of the thread, between 0 (lowest) and 100 (highest). 1126 1127 @see SetPriority() 1128 */ 1129 unsigned int GetPriority() const; 1130 1131 /** 1132 Returns @true if the thread is alive (i.e.\ started and not terminating). 1133 1134 Note that this function can only safely be used with joinable threads, not 1135 detached ones as the latter delete themselves and so when the real thread is 1136 no longer alive, it is not possible to call this function because 1137 the wxThread object no longer exists. 1138 */ 1139 bool IsAlive() const; 1140 1141 /** 1142 Returns @true if the thread is of the detached kind, @false if it is a 1143 joinable one. 1144 */ 1145 bool IsDetached() const; 1146 1147 /** 1148 Returns @true if the calling thread is the main application thread. 1149 1150 Main thread in the context of wxWidgets is the one which initialized 1151 the library. 1152 1153 @see GetMainId(), GetCurrentId() 1154 */ 1155 static bool IsMain(); 1156 1157 /** 1158 Returns @true if the thread is paused. 1159 */ 1160 bool IsPaused() const; 1161 1162 /** 1163 Returns @true if the thread is running. 1164 1165 This method may only be safely used for joinable threads, see the remark in 1166 IsAlive(). 1167 */ 1168 bool IsRunning() const; 1169 1170 /** 1171 Immediately terminates the target thread. 1172 1173 @b "This function is dangerous and should be used with extreme care" 1174 (and not used at all whenever possible)! The resources allocated to the 1175 thread will not be freed and the state of the C runtime library may become 1176 inconsistent. Use Delete() for detached threads or Wait() for joinable 1177 threads instead. 1178 1179 For detached threads Kill() will also delete the associated C++ object. 1180 However this will not happen for joinable threads and this means that you will 1181 still have to delete the wxThread object yourself to avoid memory leaks. 1182 1183 In neither case OnExit() of the dying thread will be called, so no 1184 thread-specific cleanup will be performed. 1185 This function can only be called from another thread context, i.e. a thread 1186 cannot kill itself. 1187 1188 It is also an error to call this function for a thread which is not running or 1189 paused (in the latter case, the thread will be resumed first) -- if you do it, 1190 a @b wxTHREAD_NOT_RUNNING error will be returned. 1191 */ 1192 wxThreadError Kill(); 1193 1194 /** 1195 Suspends the thread. 1196 1197 Under some implementations (Win32), the thread is suspended immediately, 1198 under others it will only be suspended when it calls TestDestroy() for 1199 the next time (hence, if the thread doesn't call it at all, it won't be 1200 suspended). 1201 1202 This function can only be called from another thread context. 1203 */ 1204 wxThreadError Pause(); 1205 1206 /** 1207 Resumes a thread suspended by the call to Pause(). 1208 1209 This function can only be called from another thread context. 1210 */ 1211 wxThreadError Resume(); 1212 1213 /** 1214 Starts the thread execution. 1215 1216 Note that once you Run() a @b detached thread, @e any function call you do 1217 on the thread pointer (you must allocate it on the heap) is @e "unsafe"; 1218 i.e. the thread may have terminated at any moment after Run() and your pointer 1219 may be dangling. See @ref thread_types for an example of safe manipulation 1220 of detached threads. 1221 1222 This function can only be called from another thread context. 1223 1224 Finally, note that once a thread has completed and its Entry() function 1225 returns, you cannot call Run() on it again (an assert will fail in debug 1226 builds or @c wxTHREAD_RUNNING will be returned in release builds). 1227 */ 1228 wxThreadError Run(); 1229 1230 /** 1231 Sets the thread concurrency level for this process. 1232 1233 This is, roughly, the number of threads that the system tries to schedule 1234 to run in parallel. 1235 The value of 0 for @a level may be used to set the default one. 1236 1237 @return @true on success or @false otherwise (for example, if this function is 1238 not implemented for this platform -- currently everything except Solaris). 1239 */ 1240 static bool SetConcurrency(size_t level); 1241 1242 /** 1243 Sets the priority of the thread, between 0 (lowest) and 100 (highest). 1244 1245 The following symbolic constants can be used in addition to raw 1246 values in 0..100 range: 1247 - @c wxPRIORITY_MIN: 0 1248 - @c wxPRIORITY_DEFAULT: 50 1249 - @c wxPRIORITY_MAX: 100 1250 1251 Notice that in the MSW implementation the thread priority can currently 1252 be only set after creating the thread with CreateThread(). But under 1253 all platforms this method can be called either before launching the 1254 thread using Run() or after doing it. 1255 1256 Please note that currently this function is not implemented when using 1257 the default (@c SCHED_OTHER) scheduling policy under POSIX systems. 1258 */ 1259 void SetPriority(unsigned int priority); 1260 1261 /** 1262 Pauses the thread execution for the given amount of time. 1263 1264 This is the same as wxMilliSleep(). 1265 */ 1266 static void Sleep(unsigned long milliseconds); 1267 1268 /** 1269 This function should be called periodically by the thread to ensure that 1270 calls to Pause() and Delete() will work. 1271 1272 If it returns @true, the thread should exit as soon as possible. 1273 Notice that under some platforms (POSIX), implementation of Pause() also 1274 relies on this function being called, so not calling it would prevent 1275 both stopping and suspending thread from working. 1276 */ 1277 virtual bool TestDestroy(); 1278 1279 /** 1280 Return the thread object for the calling thread. 1281 1282 @NULL is returned if the calling thread is the main (GUI) thread, but 1283 IsMain() should be used to test whether the thread is really the main one 1284 because @NULL may also be returned for the thread not created with wxThread 1285 class. Generally speaking, the return value for such a thread is undefined. 1286 */ 1287 static wxThread* This(); 1288 1289 /** 1290 Waits for a @b joinable thread to terminate and returns the value the thread 1291 returned from Entry() or @c "(ExitCode)-1" on error. Notice that, unlike 1292 Delete(), this function doesn't cancel the thread in any way so the caller 1293 waits for as long as it takes to the thread to exit. 1294 1295 You can only Wait() for @b joinable (not detached) threads. 1296 1297 This function can only be called from another thread context. 1298 1299 @param flags 1300 As described in wxThreadWait documentation, wxTHREAD_WAIT_BLOCK 1301 should be used as the wait mode even although currently 1302 wxTHREAD_WAIT_YIELD is for compatibility reasons. This parameter is 1303 new in wxWidgets 2.9.2. 1304 1305 See @ref thread_deletion for a broader explanation of this routine. 1306 */ 1307 ExitCode Wait(wxThreadWait flags = wxTHREAD_WAIT_BLOCK); 1308 1309 /** 1310 Give the rest of the thread's time-slice to the system allowing the other 1311 threads to run. 1312 1313 Note that using this function is @b strongly discouraged, since in 1314 many cases it indicates a design weakness of your threading model 1315 (as does using Sleep() functions). 1316 1317 Threads should use the CPU in an efficient manner, i.e. they should 1318 do their current work efficiently, then as soon as the work is done block 1319 on a wakeup event (wxCondition, wxMutex, select(), poll(), ...) which will 1320 get signalled e.g. by other threads or a user device once further thread 1321 work is available. 1322 Using Yield() or Sleep() indicates polling-type behaviour, since we're 1323 fuzzily giving up our timeslice and wait until sometime later we'll get 1324 reactivated, at which time we realize that there isn't really much to do 1325 and Yield() again... 1326 1327 The most critical characteristic of Yield() is that it's operating system 1328 specific: there may be scheduler changes which cause your thread to not 1329 wake up relatively soon again, but instead many seconds later, 1330 causing huge performance issues for your application. 1331 1332 <strong> 1333 With a well-behaving, CPU-efficient thread the operating system is likely 1334 to properly care for its reactivation the moment it needs it, whereas with 1335 non-deterministic, Yield-using threads all bets are off and the system 1336 scheduler is free to penalize them drastically</strong>, and this effect 1337 gets worse with increasing system load due to less free CPU resources available. 1338 You may refer to various Linux kernel @c sched_yield discussions for more 1339 information. 1340 1341 See also Sleep(). 1342 */ 1343 static void Yield(); 1344 1345 protected: 1346 1347 /** 1348 This is the entry point of the thread. 1349 1350 This function is pure virtual and must be implemented by any derived class. 1351 The thread execution will start here. 1352 1353 The returned value is the thread exit code which is only useful for 1354 joinable threads and is the value returned by Wait(). 1355 This function is called by wxWidgets itself and should never be called 1356 directly. 1357 */ 1358 virtual ExitCode Entry() = 0; 1359 1360 /** 1361 This is a protected function of the wxThread class and thus can only be called 1362 from a derived class. It also can only be called in the context of this 1363 thread, i.e. a thread can only exit from itself, not from another thread. 1364 1365 This function will terminate the OS thread (i.e. stop the associated path of 1366 execution) and also delete the associated C++ object for detached threads. 1367 OnExit() will be called just before exiting. 1368 */ 1369 void Exit(ExitCode exitcode = 0); 1370 1371 private: 1372 1373 /** 1374 Called when the thread exits. 1375 1376 This function is called in the context of the thread associated with the 1377 wxThread object, not in the context of the main thread. 1378 This function will not be called if the thread was @ref Kill() killed. 1379 1380 This function should never be called directly. 1381 */ 1382 virtual void OnExit(); 1383 }; 1384 1385 1386 /** See wxSemaphore. */ 1387 enum wxSemaError 1388 { 1389 wxSEMA_NO_ERROR = 0, 1390 wxSEMA_INVALID, //!< semaphore hasn't been initialized successfully 1391 wxSEMA_BUSY, //!< returned by TryWait() if Wait() would block 1392 wxSEMA_TIMEOUT, //!< returned by WaitTimeout() 1393 wxSEMA_OVERFLOW, //!< Post() would increase counter past the max 1394 wxSEMA_MISC_ERROR 1395 }; 1396 1397 /** 1398 @class wxSemaphore 1399 1400 wxSemaphore is a counter limiting the number of threads concurrently accessing 1401 a shared resource. This counter is always between 0 and the maximum value 1402 specified during the semaphore creation. When the counter is strictly greater 1403 than 0, a call to wxSemaphore::Wait() returns immediately and decrements the 1404 counter. As soon as it reaches 0, any subsequent calls to wxSemaphore::Wait 1405 block and only return when the semaphore counter becomes strictly positive 1406 again as the result of calling wxSemaphore::Post which increments the counter. 1407 1408 In general, semaphores are useful to restrict access to a shared resource 1409 which can only be accessed by some fixed number of clients at the same time. 1410 For example, when modeling a hotel reservation system a semaphore with the counter 1411 equal to the total number of available rooms could be created. Each time a room 1412 is reserved, the semaphore should be acquired by calling wxSemaphore::Wait 1413 and each time a room is freed it should be released by calling wxSemaphore::Post. 1414 1415 @library{wxbase} 1416 @category{threading} 1417 */ 1418 class wxSemaphore 1419 { 1420 public: 1421 /** 1422 Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if 1423 there is no upper limit. If @a maxcount is 1, the semaphore behaves almost as a 1424 mutex (but unlike a mutex it can be released by a thread different from the one 1425 which acquired it). 1426 1427 @a initialcount is the initial value of the semaphore which must be between 1428 0 and @a maxcount (if it is not set to 0). 1429 */ 1430 wxSemaphore(int initialcount = 0, int maxcount = 0); 1431 1432 /** 1433 Destructor is not virtual, don't use this class polymorphically. 1434 */ 1435 ~wxSemaphore(); 1436 1437 /** 1438 Increments the semaphore count and signals one of the waiting 1439 threads in an atomic way. Returns @e wxSEMA_OVERFLOW if the count 1440 would increase the counter past the maximum. 1441 1442 @return One of: 1443 - wxSEMA_NO_ERROR: There was no error. 1444 - wxSEMA_INVALID : Semaphore hasn't been initialized successfully. 1445 - wxSEMA_OVERFLOW: Post() would increase counter past the max. 1446 - wxSEMA_MISC_ERROR: Miscellaneous error. 1447 */ 1448 wxSemaError Post(); 1449 1450 /** 1451 Same as Wait(), but returns immediately. 1452 1453 @return One of: 1454 - wxSEMA_NO_ERROR: There was no error. 1455 - wxSEMA_INVALID: Semaphore hasn't been initialized successfully. 1456 - wxSEMA_BUSY: Returned by TryWait() if Wait() would block, i.e. the count is zero. 1457 - wxSEMA_MISC_ERROR: Miscellaneous error. 1458 */ 1459 wxSemaError TryWait(); 1460 1461 /** 1462 Wait indefinitely until the semaphore count becomes strictly positive 1463 and then decrement it and return. 1464 1465 @return One of: 1466 - wxSEMA_NO_ERROR: There was no error. 1467 - wxSEMA_INVALID: Semaphore hasn't been initialized successfully. 1468 - wxSEMA_MISC_ERROR: Miscellaneous error. 1469 */ 1470 wxSemaError Wait(); 1471 1472 /** 1473 Same as Wait(), but with a timeout limit. 1474 1475 @return One of: 1476 - wxSEMA_NO_ERROR: There was no error. 1477 - wxSEMA_INVALID: Semaphore hasn't been initialized successfully. 1478 - wxSEMA_TIMEOUT: Timeout occurred without receiving semaphore. 1479 - wxSEMA_MISC_ERROR: Miscellaneous error. 1480 */ 1481 wxSemaError WaitTimeout(unsigned long timeout_millis); 1482 }; 1483 1484 1485 1486 /** 1487 @class wxMutexLocker 1488 1489 This is a small helper class to be used with wxMutex objects. 1490 1491 A wxMutexLocker acquires a mutex lock in the constructor and releases 1492 (or unlocks) the mutex in the destructor making it much more difficult to 1493 forget to release a mutex (which, in general, will promptly lead to serious 1494 problems). See wxMutex for an example of wxMutexLocker usage. 1495 1496 @library{wxbase} 1497 @category{threading} 1498 1499 @see wxMutex, wxCriticalSectionLocker 1500 */ 1501 class wxMutexLocker 1502 { 1503 public: 1504 /** 1505 Constructs a wxMutexLocker object associated with mutex and locks it. 1506 Call IsOk() to check if the mutex was successfully locked. 1507 */ 1508 wxMutexLocker(wxMutex& mutex); 1509 1510 /** 1511 Destructor releases the mutex if it was successfully acquired in the ctor. 1512 */ 1513 ~wxMutexLocker(); 1514 1515 /** 1516 Returns @true if mutex was acquired in the constructor, @false otherwise. 1517 */ 1518 bool IsOk() const; 1519 }; 1520 1521 1522 /** 1523 The possible wxMutex kinds. 1524 */ 1525 enum wxMutexType 1526 { 1527 /** Normal non-recursive mutex: try to always use this one. */ 1528 wxMUTEX_DEFAULT, 1529 1530 /** Recursive mutex: don't use these ones with wxCondition. */ 1531 wxMUTEX_RECURSIVE 1532 }; 1533 1534 1535 /** 1536 The possible wxMutex errors. 1537 */ 1538 enum wxMutexError 1539 { 1540 /** The operation completed successfully. */ 1541 wxMUTEX_NO_ERROR = 0, 1542 1543 /** The mutex hasn't been initialized. */ 1544 wxMUTEX_INVALID, 1545 1546 /** The mutex is already locked by the calling thread. */ 1547 wxMUTEX_DEAD_LOCK, 1548 1549 /** The mutex is already locked by another thread. */ 1550 wxMUTEX_BUSY, 1551 1552 /** An attempt to unlock a mutex which is not locked. */ 1553 wxMUTEX_UNLOCKED, 1554 1555 /** wxMutex::LockTimeout() has timed out. */ 1556 wxMUTEX_TIMEOUT, 1557 1558 /** Any other error */ 1559 wxMUTEX_MISC_ERROR 1560 }; 1561 1562 1563 /** 1564 @class wxMutex 1565 1566 A mutex object is a synchronization object whose state is set to signaled when 1567 it is not owned by any thread, and nonsignaled when it is owned. Its name comes 1568 from its usefulness in coordinating mutually-exclusive access to a shared 1569 resource as only one thread at a time can own a mutex object. 1570 1571 Mutexes may be recursive in the sense that a thread can lock a mutex which it 1572 had already locked before (instead of dead locking the entire process in this 1573 situation by starting to wait on a mutex which will never be released while the 1574 thread is waiting) but using them is not recommended under Unix and they are 1575 @b not recursive by default. The reason for this is that recursive 1576 mutexes are not supported by all Unix flavours and, worse, they cannot be used 1577 with wxCondition. 1578 1579 For example, when several threads use the data stored in the linked list, 1580 modifications to the list should only be allowed to one thread at a time 1581 because during a new node addition the list integrity is temporarily broken 1582 (this is also called @e program @e invariant). 1583 1584 @code 1585 // this variable has an "s_" prefix because it is static: seeing an "s_" in 1586 // a multithreaded program is in general a good sign that you should use a 1587 // mutex (or a critical section) 1588 static wxMutex *s_mutexProtectingTheGlobalData; 1589 1590 // we store some numbers in this global array which is presumably used by 1591 // several threads simultaneously 1592 wxArrayInt s_data; 1593 1594 void MyThread::AddNewNode(int num) 1595 { 1596 // ensure that no other thread accesses the list 1597 s_mutexProtectingTheGlobalList->Lock(); 1598 1599 s_data.Add(num); 1600 1601 s_mutexProtectingTheGlobalList->Unlock(); 1602 } 1603 1604 // return true if the given number is greater than all array elements 1605 bool MyThread::IsGreater(int num) 1606 { 1607 // before using the list we must acquire the mutex 1608 wxMutexLocker lock(s_mutexProtectingTheGlobalData); 1609 1610 size_t count = s_data.Count(); 1611 for ( size_t n = 0; n < count; n++ ) 1612 { 1613 if ( s_data[n] > num ) 1614 return false; 1615 } 1616 1617 return true; 1618 } 1619 @endcode 1620 1621 Notice how wxMutexLocker was used in the second function to ensure that the 1622 mutex is unlocked in any case: whether the function returns true or false 1623 (because the destructor of the local object @e lock is always called). 1624 Using this class instead of directly using wxMutex is, in general, safer 1625 and is even more so if your program uses C++ exceptions. 1626 1627 @library{wxbase} 1628 @category{threading} 1629 1630 @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection 1631 */ 1632 class wxMutex 1633 { 1634 public: 1635 /** 1636 Default constructor. 1637 */ 1638 wxMutex(wxMutexType type = wxMUTEX_DEFAULT); 1639 1640 /** 1641 Destroys the wxMutex object. 1642 */ 1643 ~wxMutex(); 1644 1645 /** 1646 Locks the mutex object. 1647 This is equivalent to LockTimeout() with infinite timeout. 1648 1649 Note that if this mutex is already locked by the caller thread, 1650 this function doesn't block but rather immediately returns. 1651 1652 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK. 1653 */ 1654 wxMutexError Lock(); 1655 1656 /** 1657 Try to lock the mutex object during the specified time interval. 1658 1659 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK, @c wxMUTEX_TIMEOUT. 1660 */ 1661 wxMutexError LockTimeout(unsigned long msec); 1662 1663 /** 1664 Tries to lock the mutex object. If it can't, returns immediately with an error. 1665 1666 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_BUSY. 1667 */ 1668 wxMutexError TryLock(); 1669 1670 /** 1671 Unlocks the mutex object. 1672 1673 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_UNLOCKED. 1674 */ 1675 wxMutexError Unlock(); 1676 }; 1677 1678 1679 1680 // ============================================================================ 1681 // Global functions/macros 1682 // ============================================================================ 1683 1684 /** @addtogroup group_funcmacro_thread */ 1685 //@{ 1686 1687 /** 1688 This macro declares a (static) critical section object named @a cs if 1689 @c wxUSE_THREADS is 1 and does nothing if it is 0. 1690 1691 @header{wx/thread.h} 1692 */ 1693 #define wxCRIT_SECT_DECLARE(cs) 1694 1695 /** 1696 This macro declares a critical section object named @a cs if 1697 @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include 1698 the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to 1699 declare a class or struct member which explains its name. 1700 1701 @header{wx/thread.h} 1702 */ 1703 #define wxCRIT_SECT_DECLARE_MEMBER(cs) 1704 1705 /** 1706 This macro creates a wxCriticalSectionLocker named @a name and associated 1707 with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing 1708 if it is 0. 1709 1710 @header{wx/thread.h} 1711 */ 1712 #define wxCRIT_SECT_LOCKER(name, cs) 1713 1714 /** 1715 This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it 1716 creates a static critical section object and also the lock object 1717 associated with it. Because of this, it can be only used inside a function, 1718 not at global scope. For example: 1719 1720 @code 1721 int IncCount() 1722 { 1723 static int s_counter = 0; 1724 1725 wxCRITICAL_SECTION(counter); 1726 1727 return ++s_counter; 1728 } 1729 @endcode 1730 1731 Note that this example assumes that the function is called the first time 1732 from the main thread so that the critical section object is initialized 1733 correctly by the time other threads start calling it, if this is not the 1734 case this approach can @b not be used and the critical section must be made 1735 a global instead. 1736 1737 @header{wx/thread.h} 1738 */ 1739 #define wxCRITICAL_SECTION(name) 1740 1741 /** 1742 This macro is equivalent to 1743 @ref wxCriticalSection::Leave "critical_section.Leave()" if 1744 @c wxUSE_THREADS is 1 and does nothing if it is 0. 1745 1746 @header{wx/thread.h} 1747 */ 1748 #define wxLEAVE_CRIT_SECT(critical_section) 1749 1750 /** 1751 This macro is equivalent to 1752 @ref wxCriticalSection::Enter "critical_section.Enter()" if 1753 @c wxUSE_THREADS is 1 and does nothing if it is 0. 1754 1755 @header{wx/thread.h} 1756 */ 1757 #define wxENTER_CRIT_SECT(critical_section) 1758 1759 /** 1760 Returns @true if this thread is the main one. Always returns @true if 1761 @c wxUSE_THREADS is 0. 1762 1763 @header{wx/thread.h} 1764 */ 1765 bool wxIsMainThread(); 1766 1767 1768 1769 /** 1770 This function must be called when any thread other than the main GUI thread 1771 wants to get access to the GUI library. This function will block the 1772 execution of the calling thread until the main thread (or any other thread 1773 holding the main GUI lock) leaves the GUI library and no other thread will 1774 enter the GUI library until the calling thread calls wxMutexGuiLeave(). 1775 1776 Typically, these functions are used like this: 1777 1778 @code 1779 void MyThread::Foo(void) 1780 { 1781 // before doing any GUI calls we must ensure that 1782 // this thread is the only one doing it! 1783 1784 wxMutexGuiEnter(); 1785 1786 // Call GUI here: 1787 my_window->DrawSomething(); 1788 1789 wxMutexGuiLeave(); 1790 } 1791 @endcode 1792 1793 This function is only defined on platforms which support preemptive 1794 threads and only works under some ports (wxMSW currently). 1795 1796 @note Under GTK, no creation of top-level windows is allowed in any thread 1797 but the main one. 1798 1799 @header{wx/thread.h} 1800 */ 1801 void wxMutexGuiEnter(); 1802 1803 /** 1804 This function is only defined on platforms which support preemptive 1805 threads. 1806 1807 @see wxMutexGuiEnter() 1808 1809 @header{wx/thread.h} 1810 */ 1811 void wxMutexGuiLeave(); 1812 1813 //@} 1814 1815