Thread functions

The functions and macros here mainly exist to make it writing the code which may be compiled in multi thread build (wxUSE_THREADS = 1) as well as in single thread configuration (wxUSE_THREADS = 0).

For example, a static variable must be protected against simultaneous access by multiple threads in the former configuration but in the latter the extra overhead of using the critical section is not needed. To solve this problem, the wxCRITICAL_SECTION macro may be used to create and use the critical section only when needed.

Include files

<wx/thread.h>

See also

wxThread, wxMutex, Multithreading overview

wxCRIT_SECT_DECLARE
wxCRIT_SECT_DECLARE_MEMBER
wxCRIT_SECT_LOCKER
wxCRITICAL_SECTION
wxENTER_CRIT_SECT
::wxIsMainThread
wxLEAVE_CRIT_SECT
::wxMutexGuiEnter
::wxMutexGuiLeave

wxCRIT_SECT_DECLARE

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.

wxCRIT_SECT_DECLARE_MEMBER

wxCRIT_SECT_DECLARE(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.

wxCRIT_SECT_LOCKER

wxCRIT_SECT_LOCKER(name, cs)

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

wxCRITICAL_SECTION

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;

    wxCRITICAL_SECTION(counter);

    return ++s_counter;
}

wxENTER_CRIT_SECT

wxENTER_CRIT_SECT(wxCriticalSection& cs)

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

::wxIsMainThread

bool wxIsMainThread()

Returns true if this thread is the main one. Always returns true if wxUSE_THREADS is 0.

wxLEAVE_CRIT_SECT

wxLEAVE_CRIT_SECT(wxCriticalSection& cs)

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

::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!

    wxMutexGuiEnter();

    // Call GUI here:
    my_window->DrawSomething();

    wxMutexGuiLeave();
}

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

::wxMutexGuiLeave

void wxMutexGuiLeave()

See ::wxMutexGuiEnter().

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