docs/latex/wx/threadh.tex

   1 \section{\class{wxThreadHelper}}\label{wxthreadhelper}
   2
   3 The wxThreadHelper class is a mix-in class that manages a single background
   4 thread.  By deriving from wxThreadHelper, a class can implement the thread
   5 code in its own \helpref{wxThreadHelper::Entry}{wxthreadhelperentry} method
   6 and easily share data and synchronization objects between the main thread
   7 and the worker thread.  Doing this prevents the awkward passing of pointers
   8 that is needed when the original object in the main thread needs to
   9 synchronize with its worker thread in its own wxThread derived object.
  10
  11 For example, \helpref{wxFrame}{wxframe} may need to make some calculations
  12 in a background thread and then display the results of those calculations in
  13 the main window.
  14
  15 Ordinarily, a \helpref{wxThread}{wxthread} derived object would be created
  16 with the calculation code implemented in
  17 \helpref{wxThread::Entry}{wxthreadentry}.  To access the inputs to the
  18 calculation, the frame object would often to pass a pointer to itself to the
  19 thread object.  Similarly, the frame object would hold a pointer to the
  20 thread object.  Shared data and synchronization objects could be stored in
  21 either object though the object without the data would have to access the
  22 data through a pointer.
  23
  24 However, with wxThreadHelper, the frame object and the thread object are
  25 treated as the same object.  Shared data and synchronization variables are
  26 stored in the single object, eliminating a layer of indirection and the
  27 associated pointers.
  28
  29 \wxheading{Derived from}
  30
  31 None.
  32
  33 \wxheading{Include files}
  34
  35 <wx/thread.h>
  36
  37 \wxheading{Library}
  38
  39 \helpref{wxBase}{librarieslist}
  40
  41 \wxheading{See also}
  42
  43 \helpref{wxThread}{wxthread}
  44
  45 \latexignore{\rtfignore{\wxheading{Members}}}
  46
  47 \membersection{wxThreadHelper::wxThreadHelper}\label{wxthreadhelperctor}
  48
  49 \func{}{wxThreadHelper}{\void}
  50
  51 This constructor simply initializes a member variable.
  52
  53 \membersection{wxThreadHelper::m\_thread}\label{wxthreadhelpermthread}
  54
  55 \member{wxThread *}{m\_thread}
  56
  57 the actual \helpref{wxThread}{wxthread} object.
  58
  59 \membersection{wxThreadHelper::\destruct{wxThreadHelper}}\label{wxthreadhelperdtor}
  60
  61 \func{}{\destruct{wxThreadHelper}}{\void}
  62
  63 The destructor frees the resources associated with the thread.
  64
  65 \membersection{wxThreadHelper::Create}\label{wxthreadhelpercreate}
  66
  67 \func{wxThreadError}{Create}{\param{unsigned int }{stackSize = 0}}
  68
  69 Creates a new thread. The thread object is created in the suspended state, and you
  70 should call \helpref{GetThread()->Run()}{wxthreadrun} to start running
  71 it.  You may optionally specify the stack size to be allocated to it (Ignored on
  72 platforms that don't support setting it explicitly, eg. Unix).
  73
  74 \wxheading{Return value}
  75
  76 One of:
  77
  78 \twocolwidtha{7cm}
  79 \begin{twocollist}\itemsep=0pt
  80 \twocolitem{{\bf wxTHREAD\_NO\_ERROR}}{There was no error.}
  81 \twocolitem{{\bf wxTHREAD\_NO\_RESOURCE}}{There were insufficient resources to create a new thread.}
  82 \twocolitem{{\bf wxTHREAD\_RUNNING}}{The thread is already running.}
  83 \end{twocollist}
  84
  85 \membersection{wxThreadHelper::Entry}\label{wxthreadhelperentry}
  86
  87 \func{virtual ExitCode}{Entry}{\void}
  88
  89 This is the entry point of the thread. This function is pure virtual and must
  90 be implemented by any derived class. The thread execution will start here.
  91
  92 The returned value is the thread exit code which is only useful for
  93 joinable threads and is the value returned by
  94 \helpref{GetThread()->Wait()}{wxthreadwait}.
  95
  96 This function is called by wxWidgets itself and should never be called
  97 directly.
  98
  99 \membersection{wxThreadHelper::GetThread}\label{wxthreadhelpergetthread}
 100
 101 \func{wxThread *}{GetThread}{\void}
 102
 103 This is a public function that returns the \helpref{wxThread}{wxthread} object
 104 associated with the thread.
 105