casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
PlotMSThread.qo.h
Go to the documentation of this file.
00001 //# PlotMSThread.qo.h: Threading classes for PlotMS.
00002 //# Copyright (C) 2009
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: $
00027 #ifndef PLOTMSTHREAD_QO_H_
00028 #define PLOTMSTHREAD_QO_H_
00029 
00030 #include <graphics/GenericPlotter/PlotOperation.h>
00031 
00032 #include <QMutex>
00033 #include <QObject>
00034 #include <QString>
00035 
00036 #include <casa/namespace.h>
00037 
00038 namespace casa {
00039 
00040 //# Forward declarations.
00041 class QtProgressWidget;
00042 
00043 
00044 // Typedefs for using post-thread methods.
00045 // <group>
00046 typedef void* PMSPTObject;
00047 typedef void PMSPTMethod(PMSPTObject, bool);
00048 // </group>
00049 
00050 
00051 // Abstract class for a threaded operation for plotms.  PlotMSThread does not
00052 // directly inherit from QThread in case the threading is happening elsewhere
00053 // in the code (such as a plotter implementation that threads its own drawing).
00054 // Classes that want to run PlotMSThreads should:
00055 // 1) Provide a QtProgressWidget in the main (GUI) thread.
00056 // 2) Connect the finishedOperation() signal to a slot as needed.
00057 // 3) Call startOperation() to start the thread.
00058 // 4) Call the post-thread method after completion, if there is one.
00059 class PlotMSThread : public QObject {
00060     Q_OBJECT
00061     
00062 public:
00063     // Constructor which takes the progress widget to use, and an optional
00064     // post-thread method that should be called when the thread is finished.
00065     PlotMSThread(QtProgressWidget* progress,
00066             PMSPTMethod postThreadMethod = NULL,
00067             PMSPTObject postThreadObject = NULL);
00068     
00069     // Destructor.
00070     virtual ~PlotMSThread();
00071     
00072     
00073     // ABSTRACT METHODS //
00074     
00075     // Abstract method which does the operation.  IMPORTANT: subclasses MUST
00076     // emit the finished() signal when finished.
00077     virtual void startOperation() = 0;
00078     
00079     
00080     // IMPLEMENTED METHODS //
00081     
00082     // Method which terminates the operation regardless of whether it has
00083     // finished or not.
00084     virtual void terminateOperation() { cancel(); }
00085       
00086     // Executes the post-thread method as needed.  Does nothing if a
00087     // post-thread method was not set in the constructor.
00088     virtual void postThreadMethod();
00089     
00090 signals:
00091     // This signal MUST be emitted after start() has been called, and when the
00092     // operation has finished.  The thread parameter points to the thread that
00093     // has just completed.
00094     void finishedOperation(PlotMSThread* thread);
00095     
00096     // These signals are used to update the QtProgressWidget across different
00097     // threads.  They shouldn't need to be used by other classes, even
00098     // children.
00099     // <group>
00100     void initializeProgress(const QString& operationName);
00101     void updateProgress(unsigned int progress, const QString& status);
00102     void finalizeProgress();
00103     // </group>
00104     
00105 protected:
00106     // ABSTRACT METHODS //
00107     
00108     // Returns true if the threaded finished due to be canceled, false
00109     // otherwise.
00110     virtual bool wasCanceled() const = 0;
00111     
00112     
00113     // IMPLEMENTED METHODS //
00114     
00115     // Access for subclasses to initialize the progress widget with the given
00116     // operation name.
00117     void initializeProgressWidget(const String& operationName);
00118     
00119     // Access for subclasses to update the progress widget.
00120     void updateProgressWidget(unsigned int progress, const String& status);
00121     
00122     // Access for subclasses to finalize the progress widget.
00123     void finalizeProgressWidget();
00124     
00125     // Access for subclasses to set allowed operations on the progress widget.
00126     void setAllowedOperations(bool background, bool pauseResume, bool cancel);
00127     
00128 protected slots:
00129     // For when the user requests "background" for the thread.
00130     virtual void background() = 0;
00131     
00132     // For when the user requests "pause" for the thread.
00133     virtual void pause() = 0;
00134     
00135     // For when the user requests "resume" for the thread.
00136     virtual void resume() = 0;
00137     
00138     // For when the user requests "cancel" for the thread.
00139     virtual void cancel() = 0;
00140     
00141 private:
00142     // Progress widget.
00143     QtProgressWidget* itsProgressWidget_;
00144     
00145     // Method/Object to run when thread is finished.
00146     // <group>
00147     PMSPTMethod* itsPostThreadMethod_;
00148     PMSPTObject itsPostThreadObject_;
00149     // </group>
00150 };
00151 
00152 
00153 // Implementation of PlotMutex for QThreads using a QMutex.  Note: this is a
00154 // duplication of QPMutex in the QwtPlotter, but this is a small and simple
00155 // class and its re-implementation avoids a dependency on the QwtPlotter.
00156 class PlotMSMutex : public PlotMutex {
00157 public:
00158     // Constructor.
00159     PlotMSMutex() { }
00160     
00161     // Destructor.
00162     ~PlotMSMutex() { }
00163     
00164     
00165     // Implements PlotMutex::lock().
00166     void lock() { itsMutex_.lock(); }
00167     
00168     // Implements PlotMutex::unlock().
00169     void unlock() { itsMutex_.unlock(); }
00170     
00171     // Implements PlotMutex::tryLock().
00172     bool tryLock() { return itsMutex_.tryLock(); }
00173     
00174 private:
00175     // Mutex.
00176     QMutex itsMutex_;
00177 };
00178 
00179 }
00180 
00181 #endif /* PLOTMSTHREAD_QO_H_ */