Version: 3.0.5
Loading...
Searching...
No Matches
thread.h File Reference

Classes

class  wxCondition
 wxCondition variables correspond to pthread conditions or to Win32 event objects. More...
 
class  wxCriticalSectionLocker
 This is a small helper class to be used with wxCriticalSection objects. More...
 
class  wxThreadHelper
 The wxThreadHelper class is a mix-in class that manages a single background thread, either detached or joinable (see wxThread for the differences). More...
 
class  wxCriticalSection
 A critical section object is used for exactly the same purpose as a wxMutex. More...
 
class  wxThread
 A thread is basically a path of execution through a program. More...
 
class  wxSemaphore
 wxSemaphore is a counter limiting the number of threads concurrently accessing a shared resource. More...
 
class  wxMutexLocker
 This is a small helper class to be used with wxMutex objects. More...
 
class  wxMutex
 A mutex object is a synchronization object whose state is set to signaled when it is not owned by any thread, and nonsignaled when it is owned. More...
 

Macros

#define wxCRIT_SECT_DECLARE(cs)
 This macro declares a (static) critical section object named cs if wxUSE_THREADS is 1 and does nothing if it is 0.
 
#define wxCRIT_SECT_DECLARE_MEMBER(cs)
 This macro declares a critical section object named cs if wxUSE_THREADS is 1 and does nothing if it is 0.
 
#define wxCRIT_SECT_LOCKER(name, cs)
 This macro creates a wxCriticalSectionLocker named name and associated with the critical section cs if wxUSE_THREADS is 1 and does nothing if it is 0.
 
#define wxCRITICAL_SECTION(name)
 This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it creates a static critical section object and also the lock object associated with it.
 
#define wxLEAVE_CRIT_SECT(critical_section)
 This macro is equivalent to critical_section.Leave() if wxUSE_THREADS is 1 and does nothing if it is 0.
 
#define wxENTER_CRIT_SECT(critical_section)
 This macro is equivalent to critical_section.Enter() if wxUSE_THREADS is 1 and does nothing if it is 0.
 

Enumerations

enum  wxCondError {
  wxCOND_NO_ERROR = 0 ,
  wxCOND_INVALID ,
  wxCOND_TIMEOUT ,
  wxCOND_MISC_ERROR
}
 See wxCondition. More...
 
enum  wxCriticalSectionType {
  wxCRITSEC_DEFAULT ,
  wxCRITSEC_NON_RECURSIVE
}
 Possible critical section types. More...
 
enum  wxThreadWait {
  wxTHREAD_WAIT_BLOCK ,
  wxTHREAD_WAIT_YIELD ,
  wxTHREAD_WAIT_DEFAULT = wxTHREAD_WAIT_YIELD
}
 The possible thread wait types. More...
 
enum  wxThreadKind {
  wxTHREAD_DETACHED ,
  wxTHREAD_JOINABLE
}
 The possible thread kinds. More...
 
enum  wxThreadError {
  wxTHREAD_NO_ERROR = 0 ,
  wxTHREAD_NO_RESOURCE ,
  wxTHREAD_RUNNING ,
  wxTHREAD_NOT_RUNNING ,
  wxTHREAD_KILLED ,
  wxTHREAD_MISC_ERROR
}
 The possible thread errors. More...
 
enum  wxSemaError {
  wxSEMA_NO_ERROR = 0 ,
  wxSEMA_INVALID ,
  wxSEMA_BUSY ,
  wxSEMA_TIMEOUT ,
  wxSEMA_OVERFLOW ,
  wxSEMA_MISC_ERROR
}
 See wxSemaphore. More...
 
enum  wxMutexType {
  wxMUTEX_DEFAULT ,
  wxMUTEX_RECURSIVE
}
 The possible wxMutex kinds. More...
 
enum  wxMutexError {
  wxMUTEX_NO_ERROR = 0 ,
  wxMUTEX_INVALID ,
  wxMUTEX_DEAD_LOCK ,
  wxMUTEX_BUSY ,
  wxMUTEX_UNLOCKED ,
  wxMUTEX_TIMEOUT ,
  wxMUTEX_MISC_ERROR
}
 The possible wxMutex errors. More...
 

Functions

bool wxIsMainThread ()
 Returns true if this thread is the main one.
 
void wxMutexGuiEnter ()
 This function must be called when any thread other than the main GUI thread wants to get access to the GUI library.
 
void wxMutexGuiLeave ()
 This function is only defined on platforms which support preemptive threads.
 

Macro Definition Documentation

◆ wxCRIT_SECT_DECLARE

#define wxCRIT_SECT_DECLARE (   cs)

This macro declares a (static) critical section object named cs if wxUSE_THREADS is 1 and does nothing if it is 0.

Include file:

#include <wx/thread.h> 

◆ wxCRIT_SECT_DECLARE_MEMBER

#define wxCRIT_SECT_DECLARE_MEMBER (   cs)

This macro declares a critical section object named cs if wxUSE_THREADS is 1 and does nothing if it is 0.

As it doesn't include the static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to declare a class or struct member which explains its name.

Include file:

#include <wx/thread.h> 

◆ wxCRIT_SECT_LOCKER

#define wxCRIT_SECT_LOCKER (   name,
  cs 
)

This macro creates a wxCriticalSectionLocker named name and associated with the critical section cs if wxUSE_THREADS is 1 and does nothing if it is 0.

Include file:

#include <wx/thread.h> 

◆ wxCRITICAL_SECTION

#define wxCRITICAL_SECTION (   name)

This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it creates a static critical section object and also the lock object associated with it.

Because of this, it can be only used inside a function, not at global scope. For example:

int IncCount()
{
static int s_counter = 0;
return ++s_counter;
}
#define wxCRITICAL_SECTION(name)
This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it creates a static critical sect...
Definition thread.h:1739

