I changed wxUSE_HTML (and other related wxUSEs) to 1. wxHTML is stable enough and...
[wxWidgets.git] / include / wx / thread.h
0 / 446 (  0%)
CommitLineData
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// ----------------------------------------------------------------------------
17// headers
18// ----------------------------------------------------------------------------
19
20// get the value of wxUSE_THREADS configuration flag
21#include "wx/setup.h"
22
23#if wxUSE_THREADS
24/* otherwise we get undefined references for non-thread case (KB)*/
25#ifdef __GNUG__
26 #pragma interface "thread.h"
27#endif
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
40typedef 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
49typedef 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
72class WXDLLEXPORT wxMutexInternal;
73class WXDLLEXPORT wxMutex
74{
75public:
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
90protected:
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
104class WXDLLEXPORT wxMutexLocker
105{
106public:
107 // lock the mutex in the ctor
108 wxMutexLocker(wxMutex& mutex) : m_mutex(mutex)
109 { m_isOk = m_mutex.Lock() == wxMUTEX_NO_ERROR; }
110
111 // returns TRUE if mutex was successfully locked in ctor
112 bool IsOk() const
113 { return m_isOk; }
114
115 // unlock the mutex in dtor
116 ~wxMutexLocker()
117 { if ( IsOk() ) m_mutex.Unlock(); }
118
119private:
120 // no assignment operator nor copy ctor
121 wxMutexLocker(const wxMutexLocker&);
122 wxMutexLocker& operator=(const wxMutexLocker&);
123
124 bool m_isOk;
125 wxMutex& m_mutex;
126};
127
128// ----------------------------------------------------------------------------
129// Critical section: this is the same as mutex but is only visible to the
130// threads of the same process. For the platforms which don't have native
131// support for critical sections, they're implemented entirely in terms of
132// mutexes
133// ----------------------------------------------------------------------------
134
135// in order to avoid any overhead under !MSW make all wxCriticalSection class
136// functions inline - but this can't be done under MSW
137#if defined(__WXMSW__) || defined(__WXPM__)
138 class WXDLLEXPORT wxCriticalSectionInternal;
139 #define WXCRITICAL_INLINE
140#elif defined(__WXMAC__)
141 class WXDLLEXPORT wxCriticalSectionInternal;
142 #define WXCRITICAL_INLINE
143#else // !MSW && !PM
144 #define WXCRITICAL_INLINE inline
145#endif // MSW/!MSW
146
147// you should consider wxCriticalSectionLocker whenever possible instead of
148// directly working with wxCriticalSection class - it is safer
149class WXDLLEXPORT wxCriticalSection
150{
151public:
152 // ctor & dtor
153 WXCRITICAL_INLINE wxCriticalSection();
154 WXCRITICAL_INLINE ~wxCriticalSection();
155
156 // enter the section (the same as locking a mutex)
157 WXCRITICAL_INLINE void Enter();
158 // leave the critical section (same as unlocking a mutex)
159 WXCRITICAL_INLINE void Leave();
160
161private:
162 // no assignment operator nor copy ctor
163 wxCriticalSection(const wxCriticalSection&);
164 wxCriticalSection& operator=(const wxCriticalSection&);
165
166#if defined(__WXMSW__) || defined(__WXPM__) || defined(__WXMAC__)
167 wxCriticalSectionInternal *m_critsect;
168#else // !MSW
169 wxMutex m_mutex;
170#endif // MSW/!MSW
171};
172
173// keep your preprocessor name space clean
174#undef WXCRITICAL_INLINE
175
176// wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is
177// to th mutexes
178class WXDLLEXPORT wxCriticalSectionLocker
179{
180public:
181 inline wxCriticalSectionLocker(wxCriticalSection& critsect);
182 inline ~wxCriticalSectionLocker();
183
184private:
185 // no assignment operator nor copy ctor
186 wxCriticalSectionLocker(const wxCriticalSectionLocker&);
187 wxCriticalSectionLocker& operator=(const wxCriticalSectionLocker&);
188
189 wxCriticalSection& m_critsect;
190};
191
192// ----------------------------------------------------------------------------
193// Condition handler.
194// ----------------------------------------------------------------------------
195
196class wxConditionInternal;
197class WXDLLEXPORT wxCondition
198{
199public:
200 // constructor & destructor
201 wxCondition();
202 ~wxCondition();
203
204 // Waits indefinitely.
205 void Wait(wxMutex& mutex);
206 // Waits until a signal is raised or the timeout is elapsed.
207 bool Wait(wxMutex& mutex, unsigned long sec, unsigned long nsec);
208 // Raises a signal: only one "Waiter" is released.
209 void Signal();
210 // Broadcasts to all "Waiters".
211 void Broadcast();
212
213private:
214 wxConditionInternal *p_internal;
215};
216
217// ----------------------------------------------------------------------------
218// Thread management class
219// ----------------------------------------------------------------------------
220
221// FIXME Thread termination model is still unclear. Delete() should probably
222// have a timeout after which the thread must be Kill()ed.
223
224// NB: in the function descriptions the words "this thread" mean the thread
225// created by the wxThread object while "main thread" is the thread created
226// during the process initialization (a.k.a. the GUI thread)
227class wxThreadInternal;
228class WXDLLEXPORT wxThread
229{
230public:
231 // the return type for the thread function
232 typedef void *ExitCode;
233
234 // static functions
235 // Returns the wxThread object for the calling thread. NULL is returned
236 // if the caller is the main thread (but it's recommended to use
237 // IsMain() and only call This() for threads other than the main one
238 // because NULL is also returned on error). If the thread wasn't
239 // created with wxThread class, the returned value is undefined.
240 static wxThread *This();
241
242 // Returns true if current thread is the main thread.
243 static bool IsMain();
244
245 // Release the rest of our time slice leting the other threads run
246 static void Yield();
247
248 // Sleep during the specified period of time in milliseconds
249 //
250 // NB: at least under MSW worker threads can not call ::wxSleep()!
251 static void Sleep(unsigned long milliseconds);
252
253 // default constructor
254 wxThread();
255
256 // function that change the thread state
257 // create a new thread - call Run() to start it
258 wxThreadError Create();
259
260 // starts execution of the thread - from the moment Run() is called the
261 // execution of wxThread::Entry() may start at any moment, caller
262 // shouldn't suppose that it starts after (or before) Run() returns.
263 wxThreadError Run();
264
265 // stops the thread if it's running and deletes the wxThread object
266 // freeing its memory. This function should also be called if the
267 // Create() or Run() fails to free memory (otherwise it will be done by
268 // the thread itself when it terminates). The return value is the
269 // thread exit code if the thread was gracefully terminated, 0 if it
270 // wasn't running and -1 if an error occured.
271 ExitCode Delete();
272
273 // kills the thread without giving it any chance to clean up - should
274 // not be used in normal circumstances, use Delete() instead. It is a
275 // dangerous function that should only be used in the most extreme
276 // cases! The wxThread object is deleted by Kill() if thread was
277 // killed (i.e. no errors occured).
278 wxThreadError Kill();
279
280 // pause a running thread
281 wxThreadError Pause();
282
283 // resume a paused thread
284 wxThreadError Resume();
285
286 // priority
287 // Sets the priority to "prio": see WXTHREAD_XXX_PRIORITY constants
288 //
289 // NB: the priority can only be set before the thread is created
290 void SetPriority(unsigned int prio);
291
292 // Get the current priority.
293 unsigned int GetPriority() const;
294
295 // Get the thread ID - a platform dependent number which uniquely
296 // identifies a thread inside a process
297 unsigned long GetID() const;
298
299 // thread status inquiries
300 // Returns true if the thread is alive: i.e. running or suspended
301 bool IsAlive() const;
302 // Returns true if the thread is running (not paused, not killed).
303 bool IsRunning() const;
304 // Returns true if the thread is suspended
305 bool IsPaused() const;
306
307 // called when the thread exits - in the context of this thread
308 //
309 // NB: this function will not be called if the thread is Kill()ed
310 virtual void OnExit() { }
311
312protected:
313 // Returns TRUE if the thread was asked to terminate: this function should
314 // be called by the thread from time to time, otherwise the main thread
315 // will be left forever in Delete()!
316 bool TestDestroy();
317
318 // exits from the current thread - can be called only from this thread
319 void Exit(void *exitcode = 0);
320
321 // destructor is private - user code can't delete thread objects, they will
322 // auto-delete themselves (and thus must be always allocated on the heap).
323 // Use Delete() or Kill() instead.
324 //
325 // NB: derived classes dtors shouldn't be public neither!
326 virtual ~wxThread();
327
328 // entry point for the thread - called by Run() and executes in the context
329 // of this thread.
330 virtual void *Entry() = 0;
331
332private:
333 // no copy ctor/assignment operator
334 wxThread(const wxThread&);
335 wxThread& operator=(const wxThread&);
336
337 friend class wxThreadInternal;
338
339 // the (platform-dependent) thread class implementation
340 wxThreadInternal *p_internal;
341
342 // protects access to any methods of wxThreadInternal object
343 wxCriticalSection m_critsect;
344};
345
346// ----------------------------------------------------------------------------
347// Automatic initialization
348// ----------------------------------------------------------------------------
349
350// GUI mutex handling.
351void WXDLLEXPORT wxMutexGuiEnter();
352void WXDLLEXPORT wxMutexGuiLeave();
353
354// macros for entering/leaving critical sections which may be used without
355// having to take them inside "#if wxUSE_THREADS"
356#define wxENTER_CRIT_SECT(cs) (cs)->Enter()
357#define wxLEAVE_CRIT_SECT(cs) (cs)->Leave()
358#define wxCRIT_SECT_LOCKER(name, cs) wxCriticalSectionLocker name(*cs)
359
360#else // !wxUSE_THREADS
361
362#include "wx/defs.h" // for WXDLLEXPORT
363
364// no thread support
365inline void WXDLLEXPORT wxMutexGuiEnter() { }
366inline void WXDLLEXPORT wxMutexGuiLeave() { }
367
368// macros for entering/leaving critical sections which may be used without
369// having to take them inside "#if wxUSE_THREADS"
370#define wxENTER_CRIT_SECT(cs)
371#define wxLEAVE_CRIT_SECT(cs)
372#define wxCRIT_SECT_LOCKER(name, cs)
373
374#endif // wxUSE_THREADS
375
376// automatically unlock GUI mutex in dtor
377class WXDLLEXPORT wxMutexGuiLocker
378{
379public:
380 wxMutexGuiLocker() { wxMutexGuiEnter(); }
381 ~wxMutexGuiLocker() { wxMutexGuiLeave(); }
382};
383
384// -----------------------------------------------------------------------------
385// implementation only until the end of file
386// -----------------------------------------------------------------------------
387
388#if wxUSE_THREADS
389
390#if defined(__WXMSW__)
391 // unlock GUI if there are threads waiting for and lock it back when
392 // there are no more of them - should be called periodically by the main
393 // thread
394 extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
395
396 // returns TRUE if the main thread has GUI lock
397 extern bool WXDLLEXPORT wxGuiOwnedByMainThread();
398
399 // wakes up the main thread if it's sleeping inside ::GetMessage()
400 extern void WXDLLEXPORT wxWakeUpMainThread();
401
402 // return TRUE if the main thread is waiting for some other to terminate:
403 // wxApp then should block all "dangerous" messages
404 extern bool WXDLLEXPORT wxIsWaitingForThread();
405#elif defined(__WXMAC__)
406 extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
407
408 // returns TRUE if the main thread has GUI lock
409 extern bool WXDLLEXPORT wxGuiOwnedByMainThread();
410
411 // wakes up the main thread if it's sleeping inside ::GetMessage()
412 extern void WXDLLEXPORT wxWakeUpMainThread();
413
414 // return TRUE if the main thread is waiting for some other to terminate:
415 // wxApp then should block all "dangerous" messages
416 extern bool WXDLLEXPORT wxIsWaitingForThread();
417#elif defined(__WXPM__)
418 // unlock GUI if there are threads waiting for and lock it back when
419 // there are no more of them - should be called periodically by the main
420 // thread
421 extern void WXDLLEXPORT wxMutexGuiLeaveOrEnter();
422
423 // returns TRUE if the main thread has GUI lock
424 extern bool WXDLLEXPORT wxGuiOwnedByMainThread();
425 // return TRUE if the main thread is waiting for some other to terminate:
426 // wxApp then should block all "dangerous" messages
427 extern bool WXDLLEXPORT wxIsWaitingForThread();
428#else // !MSW && !PM
429 // implement wxCriticalSection using mutexes
430 inline wxCriticalSection::wxCriticalSection() { }
431 inline wxCriticalSection::~wxCriticalSection() { }
432
433 inline void wxCriticalSection::Enter() { (void)m_mutex.Lock(); }
434 inline void wxCriticalSection::Leave() { (void)m_mutex.Unlock(); }
435#endif // MSW/!MSW
436
437 // we can define these inline functions now (they should be defined after
438 // wxCriticalSection::Enter/Leave)
439 inline
440 wxCriticalSectionLocker:: wxCriticalSectionLocker(wxCriticalSection& cs)
441 : m_critsect(cs) { m_critsect.Enter(); }
442 inline
443 wxCriticalSectionLocker::~wxCriticalSectionLocker() { m_critsect.Leave(); }
444#endif // wxUSE_THREADS
445
446#endif // __THREADH__