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
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _Interface_STAT_HeaderFile
18 #define _Interface_STAT_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
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;
34 //! This class manages statistics to be queried asynchronously.
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
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.
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.
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
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
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...
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
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 = "");
98 //! used when starting
99 Standard_EXPORT Interface_STAT(const Interface_STAT& other);
101 //! Returns fields in once, without copying them, used for copy
103 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;
105 //! Adds a new phase to the description.
106 //! The first one after Create replaces the default unique one
107 Standard_EXPORT void AddPhase (const Standard_Real weight, const Standard_CString name = "");
109 //! Adds a new step for the last added phase, the default unique
110 //! one if no AddPhase has already been added
111 //! Warning : AddStep before the first AddPhase are cancelled
112 Standard_EXPORT void AddStep (const Standard_Real weight = 1);
114 //! Returns global description (cumulated weights of all phases,
115 //! count of phases,1 for default, and title)
116 Standard_EXPORT void Description (Standard_Integer& nbphases, Standard_Real& total, Standard_CString& title) const;
118 //! Returns description of a phase, given its rank
119 //! (n0 for first step, count of steps, default gives one;
121 Standard_EXPORT void Phase (const Standard_Integer num, Standard_Integer& n0step, Standard_Integer& nbstep, Standard_Real& weight, Standard_CString& name) const;
123 //! Returns weight of a Step, related to the cumul given for the
125 //! <num> is given by <n0step> + i, i between 1 and <nbsteps>
126 //! (default gives n0step < 0 then weight is one)
127 Standard_EXPORT Standard_Real Step (const Standard_Integer num) const;
129 //! Starts a STAT on its first phase (or its default one)
130 //! <items> gives the total count of items, <cycles> the count of
132 //! If <cycles> is more than one, the first Cycle must then be
133 //! started by NextCycle (NextStep/NextItem are ignored).
134 //! If it is one, NextItem/NextStep can then be called
135 Standard_EXPORT void Start (const Standard_Integer items, const Standard_Integer cycles = 1) const;
137 //! Starts a default STAT, with no phase, no step, ready to just
139 //! <items> gives the total count of items
140 //! Hence, NextItem is available to directly count
141 Standard_EXPORT static void StartCount (const Standard_Integer items, const Standard_CString title = "");
143 //! Commands to resume the preceeding phase and start a new one
144 //! <items> and <cycles> as for Start, but for this new phase
145 //! Ignored if count of phases is already passed
146 //! If <cycles> is more than one, the first Cycle must then be
147 //! started by NextCycle (NextStep/NextItem are ignored).
148 //! If it is one, NextItem/NextStep can then be called
149 Standard_EXPORT static void NextPhase (const Standard_Integer items, const Standard_Integer cycles = 1);
151 //! Changes the parameters of the phase to start
152 //! To be used before first counting (i.e. just after NextPhase)
153 //! Can be used by an operator which has to reajust counts on run
154 Standard_EXPORT static void SetPhase (const Standard_Integer items, const Standard_Integer cycles = 1);
156 //! Commands to resume the preceeding cycle and start a new one,
157 //! with a count of items
158 //! Ignored if count of cycles is already passed
159 //! Then, first step is started (or default one)
160 //! NextItem can be called for the first step, or NextStep to pass
162 Standard_EXPORT static void NextCycle (const Standard_Integer items);
164 //! Commands to resume the preceeding step of the cycle
165 //! Ignored if count of steps is already passed
166 //! NextItem can be called for this step, NextStep passes to next
167 Standard_EXPORT static void NextStep();
169 //! Commands to add an item in the current step of the current
170 //! cycle of the current phase
171 //! By default, one item per call, can be overpassed
172 //! Ignored if count of items of this cycle is already passed
173 Standard_EXPORT static void NextItem (const Standard_Integer nbitems = 1);
175 //! Commands to declare the process ended (hence, advancement is
177 Standard_EXPORT static void End();
179 //! Returns an identification of the STAT :
180 //! <phase> True (D) : the name of the current phase
181 //! <phase> False : the title of the current STAT
182 Standard_EXPORT static Standard_CString Where (const Standard_Boolean phase = Standard_True);
184 //! Returns the advancement as a percentage :
185 //! <phase> True : inside the current phase
186 //! <phase> False (D) : relative to the whole process
187 Standard_EXPORT static Standard_Integer Percent (const Standard_Boolean phase = Standard_False);
202 Handle(TCollection_HAsciiString) thetitle;
203 Standard_Real thetotal;
204 Handle(TColStd_HSequenceOfAsciiString) thephnam;
205 Handle(TColStd_HSequenceOfReal) thephw;
206 Handle(TColStd_HSequenceOfInteger) thephdeb;
207 Handle(TColStd_HSequenceOfInteger) thephfin;
208 Handle(TColStd_HSequenceOfReal) thestw;
219 #endif // _Interface_STAT_HeaderFile