]>
Commit | Line | Data |
---|---|---|
1 | \section{\class{wxThread}}\label{wxthread} | |
2 | ||
3 | A thread is basically a path of execution through a program. Threads are also | |
4 | sometimes called {\it light-weight processes}, but the fundamental difference | |
5 | between threads and processes is that memory spaces of different processes are | |
6 | separated while all threads share the same address space. While it makes it | |
7 | much easier to share common data between several threads, it also makes much | |
8 | easier to shoot oneself in the foot, so careful use of synchronization objects | |
9 | such as \helpref{mutexes}{wxmutex} and/or \helpref{critical sections}{wxcriticalsection} is recommended. | |
10 | ||
11 | \wxheading{Derived from} | |
12 | ||
13 | None. | |
14 | ||
15 | \wxheading{Include files} | |
16 | ||
17 | <wx/thread.h> | |
18 | ||
19 | \wxheading{See also} | |
20 | ||
21 | \helpref{wxMutex}{wxmutex}, \helpref{wxCondition}{wxcondition}, \helpref{wxCriticalSection}{wxcriticalsection} | |
22 | ||
23 | \latexignore{\rtfignore{\wxheading{Members}}} | |
24 | ||
25 | \membersection{wxThread::wxThread}\label{wxthreadctor} | |
26 | ||
27 | \func{}{wxThread}{\void} | |
28 | ||
29 | Default constructor: it doesn't create nor starts the thread. | |
30 | ||
31 | \membersection{wxThread::\destruct{wxThread}} | |
32 | ||
33 | \func{}{\destruct{wxThread}}{\void} | |
34 | ||
35 | wxThread destructor is private, so you can not call it directly - i.e., deleting | |
36 | wxThread objects is forbidden. Instead, you should use \helpref{Delete}{wxthreaddelete} or | |
37 | \helpref{Kill}{wxthreadkill} methods. This also means that thread objects should | |
38 | eb {\bf always} allocated on the heap (i.e. with {\it new}) because the functions | |
39 | mentioned above will try to reclaim the storage from the heap. | |
40 | ||
41 | \membersection{wxThread::Create}\label{wxthreadcreate} | |
42 | ||
43 | \func{wxThreadError}{Create}{\void} | |
44 | ||
45 | Creates a new thread. The thread object is created in the suspended state, you | |
46 | should call \helpref{Run}{wxthreadrun} to start running it. | |
47 | ||
48 | \wxheading{Return value} | |
49 | ||
50 | One of: | |
51 | ||
52 | \twocolwidtha{7cm} | |
53 | \begin{twocollist}\itemsep=0pt | |
54 | \twocolitem{{\bf wxTHREAD\_NO\_ERROR}}{There was no error.} | |
55 | \twocolitem{{\bf wxTHREAD\_NO\_RESOURCE}}{There were insufficient resources to create a new thread.} | |
56 | \twocolitem{{\bf wxTHREAD\_RUNNING}}{The thread is already running.} | |
57 | \end{twocollist} | |
58 | ||
59 | \membersection{wxThread::Delete}\label{wxthreaddelete} | |
60 | ||
61 | \func{\void}{Delete}{\void} | |
62 | ||
63 | This function should be called to terminate this thread. Unlike \helpref{Kill}{wxthreadkill}, it | |
64 | gives the target thread the time to terminate gracefully. Because of this, however, this function | |
65 | may not return immediately and if the thread is "hung" won't return at all. Also, message processing | |
66 | is not stopped during this function execution, so the message handlers may be called from inside | |
67 | it. | |
68 | ||
69 | Delete() may be called for thread in any state: running, paused or even not yet created. Moreover, | |
70 | it must be called if \helpref{Create}{wxthreadcreate} or \helpref{Run}{wxthreadrun} fail to free | |
71 | the memory occupied by the thread object. | |
72 | ||
73 | \membersection{wxThread::GetID}\label{wxthreadgetid} | |
74 | ||
75 | \constfunc{unsigned long}{GetID}{\void} | |
76 | ||
77 | Gets the thread identifier: this is a platform dependent number which uniquely identifies the | |
78 | thread throughout the system during its existence (i.e. the thread identifiers may be reused). | |
79 | ||
80 | \membersection{wxThread::GetPriority}\label{wxthreadgetpriority} | |
81 | ||
82 | \constfunc{int}{GetPriority}{\void} | |
83 | ||
84 | Gets the priority of the thread, between zero and 100. | |
85 | ||
86 | The following priorities are already defined: | |
87 | ||
88 | \twocolwidtha{7cm} | |
89 | \begin{twocollist}\itemsep=0pt | |
90 | \twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0} | |
91 | \twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50} | |
92 | \twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100} | |
93 | \end{twocollist} | |
94 | ||
95 | \membersection{wxThread::IsAlive}\label{wxthreadisalive} | |
96 | ||
97 | \constfunc{bool}{IsAlive}{\void} | |
98 | ||
99 | Returns TRUE if the thread is alive (i.e. started and not terminating). | |
100 | ||
101 | \membersection{wxThread::IsMain}\label{wxthreadismain} | |
102 | ||
103 | \constfunc{bool}{IsMain}{\void} | |
104 | ||
105 | Returns TRUE if the calling thread is the main application thread. | |
106 | ||
107 | \membersection{wxThread::IsPaused}\label{wxthreadispaused} | |
108 | ||
109 | \constfunc{bool}{IsPaused}{\void} | |
110 | ||
111 | Returns TRUE if the thread is paused. | |
112 | ||
113 | \membersection{wxThread::IsRunning}\label{wxthreadisrunning} | |
114 | ||
115 | \constfunc{bool}{IsRunning}{\void} | |
116 | ||
117 | Returns TRUE if the thread is running. | |
118 | ||
119 | \membersection{wxThread::Kill}\label{wxthreadkill} | |
120 | ||
121 | \func{wxThreadError}{Kill}{\void} | |
122 | ||
123 | Immediately terminates the target thread. {\bf This function is dangerous and should | |
124 | be used with extreme care (and not used at all whenever possible)!} The resources | |
125 | allocated to the thread will not be freed and the state of the C runtime library | |
126 | may become inconsistent. Use \helpref{Delete()}{wxthreaddelete} instead. | |
127 | ||
128 | \membersection{wxThread::OnExit}\label{wxthreadonexit} | |
129 | ||
130 | \func{void}{OnExit}{\void} | |
131 | ||
132 | Called when the thread exits. This function is called in the context of the thread | |
133 | associated with the wxThread object, not in the context of the main thread. | |
134 | ||
135 | \membersection{wxThread::Run}\label{wxthreadrun} | |
136 | ||
137 | \func{wxThreadError}{Run}{\void} | |
138 | ||
139 | Runs the thread. | |
140 | ||
141 | \membersection{wxThread::SetPriority}\label{wxthreadsetpriority} | |
142 | ||
143 | \func{void}{SetPriority}{\param{int}{ priority}} | |
144 | ||
145 | Sets the priority of the thread, between zero and 100. This must be set before the thread is created. | |
146 | ||
147 | The following priorities are already defined: | |
148 | ||
149 | \twocolwidtha{7cm} | |
150 | \begin{twocollist}\itemsep=0pt | |
151 | \twocolitem{{\bf WXTHREAD\_MIN\_PRIORITY}}{0} | |
152 | \twocolitem{{\bf WXTHREAD\_DEFAULT\_PRIORITY}}{50} | |
153 | \twocolitem{{\bf WXTHREAD\_MAX\_PRIORITY}}{100} | |
154 | \end{twocollist} | |
155 | ||
156 | \membersection{wxThread::Sleep}\label{wxthreadsleep} | |
157 | ||
158 | \func{\void}{Sleep}{\param{unsigned long }{milliseconds}} | |
159 | ||
160 | Pauses the thread execution for the given amount of time. | |
161 | ||
162 | This function should be used instead of \helpref{wxSleep}{wxsleep} by all worker | |
163 | (i.e. all except the main one) threads. | |
164 | ||
165 | \membersection{wxThread::This}\label{wxthreadthis} | |
166 | ||
167 | \func{wxThread *}{This}{\void} | |
168 | ||
169 | Return the thread object for the calling thread. NULL is returned if the calling thread | |
170 | is the main (GUI) thread, but \helpref{IsMain}{wxthreadismain} should be used to test | |
171 | whether the thread is really the main one because NULL may also be returned for the thread | |
172 | not created with wxThread class. Generally speaking, the return value for such thread | |
173 | is undefined. | |
174 | ||
175 | \membersection{wxThread::Yield}\label{wxthreadyield} | |
176 | ||
177 | \func{\void}{Yield}{\void} | |
178 | ||
179 | Give the rest of the thread time slice to the system allowing the other threads to run. | |
180 | See also \helpref{Sleep()}{wxthreadsleep}. | |
181 |