]> git.saurik.com Git - wxWidgets.git/blob - include/wx/thread.h
1. wxMotif fixes for compilation in "no compatible" mode
[wxWidgets.git] / include / wx / thread.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: thread.h
3 // Purpose: Thread API
4 // Author: Guilhem Lavaux
5 // Modified by: Vadim Zeitlin (modifications partly inspired by omnithreads
6 // package from Olivetti & Oracle Research Laboratory)
7 // Created: 04/13/98
8 // RCS-ID: $Id$
9 // Copyright: (c) Guilhem Lavaux
10 // Licence: wxWindows licence
11 /////////////////////////////////////////////////////////////////////////////
12
13 #ifndef __THREADH__
14 #define __THREADH__
15
16 #ifdef __GNUG__
17 #pragma interface "thread.h"
18 #endif
19
20 // ----------------------------------------------------------------------------
21 // headers
22 // ----------------------------------------------------------------------------
23
24 // get the value of wxUSE_THREADS configuration flag
25 #include "wx/setup.h"
26
27 #if wxUSE_THREADS
28
29 // Windows headers define it
30 #ifdef Yield
31 #undef Yield
32 #endif
33
34 #include "wx/module.h"
35
36 // ----------------------------------------------------------------------------
37 // constants
38 // ----------------------------------------------------------------------------
39
40 typedef enum
41 {
42 wxMUTEX_NO_ERROR = 0,
43 wxMUTEX_DEAD_LOCK, // Mutex has been already locked by THE CALLING thread
44 wxMUTEX_BUSY, // Mutex has been already locked by ONE thread
45 wxMUTEX_UNLOCKED,
46 wxMUTEX_MISC_ERROR
47 } wxMutexError;
48
49 typedef enum
50 {
51 wxTHREAD_NO_ERROR = 0, // No error
52 wxTHREAD_NO_RESOURCE, // No resource left to create a new thread
53 wxTHREAD_RUNNING, // The thread is already running
54 wxTHREAD_NOT_RUNNING, // The thread isn't running
55 wxTHREAD_MISC_ERROR // Some other error
56 } wxThreadError;
57
58 // defines the interval of priority
59 #define WXTHREAD_MIN_PRIORITY 0u
60 #define WXTHREAD_DEFAULT_PRIORITY 50u
61 #define WXTHREAD_MAX_PRIORITY 100u
62
63 // ----------------------------------------------------------------------------
64 // A mutex object is a synchronization object whose state is set to signaled
65 // when it is not owned by any thread, and nonsignaled when it is owned. Its
66 // name comes from its usefulness in coordinating mutually-exclusive access to
67 // a shared resource. Only one thread at a time can own a mutex object.
68 // ----------------------------------------------------------------------------
69
70 // you should consider wxMutexLocker whenever possible instead of directly
71 // working with wxMutex class - it is safer
72 class WXDLLEXPORT wxMutexInternal;
73 class WXDLLEXPORT wxMutex
74 {
75 public:
76 // constructor & destructor
77 wxMutex();
78 ~wxMutex();
79
80 // Lock the mutex.
81 wxMutexError Lock();
82 // Try to lock the mutex: if it can't, returns immediately with an error.
83 wxMutexError TryLock();
84 // Unlock the mutex.
85 wxMutexError Unlock();
86
87 // Returns true if the mutex is locked.
88 bool IsLocked() const { return (m_locked > 0); }
89
90 protected:
91 friend class wxCondition;
92
93 // no assignment operator nor copy ctor
94 wxMutex(const wxMutex&);
95 wxMutex& operator=(const wxMutex&);
96
97 int m_locked;
98 wxMutexInternal *p_internal;
99 };
100
101 // a helper class which locks the mutex in the ctor and unlocks it in the dtor:
102 // this ensures that mutex is always unlocked, even if the function returns or
103 // throws an exception before it reaches the end
104 class WXDLLEXPORT wxMutexLocker
105 {
106 public:
107 // lock the mutex in the ctor
108 wxMutexLocker(wxMutex *mutex)
109 { m_isOk = mutex && ((m_mutex = mutex)->Lock() == wxMUTEX_NO_ERROR); }
110
111 // returns TRUE if mutex was successfully locked in ctor
112 bool IsOk() const { return m_isOk; }
113
114 // unlock the mutex in dtor
115 ~wxMutexLocker() { if ( IsOk() ) m_mutex->Unlock(); }
116
117 private:
118 // no assignment operator nor copy ctor
119 wxMutexLocker(const wxMutexLocker&);
120 wxMutexLocker& operator=(const wxMutexLocker&);
121
122 bool m_isOk;
123 wxMutex *m_mutex;
124 };
125
126 // ----------------------------------------------------------------------------
127 // Critical section: this is the same as mutex but is only visible to the
128 // threads of the same process. For the platforms which don't have native
129 // support for critical sections, they're implemented entirely in terms of
130 // mutexes
131 // ----------------------------------------------------------------------------
132
133 // in order to avoid any overhead under !MSW make all wxCriticalSection class
134 // functions inline - but this can't be done under MSW
135 #ifdef __WXMSW__
136 class WXDLLEXPORT wxCriticalSectionInternal;
137 #define WXCRITICAL_INLINE
138 #else // !MSW
139 #define WXCRITICAL_INLINE inline
140 #endif // MSW/!MSW
141
142 // you should consider wxCriticalSectionLocker whenever possible instead of
143 // directly working with wxCriticalSection class - it is safer
144 class WXDLLEXPORT wxCriticalSection
145 {
146 public:
147 // ctor & dtor
148 WXCRITICAL_INLINE wxCriticalSection();
149 WXCRITICAL_INLINE ~wxCriticalSection();
150
151 // enter the section (the same as locking a mutex)
152 void WXCRITICAL_INLINE Enter();
153 // leave the critical section (same as unlocking a mutex)
154 void WXCRITICAL_INLINE Leave();
155
156 private:
157 // no assignment operator nor copy ctor
158 wxCriticalSection(const wxCriticalSection&);
159 wxCriticalSection& operator=(const wxCriticalSection&);
160
161 #ifdef __WXMSW__
162 wxCriticalSectionInternal *m_critsect;
163 #else // !MSW
164 wxMutex m_mutex;
165 #endif // MSW/!MSW
166 };
167
168 // keep your preprocessor name space clean
169 #undef WXCRITICAL_INLINE
170
171 // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is
172 // to th mutexes
173 class WXDLLEXPORT wxCriticalSectionLocker
174 {
175 public:
176 wxCriticalSectionLocker(wxCriticalSection& critsect) : m_critsect(critsect)
177 { m_critsect.Enter(); }
178 ~wxCriticalSectionLocker()
179 { m_critsect.Leave(); }
180
181 private:
182 // no assignment operator nor copy ctor
183 wxCriticalSectionLocker(const wxCriticalSectionLocker&);
184 wxCriticalSectionLocker& operator=(const wxCriticalSectionLocker&);
185
186 wxCriticalSection& m_critsect;
187 };
188
189 // ----------------------------------------------------------------------------
190 // Condition handler.
191 // ----------------------------------------------------------------------------
192
193 class wxConditionInternal;
194 class WXDLLEXPORT wxCondition
195 {
196 public:
197 // constructor & destructor
198 wxCondition();
199 ~wxCondition();
200
201 // Waits indefinitely.
202 void Wait(wxMutex& mutex);
203 // Waits until a signal is raised or the timeout is elapsed.
204 bool Wait(wxMutex& mutex, unsigned long sec, unsigned long nsec);
205 // Raises a signal: only one "Waiter" is released.
206 void Signal();
207 // Broadcasts to all "Waiters".
208 void Broadcast();
209
210 private:
211 wxConditionInternal *p_internal;
212 };
213
214 // ----------------------------------------------------------------------------
215 // Thread management class
216 // ----------------------------------------------------------------------------
217
218 // FIXME Thread termination model is still unclear. Delete() should probably
219 // have a timeout after which the thread must be Kill()ed.
220
221 // NB: in the function descriptions the words "this thread" mean the thread
222 // created by the wxThread object while "main thread" is the thread created
223 // during the process initialization (a.k.a. the GUI thread)
224 class wxThreadInternal;
225 class WXDLLEXPORT wxThread
226 {
227 public:
228 // the return type for the thread function
229 typedef void *ExitCode;
230
231 // static functions
232 // Returns the wxThread object for the calling thread. NULL is returned
233 // if the caller is the main thread (but it's recommended to use
234 // IsMain() and only call This() for threads other than the main one
235 // because NULL is also returned on error). If the thread wasn't
236 // created with wxThread class, the returned value is undefined.
237 static wxThread *This();
238
239 // Returns true if current thread is the main thread.
240 static bool IsMain();
241
242 // Release the rest of our time slice leting the other threads run
243 static void Yield();
244
245 // Sleep during the specified period of time in milliseconds
246 //
247 // NB: at least under MSW worker threads can not call ::wxSleep()!
248 static void Sleep(unsigned long milliseconds);
249
250 // default constructor
251 wxThread();
252
253 // function that change the thread state
254 // create a new thread - call Run() to start it
255 wxThreadError Create();
256
257 // starts execution of the thread - from the moment Run() is called the
258 // execution of wxThread::Entry() may start at any moment, caller
259 // shouldn't suppose that it starts after (or before) Run() returns.
260 wxThreadError Run();
261
262 // stops the thread if it's running and deletes the wxThread object
263 // freeing its memory. This function should also be called if the
264 // Create() or Run() fails to free memory (otherwise it will be done by
265 // the thread itself when it terminates). The return value is the
266 // thread exit code if the thread was gracefully terminated, 0 if it
267 // wasn't running and -1 if an error occured.
268 ExitCode Delete();
269
270 // kills the thread without giving it any chance to clean up - should
271 // not be used in normal circumstances, use Delete() instead. It is a
272 // dangerous function that should only be used in the most extreme
273 // cases! The wxThread object is deleted by Kill() if thread was
274 // killed (i.e. no errors occured).
275 wxThreadError Kill();
276
277 // pause a running thread
278 wxThreadError Pause();
279
280 // resume a paused thread
281 wxThreadError Resume();
282
283 // priority
284 // Sets the priority to "prio": see WXTHREAD_XXX_PRIORITY constants
285 //
286 // NB: the priority can only be set before the thread is created
287 void SetPriority(unsigned int prio);
288
289 // Get the current priority.
290 unsigned int GetPriority() const;
291
292 // Get the thread ID - a platform dependent number which uniquely
293 // identifies a thread inside a process
294 unsigned long GetID() const;
295
296 // thread status inquiries
297 // Returns true if the thread is alive: i.e. running or suspended
298 bool IsAlive() const;
299 // Returns true if the thread is running (not paused, not killed).
300 bool IsRunning() const;
301 // Returns true if the thread is suspended
302 bool IsPaused() const { return IsAlive() && !IsRunning(); }
303
304 // called when the thread exits - in the context of this thread
305 //
306 // NB: this function will not be called if the thread is Kill()ed
307 virtual void OnExit() { }
308
309 protected:
310 // Returns TRUE if the thread was asked to terminate: this function should
311 // be called by the thread from time to time, otherwise the main thread
312 // will be left forever in Delete()!
313 bool TestDestroy() const;
314
315 // exits from the current thread - can be called only from this thread
316 void Exit(void *exitcode = 0);
317
318 // destructor is private - user code can't delete thread objects, they will
319 // auto-delete themselves (and thus must be always allocated on the heap).
320 // Use Delete() or Kill() instead.
321 //
322 // NB: derived classes dtors shouldn't be public neither!
323 virtual ~wxThread();
324
325 // entry point for the thread - called by Run() and executes in the context
326 // of this thread.
327 virtual void *Entry() = 0;
328
329 private:
330 // no copy ctor/assignment operator
331 wxThread(const wxThread&);
332 wxThread& operator=(const wxThread&);
333
334 friend class wxThreadInternal;
335
336 // the (platform-dependent) thread class implementation
337 wxThreadInternal *p_internal;
338
339 // protects access to any methods of wxThreadInternal object
340 wxCriticalSection m_critsect;
341 };
342
343 // ----------------------------------------------------------------------------
344 // Automatic initialization
345 // ----------------------------------------------------------------------------
346
347 // GUI mutex handling.
348 void WXDLLEXPORT wxMutexGuiEnter();
349 void WXDLLEXPORT wxMutexGuiLeave();
350
351 #else // !wxUSE_THREADS
352
353 // no thread support
354 inline void WXDLLEXPORT wxMutexGuiEnter() { }
355 inline void WXDLLEXPORT wxMutexGuiLeave() { }
356
357 #endif // wxUSE_THREADS
358
359 // automatically unlock GUI mutex in dtor
360 class WXDLLEXPORT wxMutexGuiLocker
361 {
362 public:
363 wxMutexGuiLocker() { wxMutexGuiEnter(); }
364 ~wxMutexGuiLocker() { wxMutexGuiLeave(); }
365 };
366
367 // -----------------------------------------------------------------------------
368 // implementation only until the end of file
369 // -----------------------------------------------------------------------------
370 #ifdef wxUSE_THREADS
371 #ifdef __WXMSW__
372 // unlock GUI if there are threads waiting for and lock it back when
373 // there are no more of them - should be called periodically by the main
374 // thread
375 extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
376
377 // returns TRUE if the main thread has GUI lock
378 extern bool WXDLLEXPORT wxGuiOwnedByMainThread();
379
380 // wakes up the main thread if it's sleeping inside ::GetMessage()
381 extern void WXDLLEXPORT wxWakeUpMainThread();
382
383 // return TRUE if the main thread is waiting for some other to terminate:
384 // wxApp then should block all "dangerous" messages
385 extern bool WXDLLEXPORT wxIsWaitingForThread();
386 #else // !MSW
387 // implement wxCriticalSection using mutexes
388 inline wxCriticalSection::wxCriticalSection() { }
389 inline wxCriticalSection::~wxCriticalSection() { }
390
391 inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); }
392 inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); }
393 #endif // MSW/!MSW
394 #endif // wxUSE_THREADS
395
396 #endif // __THREADH__