OpenWalnut  1.4.0
WProgressCombiner.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WPROGRESSCOMBINER_H
26 #define WPROGRESSCOMBINER_H
27 
28 #include <set>
29 #include <string>
30 
31 #include <boost/thread.hpp>
32 #include <boost/shared_ptr.hpp>
33 
34 #include "WProgress.h"
35 
36 /**
37  * Base class for all kinds of progress combinations. You might want to derive from this class to implement some special progress
38  * combination.
39  */
41 {
42 friend class WProgressCombinerTest;
43 public:
44  /**
45  * Abbreviate shared_ptr for this class.
46  */
47  typedef boost::shared_ptr< WProgressCombiner > SPtr;
48 
49  /**
50  * Abbreviate shared_ptr for this class.
51  */
52  typedef boost::shared_ptr< const WProgressCombiner > ConstSPtr;
53 
54  /**
55  * Default constructor. It creates a empty combiner.
56  *
57  * \param name the (optional) name of this progress.
58  */
59  explicit WProgressCombiner( std::string name = "" );
60 
61  /**
62  * Destructor.
63  */
64  virtual ~WProgressCombiner();
65 
66  /**
67  * Stops the progress. Progress combiner propagate this request to their children. Please not that this operation is
68  * expansive. It locks the updateLock and removes all child progress.
69  */
70  virtual void finish();
71 
72  /**
73  * Simple increment operator to signal a forward stepping.
74  *
75  * \note this actually is for ++p. p++ is not useful since it returns a copy of WProgress with the old count.
76  *
77  * \return the incremented WProgress instance.
78  */
79  virtual WProgressCombiner& operator++();
80 
81  /**
82  * Returns the overall progress of this progress instance, including the child progress'.
83  *
84  * \return the progress.
85  */
86  virtual float getProgress();
87 
88  /**
89  * Adds a new progress to this combiner. It does not check whether the specified progress already is associated with another
90  * combiner, which allows some kind of "shared" progress. The progress stays in the progress list until finish() is called,
91  * which actually cleans up and resets a combiner.
92  *
93  * \param progress the progress to add as a child.
94  * \note it is possible to add ProgressCombiner instances as well.
95  */
96  virtual void addSubProgress( boost::shared_ptr< WProgress > progress );
97 
98  /**
99  * Removes the specified sub progress from this combiner.
100  *
101  * \param progress the progress to remove.
102  */
103  virtual void removeSubProgress( boost::shared_ptr< WProgress > progress );
104 
105  /**
106  * Function updating the internal state. This needs to be called before any get function to ensure the getter return the right
107  * values.
108  *
109  * \note this method is expansive. It uses a lock to avoid concurrent write and iterates over this combiners children.
110  */
111  virtual void update();
112 
113  /**
114  * Generates a string combined out of every child progress name.
115  *
116  * \param excludeFinished if true, the combined name list only contains unfinished progress'
117  *
118  * \return One describing string for all child progress names.
119  */
120  std::string getCombinedNames( bool excludeFinished = false ) const;
121 
122 protected:
123  /**
124  * The name of the combiner.
125  */
126  std::string m_name;
127 
128  /**
129  * The current conglomerated progress. Set by update().
130  */
131  float m_progress;
132 
133  /**
134  * Set of all child progress.
135  */
136  std::set< boost::shared_ptr< WProgress > > m_children;
137 
138  /**
139  * Lock for the above child set and the internal state update.
140  */
141  mutable boost::shared_mutex m_updateLock;
142 
143 private:
144 };
145 
146 #endif // WPROGRESSCOMBINER_H
147