Threads

Detailed Description

The functions and macros here mainly exist to make it possible to write 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.

See Also

wxThread, wxMutex, Multithreading Overview

Related class group: Threading

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.

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

#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> 

#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> 

#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> 

#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;

    wxCRITICAL_SECTION(counter);

    return ++s_counter;
}

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> 

#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> 

#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> 

Function Documentation

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> 

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

void wxMutexGuiLeave

(

)

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

See Also

wxMutexGuiEnter()

Include file:

#include <wx/thread.h>