Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members

FXThread.h

Go to the documentation of this file.
00001 /********************************************************************************
00002 *                                                                               *
00003 *                   Base type for thread objects                                *
00004 *                                                                               *
00005 *********************************************************************************
00006 * Copyright (C) 2003 by Mathew Robertson.   All Rights Reserved.                *
00007 *********************************************************************************
00008 * This library is free software; you can redistribute it and/or                 *
00009 * modify it under the terms of the GNU Lesser General Public                    *
00010 * License as published by the Free Software Foundation; either                  *
00011 * version 2.1 of the License, or (at your option) any later version.            *
00012 *                                                                               *
00013 * This library is distributed in the hope that it will be useful,               *
00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of                *
00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU             *
00016 * Lesser General Public License for more details.                               *
00017 *                                                                               *
00018 * You should have received a copy of the GNU Lesser General Public              *
00019 * License along with this library; if not, write to the Free Software           *
00020 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.    *
00021 *********************************************************************************/
00022 #ifndef FXTHREAD_H
00023 #define FXTHREAD_H
00024 
00025 #ifndef FXRUNNABLE_H
00026 #include "FXRunnable.h"
00027 #endif
00028 namespace FXEX {
00029 class FXAtomicInt;
00030 
00031 /**
00032  * Thread base class for worker thread objects.
00033  *
00034  * The idea here is that you derive from this class, to create your wroker thread.
00035  * Facilities are provided to:
00036  * a) start the thread, from another thread
00037  * b) request a stop from another thread.
00038  *
00039  * Note, the stop functionality only provides a facility to 'request' a stop of a thread.
00040  * There isn't an implementation that I can think of (in a working program) where forcibly stopping
00041  * a thread is a good thing...  As such, it is up to the worker thread to periodically
00042  * poll the status of the 'stopThread' variable, to find out if another thread (ie the main
00043  * thread) has asked the worker thread to stop.  This is reasonably important, since the
00044  * owner thread will wait for the worker thread to stop before it will completely destruct.
00045  *
00046  * Your derived class only need to implement the 'run()' method.  This method is started in
00047  * a worker thread when you call start() on the object.  If you need to pass parameters to
00048  * the worker thread, just create set/get methods in your derived class (which then sets/gets
00049  * the parameter that you want access to).
00050  *
00051  * To facilitate simple access to class local variables, the FXThread class inherits a
00052  * mutex (call 'mutex') from the FXRunnable class.  Your accessor methods then simply needs
00053  * to either:
00054  * a) call lock()/unlock() on the mutex
00055  * b) use the FXSynchronise object to auto-lock/unlock the mutex
00056  *
00057  * Alternatively you could use the FXAtomic data types, which provide implicit lock/unlock
00058  * calls for each of its accessor methods.  This technique is used internally within the
00059  * FXAtomicDataTarget class to create a FOX DataTarget which works across threads.
00060  */
00061 class FXAPI FXThread : public FXRunnable {
00062   FXDECLARE_ABSTRACT(FXThread)
00063 
00064 private:
00065   FXThread(const FXThread&);
00066   FXThread& operator=(const FXThread&);
00067 
00068 private:
00069   FXThreadHandle thread;     // the thread
00070 
00071 protected:
00072   FXAtomicInt *stopThread;
00073 
00074 public:
00075   enum {
00076     ID_STOP=FXRunnable::ID_LAST,
00077     ID_LAST
00078     };
00079 
00080 public:
00081   long onStop(FXObject*,FXSelector,void*);
00082   long onCmdGetIntValue(FXObject*,FXSelector,void*);
00083   long onCmdSetIntValue(FXObject*,FXSelector,void*);
00084 
00085 public:
00086   /// You dont normally need to call these, they are used internally but must be public
00087 
00088   /// Reset the thread object, so that it can be re-used
00089   void reset();
00090 
00091   /// you are meant to overload this in your child thread classes...
00092   virtual void run()=0;
00093 
00094 protected:
00095   /// This is the ctor you need when you sub-class FXThread
00096   FXThread(FXObject *tgt=NULL,FXSelector sel=0);
00097 
00098   /// yield the thread - allows other threads/processes to access the CPU
00099   void yield();
00100 
00101 public:
00102   /// start running the object
00103   void start();
00104 
00105   /// request to stop the thread - the thread can ignore this
00106   void stop();
00107 
00108   /// is thread curently running?
00109   FXbool isRunning();
00110 
00111   /// dtor
00112   virtual ~FXThread();
00113   };
00114 
00115 }; // namespace FXEX
00116 #endif // FXTHREAD_H
00117