Note that this example assumes that the function is called the first time from the main thread so that the critical section object is initialized correctly by the time other threads start calling it, if this is not the case this approach can not be used and the critical section must be made a global instead.

Include file:

#include <wx/thread.h> 

◆ wxENTER_CRIT_SECT

#define wxENTER_CRIT_SECT (   critical_section)

This macro is equivalent to critical_section.Enter() if wxUSE_THREADS is 1 and does nothing if it is 0.

Include file:

#include <wx/thread.h> 

◆ wxLEAVE_CRIT_SECT

#define wxLEAVE_CRIT_SECT (   critical_section)

This macro is equivalent to critical_section.Leave() if wxUSE_THREADS is 1 and does nothing if it is 0.

Include file:

#include <wx/thread.h> 

Enumeration Type Documentation

◆ wxCondError

See wxCondition.

Enumerator
wxCOND_NO_ERROR 
wxCOND_INVALID 
wxCOND_TIMEOUT 

WaitTimeout() has timed out.

wxCOND_MISC_ERROR 

◆ wxCriticalSectionType

Possible critical section types.

Enumerator
wxCRITSEC_DEFAULT 
wxCRITSEC_NON_RECURSIVE 

Recursive critical section under both Windows and Unix.

Non-recursive critical section under Unix, recursive under Windows

◆ wxMutexError

The possible wxMutex errors.

Enumerator
wxMUTEX_NO_ERROR 

The operation completed successfully.

wxMUTEX_INVALID 

The mutex hasn't been initialized.

wxMUTEX_DEAD_LOCK 

The mutex is already locked by the calling thread.

wxMUTEX_BUSY 

The mutex is already locked by another thread.

wxMUTEX_UNLOCKED 

An attempt to unlock a mutex which is not locked.

wxMUTEX_TIMEOUT 

wxMutex::LockTimeout() has timed out.

wxMUTEX_MISC_ERROR 

Any other error.

◆ wxMutexType

The possible wxMutex kinds.

Enumerator
wxMUTEX_DEFAULT 

Normal non-recursive mutex: try to always use this one.

wxMUTEX_RECURSIVE 

Recursive mutex: don't use these ones with wxCondition.

◆ wxSemaError

See wxSemaphore.

Enumerator
wxSEMA_NO_ERROR 
wxSEMA_INVALID 

semaphore hasn't been initialized successfully

wxSEMA_BUSY 

returned by TryWait() if Wait() would block

wxSEMA_TIMEOUT 

returned by WaitTimeout()

wxSEMA_OVERFLOW 

Post() would increase counter past the max.

wxSEMA_MISC_ERROR 

◆ wxThreadError

The possible thread errors.

Enumerator
wxTHREAD_NO_ERROR 

No error.

wxTHREAD_NO_RESOURCE 

No resource left to create a new thread.

wxTHREAD_RUNNING 

The thread is already running.

wxTHREAD_NOT_RUNNING 

The thread isn't running.

wxTHREAD_KILLED 

Thread we waited for had to be killed.

wxTHREAD_MISC_ERROR 

Some other error.

◆ wxThreadKind

The possible thread kinds.

Enumerator
wxTHREAD_DETACHED 

Detached thread.

wxTHREAD_JOINABLE 

Joinable thread.

◆ wxThreadWait

The possible thread wait types.

Since
2.9.2
Enumerator
wxTHREAD_WAIT_BLOCK 

No events are processed while waiting.

This is the default under all platforms except for wxMSW.

wxTHREAD_WAIT_YIELD 

Yield for event dispatching while waiting.

This flag is dangerous as it exposes the program using it to unexpected reentrancies in the same way as calling wxYield() function does so you are strongly advised to avoid its use and not wait for the thread termination from the main (GUI) thread at all to avoid making your application unresponsive.

Also notice that this flag is not portable as it is only implemented in wxMSW and simply ignored under the other platforms.

wxTHREAD_WAIT_DEFAULT 

Default wait mode for wxThread::Wait() and wxThread::Delete().

For compatibility reasons, the default wait mode is currently wxTHREAD_WAIT_YIELD if WXWIN_COMPATIBILITY_2_8 is defined (and it is by default). However, as mentioned above, you're strongly encouraged to not use wxTHREAD_WAIT_YIELD and pass wxTHREAD_WAIT_BLOCK to wxThread method explicitly.

Function Documentation

◆ wxIsMainThread()

bool wxIsMainThread ( )

Returns true if this thread is the main one.

Always returns true if wxUSE_THREADS is 0.

Include file:

#include <wx/thread.h> 

◆ wxMutexGuiEnter()

void wxMutexGuiEnter ( )

This function must be called when any thread other than the main GUI thread wants to get access to the GUI library.

This function will block the execution of the calling thread until the main thread (or any other thread holding the main GUI lock) leaves the GUI library and no other thread will enter the GUI library until the calling thread calls wxMutexGuiLeave().

Typically, these functions are used like this:

void MyThread::Foo(void)
{
// before doing any GUI calls we must ensure that
// this thread is the only one doing it!
// Call GUI here:
my_window->DrawSomething();
}
void wxMutexGuiEnter()
This function must be called when any thread other than the main GUI thread wants to get access to th...
void wxMutexGuiLeave()
This function is only defined on platforms which support preemptive threads.

This function is only defined on platforms which support preemptive threads and only works under some ports (wxMSW currently).

Note
Under GTK, no creation of top-level windows is allowed in any thread but the main one.

Include file:

#include <wx/thread.h> 

◆ wxMutexGuiLeave()

void wxMutexGuiLeave ( )

This function is only defined on platforms which support preemptive threads.

See also
wxMutexGuiEnter()

Include file:

#include <wx/thread.h>