b5722c2283f5976a4ce2ffa7532eba3b6d3cf9fb
[occt.git] / src / Message / Message_ProgressScope.hxx
1 // Created on: 2002-02-22
2 // Created by: Andrey BETENEV
3 // Copyright (c) 2002-2014 OPEN CASCADE SAS
4 //
5 // This file is part of Open CASCADE Technology software library.
6 //
7 // This library is free software; you can redistribute it and/or modify it under
8 // the terms of the GNU Lesser General Public License version 2.1 as published
9 // by the Free Software Foundation, with special exception defined in the file
10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 // distribution for complete text of the license and disclaimer of any warranty.
12 //
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
15
16 #ifndef _Message_ProgressScope_HeaderFile
17 #define _Message_ProgressScope_HeaderFile
18
19 #include <Standard_Assert.hxx>
20 #include <Standard_TypeDef.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23 #include <Precision.hxx>
24 #include <TCollection_AsciiString.hxx>
25
26 class Message_ProgressRange;
27 class Message_ProgressIndicator;
28
29 //! Message_ProgressScope class provides convenient way to advance progress
30 //! indicator in context of complex program organized in hierarchical way,
31 //! where usually it is difficult (or even not possible) to consider process 
32 //! as linear with fixed step.
33 //!
34 //! On every level (sub-operation) in hierarchy of operations
35 //! the local instance of the Message_ProgressScope class is created.
36 //! It takes a part of the upper-level scope (via Message_ProgressRange) and provides 
37 //! a way to consider this part as independent scale with locally defined range. 
38 //!
39 //! The position on the local scale may be advanced using the method Next(),
40 //! which allows iteration-like advancement. This method can take argument to 
41 //! advance on the needed value. And, this method returns ProgressRange object
42 //! that takes responsibility of making the specified step at its destruction.
43 //! The ProgressRange can be used to create a new progress sub-scope.
44 //!
45 //! It is important that sub-scope must have life time less than 
46 //! the life time of its parent scope that provided the range.
47 //!
48 //! The scope has a name that can be used in visualization of the progress.
49 //! It can be null. Note that the string is not copied, just pointer is stored.
50 //! So, the pointer must point to the string with life time
51 //! greater than that of the scope object.
52 //!
53 //! In multithreaded programs, for each task running concurrently it is recommended
54 //! to create a separate progress scope. The same instance of the progress scope
55 //! must not be used concurrently from different threads.
56 //!
57 //! A progress scope created with empty constructor is not connected to any
58 //! progress indicator, and passing the range created on it to any algorithm 
59 //! allows it executing safely without progress indication.
60 //!
61 //! Example of preparation of progress indicator:
62 //!
63 //! @code{.cpp}
64 //!   Handle(Message_ProgressIndicator) aProgress = ...; // assume it can be null
65 //!   func (Message_ProgressIndicator::Start (aProgress));
66 //! @endcode
67 //!
68 //! Example of usage in sequential process:
69 //!
70 //! @code{.cpp}
71 //!   Message_ProgressScope aWholePS(aRange, "Whole process", 100);
72 //!
73 //!   // do one step taking 20%
74 //!   func1 (aWholePS.Next (20)); // func1 will take 20% of the whole scope
75 //!   if (aWholePS.UserBreak()) // exit prematurely if the user requested break
76 //!     return;
77 //!
78 //!   // ... do next step taking 50%
79 //!   func2 (aWholePS.Next (50));
80 //!   if (aWholePS.UserBreak())
81 //!     return;
82 //! @endcode
83 //!
84 //! Example of usage in nested cycle:
85 //!
86 //! @code{.cpp}
87 //!   // Outer cycle
88 //!   Message_ProgressScope anOuter (theProgress, "Outer", nbOuter);
89 //!   for (Standard_Integer i = 0; i < nbOuter && anOuter.More(); i++)
90 //!   {
91 //!     // Inner cycle
92 //!     Message_ProgressScope anInner (anOuter.Next(), "Inner", nbInner);
93 //!     for (Standard_Integer j = 0; j < nbInner && anInner.More(); j++)
94 //!     {
95 //!       // Cycle body
96 //!       func (anInner.Next());
97 //!     }
98 //!   }
99 //! @endcode
100 //!
101 //! Example of use in function:
102 //!
103 //! @code{.cpp}
104 //! //! Implementation of iterative algorithm showing its progress
105 //! func (const Message_ProgressRange& theProgress)
106 //! {
107 //!   // Create local scope covering the given progress range.
108 //!   // Set this scope to count aNbSteps steps.
109 //!   Message_ProgressScope aScope (theProgress, "", aNbSteps);
110 //!   for (Standard_Integer i = 0; i < aNbSteps && aScope.More(); i++)
111 //!   {
112 //!     // Optional: pass range returned by method Next() to the nested algorithm 
113 //!     // to allow it to show its progress too (by creating its own scope object).
114 //!     // In any case the progress will advance to the next step by the end of the func2 call.
115 //!     func2 (aScope.Next());
116 //!   }
117 //! }
118 //! @endcode
119 //!
120 //! Example of usage in parallel process:
121 //!
122 //! @code{.cpp}
123 //! struct Task
124 //! {
125 //!   Data& Data;
126 //!   Message_ProgressRange Range;
127 //!
128 //!   Task (const Data& theData, const Message_ProgressRange& theRange)
129 //!     : Data (theData), Range (theRange) {}
130 //! };
131 //! struct Functor
132 //! {
133 //!   void operator() (Task& theTask) const
134 //!   {
135 //!     // Note: it is essential that this method is executed only once
136 //!     // for the same Task object
137 //!     Message_ProgressScope aPS (theTask.Range, "Processing task", 1);
138 //!     if (aPS.More())
139 //!     {
140 //!       // ... process data
141 //!     }
142 //!   }
143 //! };
144 //! ...
145 //! {
146 //!   std::vector<Data> aData = ...;
147 //!   std::vector<Task> aTasks;
148 //!
149 //!   Message_ProgressScope aPS (aRootRange, "Data processing", aData.size());
150 //!   for (Standard_Integer i = 0; i < aData.size(); ++i)
151 //!     aTasks.push_back (Task (aData[i], aPS.Next()));
152 //!   
153 //!   OSD_Parallel::ForEach (aTasks.begin(), aTasks.end(), Functor());
154 //! }
155 //! @endcode
156 class Message_ProgressScope
157 {
158 public:
159   class NullString; //!< auxiliary type for passing NULL name to Message_ProgressScope constructor
160 public: //! @name Preparation methods
161
162   //! Creates dummy scope.
163   //! It can be safely passed to algorithms; no progress indication will be done.
164   Message_ProgressScope()
165   : myProgress (0),
166     myParent (0),
167     myName (0),
168     myPortion (1.), myMax (1.), myValue (0.),
169     myIsActive (false),
170     myIsOwnName (false),
171     myIsInfinite (false)
172   {}
173
174   //! Creates a new scope taking responsibility of the part of the progress 
175   //! scale described by theRange. The new scope has own range from 0 to 
176   //! theMax, which is mapped to the given range.
177   //!
178   //! The topmost scope is created and owned by Message_ProgressIndicator
179   //! and its pointer is contained in the Message_ProgressRange returned by the Start() method of progress indicator.
180   //!
181   //! @param theRange [in][out] range to fill (will be disarmed)
182   //! @param theName  [in]      new scope name
183   //! @param theMax   [in]      number of steps in scope
184   //! @param isInfinite [in]    infinite flag
185   Message_ProgressScope (const Message_ProgressRange& theRange,
186                          const TCollection_AsciiString& theName,
187                          Standard_Real theMax,
188                          Standard_Boolean isInfinite = false);
189
190   //! Creates a new scope taking responsibility of the part of the progress 
191   //! scale described by theRange. The new scope has own range from 0 to 
192   //! theMax, which is mapped to the given range.
193   //!
194   //! The topmost scope is created and owned by Message_ProgressIndicator
195   //! and its pointer is contained in the Message_ProgressRange returned by the Start() method of progress indicator.
196   //!
197   //! @param theRange [in][out] range to fill (will be disarmed)
198   //! @param theName  [in]      new scope name constant (will be stored by pointer with no deep copy)
199   //! @param theMax   [in]      number of steps in scope
200   //! @param isInfinite [in]    infinite flag
201   template<size_t N>
202   Message_ProgressScope (const Message_ProgressRange& theRange,
203                          const char (&theName)[N],
204                          Standard_Real theMax,
205                          Standard_Boolean isInfinite = false);
206
207   //! Creates a new scope taking responsibility of the part of the progress 
208   //! scale described by theRange. The new scope has own range from 0 to 
209   //! theMax, which is mapped to the given range.
210   //!
211   //! The topmost scope is created and owned by Message_ProgressIndicator
212   //! and its pointer is contained in the Message_ProgressRange returned by the Start() method of progress indicator.
213   //!
214   //! @param theRange [in][out] range to fill (will be disarmed)
215   //! @param theName  [in]      empty scope name (only NULL is accepted as argument)
216   //! @param theMax   [in]      number of steps in scope
217   //! @param isInfinite [in]    infinite flag
218   Message_ProgressScope (const Message_ProgressRange& theRange,
219                          const NullString* theName,
220                          Standard_Real theMax,
221                          Standard_Boolean isInfinite = false);
222
223   //! Sets the name of the scope.
224   void SetName (const TCollection_AsciiString& theName)
225   {
226     if (myIsOwnName)
227     {
228       Standard::Free (myName);
229       myIsOwnName = false;
230     }
231     myName = NULL;
232     if (!theName.IsEmpty())
233     {
234       myIsOwnName = true;
235       myName = (char* )Standard::Allocate (theName.Length() + 1);
236       char* aName = (char* )myName;
237       memcpy (aName, theName.ToCString(), theName.Length());
238       aName[theName.Length()] = '\0';
239     }
240   }
241
242   //! Sets the name of the scope; can be null.
243   //! Note! Just pointer to the given string is copied,
244   //! so do not pass string from a temporary variable whose
245   //! lifetime is less than that of this object.
246   template<size_t N>
247   void SetName (const char (&theName)[N])
248   {
249     if (myIsOwnName)
250     {
251       Standard::Free (myName);
252       myIsOwnName = false;
253     }
254     myName = theName;
255   }
256
257 public: //! @name Advance by iterations
258
259   //! Returns true if ProgressIndicator signals UserBreak
260   Standard_Boolean UserBreak() const;
261
262   //! Returns false if ProgressIndicator signals UserBreak
263   Standard_Boolean More() const
264   {
265     return !UserBreak();
266   }
267
268   //! Advances position by specified step and returns the range
269   //! covering this step
270   Message_ProgressRange Next (Standard_Real theStep = 1.);
271
272 public: //! @name Auxiliary methods to use in ProgressIndicator
273
274   //! Force update of presentation of the progress indicator.
275   //! Should not be called concurrently.
276   void Show();
277
278   //! Returns true if this progress scope is attached to some indicator.
279   Standard_Boolean IsActive() const
280   {
281     return myIsActive;
282   }
283
284   //! Returns the name of the scope (may be null).
285   //! Scopes with null name (e.g. root scope) should
286   //! be bypassed when reporting progress to the user.
287   Standard_CString Name() const
288   {
289     return myName;
290   }
291
292   //! Returns parent scope (null for top-level scope)
293   const Message_ProgressScope* Parent() const
294   {
295     return myParent;
296   }
297
298   //! Returns the maximal value of progress in this scope
299   Standard_Real MaxValue() const
300   {
301     return myMax;
302   }
303
304   //! Returns the current value of progress in this scope.
305   //! If this scope is being advanced by sub-scoping, that value is
306   //! computed by mapping current global progress into this scope range.
307   Standard_Real Value() const
308   {
309     return myIsActive ? myValue : myMax;
310   }
311
312   //! Returns the infinite flag
313   Standard_Boolean IsInfinite() const
314   {
315     return myIsInfinite;
316   }
317
318   //! Get the portion of the indicator covered by this scope (from 0 to 1)
319   Standard_Real GetPortion() const
320   {
321     return myPortion;
322   }
323
324 public: //! @name Destruction, allocation
325
326   //! Destructor - closes the scope and adds its scale to the total progress
327   ~Message_ProgressScope()
328   {
329     Relieve();
330     if (myIsOwnName)
331     {
332       Standard::Free (myName);
333       myIsOwnName = false;
334       myName = NULL;
335     }
336   }
337
338   //! Closes the scope and adds its scale to the total progress.
339   //! Relieved scope should not be used.
340   void Relieve();
341
342   DEFINE_STANDARD_ALLOC
343
344 private: //! @name Internal methods
345   
346   //! Creates a top-level scope with default range [0,1] and step 1.
347   //! Called only by Message_ProgressIndicator constructor.
348   Message_ProgressScope (Message_ProgressIndicator* theProgress);
349
350   //! Convert value from this scale to global one 
351   Standard_Real localToGlobal(const Standard_Real theVal) const;
352
353   //! Convert value from global scale to this one 
354   Standard_Real globalToLocal(const Standard_Real theVal) const;
355
356 private:
357   //! Copy constructor is prohibited
358   Message_ProgressScope (const Message_ProgressScope& theOther);
359
360   //! Copy assignment is prohibited
361   Message_ProgressScope& operator= (const Message_ProgressScope& theOther);
362
363 private:
364
365   Message_ProgressIndicator* myProgress; //!< Pointer to progress indicator instance
366   const Message_ProgressScope* myParent; //!< Pointer to parent scope
367   Standard_CString   myName;        //!< Name of the operation being done in this scope, or null
368
369   Standard_Real      myPortion;     //!< The portion of the global scale covered by this scope (from 0 to 1)
370   Standard_Real      myMax;         //!< Maximal value of progress in this scope
371   Standard_Real      myValue;       //!< Current position advanced within this scope [0, Max]
372
373   Standard_Boolean   myIsActive;    //!< flag indicating armed/disarmed state
374   Standard_Boolean   myIsOwnName;   //!< flag indicating if name was allocated or not
375   Standard_Boolean   myIsInfinite;  //!< Option to advance by hyperbolic law
376
377 private:
378   friend class Message_ProgressIndicator;
379   friend class Message_ProgressRange;
380 };
381
382 #include <Message_ProgressRange.hxx>
383
384 //=======================================================================
385 //function : Message_ProgressScope
386 //purpose  :
387 //=======================================================================
388 inline Message_ProgressScope::Message_ProgressScope (Message_ProgressIndicator* theProgress)
389 : myProgress(theProgress),
390   myParent(0),
391   myName(0),
392   myPortion(1.),
393   myMax(1.),
394   myValue(0.),
395   myIsActive(theProgress != NULL),
396   myIsOwnName(false),
397   myIsInfinite(false)
398 {
399 }
400
401 //=======================================================================
402 //function : Message_ProgressScope
403 //purpose  :
404 //=======================================================================
405 inline Message_ProgressScope::Message_ProgressScope (const Message_ProgressRange& theRange,
406                                                      const TCollection_AsciiString& theName,
407                                                      Standard_Real theMax,
408                                                      Standard_Boolean isInfinite)
409 : myProgress (theRange.myParentScope != NULL ? theRange.myParentScope->myProgress : NULL),
410   myParent (theRange.myParentScope),
411   myName (NULL),
412   myPortion (theRange.myDelta),
413   myMax (Max (1.e-6, theMax)), // protection against zero range
414   myValue (0.),
415   myIsActive (myProgress != NULL && !theRange.myWasUsed),
416   myIsOwnName (false),
417   myIsInfinite (isInfinite)
418 {
419   SetName (theName);
420   Standard_ASSERT_VOID (! theRange.myWasUsed, "Message_ProgressRange is used to initialize more than one scope");
421   theRange.myWasUsed = true; // Disarm the range
422 }
423
424 //=======================================================================
425 //function : Message_ProgressScope
426 //purpose  :
427 //=======================================================================
428 template<size_t N>
429 Message_ProgressScope::Message_ProgressScope (const Message_ProgressRange& theRange,
430                                               const char (&theName)[N],
431                                               Standard_Real theMax,
432                                               Standard_Boolean isInfinite)
433 : myProgress (theRange.myParentScope != NULL ? theRange.myParentScope->myProgress : NULL),
434   myParent (theRange.myParentScope),
435   myName (theName),
436   myPortion (theRange.myDelta),
437   myMax (Max (1.e-6, theMax)), // protection against zero range
438   myValue (0.),
439   myIsActive (myProgress != NULL && !theRange.myWasUsed),
440   myIsOwnName (false),
441   myIsInfinite (isInfinite)
442 {
443   Standard_ASSERT_VOID (! theRange.myWasUsed, "Message_ProgressRange is used to initialize more than one scope");
444   theRange.myWasUsed = true; // Disarm the range
445 }
446
447 //=======================================================================
448 //function : Message_ProgressScope
449 //purpose  :
450 //=======================================================================
451 inline Message_ProgressScope::Message_ProgressScope (const Message_ProgressRange& theRange,
452                                                      const NullString* ,
453                                                      Standard_Real theMax,
454                                                      Standard_Boolean isInfinite)
455 : myProgress (theRange.myParentScope != NULL ? theRange.myParentScope->myProgress : NULL),
456   myParent (theRange.myParentScope),
457   myName (NULL),
458   myPortion (theRange.myDelta),
459   myMax (Max (1.e-6, theMax)), // protection against zero range
460   myValue (0.),
461   myIsActive (myProgress != NULL && !theRange.myWasUsed),
462   myIsOwnName (false),
463   myIsInfinite (isInfinite)
464 {
465   Standard_ASSERT_VOID (! theRange.myWasUsed, "Message_ProgressRange is used to initialize more than one scope");
466   theRange.myWasUsed = true; // Disarm the range
467 }
468
469 //=======================================================================
470 //function : Relieve
471 //purpose  :
472 //=======================================================================
473 inline void Message_ProgressScope::Relieve()
474 {
475   if (!myIsActive)
476   {
477     return;
478   }
479
480   // Advance indicator to the end of the scope
481   Standard_Real aCurr = localToGlobal (myValue);
482   myValue = (myIsInfinite ? Precision::Infinite() : myMax);
483   Standard_Real aDelta = myPortion - aCurr;
484   if (aDelta > 0.)
485   {
486     myProgress->Increment (aDelta, *this);
487   }
488   Standard_ASSERT_VOID (myParent == 0 || myParent->myIsActive,
489     "Parent progress scope has been closed before child");
490
491   myIsActive = false;
492 }
493
494 //=======================================================================
495 //function : UserBreak
496 //purpose  :
497 //=======================================================================
498 inline Standard_Boolean Message_ProgressScope::UserBreak() const
499 {
500   return myProgress && myProgress->UserBreak();
501 }
502
503 //=======================================================================
504 //function : Next
505 //purpose  :
506 //=======================================================================
507 inline Message_ProgressRange Message_ProgressScope::Next (Standard_Real theStep)
508 {
509   if (myIsActive)
510   {
511     if (theStep > 0.)
512     {
513       Standard_Real aCurr = localToGlobal (myValue);
514       Standard_Real aNext = localToGlobal (myValue += theStep);
515       Standard_Real aDelta = aNext - aCurr;
516       if (aDelta > 0.)
517       {
518         return Message_ProgressRange (*this, aDelta);
519       }
520     }
521   }
522   return Message_ProgressRange();
523 }
524
525 //=======================================================================
526 //function : Show
527 //purpose  :
528 //=======================================================================
529
530 inline void Message_ProgressScope::Show ()
531 {
532   if (myIsActive)
533   {
534     myProgress->Show (*this, Standard_True);
535   }
536 }
537
538 //=======================================================================
539 //function : localToGlobal
540 //purpose  :
541 //=======================================================================
542 inline Standard_Real Message_ProgressScope::localToGlobal (const Standard_Real theVal) const
543 {
544   if (theVal <= 0.)
545     return 0.;
546
547   if (!myIsInfinite)
548   {
549     if (myMax - theVal < RealSmall())
550       return myPortion;
551     return myPortion * theVal / myMax;
552   }
553
554   double x = theVal / myMax;
555   // return myPortion * ( 1. - std::exp ( -x ) ); // exponent
556   return myPortion * x / (1. + x);  // hyperbola
557 }
558
559 //=======================================================================
560 //function : globalToLocal
561 //purpose  :
562 //=======================================================================
563
564 inline Standard_Real Message_ProgressScope::globalToLocal (const Standard_Real theVal) const
565 {
566   // if at end of the scope (or behind), report the maximum
567   Standard_Real aDist = myPortion - theVal;
568   if (aDist <= Precision::Confusion())
569     return myIsInfinite ? Precision::Infinite() : myMax;
570
571   if (!myIsInfinite)
572     return myMax * theVal / myPortion;
573
574   //  Standard_Real x = log (theVal / aDist); // exponent
575   Standard_Real x = theVal / aDist;         // hyperbola
576   return x * myMax;
577 }
578
579 #endif // _Message_ProgressScope_HeaderFile