]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/thread.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxCondition
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 wxCondition variables correspond to pthread conditions or to Win32 event
13 objects. They may be used in a multithreaded application to wait until the
14 given condition becomes @true which happens when the condition becomes signaled.
16 For example, if a worker thread is doing some long task and another thread has
17 to wait until it is finished, the latter thread will wait on the condition
18 object and the worker thread will signal it on exit (this example is not
19 perfect because in this particular case it would be much better to just
20 wxThread::Wait for the worker thread, but if there are several
21 worker threads it already makes much more sense).
23 Note that a call to wxCondition::Signal may happen before the
24 other thread calls wxCondition::Wait and, just as with the
25 pthread conditions, the signal is then lost and so if you want to be sure that
26 you don't miss it you must keep the mutex associated with the condition
27 initially locked and lock it again before calling
28 wxCondition::Signal. Of course, this means that this call is
29 going to block until wxCondition::Wait is called by another
35 @see wxThread, wxMutex
41 Default and only constructor. The @a mutex must be locked by the caller
42 before calling Wait() function.
43 Use IsOk() to check if the object was successfully
46 wxCondition(wxMutex
& mutex
);
49 Destroys the wxCondition object. The destructor is not virtual so this class
50 should not be used polymorphically.
55 Broadcasts to all waiting threads, waking all of them up. Note that this method
56 may be called whether the mutex associated with this condition is locked or
64 Returns @true if the object had been initialized successfully, @false
70 Signals the object waking up at most one thread. If several threads are waiting
71 on the same condition, the exact thread which is woken up is undefined. If no
72 threads are waiting, the signal is lost and the condition would have to be
73 signalled again to wake up any thread which may start waiting on it later.
74 Note that this method may be called whether the mutex associated with this
75 condition is locked or not.
82 Waits until the condition is signalled.
83 This method atomically releases the lock on the mutex associated with this
84 condition (this is why it must be locked prior to calling Wait) and puts the
85 thread to sleep until Signal() or
86 Broadcast() is called. It then locks the mutex
88 Note that even if Signal() had been called before
89 Wait without waking up any thread, the thread would still wait for another one
90 and so it is important to ensure that the condition will be signalled after
91 Wait or the thread may sleep forever.
93 @return Returns wxCOND_NO_ERROR on success, another value if an error
101 Waits until the condition is signalled or the timeout has elapsed.
102 This method is identical to Wait() except that it
103 returns, with the return code of @c wxCOND_TIMEOUT as soon as the given
107 Timeout in milliseconds
109 wxCondError
WaitTimeout(unsigned long milliseconds
);
115 @class wxCriticalSectionLocker
117 This is a small helper class to be used with wxCriticalSection
118 objects. A wxCriticalSectionLocker enters the critical section in the
119 constructor and leaves it in the destructor making it much more difficult to
120 forget to leave a critical section (which, in general, will lead to serious
121 and difficult to debug problems).
128 // gs_critSect is some (global) critical section guarding access to the
130 wxCriticalSectionLocker locker(gs_critSect);
147 Without wxCriticalSectionLocker, you would need to remember to manually leave
148 the critical section before each @c return.
153 @see wxCriticalSection, wxMutexLocker
155 class wxCriticalSectionLocker
159 Constructs a wxCriticalSectionLocker object associated with given
160 @a criticalsection and enters it.
162 wxCriticalSectionLocker(wxCriticalSection
& criticalsection
);
165 Destructor leaves the critical section.
167 ~wxCriticalSectionLocker();
173 @class wxThreadHelper
175 The wxThreadHelper class is a mix-in class that manages a single background
176 thread. By deriving from wxThreadHelper, a class can implement the thread
177 code in its own wxThreadHelper::Entry method
178 and easily share data and synchronization objects between the main thread
179 and the worker thread. Doing this prevents the awkward passing of pointers
180 that is needed when the original object in the main thread needs to
181 synchronize with its worker thread in its own wxThread derived object.
183 For example, wxFrame may need to make some calculations
184 in a background thread and then display the results of those calculations in
187 Ordinarily, a wxThread derived object would be created
188 with the calculation code implemented in
189 wxThread::Entry. To access the inputs to the
190 calculation, the frame object would often to pass a pointer to itself to the
191 thread object. Similarly, the frame object would hold a pointer to the
192 thread object. Shared data and synchronization objects could be stored in
193 either object though the object without the data would have to access the
194 data through a pointer.
196 However, with wxThreadHelper, the frame object and the thread object are
197 treated as the same object. Shared data and synchronization variables are
198 stored in the single object, eliminating a layer of indirection and the
210 This constructor simply initializes a member variable.
215 The destructor frees the resources associated with the thread.
220 Creates a new thread. The thread object is created in the suspended state, and
222 should call @ref wxThread::Run GetThread()-Run to start running
223 it. You may optionally specify the stack size to be allocated to it (Ignored on
224 platforms that don't support setting it explicitly, eg. Unix).
228 wxThreadError
Create(unsigned int stackSize
= 0);
231 This is the entry point of the thread. This function is pure virtual and must
232 be implemented by any derived class. The thread execution will start here.
233 The returned value is the thread exit code which is only useful for
234 joinable threads and is the value returned by
235 @ref wxThread::Wait GetThread()-Wait.
236 This function is called by wxWidgets itself and should never be called
239 virtual ExitCode
Entry();
242 This is a public function that returns the wxThread object
243 associated with the thread.
245 wxThread
* GetThread();
249 the actual wxThread object.
256 @class wxCriticalSection
258 A critical section object is used for exactly the same purpose as
259 mutexes(). The only difference is that under Windows platform
260 critical sections are only visible inside one process, while mutexes may be
261 shared among processes, so using critical sections is slightly more
262 efficient. The terminology is also slightly different: mutex may be locked (or
263 acquired) and unlocked (or released) while critical section is entered and left
266 Finally, you should try to use
267 wxCriticalSectionLocker class whenever
268 possible instead of directly using wxCriticalSection for the same reasons
269 wxMutexLocker is preferrable to
270 wxMutex - please see wxMutex for an example.
275 @see wxThread, wxCondition, wxCriticalSectionLocker
277 class wxCriticalSection
281 Default constructor initializes critical section object.
286 Destructor frees the resources.
288 ~wxCriticalSection();
291 Enter the critical section (same as locking a mutex). There is no error return
292 for this function. After entering the critical section protecting some global
293 data the thread running in critical section may safely use/modify it.
298 Leave the critical section allowing other threads use the global data protected
299 by it. There is no error return for this function.
309 A thread is basically a path of execution through a program. Threads are
310 sometimes called @e light-weight processes, but the fundamental difference
311 between threads and processes is that memory spaces of different processes are
312 separated while all threads share the same address space.
314 While it makes it much easier to share common data between several threads, it
315 also makes it much easier to shoot oneself in the foot, so careful use of
316 synchronization objects such as mutexes() or @ref wxCriticalSection
317 "critical sections" is recommended. In addition, don't create global thread
318 objects because they allocate memory in their constructor, which will cause
319 problems for the memory checking system.
321 @section overview_typeswxthread Types of wxThreads
322 There are two types of threads in wxWidgets: @e detached and @e joinable,
323 modeled after the the POSIX thread API. This is different from the Win32 API
324 where all threads are joinable.
326 By default wxThreads in wxWidgets use the detached behavior. Detached threads
327 delete themselves once they have completed, either by themselves when they
328 complete processing or through a call to Delete(), and thus
329 must be created on the heap (through the new operator, for example).
330 Conversely, joinable threads do not delete themselves when they are done
331 processing and as such are safe to create on the stack. Joinable threads
332 also provide the ability for one to get value it returned from Entry()
335 You shouldn't hurry to create all the threads joinable, however, because this
336 has a disadvantage as well: you @b must Wait() for a joinable thread or the
337 system resources used by it will never be freed, and you also must delete the
338 corresponding wxThread object yourself if you did not create it on the stack.
339 In contrast, detached threads are of the "fire-and-forget" kind: you only have to
340 start a detached thread and it will terminate and destroy itself.
342 @section overview_deletionwxthread wxThread Deletion
343 Regardless of whether it has terminated or not, you should call
344 Wait() on a joinable thread to release its memory, as outlined in
345 @ref overview_typeswxthread "Types of wxThreads". If you created
346 a joinable thread on the heap, remember to delete it manually with the delete
347 operator or similar means as only detached threads handle this type of memory
350 Since detached threads delete themselves when they are finished processing,
351 you should take care when calling a routine on one. If you are certain the
352 thread is still running and would like to end it, you may call Delete()
353 to gracefully end it (which implies that the thread will be deleted after
354 that call to Delete()). It should be implied that you should never attempt
355 to delete a detached thread with the delete operator or similar means.
356 As mentioned, Wait() or Delete() attempts to gracefully terminate a
357 joinable and detached thread, respectively. It does this by waiting until
358 the thread in question calls TestDestroy() or ends processing (returns
359 from wxThread::Entry).
361 Obviously, if the thread does call TestDestroy() and does not end the calling
362 thread will come to halt. This is why it is important to call TestDestroy() in
363 the Entry() routine of your threads as often as possible.
364 As a last resort you can end the thread immediately through Kill(). It is
365 strongly recommended that you do not do this, however, as it does not free
366 the resources associated with the object (although the wxThread object of
367 detached threads will still be deleted) and could leave the C runtime
368 library in an undefined state.
370 @section overview_secondarythreads wxWidgets Calls in Secondary Threads
371 All threads other than the "main application thread" (the one
372 wxApp::OnInit or your main function runs in, for example) are considered
373 "secondary threads". These include all threads created by Create() or the
374 corresponding constructors.
376 GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe
377 at all in secondary threads and could end your application prematurely.
378 This is due to several reasons, including the underlying native API and
379 the fact that wxThread does not run a GUI event loop similar to other APIs
382 A workaround for some wxWidgets ports is calling wxMutexGUIEnter()
383 before any GUI calls and then calling wxMutexGUILeave() afterwords. However,
384 the recommended way is to simply process the GUI calls in the main thread
385 through an event that is posted by either wxQueueEvent().
386 This does not imply that calls to these classes are thread-safe, however,
387 as most wxWidgets classes are not thread-safe, including wxString.
389 @section overview_pollwxThread Don't Poll a wxThread
390 A common problem users experience with wxThread is that in their main thread
391 they will check the thread every now and then to see if it has ended through
392 IsRunning(), only to find that their application has run into problems
393 because the thread is using the default behavior and has already deleted
394 itself. Naturally, they instead attempt to use joinable threads in place
395 of the previous behavior. However, polling a wxThread for when it has ended
396 is in general a bad idea - in fact calling a routine on any running wxThread
397 should be avoided if possible. Instead, find a way to notify yourself when
398 the thread has ended.
400 Usually you only need to notify the main thread, in which case you can
401 post an event to it via wxPostEvent() or wxEvtHandler::AddPendingEvent.
402 In the case of secondary threads you can call a routine of another class
403 when the thread is about to complete processing and/or set the value of
404 a variable, possibly using mutexes() and/or other synchronization means
409 @see wxMutex, wxCondition, wxCriticalSection
415 This constructor creates a new detached (default) or joinable C++
416 thread object. It does not create or start execution of the real thread --
417 for this you should use the Create() and Run() methods.
419 The possible values for @a kind parameters are:
420 - @b wxTHREAD_DETACHED - Creates a detached thread.
421 - @b wxTHREAD_JOINABLE - Creates a joinable thread.
423 wxThread(wxThreadKind kind
= wxTHREAD_DETACHED
);
426 The destructor frees the resources associated with the thread. Notice that you
427 should never delete a detached thread -- you may only call
428 Delete() on it or wait until it terminates (and auto
429 destructs) itself. Because the detached threads delete themselves, they can
430 only be allocated on the heap.
431 Joinable threads should be deleted explicitly. The Delete() and Kill() functions
432 will not delete the C++ thread object. It is also safe to allocate them on
438 Creates a new thread. The thread object is created in the suspended state,
439 and you should call Run() to start running it. You may optionally
440 specify the stack size to be allocated to it (Ignored on platforms that don't
441 support setting it explicitly, eg. Unix system without
442 @c pthread_attr_setstacksize). If you do not specify the stack size,
443 the system's default value is used.
444 @b Warning: It is a good idea to explicitly specify a value as systems'
445 default values vary from just a couple of KB on some systems (BSD and
446 OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you
447 have a thread that requires more than just a few KB of memory, you will
448 have mysterious problems on some platforms but not on the common ones. On the
449 other hand, just indicating a large stack size by default will give you
450 performance issues on those systems with small default stack since those
451 typically use fully committed memory for the stack. On the contrary, if
452 use a lot of threads (say several hundred), virtual adress space can get tight
453 unless you explicitly specify a smaller amount of thread stack space for each
457 - @b wxTHREAD_NO_ERROR - No error.
458 - @b wxTHREAD_NO_RESOURCE - There were insufficient resources to create the thread.
459 - @b wxTHREAD_NO_RUNNING - The thread is already running
461 wxThreadError
Create(unsigned int stackSize
= 0);
464 Calling Delete() gracefully terminates a
465 detached thread, either when the thread calls TestDestroy() or finished
467 (Note that while this could work on a joinable thread you simply should not
468 call this routine on one as afterwards you may not be able to call
469 Wait() to free the memory of that thread).
470 See @ref overview_deletionwxthread "wxThread deletion" for a broader
471 explanation of this routine.
473 wxThreadError
Delete();
476 This is the entry point of the thread. This function is pure virtual and must
477 be implemented by any derived class. The thread execution will start here.
478 The returned value is the thread exit code which is only useful for
479 joinable threads and is the value returned by Wait().
480 This function is called by wxWidgets itself and should never be called
483 virtual ExitCode
Entry();
486 This is a protected function of the wxThread class and thus can only be called
487 from a derived class. It also can only be called in the context of this
488 thread, i.e. a thread can only exit from itself, not from another thread.
489 This function will terminate the OS thread (i.e. stop the associated path of
490 execution) and also delete the associated C++ object for detached threads.
491 OnExit() will be called just before exiting.
493 void Exit(ExitCode exitcode
= 0);
496 Returns the number of system CPUs or -1 if the value is unknown.
498 @see SetConcurrency()
500 static int GetCPUCount();
503 Returns the platform specific thread ID of the current thread as a
504 long. This can be used to uniquely identify threads, even if they are
507 static unsigned long GetCurrentId();
510 Gets the thread identifier: this is a platform dependent number that uniquely
512 thread throughout the system during its existence (i.e. the thread identifiers
515 unsigned long GetId() const;
518 Gets the priority of the thread, between zero and 100.
520 The following priorities are defined:
521 - @b WXTHREAD_MIN_PRIORITY: 0
522 - @b WXTHREAD_DEFAULT_PRIORITY: 50
523 - @b WXTHREAD_MAX_PRIORITY: 100
525 int GetPriority() const;
528 Returns @true if the thread is alive (i.e. started and not terminating).
529 Note that this function can only safely be used with joinable threads, not
530 detached ones as the latter delete themselves and so when the real thread is
531 no longer alive, it is not possible to call this function because
532 the wxThread object no longer exists.
534 bool IsAlive() const;
537 Returns @true if the thread is of the detached kind, @false if it is a
541 bool IsDetached() const;
544 Returns @true if the calling thread is the main application thread.
546 static bool IsMain();
549 Returns @true if the thread is paused.
551 bool IsPaused() const;
554 Returns @true if the thread is running.
555 This method may only be safely used for joinable threads, see the remark in
558 bool IsRunning() const;
561 Immediately terminates the target thread. @b This function is dangerous and
563 be used with extreme care (and not used at all whenever possible)! The resources
564 allocated to the thread will not be freed and the state of the C runtime library
565 may become inconsistent. Use Delete() for detached
566 threads or Wait() for joinable threads instead.
567 For detached threads Kill() will also delete the associated C++ object.
568 However this will not happen for joinable threads and this means that you will
569 still have to delete the wxThread object yourself to avoid memory leaks.
570 In neither case OnExit() of the dying thread will be
571 called, so no thread-specific cleanup will be performed.
572 This function can only be called from another thread context, i.e. a thread
574 It is also an error to call this function for a thread which is not running or
575 paused (in the latter case, the thread will be resumed first) -- if you do it,
576 a @b wxTHREAD_NOT_RUNNING error will be returned.
578 wxThreadError
Kill();
581 Called when the thread exits. This function is called in the context of the
582 thread associated with the wxThread object, not in the context of the main
583 thread. This function will not be called if the thread was
585 This function should never be called directly.
590 Suspends the thread. Under some implementations (Win32), the thread is
591 suspended immediately, under others it will only be suspended when it calls
592 TestDestroy() for the next time (hence, if the
593 thread doesn't call it at all, it won't be suspended).
594 This function can only be called from another thread context.
596 wxThreadError
Pause();
599 Resumes a thread suspended by the call to Pause().
600 This function can only be called from another thread context.
602 wxThreadError
Resume();
605 Starts the thread execution. Should be called after
607 This function can only be called from another thread context.
612 Sets the thread concurrency level for this process. This is, roughly, the
613 number of threads that the system tries to schedule to run in parallel.
614 The value of 0 for @a level may be used to set the default one.
615 Returns @true on success or @false otherwise (for example, if this function is
616 not implemented for this platform -- currently everything except Solaris).
618 static bool SetConcurrency(size_t level
);
621 Sets the priority of the thread, between 0 and 100. It can only be set
622 after calling Create() but before calling
625 The following priorities are defined:
626 - @b WXTHREAD_MIN_PRIORITY: 0
627 - @b WXTHREAD_DEFAULT_PRIORITY: 50
628 - @b WXTHREAD_MAX_PRIORITY: 100
630 void SetPriority(int priority
);
633 Pauses the thread execution for the given amount of time.
635 This is the same as wxMilliSleep().
637 static void Sleep(unsigned long milliseconds
);
640 This function should be called periodically by the thread to ensure that
641 calls to Pause() and Delete() will work. If it returns @true, the thread
642 should exit as soon as possible. Notice that under some platforms (POSIX),
643 implementation of Pause() also relies on this function being called, so
644 not calling it would prevent both stopping and suspending thread from working.
646 virtual bool TestDestroy();
649 Return the thread object for the calling thread. @NULL is returned if
650 the calling thread is the main (GUI) thread, but IsMain() should be used
651 to test whether the thread is really the main one because @NULL may also
652 be returned for the thread not created with wxThread class. Generally
653 speaking, the return value for such a thread is undefined.
655 static wxThread
* This();
658 Waits for a joinable thread to terminate and returns the value the thread
659 returned from Entry() or @c (ExitCode)-1 on error. Notice that, unlike
660 Delete() doesn't cancel the thread in any way so the caller waits for as
661 long as it takes to the thread to exit.
662 You can only Wait() for joinable (not detached) threads.
663 This function can only be called from another thread context.
664 See @ref overview_deletionwxthread "wxThread deletion" for a broader
665 explanation of this routine.
667 ExitCode
Wait() const;
670 Give the rest of the thread time slice to the system allowing the other
672 Note that using this function is @b strongly discouraged, since in
673 many cases it indicates a design weakness of your threading model (as
674 does using Sleep functions).
675 Threads should use the CPU in an efficient manner, i.e. they should
676 do their current work efficiently, then as soon as the work is done block
677 on a wakeup event (wxCondition, wxMutex, select(), poll(), ...)
678 which will get signalled e.g. by other threads or a user device once further
679 thread work is available. Using Yield or Sleep
680 indicates polling-type behaviour, since we're fuzzily giving up our timeslice
681 and wait until sometime later we'll get reactivated, at which time we
682 realize that there isn't really much to do and Yield again...
683 The most critical characteristic of Yield is that it's operating system
684 specific: there may be scheduler changes which cause your thread to not
685 wake up relatively soon again, but instead many seconds later,
686 causing huge performance issues for your application. @b with a
687 well-behaving, CPU-efficient thread the operating system is likely to properly
688 care for its reactivation the moment it needs it, whereas with
689 non-deterministic, Yield-using threads all bets are off and the system
690 scheduler is free to penalize drastically, and this effect gets worse
691 with increasing system load due to less free CPU resources available.
692 You may refer to various Linux kernel sched_yield discussions for more
702 wxSemaphore is a counter limiting the number of threads concurrently accessing
703 a shared resource. This counter is always between 0 and the maximum value
704 specified during the semaphore creation. When the counter is strictly greater
705 than 0, a call to wxSemaphore::Wait returns immediately and
706 decrements the counter. As soon as it reaches 0, any subsequent calls to
707 wxSemaphore::Wait block and only return when the semaphore
708 counter becomes strictly positive again as the result of calling
709 wxSemaphore::Post which increments the counter.
711 In general, semaphores are useful to restrict access to a shared resource
712 which can only be accessed by some fixed number of clients at the same time. For
713 example, when modeling a hotel reservation system a semaphore with the counter
714 equal to the total number of available rooms could be created. Each time a room
715 is reserved, the semaphore should be acquired by calling
716 wxSemaphore::Wait and each time a room is freed it should be
717 released by calling wxSemaphore::Post.
726 Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if
727 there is no upper limit. If maxcount is 1, the semaphore behaves almost as a
728 mutex (but unlike a mutex it can be released by a thread different from the one
730 @a initialcount is the initial value of the semaphore which must be between
731 0 and @a maxcount (if it is not set to 0).
733 wxSemaphore(int initialcount
= 0, int maxcount
= 0);
736 Destructor is not virtual, don't use this class polymorphically.
741 Increments the semaphore count and signals one of the waiting
742 threads in an atomic way. Returns wxSEMA_OVERFLOW if the count
743 would increase the counter past the maximum.
750 Same as Wait(), but returns immediately.
754 wxSemaError
TryWait();
757 Wait indefinitely until the semaphore count becomes strictly positive
758 and then decrement it and return.
770 This is a small helper class to be used with wxMutex
771 objects. A wxMutexLocker acquires a mutex lock in the constructor and releases
772 (or unlocks) the mutex in the destructor making it much more difficult to
773 forget to release a mutex (which, in general, will promptly lead to serious
774 problems). See wxMutex for an example of wxMutexLocker
780 @see wxMutex, wxCriticalSectionLocker
786 Constructs a wxMutexLocker object associated with mutex and locks it.
787 Call @ref IsOk() IsLocked to check if the mutex was
790 wxMutexLocker(wxMutex
& mutex
);
793 Destructor releases the mutex if it was successfully acquired in the ctor.
798 Returns @true if mutex was acquired in the constructor, @false otherwise.
808 A mutex object is a synchronization object whose state is set to signaled when
809 it is not owned by any thread, and nonsignaled when it is owned. Its name comes
810 from its usefulness in coordinating mutually-exclusive access to a shared
811 resource as only one thread at a time can own a mutex object.
813 Mutexes may be recursive in the sense that a thread can lock a mutex which it
814 had already locked before (instead of dead locking the entire process in this
815 situation by starting to wait on a mutex which will never be released while the
816 thread is waiting) but using them is not recommended under Unix and they are
817 @b not recursive there by default. The reason for this is that recursive
818 mutexes are not supported by all Unix flavours and, worse, they cannot be used
819 with wxCondition. On the other hand, Win32 mutexes are
822 For example, when several threads use the data stored in the linked list,
823 modifications to the list should only be allowed to one thread at a time
824 because during a new node addition the list integrity is temporarily broken
825 (this is also called @e program invariant).
830 @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection
838 wxMutex(wxMutexType type
= wxMUTEX_DEFAULT
);
841 Destroys the wxMutex object.
846 Locks the mutex object. This is equivalent to
847 LockTimeout() with infinite timeout.
854 Try to lock the mutex object during the specified time interval.
858 wxMutexError
LockTimeout(unsigned long msec
);
861 Tries to lock the mutex object. If it can't, returns immediately with an error.
865 wxMutexError
TryLock();
868 Unlocks the mutex object.
872 wxMutexError
Unlock();
877 // ============================================================================
878 // Global functions/macros
879 // ============================================================================
881 /** @ingroup group_funcmacro_thread */
885 This macro declares a (static) critical section object named @a cs if
886 @c wxUSE_THREADS is 1 and does nothing if it is 0.
890 #define wxCRIT_SECT_DECLARE(cs)
893 This macro declares a critical section object named @a cs if
894 @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include
895 the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to
896 declare a class or struct member which explains its name.
900 #define wxCRIT_SECT_DECLARE_MEMBER(cs)
903 This macro creates a wxCriticalSectionLocker named @a name and associated
904 with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing
909 #define wxCRIT_SECT_LOCKER(name, cs)
912 This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it
913 creates a static critical section object and also the lock object
914 associated with it. Because of this, it can be only used inside a function,
915 not at global scope. For example:
920 static int s_counter = 0;
922 wxCRITICAL_SECTION(counter);
928 Note that this example assumes that the function is called the first time
929 from the main thread so that the critical section object is initialized
930 correctly by the time other threads start calling it, if this is not the
931 case this approach can @b not be used and the critical section must be made
936 #define wxCRITICAL_SECTION(name)
939 This macro is equivalent to
940 @ref wxCriticalSection::Leave "critical_section.Leave()" if
941 @c wxUSE_THREADS is 1 and does nothing if it is 0.
945 #define wxLEAVE_CRIT_SECT(critical_section)
948 This macro is equivalent to
949 @ref wxCriticalSection::Enter "critical_section.Enter()" if
950 @c wxUSE_THREADS is 1 and does nothing if it is 0.
954 #define wxENTER_CRIT_SECT(critical_section)
957 Returns @true if this thread is the main one. Always returns @true if
958 @c wxUSE_THREADS is 0.
962 bool wxIsMainThread();
965 This function must be called when any thread other than the main GUI thread
966 wants to get access to the GUI library. This function will block the
967 execution of the calling thread until the main thread (or any other thread
968 holding the main GUI lock) leaves the GUI library and no other thread will
969 enter the GUI library until the calling thread calls wxMutexGuiLeave().
971 Typically, these functions are used like this:
974 void MyThread::Foo(void)
976 // before doing any GUI calls we must ensure that
977 // this thread is the only one doing it!
982 my_window-DrawSomething();
988 This function is only defined on platforms which support preemptive
991 @note Under GTK, no creation of top-level windows is allowed in any thread
996 void wxMutexGuiEnter();
999 This function is only defined on platforms which support preemptive
1002 @see wxMutexGuiEnter()
1004 @header{wx/thread.h}
1006 void wxMutexGuiLeave();