# Threads
[Functions and Macros by Category]

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

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

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

|  | [ top ]