0031004: Coding - eliminate warnings issued by gcc 9.1.0
[occt.git] / src / Interface / Interface_STAT.hxx
1 // Created on: 1996-02-15
2 // Created by: Christian CAILLET
3 // Copyright (c) 1996-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 //
6 // This file is part of Open CASCADE Technology software library.
7 //
8 // This library is free software; you can redistribute it and/or modify it under
9 // the terms of the GNU Lesser General Public License version 2.1 as published
10 // by the Free Software Foundation, with special exception defined in the file
11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 // distribution for complete text of the license and disclaimer of any warranty.
13 //
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
16
17 #ifndef _Interface_STAT_HeaderFile
18 #define _Interface_STAT_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23
24 #include <Standard_Real.hxx>
25 #include <TColStd_HSequenceOfAsciiString.hxx>
26 #include <TColStd_HSequenceOfReal.hxx>
27 #include <TColStd_HSequenceOfInteger.hxx>
28 #include <Standard_CString.hxx>
29 #include <Standard_Integer.hxx>
30 #include <Standard_Boolean.hxx>
31 class TCollection_HAsciiString;
32
33
34 //! This class manages statistics to be queried asynchronously.
35 //! Way of use :
36 //! An operator describes a STAT form then fills it according to
37 //! its progression. This produces a state of advancement of the
38 //! process. This state can then be queried asynchronously :
39 //! typically it is summarised as a percentage. There are also
40 //! an identification of the current state, and informations on
41 //! processed volume.
42 //!
43 //! A STAT form can be described once for all (as static).
44 //! It describes the stream of the process (see later), in terms
45 //! of phases, cycles, steps, with estimated weights. But it
46 //! brings no current data.
47 //!
48 //! One STAT at a time is active for filling and querying. It is
49 //! used to control phasing, weighting ... Specific data for
50 //! execution are given when running on active STAT : counts of
51 //! items ... Data for query are then recorded and can be accessed
52 //! at any time, asynchronously.
53 //!
54 //! A STAT is organised as follows :
55 //! - it can be split into PHASES (by default, there is none, and
56 //! all process takes place in one "default" phase)
57 //! - each phase is identified by a name and is attached a weight
58 //! -> the sum of the weights is used to compute relative weights
59 //! - for each phase, or for the unique default phase if none :
60 //! -- the process works on a list of ITEMS
61 //! -- by default, all the items are processed in once
62 //! -- but this list can be split into CYCLES, each one takes
63 //! a sub-list : the weight of each cycle is related to its
64 //! count of items
65 //! -- a cycle can be split into STEPS, by default there are none
66 //! then one "default step" is considered
67 //! -- each step is attached a weight
68 //! -> the sum of the weights of steps is used to compute relative
69 //! weights of the steps in each cycle
70 //! -> all the cycles of a phase have the same organisation
71 //!
72 //! Hence, when defining the STAT form, the phases have to be
73 //! described. If no weight is precisely known, give 1. for all...
74 //! No phase description will give only one "default" phase
75 //! For each phase, a typical cycle can be described by its steps.
76 //! Here too, for no weight precisely known, give 1. for all...
77 //!
78 //! For executing, activate a STAT to begin count. Give counts of
79 //! items and cycles for the first phase (for the unique default
80 //! one if no phasing is described)
81 //! Else, give count of items and cycles for each new phase.
82 //! Class methods allow also to set next cycle (given count of
83 //! items), next step in cycle (if more then one), next item in
84 //! step.
85 class Interface_STAT 
86 {
87 public:
88
89   DEFINE_STANDARD_ALLOC
90
91   
92   //! Creates a STAT form. At start, one default phase is defined,
93   //! with one default step. Then, it suffises to start with a
94   //! count of items (and cycles if several) then record items,
95   //! to have a queryable report.
96   Standard_EXPORT Interface_STAT(const Standard_CString title = "");
97   
98   //! used when starting
99   Standard_EXPORT Interface_STAT(const Interface_STAT& other);
100
101   //! Assignment
102   Interface_STAT& operator= (const Interface_STAT& theOther)
103   {
104     theOther.Internals (thetitle, thetotal, thephnam, thephw, thephdeb,thephfin, thestw);
105     return *this;
106   }
107
108   //! Returns fields in once, without copying them, used for copy
109   //! when starting
110   Standard_EXPORT void Internals (Handle(TCollection_HAsciiString)& tit, Standard_Real& total, Handle(TColStd_HSequenceOfAsciiString)& phn, Handle(TColStd_HSequenceOfReal)& phw, Handle(TColStd_HSequenceOfInteger)& phdeb, Handle(TColStd_HSequenceOfInteger)& phfin, Handle(TColStd_HSequenceOfReal)& stw) const;
111   
112   //! Adds a new phase to the description.
113   //! The first one after Create replaces the default unique one
114   Standard_EXPORT void AddPhase (const Standard_Real weight, const Standard_CString name = "");
115   
116   //! Adds a new step for the last added phase, the default unique
117   //! one if no AddPhase has already been added
118   //! Warning : AddStep before the first AddPhase are cancelled
119   Standard_EXPORT void AddStep (const Standard_Real weight = 1);
120   
121   //! Returns global description (cumulated weights of all phases,
122   //! count of phases,1 for default, and title)
123   Standard_EXPORT void Description (Standard_Integer& nbphases, Standard_Real& total, Standard_CString& title) const;
124   
125   //! Returns description of a phase, given its rank
126   //! (n0 for first step, count of steps, default gives one;
127   //! weight, name)
128   Standard_EXPORT void Phase (const Standard_Integer num, Standard_Integer& n0step, Standard_Integer& nbstep, Standard_Real& weight, Standard_CString& name) const;
129   
130   //! Returns weight of a Step, related to the cumul given for the
131   //! phase.
132   //! <num> is given by <n0step> + i, i between 1 and <nbsteps>
133   //! (default gives n0step < 0 then weight is one)
134   Standard_EXPORT Standard_Real Step (const Standard_Integer num) const;
135   
136   //! Starts a STAT on its first phase (or its default one)
137   //! <items> gives the total count of items, <cycles> the count of
138   //! cycles
139   //! If <cycles> is more than one, the first Cycle must then be
140   //! started by NextCycle (NextStep/NextItem are ignored).
141   //! If it is one, NextItem/NextStep can then be called
142   Standard_EXPORT void Start (const Standard_Integer items, const Standard_Integer cycles = 1) const;
143   
144   //! Starts a default STAT, with no phase, no step, ready to just
145   //! count items.
146   //! <items> gives the total count of items
147   //! Hence, NextItem is available to directly count
148   Standard_EXPORT static void StartCount (const Standard_Integer items, const Standard_CString title = "");
149   
150   //! Commands to resume the preceeding phase and start a new one
151   //! <items> and <cycles> as for Start, but for this new phase
152   //! Ignored if count of phases is already passed
153   //! If <cycles> is more than one, the first Cycle must then be
154   //! started by NextCycle (NextStep/NextItem are ignored).
155   //! If it is one, NextItem/NextStep can then be called
156   Standard_EXPORT static void NextPhase (const Standard_Integer items, const Standard_Integer cycles = 1);
157   
158   //! Changes the parameters of the phase to start
159   //! To be used before first counting (i.e. just after NextPhase)
160   //! Can be used by an operator which has to reajust counts on run
161   Standard_EXPORT static void SetPhase (const Standard_Integer items, const Standard_Integer cycles = 1);
162   
163   //! Commands to resume the preceeding cycle and start a new one,
164   //! with a count of items
165   //! Ignored if count of cycles is already passed
166   //! Then, first step is started (or default one)
167   //! NextItem can be called for the first step, or NextStep to pass
168   //! to the next one
169   Standard_EXPORT static void NextCycle (const Standard_Integer items);
170   
171   //! Commands to resume the preceeding step of the cycle
172   //! Ignored if count of steps is already passed
173   //! NextItem can be called for this step, NextStep passes to next
174   Standard_EXPORT static void NextStep();
175   
176   //! Commands to add an item in the current step of the current
177   //! cycle of the current phase
178   //! By default, one item per call, can be overpassed
179   //! Ignored if count of items of this cycle is already passed
180   Standard_EXPORT static void NextItem (const Standard_Integer nbitems = 1);
181   
182   //! Commands to declare the process ended (hence, advancement is
183   //! forced to 100 %)
184   Standard_EXPORT static void End();
185   
186   //! Returns an identification of the STAT :
187   //! <phase> True (D) : the name of the current phase
188   //! <phase> False : the title of the current STAT
189   Standard_EXPORT static Standard_CString Where (const Standard_Boolean phase = Standard_True);
190   
191   //! Returns the advancement as a percentage :
192   //! <phase> True : inside the current phase
193   //! <phase> False (D) : relative to the whole process
194   Standard_EXPORT static Standard_Integer Percent (const Standard_Boolean phase = Standard_False);
195
196
197
198
199 protected:
200
201
202
203
204
205 private:
206
207
208
209   Handle(TCollection_HAsciiString) thetitle;
210   Standard_Real thetotal;
211   Handle(TColStd_HSequenceOfAsciiString) thephnam;
212   Handle(TColStd_HSequenceOfReal) thephw;
213   Handle(TColStd_HSequenceOfInteger) thephdeb;
214   Handle(TColStd_HSequenceOfInteger) thephfin;
215   Handle(TColStd_HSequenceOfReal) thestw;
216
217
218 };
219
220
221
222
223
224
225
226 #endif // _Interface_STAT_HeaderFile