1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of all thread-related wxWidgets classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 /** See wxCondition. */
15 wxCOND_TIMEOUT
, //!< WaitTimeout() has timed out
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.
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).
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.
41 @section condition_example Example
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:
47 class MySignallingThread : public wxThread
50 MySignallingThread(wxMutex *mutex, wxCondition *condition)
53 m_condition = condition;
58 virtual ExitCode Entry()
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
72 wxCondition *m_condition;
79 wxCondition condition(mutex);
81 // the mutex should be initially locked
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);
90 // wait for the thread termination: Wait() atomically unlocks the mutex
91 // which allows the thread to continue and starts waiting
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.
106 @see wxThread, wxMutex
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.
116 wxCondition(wxMutex
& mutex
);
119 Destroys the wxCondition object.
121 The destructor is not virtual so this class should not be used polymorphically.
126 Broadcasts to all waiting threads, waking all of them up.
128 Note that this method may be called whether the mutex associated with
129 this condition is locked or not.
133 wxCondError
Broadcast();
136 Returns @true if the object had been initialized successfully, @false
137 if an error occurred.
142 Signals the object waking up at most one thread.
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.
149 Note that this method may be called whether the mutex associated with this
150 condition is locked or not.
154 wxCondError
Signal();
157 Waits until the condition is signalled.
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.
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.
169 @return Returns wxCOND_NO_ERROR on success, another value if an error occurred.
176 Waits until the condition is signalled or the timeout has elapsed.
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.
182 Timeout in milliseconds
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.
188 wxCondError
WaitTimeout(unsigned long milliseconds
);
193 @class wxCriticalSectionLocker
195 This is a small helper class to be used with wxCriticalSection objects.
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
207 // gs_critSect is some (global) critical section guarding access to the
209 wxCriticalSectionLocker locker(gs_critSect);
226 Without wxCriticalSectionLocker, you would need to remember to manually leave
227 the critical section before each @c return.
232 @see wxCriticalSection, wxMutexLocker
234 class wxCriticalSectionLocker
238 Constructs a wxCriticalSectionLocker object associated with given
239 @a criticalsection and enters it.
241 wxCriticalSectionLocker(wxCriticalSection
& criticalsection
);
244 Destructor leaves the critical section.
246 ~wxCriticalSectionLocker();
252 @class wxThreadHelper
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.
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.
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.
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.
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
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
282 extern const wxEventType wxEVT_COMMAND_MYTHREAD_UPDATE;
284 class MyFrame : public wxFrame, public wxThreadHelper
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.
300 void DoStartALongTask();
301 void OnThreadUpdate(wxCommandEvent& evt);
302 void OnClose(wxCloseEvent& evt);
306 virtual wxThread::ExitCode Entry();
308 // the output data of the Entry() routine:
310 wxCriticalSection m_dataCS; // protects field above
312 DECLARE_EVENT_TABLE()
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)
321 void MyFrame::DoStartALongTask()
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)
327 wxLogError("Could not create the worker thread!");
332 if (GetThread()->Run() != wxTHREAD_NO_ERROR)
334 wxLogError("Could not run the worker thread!");
339 wxThread::ExitCode MyFrame::Entry()
342 // this function gets executed in the secondary thread context!
346 // here we do our long task, periodically calling TestDestroy():
347 while (!GetThread()->TestDestroy())
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!
353 // this is an example of the generic structure of a download thread:
355 download_chunk(buffer, 1024); // this takes time...
358 // ensure noone reads m_data while we write it
359 wxCriticalSectionLocker lock(m_dataCS);
360 memcpy(m_data+offset, buffer, 1024);
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()
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;
376 void MyFrame::OnClose(wxCloseEvent&)
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
382 if (GetThread() && // DoStartALongTask() may have not been called
383 GetThread()->IsRunning())
389 void MyFrame::OnThreadUpdate(wxCommandEvent&evt)
391 // ...do something... e.g. m_pGauge->Pulse();
393 // read some parts of m_data just for fun:
394 wxCriticalSectionLocker lock(m_dataCS);
395 wxPrintf("%c", m_data[100]);
408 This constructor simply initializes internal member variables and tells
409 wxThreadHelper which type the thread internally managed should be.
411 wxThreadHelper(wxThreadKind kind
= wxTHREAD_JOINABLE
);
414 The destructor frees the resources associated with the thread, forcing
415 it to terminate (it uses wxThread::Kill function).
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
422 virtual ~wxThreadHelper();
425 This is the entry point of the thread.
427 This function is pure virtual and must be implemented by any derived class.
428 The thread execution will start here.
430 You'll typically want your Entry() to look like:
432 wxThread::ExitCode Entry()
434 while (!GetThread()->TestDestroy())
436 // ... do some work ...
441 if (HappenedStoppingError)
442 return (wxThread::ExitCode)1; // failure
445 return (wxThread::ExitCode)0; // success
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()".
452 This function is called by wxWidgets itself and should never be called
455 virtual ExitCode
Entry() = 0;
459 Use CreateThread() instead.
461 wxThreadError
Create(unsigned int stackSize
= 0);
464 Creates a new thread of the given @a kind.
466 The thread object is created in the suspended state, and you
467 should call @ref wxThread::Run "GetThread()->Run()" to start running it.
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).
472 @return One of the ::wxThreadError enum values.
474 wxThreadError
CreateThread(wxThreadKind kind
= wxTHREAD_JOINABLE
,
475 unsigned int stackSize
= 0);
478 This is a public function that returns the wxThread object associated with
481 wxThread
* GetThread() const;
484 Returns the last type of thread given to the CreateThread() function
485 or to the constructor.
487 wxThreadKind
GetThreadKind() const;
491 Possible critical section types
494 enum wxCriticalSectionType
497 /** Recursive critical section under both Windows and Unix */
499 wxCRITSEC_NON_RECURSIVE
500 /** Non-recursive critical section under Unix, recursive under Windows */
504 @class wxCriticalSection
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.
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.
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.
521 @see wxThread, wxCondition, wxCriticalSectionLocker
523 class wxCriticalSection
527 Default constructor initializes critical section object.
528 By default critical sections are recursive under Unix and Windows.
530 wxCriticalSection( wxCriticalSectionType critSecType
= wxCRITSEC_DEFAULT
);
533 Destructor frees the resources.
535 ~wxCriticalSection();
538 Enter the critical section (same as locking a mutex).
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.
547 Leave the critical section allowing other threads use the global data
548 protected by it. There is no error return for this function.
554 The possible thread kinds.
558 /** Detached thread */
561 /** Joinable thread */
566 The possible thread errors.
571 wxTHREAD_NO_ERROR
= 0,
573 /** No resource left to create a new thread. */
574 wxTHREAD_NO_RESOURCE
,
576 /** The thread is already running. */
579 /** The thread isn't running. */
580 wxTHREAD_NOT_RUNNING
,
582 /** Thread we waited for had to be killed. */
585 /** Some other error */
590 Defines the interval of priority
594 WXTHREAD_MIN_PRIORITY
= 0u,
595 WXTHREAD_DEFAULT_PRIORITY
= 50u,
596 WXTHREAD_MAX_PRIORITY
= 100u
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.
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.
616 @section thread_types Types of wxThreads
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.
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).
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
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;
638 class MyThread : public wxThread
641 MyThread(MyFrame *handler)
642 : wxThread(wxTHREAD_DETACHED)
643 { m_pHandler = handler }
647 virtual ExitCode Entry();
651 class MyFrame : public wxFrame
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.
666 void DoStartThread();
667 void DoPauseThread();
669 // a resume routine would be nearly identic to DoPauseThread()
670 void DoResumeThread() { ... }
672 void OnThreadCompletion(wxCommandEvent&);
673 void OnClose(wxCloseEvent&);
677 wxCriticalSection m_pThreadCS; // protects the m_pThread pointer
679 DECLARE_EVENT_TABLE()
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)
689 DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_COMPLETED)
690 DEFINE_EVENT_TYPE(wxEVT_COMMAND_MYTHREAD_UPDATE)
692 void MyFrame::DoStartThread()
694 m_pThread = new MyThread(this);
696 if ( m_pThread->Create() != wxTHREAD_NO_ERROR )
698 wxLogError("Can't create the thread!");
704 if (m_pThread->Run() != wxTHREAD_NO_ERROR )
706 wxLogError("Can't create the thread!");
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.
718 wxThread::ExitCode MyThread::Entry()
720 while (!TestDestroy())
722 // ... do a bit of work...
724 wxQueueEvent(m_pHandler, new wxCommandEvent(wxEVT_COMMAND_MYTHREAD_UPDATE));
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));
732 return (wxThread::ExitCode)0; // success
735 MyThread::~MyThread()
737 wxCriticalSectionLocker enter(m_pHandler->m_pThreadCS);
739 // the thread is being destroyed; make sure not to leave dangling pointers around
740 m_pHandler->m_pThread = NULL;
743 void MyFrame::OnThreadCompletion(wxCommandEvent&)
745 wxMessageOutputDebug().Printf("MYFRAME: MyThread exited!\n");
748 void MyFrame::OnThreadUpdate(wxCommandEvent&)
750 wxMessageOutputDebug().Printf("MYFRAME: MyThread update...\n");
753 void MyFrame::DoPauseThread()
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
759 wxCriticalSectionLocker enter(m_pThreadCS);
761 if (m_pThread) // does the thread still exist?
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
768 if (m_pThread->Pause() != wxTHREAD_NO_ERROR )
769 wxLogError("Can't pause the thread!");
773 void MyFrame::OnClose(wxCloseEvent&)
776 wxCriticalSectionLocker enter(m_pThreadCS);
778 if (m_pThread) // does the thread still exist?
780 m_out.Printf("MYFRAME: deleting thread");
782 if (m_pThread->Delete() != wxTHREAD_NO_ERROR )
783 wxLogError("Can't delete the thread!");
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!)
791 { // was the ~MyThread() function executed?
792 wxCriticalSectionLocker enter(m_pThreadCS);
793 if (!m_pThread) break;
796 // wait for thread completion
797 wxThread::This()->Sleep(1);
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.
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()
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.
820 @section thread_deletion wxThread Deletion
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.
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.
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).
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.
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.
852 @section thread_secondary wxWidgets Calls in Secondary Threads
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.
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
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.
873 @section thread_poll Don't Poll a wxThread
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.
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
895 @see wxThreadHelper, wxMutex, wxCondition, wxCriticalSection,
902 The return type for the thread functions.
904 typedef void* ExitCode
;
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.
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.
915 wxThread(wxThreadKind kind
= wxTHREAD_DETACHED
);
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.
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.
929 Creates a new thread.
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).
936 If you do not specify the stack size,the system's default value is used.
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.
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
956 wxThreadError
Create(unsigned int stackSize
= 0);
959 Calling Delete() gracefully terminates a @b detached thread, either when
960 the thread calls TestDestroy() or when it finishes processing.
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).
968 See @ref thread_deletion for a broader explanation of this routine.
970 wxThreadError
Delete(void** rc
= NULL
);
973 Returns the number of system CPUs or -1 if the value is unknown.
975 @see SetConcurrency()
977 static int GetCPUCount();
980 Returns the platform specific thread ID of the current thread as a long.
981 This can be used to uniquely identify threads, even if they are not wxThreads.
983 static unsigned long GetCurrentId();
986 Gets the thread identifier: this is a platform dependent number that uniquely
987 identifies the thread throughout the system during its existence
988 (i.e. the thread identifiers may be reused).
990 wxThreadIdType
GetId() const;
993 Returns the thread kind as it was given in the ctor.
997 wxThreadKind
GetKind() const;
1000 Gets the priority of the thread, between zero and 100.
1002 The following priorities are defined:
1003 - @b WXTHREAD_MIN_PRIORITY: 0
1004 - @b WXTHREAD_DEFAULT_PRIORITY: 50
1005 - @b WXTHREAD_MAX_PRIORITY: 100
1007 unsigned int GetPriority() const;
1010 Returns @true if the thread is alive (i.e. started and not terminating).
1012 Note that this function can only safely be used with joinable threads, not
1013 detached ones as the latter delete themselves and so when the real thread is
1014 no longer alive, it is not possible to call this function because
1015 the wxThread object no longer exists.
1017 bool IsAlive() const;
1020 Returns @true if the thread is of the detached kind, @false if it is a
1023 bool IsDetached() const;
1026 Returns @true if the calling thread is the main application thread.
1028 static bool IsMain();
1031 Returns @true if the thread is paused.
1033 bool IsPaused() const;
1036 Returns @true if the thread is running.
1038 This method may only be safely used for joinable threads, see the remark in
1041 bool IsRunning() const;
1044 Immediately terminates the target thread.
1046 @b "This function is dangerous and should be used with extreme care"
1047 (and not used at all whenever possible)! The resources allocated to the
1048 thread will not be freed and the state of the C runtime library may become
1049 inconsistent. Use Delete() for detached threads or Wait() for joinable
1052 For detached threads Kill() will also delete the associated C++ object.
1053 However this will not happen for joinable threads and this means that you will
1054 still have to delete the wxThread object yourself to avoid memory leaks.
1056 In neither case OnExit() of the dying thread will be called, so no
1057 thread-specific cleanup will be performed.
1058 This function can only be called from another thread context, i.e. a thread
1061 It is also an error to call this function for a thread which is not running or
1062 paused (in the latter case, the thread will be resumed first) -- if you do it,
1063 a @b wxTHREAD_NOT_RUNNING error will be returned.
1065 wxThreadError
Kill();
1068 Suspends the thread.
1070 Under some implementations (Win32), the thread is suspended immediately,
1071 under others it will only be suspended when it calls TestDestroy() for
1072 the next time (hence, if the thread doesn't call it at all, it won't be
1075 This function can only be called from another thread context.
1077 wxThreadError
Pause();
1080 Resumes a thread suspended by the call to Pause().
1082 This function can only be called from another thread context.
1084 wxThreadError
Resume();
1087 Starts the thread execution. Should be called after Create().
1089 Note that once you Run() a @b detached thread, @e any function call you do
1090 on the thread pointer (you must allocate it on the heap) is @e "unsafe";
1091 i.e. the thread may have terminated at any moment after Run() and your pointer
1092 may be dangling. See @ref thread_types for an example of safe manipulation
1093 of detached threads.
1095 This function can only be called from another thread context.
1097 wxThreadError
Run();
1100 Sets the thread concurrency level for this process.
1102 This is, roughly, the number of threads that the system tries to schedule
1104 The value of 0 for @a level may be used to set the default one.
1106 @return @true on success or @false otherwise (for example, if this function is
1107 not implemented for this platform -- currently everything except Solaris).
1109 static bool SetConcurrency(size_t level
);
1112 Sets the priority of the thread, between 0 and 100.
1113 It can only be set after calling Create() but before calling Run().
1115 The following priorities are defined:
1116 - @b WXTHREAD_MIN_PRIORITY: 0
1117 - @b WXTHREAD_DEFAULT_PRIORITY: 50
1118 - @b WXTHREAD_MAX_PRIORITY: 100
1120 void SetPriority(unsigned int priority
);
1123 Pauses the thread execution for the given amount of time.
1125 This is the same as wxMilliSleep().
1127 static void Sleep(unsigned long milliseconds
);
1130 This function should be called periodically by the thread to ensure that
1131 calls to Pause() and Delete() will work.
1133 If it returns @true, the thread should exit as soon as possible.
1134 Notice that under some platforms (POSIX), implementation of Pause() also
1135 relies on this function being called, so not calling it would prevent
1136 both stopping and suspending thread from working.
1138 virtual bool TestDestroy();
1141 Return the thread object for the calling thread.
1143 @NULL is returned if the calling thread is the main (GUI) thread, but
1144 IsMain() should be used to test whether the thread is really the main one
1145 because @NULL may also be returned for the thread not created with wxThread
1146 class. Generally speaking, the return value for such a thread is undefined.
1148 static wxThread
* This();
1151 Waits for a @b joinable thread to terminate and returns the value the thread
1152 returned from Entry() or @c "(ExitCode)-1" on error. Notice that, unlike
1153 Delete(), this function doesn't cancel the thread in any way so the caller
1154 waits for as long as it takes to the thread to exit.
1156 You can only Wait() for @b joinable (not detached) threads.
1158 This function can only be called from another thread context.
1160 See @ref thread_deletion for a broader explanation of this routine.
1165 Give the rest of the thread's time-slice to the system allowing the other
1168 Note that using this function is @b strongly discouraged, since in
1169 many cases it indicates a design weakness of your threading model
1170 (as does using Sleep() functions).
1172 Threads should use the CPU in an efficient manner, i.e. they should
1173 do their current work efficiently, then as soon as the work is done block
1174 on a wakeup event (wxCondition, wxMutex, select(), poll(), ...) which will
1175 get signalled e.g. by other threads or a user device once further thread
1177 Using Yield() or Sleep() indicates polling-type behaviour, since we're
1178 fuzzily giving up our timeslice and wait until sometime later we'll get
1179 reactivated, at which time we realize that there isn't really much to do
1180 and Yield() again...
1182 The most critical characteristic of Yield() is that it's operating system
1183 specific: there may be scheduler changes which cause your thread to not
1184 wake up relatively soon again, but instead many seconds later,
1185 causing huge performance issues for your application.
1188 With a well-behaving, CPU-efficient thread the operating system is likely
1189 to properly care for its reactivation the moment it needs it, whereas with
1190 non-deterministic, Yield-using threads all bets are off and the system
1191 scheduler is free to penalize them drastically</strong>, and this effect
1192 gets worse with increasing system load due to less free CPU resources available.
1193 You may refer to various Linux kernel @c sched_yield discussions for more
1198 static void Yield();
1203 This is the entry point of the thread.
1205 This function is pure virtual and must be implemented by any derived class.
1206 The thread execution will start here.
1208 The returned value is the thread exit code which is only useful for
1209 joinable threads and is the value returned by Wait().
1210 This function is called by wxWidgets itself and should never be called
1213 virtual ExitCode
Entry() = 0;
1216 This is a protected function of the wxThread class and thus can only be called
1217 from a derived class. It also can only be called in the context of this
1218 thread, i.e. a thread can only exit from itself, not from another thread.
1220 This function will terminate the OS thread (i.e. stop the associated path of
1221 execution) and also delete the associated C++ object for detached threads.
1222 OnExit() will be called just before exiting.
1224 void Exit(ExitCode exitcode
= 0);
1229 Called when the thread exits.
1231 This function is called in the context of the thread associated with the
1232 wxThread object, not in the context of the main thread.
1233 This function will not be called if the thread was @ref Kill() killed.
1235 This function should never be called directly.
1237 virtual void OnExit();
1241 /** See wxSemaphore. */
1244 wxSEMA_NO_ERROR
= 0,
1245 wxSEMA_INVALID
, //!< semaphore hasn't been initialized successfully
1246 wxSEMA_BUSY
, //!< returned by TryWait() if Wait() would block
1247 wxSEMA_TIMEOUT
, //!< returned by WaitTimeout()
1248 wxSEMA_OVERFLOW
, //!< Post() would increase counter past the max
1255 wxSemaphore is a counter limiting the number of threads concurrently accessing
1256 a shared resource. This counter is always between 0 and the maximum value
1257 specified during the semaphore creation. When the counter is strictly greater
1258 than 0, a call to wxSemaphore::Wait() returns immediately and decrements the
1259 counter. As soon as it reaches 0, any subsequent calls to wxSemaphore::Wait
1260 block and only return when the semaphore counter becomes strictly positive
1261 again as the result of calling wxSemaphore::Post which increments the counter.
1263 In general, semaphores are useful to restrict access to a shared resource
1264 which can only be accessed by some fixed number of clients at the same time.
1265 For example, when modeling a hotel reservation system a semaphore with the counter
1266 equal to the total number of available rooms could be created. Each time a room
1267 is reserved, the semaphore should be acquired by calling wxSemaphore::Wait
1268 and each time a room is freed it should be released by calling wxSemaphore::Post.
1271 @category{threading}
1277 Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if
1278 there is no upper limit. If @a maxcount is 1, the semaphore behaves almost as a
1279 mutex (but unlike a mutex it can be released by a thread different from the one
1282 @a initialcount is the initial value of the semaphore which must be between
1283 0 and @a maxcount (if it is not set to 0).
1285 wxSemaphore(int initialcount
= 0, int maxcount
= 0);
1288 Destructor is not virtual, don't use this class polymorphically.
1293 Increments the semaphore count and signals one of the waiting
1294 threads in an atomic way. Returns @e wxSEMA_OVERFLOW if the count
1295 would increase the counter past the maximum.
1298 - wxSEMA_NO_ERROR: There was no error.
1299 - wxSEMA_INVALID : Semaphore hasn't been initialized successfully.
1300 - wxSEMA_OVERFLOW: Post() would increase counter past the max.
1301 - wxSEMA_MISC_ERROR: Miscellaneous error.
1306 Same as Wait(), but returns immediately.
1309 - wxSEMA_NO_ERROR: There was no error.
1310 - wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
1311 - wxSEMA_BUSY: Returned by TryWait() if Wait() would block, i.e. the count is zero.
1312 - wxSEMA_MISC_ERROR: Miscellaneous error.
1314 wxSemaError
TryWait();
1317 Wait indefinitely until the semaphore count becomes strictly positive
1318 and then decrement it and return.
1321 - wxSEMA_NO_ERROR: There was no error.
1322 - wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
1323 - wxSEMA_MISC_ERROR: Miscellaneous error.
1328 Same as Wait(), but with a timeout limit.
1331 - wxSEMA_NO_ERROR: There was no error.
1332 - wxSEMA_INVALID: Semaphore hasn't been initialized successfully.
1333 - wxSEMA_TIMEOUT: Timeout occurred without receiving semaphore.
1334 - wxSEMA_MISC_ERROR: Miscellaneous error.
1336 wxSemaError
WaitTimeout(unsigned long timeout_millis
);
1342 @class wxMutexLocker
1344 This is a small helper class to be used with wxMutex objects.
1346 A wxMutexLocker acquires a mutex lock in the constructor and releases
1347 (or unlocks) the mutex in the destructor making it much more difficult to
1348 forget to release a mutex (which, in general, will promptly lead to serious
1349 problems). See wxMutex for an example of wxMutexLocker usage.
1352 @category{threading}
1354 @see wxMutex, wxCriticalSectionLocker
1360 Constructs a wxMutexLocker object associated with mutex and locks it.
1361 Call IsOk() to check if the mutex was successfully locked.
1363 wxMutexLocker(wxMutex
& mutex
);
1366 Destructor releases the mutex if it was successfully acquired in the ctor.
1371 Returns @true if mutex was acquired in the constructor, @false otherwise.
1378 The possible wxMutex kinds.
1382 /** Normal non-recursive mutex: try to always use this one. */
1385 /** Recursive mutex: don't use these ones with wxCondition. */
1391 The possible wxMutex errors.
1395 /** The operation completed successfully. */
1396 wxMUTEX_NO_ERROR
= 0,
1398 /** The mutex hasn't been initialized. */
1401 /** The mutex is already locked by the calling thread. */
1404 /** The mutex is already locked by another thread. */
1407 /** An attempt to unlock a mutex which is not locked. */
1410 /** wxMutex::LockTimeout() has timed out. */
1413 /** Any other error */
1421 A mutex object is a synchronization object whose state is set to signaled when
1422 it is not owned by any thread, and nonsignaled when it is owned. Its name comes
1423 from its usefulness in coordinating mutually-exclusive access to a shared
1424 resource as only one thread at a time can own a mutex object.
1426 Mutexes may be recursive in the sense that a thread can lock a mutex which it
1427 had already locked before (instead of dead locking the entire process in this
1428 situation by starting to wait on a mutex which will never be released while the
1429 thread is waiting) but using them is not recommended under Unix and they are
1430 @b not recursive by default. The reason for this is that recursive
1431 mutexes are not supported by all Unix flavours and, worse, they cannot be used
1434 For example, when several threads use the data stored in the linked list,
1435 modifications to the list should only be allowed to one thread at a time
1436 because during a new node addition the list integrity is temporarily broken
1437 (this is also called @e program @e invariant).
1440 // this variable has an "s_" prefix because it is static: seeing an "s_" in
1441 // a multithreaded program is in general a good sign that you should use a
1442 // mutex (or a critical section)
1443 static wxMutex *s_mutexProtectingTheGlobalData;
1445 // we store some numbers in this global array which is presumably used by
1446 // several threads simultaneously
1449 void MyThread::AddNewNode(int num)
1451 // ensure that no other thread accesses the list
1452 s_mutexProtectingTheGlobalList->Lock();
1456 s_mutexProtectingTheGlobalList->Unlock();
1459 // return true if the given number is greater than all array elements
1460 bool MyThread::IsGreater(int num)
1462 // before using the list we must acquire the mutex
1463 wxMutexLocker lock(s_mutexProtectingTheGlobalData);
1465 size_t count = s_data.Count();
1466 for ( size_t n = 0; n < count; n++ )
1468 if ( s_data[n] > num )
1476 Notice how wxMutexLocker was used in the second function to ensure that the
1477 mutex is unlocked in any case: whether the function returns true or false
1478 (because the destructor of the local object @e lock is always called).
1479 Using this class instead of directly using wxMutex is, in general, safer
1480 and is even more so if your program uses C++ exceptions.
1483 @category{threading}
1485 @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection
1491 Default constructor.
1493 wxMutex(wxMutexType type
= wxMUTEX_DEFAULT
);
1496 Destroys the wxMutex object.
1501 Locks the mutex object.
1502 This is equivalent to LockTimeout() with infinite timeout.
1504 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK.
1506 wxMutexError
Lock();
1509 Try to lock the mutex object during the specified time interval.
1511 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_DEAD_LOCK, @c wxMUTEX_TIMEOUT.
1513 wxMutexError
LockTimeout(unsigned long msec
);
1516 Tries to lock the mutex object. If it can't, returns immediately with an error.
1518 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_BUSY.
1520 wxMutexError
TryLock();
1523 Unlocks the mutex object.
1525 @return One of: @c wxMUTEX_NO_ERROR, @c wxMUTEX_UNLOCKED.
1527 wxMutexError
Unlock();
1532 // ============================================================================
1533 // Global functions/macros
1534 // ============================================================================
1536 /** @ingroup group_funcmacro_thread */
1540 This macro declares a (static) critical section object named @a cs if
1541 @c wxUSE_THREADS is 1 and does nothing if it is 0.
1543 @header{wx/thread.h}
1545 #define wxCRIT_SECT_DECLARE(cs)
1548 This macro declares a critical section object named @a cs if
1549 @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include
1550 the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to
1551 declare a class or struct member which explains its name.
1553 @header{wx/thread.h}
1555 #define wxCRIT_SECT_DECLARE_MEMBER(cs)
1558 This macro creates a wxCriticalSectionLocker named @a name and associated
1559 with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing
1562 @header{wx/thread.h}
1564 #define wxCRIT_SECT_LOCKER(name, cs)
1567 This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it
1568 creates a static critical section object and also the lock object
1569 associated with it. Because of this, it can be only used inside a function,
1570 not at global scope. For example:
1575 static int s_counter = 0;
1577 wxCRITICAL_SECTION(counter);
1583 Note that this example assumes that the function is called the first time
1584 from the main thread so that the critical section object is initialized
1585 correctly by the time other threads start calling it, if this is not the
1586 case this approach can @b not be used and the critical section must be made
1589 @header{wx/thread.h}
1591 #define wxCRITICAL_SECTION(name)
1594 This macro is equivalent to
1595 @ref wxCriticalSection::Leave "critical_section.Leave()" if
1596 @c wxUSE_THREADS is 1 and does nothing if it is 0.
1598 @header{wx/thread.h}
1600 #define wxLEAVE_CRIT_SECT(critical_section)
1603 This macro is equivalent to
1604 @ref wxCriticalSection::Enter "critical_section.Enter()" if
1605 @c wxUSE_THREADS is 1 and does nothing if it is 0.
1607 @header{wx/thread.h}
1609 #define wxENTER_CRIT_SECT(critical_section)
1612 Returns @true if this thread is the main one. Always returns @true if
1613 @c wxUSE_THREADS is 0.
1615 @header{wx/thread.h}
1617 bool wxIsMainThread();
1620 This function must be called when any thread other than the main GUI thread
1621 wants to get access to the GUI library. This function will block the
1622 execution of the calling thread until the main thread (or any other thread
1623 holding the main GUI lock) leaves the GUI library and no other thread will
1624 enter the GUI library until the calling thread calls wxMutexGuiLeave().
1626 Typically, these functions are used like this:
1629 void MyThread::Foo(void)
1631 // before doing any GUI calls we must ensure that
1632 // this thread is the only one doing it!
1637 my_window-DrawSomething();
1643 This function is only defined on platforms which support preemptive
1646 @note Under GTK, no creation of top-level windows is allowed in any thread
1649 @header{wx/thread.h}
1651 void wxMutexGuiEnter();
1654 This function is only defined on platforms which support preemptive
1657 @see wxMutexGuiEnter()
1659 @header{wx/thread.h}
1661 void wxMutexGuiLeave();