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