OpenWalnut  1.3.1
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 
33 #include "WProgress.h"
34 
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  * Default constructor. It creates a empty combiner.
46  *
47  * \param name the (optional) name of this progress.
48  */
49  explicit WProgressCombiner( std::string name = "" );
50 
51  /**
52  * Destructor.
53  */
54  virtual ~WProgressCombiner();
55 
56  /**
57  * Stops the progress. Progress combiner propagate this request to their children. Please not that this operation is
58  * expansive. It locks the updateLock and removes all child progress.
59  */
60  virtual void finish();
61 
62  /**
63  * Simple increment operator to signal a forward stepping.
64  *
65  * \note this actually is for ++p. p++ is not useful since it returns a copy of WProgress with the old count.
66  *
67  * \return the incremented WProgress instance.
68  */
69  virtual WProgressCombiner& operator++();
70 
71  /**
72  * Returns the overall progress of this progress instance, including the child progress'.
73  *
74  * \return the progress.
75  */
76  virtual float getProgress();
77 
78  /**
79  * Adds a new progress to this combiner. It does not check whether the specified progress already is associated with another
80  * combiner, which allows some kind of "shared" progress. The progress stays in the progress list until finish() is called,
81  * which actually cleans up and resets a combiner.
82  *
83  * \param progress the progress to add as a child.
84  * \note it is possible to add ProgressCombiner instances as well.
85  */
86  virtual void addSubProgress( boost::shared_ptr< WProgress > progress );
87 
88  /**
89  * Removes the specified sub progress from this combiner.
90  *
91  * \param progress the progress to remove.
92  */
93  virtual void removeSubProgress( boost::shared_ptr< WProgress > progress );
94 
95  /**
96  * Function updating the internal state. This needs to be called before any get function to ensure the getter return the right
97  * values.
98  *
99  * \note this method is expansive. It uses a lock to avoid concurrent write and iterates over this combiners children.
100  */
101  virtual void update();
102 
103  /**
104  * Generates a string combined out of every child progress name.
105  *
106  * \param excludeFinished if true, the combined name list only contains unfinished progress'
107  *
108  * \return One describing string for all child progress names.
109  */
110  std::string getCombinedNames( bool excludeFinished = false ) const;
111 
112 protected:
113  /**
114  * The name of the combiner.
115  */
116  std::string m_name;
117 
118  /**
119  * The current conglomerated progress. Set by update().
120  */
121  float m_progress;
122 
123  /**
124  * Set of all child progress.
125  */
126  std::set< boost::shared_ptr< WProgress > > m_children;
127 
128  /**
129  * Lock for the above child set and the internal state update.
130  */
131  mutable boost::shared_mutex m_updateLock;
132 
133 private:
134 };
135 
136 #endif // WPROGRESSCOMBINER_H
137