OpenWalnut  1.4.0
WProgressCombiner.h
00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WPROGRESSCOMBINER_H
00026 #define WPROGRESSCOMBINER_H
00027 
00028 #include <set>
00029 #include <string>
00030 
00031 #include <boost/thread.hpp>
00032 #include <boost/shared_ptr.hpp>
00033 
00034 #include "WProgress.h"
00035 
00036 /**
00037  * Base class for all kinds of progress combinations. You might want to derive from this class to implement some special progress
00038  * combination.
00039  */
00040 class WProgressCombiner: public WProgress
00041 {
00042 friend class WProgressCombinerTest;
00043 public:
00044     /**
00045      * Abbreviate shared_ptr for this class.
00046      */
00047     typedef boost::shared_ptr< WProgressCombiner > SPtr;
00048 
00049     /**
00050      * Abbreviate shared_ptr for this class.
00051      */
00052     typedef boost::shared_ptr< const  WProgressCombiner > ConstSPtr;
00053 
00054     /**
00055      * Default constructor. It creates a empty combiner.
00056      *
00057      * \param name the (optional) name of this progress.
00058      */
00059     explicit WProgressCombiner( std::string name = "" );
00060 
00061     /**
00062      * Destructor.
00063      */
00064     virtual ~WProgressCombiner();
00065 
00066     /**
00067      * Stops the progress. Progress combiner propagate this request to their children. Please not that this operation is
00068      * expansive. It locks the updateLock and removes all child progress.
00069      */
00070     virtual void finish();
00071 
00072     /**
00073      * Simple increment operator to signal a forward stepping.
00074      *
00075      * \note this actually is for ++p. p++ is not useful since it returns a copy of WProgress with the old count.
00076      *
00077      * \return the incremented WProgress instance.
00078      */
00079     virtual WProgressCombiner& operator++();
00080 
00081     /**
00082      * Returns the overall progress of this progress instance, including the child progress'.
00083      *
00084      * \return the progress.
00085      */
00086     virtual float getProgress();
00087 
00088     /**
00089      * Adds a new progress to this combiner. It does not check whether the specified progress already is associated with another
00090      * combiner, which allows some kind of "shared" progress. The progress stays in the progress list until finish() is called,
00091      * which actually cleans up and resets a combiner.
00092      *
00093      * \param progress the progress to add as a child.
00094      * \note it is possible to add ProgressCombiner instances as well.
00095      */
00096     virtual void addSubProgress( boost::shared_ptr< WProgress > progress );
00097 
00098     /**
00099      * Removes the specified sub progress from this combiner.
00100      *
00101      * \param progress the progress to remove.
00102      */
00103     virtual void removeSubProgress( boost::shared_ptr< WProgress > progress );
00104 
00105     /**
00106      * Function updating the internal state. This needs to be called before any get function to ensure the getter return the right
00107      * values.
00108      *
00109      * \note this method is expansive. It uses a lock to avoid concurrent write and iterates over this combiners children.
00110      */
00111     virtual void update();
00112 
00113     /**
00114      * Generates a string combined out of every child progress name.
00115      *
00116      * \param excludeFinished  if true, the combined name list only contains unfinished progress'
00117      *
00118      * \return One describing string for all child progress names.
00119      */
00120     std::string getCombinedNames( bool excludeFinished = false ) const;
00121 
00122 protected:
00123     /**
00124      * The name of the combiner.
00125      */
00126     std::string m_name;
00127 
00128     /**
00129      * The current conglomerated progress. Set by update().
00130      */
00131     float m_progress;
00132 
00133     /**
00134      * Set of all child progress.
00135      */
00136     std::set< boost::shared_ptr< WProgress > > m_children;
00137 
00138     /**
00139      * Lock for the above child set and the internal state update.
00140      */
00141     mutable boost::shared_mutex m_updateLock;
00142 
00143 private:
00144 };
00145 
00146 #endif  // WPROGRESSCOMBINER_H
00147