1 /////////////////////////////////////////////////////////////////////////////
4 // Author: Guilhem Lavaux
5 // Modified by: Vadim Zeitlin (modifications partly inspired by omnithreads
6 // package from Olivetti & Oracle Research Laboratory)
9 // Copyright: (c) Guilhem Lavaux
10 // Licence: wxWindows licence
11 /////////////////////////////////////////////////////////////////////////////
16 // ----------------------------------------------------------------------------
18 // ----------------------------------------------------------------------------
20 // get the value of wxUSE_THREADS configuration flag
24 /* otherwise we get undefined references for non-thread case (KB)*/
26 #pragma interface "thread.h"
29 // Windows headers define it
34 #include "wx/module.h"
36 // ----------------------------------------------------------------------------
38 // ----------------------------------------------------------------------------
43 wxMUTEX_DEAD_LOCK
, // Mutex has been already locked by THE CALLING thread
44 wxMUTEX_BUSY
, // Mutex has been already locked by ONE thread
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
58 // defines the interval of priority
59 #define WXTHREAD_MIN_PRIORITY 0u
60 #define WXTHREAD_DEFAULT_PRIORITY 50u
61 #define WXTHREAD_MAX_PRIORITY 100u
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 // ----------------------------------------------------------------------------
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
76 // constructor & destructor
82 // Try to lock the mutex: if it can't, returns immediately with an error.
83 wxMutexError
TryLock();
85 wxMutexError
Unlock();
87 // Returns true if the mutex is locked.
88 bool IsLocked() const { return (m_locked
> 0); }
91 friend class wxCondition
;
93 // no assignment operator nor copy ctor
94 wxMutex(const wxMutex
&);
95 wxMutex
& operator=(const wxMutex
&);
98 wxMutexInternal
*p_internal
;
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
107 // lock the mutex in the ctor
108 wxMutexLocker(wxMutex
& mutex
) : m_mutex(mutex
)
109 { m_isOk
= m_mutex
.Lock() == wxMUTEX_NO_ERROR
; }
111 // returns TRUE if mutex was successfully locked in ctor
115 // unlock the mutex in dtor
117 { if ( IsOk() ) m_mutex
.Unlock(); }
120 // no assignment operator nor copy ctor
121 wxMutexLocker(const wxMutexLocker
&);
122 wxMutexLocker
& operator=(const wxMutexLocker
&);
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
133 // ----------------------------------------------------------------------------
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
141 #define WXCRITICAL_INLINE inline
144 // you should consider wxCriticalSectionLocker whenever possible instead of
145 // directly working with wxCriticalSection class - it is safer
146 class WXDLLEXPORT wxCriticalSection
150 WXCRITICAL_INLINE
wxCriticalSection();
151 WXCRITICAL_INLINE
~wxCriticalSection();
153 // enter the section (the same as locking a mutex)
154 WXCRITICAL_INLINE
void Enter();
155 // leave the critical section (same as unlocking a mutex)
156 WXCRITICAL_INLINE
void Leave();
159 // no assignment operator nor copy ctor
160 wxCriticalSection(const wxCriticalSection
&);
161 wxCriticalSection
& operator=(const wxCriticalSection
&);
163 #if defined(__WXMSW__) || defined(__WXPM__)
164 wxCriticalSectionInternal
*m_critsect
;
170 // keep your preprocessor name space clean
171 #undef WXCRITICAL_INLINE
173 // wxCriticalSectionLocker is the same to critical sections as wxMutexLocker is
175 class WXDLLEXPORT wxCriticalSectionLocker
178 wxCriticalSectionLocker(wxCriticalSection
& critsect
) : m_critsect(critsect
)
179 { m_critsect
.Enter(); }
180 ~wxCriticalSectionLocker()
181 { m_critsect
.Leave(); }
184 // no assignment operator nor copy ctor
185 wxCriticalSectionLocker(const wxCriticalSectionLocker
&);
186 wxCriticalSectionLocker
& operator=(const wxCriticalSectionLocker
&);
188 wxCriticalSection
& m_critsect
;
191 // ----------------------------------------------------------------------------
192 // Condition handler.
193 // ----------------------------------------------------------------------------
195 class wxConditionInternal
;
196 class WXDLLEXPORT wxCondition
199 // constructor & destructor
203 // Waits indefinitely.
204 void Wait(wxMutex
& mutex
);
205 // Waits until a signal is raised or the timeout is elapsed.
206 bool Wait(wxMutex
& mutex
, unsigned long sec
, unsigned long nsec
);
207 // Raises a signal: only one "Waiter" is released.
209 // Broadcasts to all "Waiters".
213 wxConditionInternal
*p_internal
;
216 // ----------------------------------------------------------------------------
217 // Thread management class
218 // ----------------------------------------------------------------------------
220 // FIXME Thread termination model is still unclear. Delete() should probably
221 // have a timeout after which the thread must be Kill()ed.
223 // NB: in the function descriptions the words "this thread" mean the thread
224 // created by the wxThread object while "main thread" is the thread created
225 // during the process initialization (a.k.a. the GUI thread)
226 class wxThreadInternal
;
227 class WXDLLEXPORT wxThread
230 // the return type for the thread function
231 typedef void *ExitCode
;
234 // Returns the wxThread object for the calling thread. NULL is returned
235 // if the caller is the main thread (but it's recommended to use
236 // IsMain() and only call This() for threads other than the main one
237 // because NULL is also returned on error). If the thread wasn't
238 // created with wxThread class, the returned value is undefined.
239 static wxThread
*This();
241 // Returns true if current thread is the main thread.
242 static bool IsMain();
244 // Release the rest of our time slice leting the other threads run
247 // Sleep during the specified period of time in milliseconds
249 // NB: at least under MSW worker threads can not call ::wxSleep()!
250 static void Sleep(unsigned long milliseconds
);
252 // default constructor
255 // function that change the thread state
256 // create a new thread - call Run() to start it
257 wxThreadError
Create();
259 // starts execution of the thread - from the moment Run() is called the
260 // execution of wxThread::Entry() may start at any moment, caller
261 // shouldn't suppose that it starts after (or before) Run() returns.
264 // stops the thread if it's running and deletes the wxThread object
265 // freeing its memory. This function should also be called if the
266 // Create() or Run() fails to free memory (otherwise it will be done by
267 // the thread itself when it terminates). The return value is the
268 // thread exit code if the thread was gracefully terminated, 0 if it
269 // wasn't running and -1 if an error occured.
272 // kills the thread without giving it any chance to clean up - should
273 // not be used in normal circumstances, use Delete() instead. It is a
274 // dangerous function that should only be used in the most extreme
275 // cases! The wxThread object is deleted by Kill() if thread was
276 // killed (i.e. no errors occured).
277 wxThreadError
Kill();
279 // pause a running thread
280 wxThreadError
Pause();
282 // resume a paused thread
283 wxThreadError
Resume();
286 // Sets the priority to "prio": see WXTHREAD_XXX_PRIORITY constants
288 // NB: the priority can only be set before the thread is created
289 void SetPriority(unsigned int prio
);
291 // Get the current priority.
292 unsigned int GetPriority() const;
294 // Get the thread ID - a platform dependent number which uniquely
295 // identifies a thread inside a process
296 unsigned long GetID() const;
298 // thread status inquiries
299 // Returns true if the thread is alive: i.e. running or suspended
300 bool IsAlive() const;
301 // Returns true if the thread is running (not paused, not killed).
302 bool IsRunning() const;
303 // Returns true if the thread is suspended
304 bool IsPaused() const;
306 // called when the thread exits - in the context of this thread
308 // NB: this function will not be called if the thread is Kill()ed
309 virtual void OnExit() { }
312 // Returns TRUE if the thread was asked to terminate: this function should
313 // be called by the thread from time to time, otherwise the main thread
314 // will be left forever in Delete()!
317 // exits from the current thread - can be called only from this thread
318 void Exit(void *exitcode
= 0);
320 // destructor is private - user code can't delete thread objects, they will
321 // auto-delete themselves (and thus must be always allocated on the heap).
322 // Use Delete() or Kill() instead.
324 // NB: derived classes dtors shouldn't be public neither!
327 // entry point for the thread - called by Run() and executes in the context
329 virtual void *Entry() = 0;
332 // no copy ctor/assignment operator
333 wxThread(const wxThread
&);
334 wxThread
& operator=(const wxThread
&);
336 friend class wxThreadInternal
;
338 // the (platform-dependent) thread class implementation
339 wxThreadInternal
*p_internal
;
341 // protects access to any methods of wxThreadInternal object
342 wxCriticalSection m_critsect
;
345 // ----------------------------------------------------------------------------
346 // Automatic initialization
347 // ----------------------------------------------------------------------------
349 // GUI mutex handling.
350 void WXDLLEXPORT
wxMutexGuiEnter();
351 void WXDLLEXPORT
wxMutexGuiLeave();
353 #else // !wxUSE_THREADS
355 #include "wx/defs.h" // for WXDLLEXPORT
358 inline void WXDLLEXPORT
wxMutexGuiEnter() { }
359 inline void WXDLLEXPORT
wxMutexGuiLeave() { }
361 #endif // wxUSE_THREADS
363 // automatically unlock GUI mutex in dtor
364 class WXDLLEXPORT wxMutexGuiLocker
367 wxMutexGuiLocker() { wxMutexGuiEnter(); }
368 ~wxMutexGuiLocker() { wxMutexGuiLeave(); }
371 // -----------------------------------------------------------------------------
372 // implementation only until the end of file
373 // -----------------------------------------------------------------------------
375 #if defined(__WXMSW__) || defined(__WXPM__)
376 // unlock GUI if there are threads waiting for and lock it back when
377 // there are no more of them - should be called periodically by the main
379 extern void WXDLLEXPORT
wxMutexGuiLeaveOrEnter();
381 // returns TRUE if the main thread has GUI lock
382 extern bool WXDLLEXPORT
wxGuiOwnedByMainThread();
384 // wakes up the main thread if it's sleeping inside ::GetMessage()
385 extern void WXDLLEXPORT
wxWakeUpMainThread();
387 // return TRUE if the main thread is waiting for some other to terminate:
388 // wxApp then should block all "dangerous" messages
389 extern bool WXDLLEXPORT
wxIsWaitingForThread();
391 // implement wxCriticalSection using mutexes
392 inline wxCriticalSection::wxCriticalSection() { }
393 inline wxCriticalSection::~wxCriticalSection() { }
395 inline void wxCriticalSection::Enter() { (void)m_mutex
.Lock(); }
396 inline void wxCriticalSection::Leave() { (void)m_mutex
.Unlock(); }
398 #endif // wxUSE_THREADS
400 #endif // __THREADH__