0025748: Parallel version of progress indicator
[occt.git] / src / Transfer / Transfer_ProcessForTransient.hxx
1 // Created on: 1992-02-03
2 // Created by: Christian CAILLET
3 // Copyright (c) 1992-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 _Transfer_ProcessForTransient_HeaderFile
18 #define _Transfer_ProcessForTransient_HeaderFile
19
20 #include <TColStd_IndexedMapOfInteger.hxx>
21 #include <Transfer_TransferMapOfProcessForTransient.hxx>
22 #include <TColStd_MapTransientHasher.hxx>
23 #include <TColStd_HSequenceOfTransient.hxx>
24 #include <Message_ProgressRange.hxx>
25
26 class Message_Messenger;
27 class Transfer_Binder;
28 class Transfer_ActorOfProcessForTransient;
29 class Interface_InterfaceError;
30 class Transfer_TransferFailure;
31 class Transfer_IteratorOfProcessForTransient;
32 class Message_Msg;
33 class Interface_Check;
34 class Interface_CheckIterator;
35
36
37 class Transfer_ProcessForTransient;
38 DEFINE_STANDARD_HANDLE(Transfer_ProcessForTransient, Standard_Transient)
39
40 //! Manages Transfer of Transient Objects. Produces also
41 //! ActorOfTransientProcess       (deferred class),
42 //! IteratorOfTransientProcess    (for Results),
43 //! TransferMapOfTransientProcess (internally used)
44 //! Normally uses as TransientProcess, which adds some specifics
45
46 class Transfer_ProcessForTransient : public Standard_Transient
47 {
48
49 public:
50
51   
52   //! Sets TransferProcess at initial state. Gives an Initial size
53   //! (indicative) for the Map when known (default is 10000).
54   //! Sets default trace file as a printer and default trace level
55   //! (see Message_TraceFile).
56   Standard_EXPORT Transfer_ProcessForTransient(const Standard_Integer nb = 10000);
57   
58   //! Sets TransferProcess at initial state. Gives an Initial size
59   //! (indicative) for the Map when known (default is 10000).
60   //! Sets a specified printer.
61   Standard_EXPORT Transfer_ProcessForTransient(const Handle(Message_Messenger)& printer, const Standard_Integer nb = 10000);
62   
63   //! Resets a TransferProcess as ready for a completely new work.
64   //! Clears general data (roots) and the Map
65   Standard_EXPORT void Clear();
66   
67   //! Rebuilds the Map and the roots to really remove Unbound items
68   //! Because Unbind keeps the entity in place, even if not bound
69   //! Hence, working by checking new items is meaningless if a
70   //! formerly unbound item is rebound
71   Standard_EXPORT void Clean();
72   
73   //! Resizes the Map as required (if a new reliable value has been
74   //! determined). Acts only if <nb> is greater than actual NbMapped
75   Standard_EXPORT void Resize (const Standard_Integer nb);
76   
77   //! Defines an Actor, which is used for automatic Transfer
78   //! If already defined, the new Actor is cumulated
79   //! (see SetNext from Actor)
80   Standard_EXPORT void SetActor (const Handle(Transfer_ActorOfProcessForTransient)& actor);
81   
82   //! Returns the defined Actor. Returns a Null Handle if
83   //! not set.
84   Standard_EXPORT Handle(Transfer_ActorOfProcessForTransient) Actor() const;
85   
86   //! Returns the Binder which is linked with a starting Object
87   //! It can either bring a Result (Transfer done) or none (for a
88   //! pre-binding).
89   //! If no Binder is linked with <start>, returns a Null Handle
90   //! Considers a category number, by default 0
91   Standard_EXPORT Handle(Transfer_Binder) Find (const Handle(Standard_Transient)& start) const;
92   
93   //! Returns True if a Result (whatever its form) is Bound with
94   //! a starting Object. I.e., if a Binder with a Result set,
95   //! is linked with it
96   //! Considers a category number, by default 0
97   Standard_EXPORT Standard_Boolean IsBound (const Handle(Standard_Transient)& start) const;
98   
99   //! Returns True if the result of the transfer of an object is
100   //! already used in other ones. If it is, Rebind cannot change it.
101   //! Considers a category number, by default 0
102   Standard_EXPORT Standard_Boolean IsAlreadyUsed (const Handle(Standard_Transient)& start) const;
103   
104   //! Creates a Link a starting Object with a Binder. This Binder
105   //! can either bring a Result (effective Binding) or none (it can
106   //! be set later : pre-binding).
107   //! Considers a category number, by default 0
108   Standard_EXPORT void Bind (const Handle(Standard_Transient)& start, const Handle(Transfer_Binder)& binder);
109   
110   //! Changes the Binder linked with a starting Object for its
111   //! unitary transfer. This it can be useful when the exact form
112   //! of the result is known once the transfer is widely engaged.
113   //! This can be done only on first transfer.
114   //! Considers a category number, by default 0
115   Standard_EXPORT void Rebind (const Handle(Standard_Transient)& start, const Handle(Transfer_Binder)& binder);
116   
117   //! Removes the Binder linked with a starting object
118   //! If this Binder brings a non-empty Check, it is replaced by
119   //! a VoidBinder. Also removes from the list of Roots as required.
120   //! Returns True if done, False if <start> was not bound
121   //! Considers a category number, by default 0
122   Standard_EXPORT Standard_Boolean Unbind (const Handle(Standard_Transient)& start);
123   
124   //! Returns a Binder for a starting entity, as follows :
125   //! Tries to Find the already bound one
126   //! If none found, creates a VoidBinder and Binds it
127   Standard_EXPORT Handle(Transfer_Binder) FindElseBind (const Handle(Standard_Transient)& start);
128   
129   //! Sets Messenger used for outputting messages.
130   Standard_EXPORT void SetMessenger (const Handle(Message_Messenger)& messenger);
131   
132   //! Returns Messenger used for outputting messages.
133   //! The returned object is guaranteed to be non-null;
134   //! default is Message::Messenger().
135   Standard_EXPORT Handle(Message_Messenger) Messenger() const;
136   
137   //! Sets trace level used for outputting messages:
138   //! <trace> = 0 : no trace at all
139   //! <trace> = 1 : handled exceptions and calls to AddError
140   //! <trace> = 2 : also calls to AddWarning
141   //! <trace> = 3 : also traces new Roots
142   //! (uses method ErrorTrace).
143   //! Default is 1 : Errors traced
144   Standard_EXPORT void SetTraceLevel (const Standard_Integer tracelev);
145   
146   //! Returns trace level used for outputting messages.
147   Standard_EXPORT Standard_Integer TraceLevel() const;
148   
149   //! New name for AddFail (Msg)
150   Standard_EXPORT void SendFail (const Handle(Standard_Transient)& start, const Message_Msg& amsg);
151   
152   //! New name for AddWarning (Msg)
153   Standard_EXPORT void SendWarning (const Handle(Standard_Transient)& start, const Message_Msg& amsg);
154   
155   //! Adds an information message
156   //! Trace is filled if trace level is at least 3
157   Standard_EXPORT void SendMsg (const Handle(Standard_Transient)& start, const Message_Msg& amsg);
158   
159   //! Adds an Error message to a starting entity (to the check of
160   //! its Binder of category 0, as a Fail)
161   Standard_EXPORT void AddFail (const Handle(Standard_Transient)& start, const Standard_CString mess, const Standard_CString orig = "");
162   
163   //! (other name of AddFail, maintained for compatibility)
164   Standard_EXPORT void AddError (const Handle(Standard_Transient)& start, const Standard_CString mess, const Standard_CString orig = "");
165   
166   //! Adds an Error Message to a starting entity from the definition
167   //! of a Msg (Original+Value)
168   Standard_EXPORT void AddFail (const Handle(Standard_Transient)& start, const Message_Msg& amsg);
169   
170   //! Adds a Warning message to a starting entity (to the check of
171   //! its Binder of category 0)
172   Standard_EXPORT void AddWarning (const Handle(Standard_Transient)& start, const Standard_CString mess, const Standard_CString orig = "");
173   
174   //! Adds a Warning Message to a starting entity from the definition
175   //! of a Msg (Original+Value)
176   Standard_EXPORT void AddWarning (const Handle(Standard_Transient)& start, const Message_Msg& amsg);
177   
178   Standard_EXPORT void Mend (const Handle(Standard_Transient)& start, const Standard_CString pref = "");
179   
180   //! Returns the Check attached to a starting entity. If <start>
181   //! is unknown, returns an empty Check
182   //! Adds a case name to a starting entity
183   //! Adds a case value to a starting entity
184   //! Returns the complete case list for an entity. Null Handle if empty
185   //! In the list of mapped items (between 1 and NbMapped),
186   //! searches for the first item which follows <num0>(not included)
187   //! and which has an attribute named <name>
188   //! Attributes are brought by Binders
189   //! Hence, allows such an iteration
190   //!
191   //! for (num = TP->NextItemWithAttribute(name,0);
192   //! num > 0;
193   //! num = TP->NextItemWithAttribute(name,num) {
194   //! .. process mapped item <num>
195   //! }
196   //! Returns the type of an Attribute attached to binders
197   //! If this name gives no Attribute, returns ParamVoid
198   //! If this name gives several different types, returns ParamMisc
199   //! Else, returns the effective type (ParamInteger, ParamReal,
200   //! ParamIdent, or ParamText)
201   //! Returns the list of recorded Attribute Names, as a Dictionary
202   //! of Integer : each value gives the count of items which bring
203   //! this attribute name
204   //! By default, considers all the attribute names
205   //! If <rootname> is given, considers only the attribute names
206   //! which begin by <rootname>
207   Standard_EXPORT Handle(Interface_Check) Check (const Handle(Standard_Transient)& start) const;
208   
209   //! Binds a starting object with a Transient Result.
210   //! Uses a SimpleBinderOfTransient to work. If there is already
211   //! one but with no Result set, sets its Result.
212   //! Considers a category number, by default 0
213   Standard_EXPORT void BindTransient (const Handle(Standard_Transient)& start, const Handle(Standard_Transient)& res);
214   
215   //! Returns the Result of the Transfer of an object <start> as a
216   //! Transient Result.
217   //! Returns a Null Handle if there is no Transient Result
218   //! Considers a category number, by default 0
219   //! Warning : Supposes that Binding is done with a SimpleBinderOfTransient
220   Standard_EXPORT const Handle(Standard_Transient)& FindTransient (const Handle(Standard_Transient)& start) const;
221   
222   //! Prepares an object <start> to be bound with several results.
223   //! If no Binder is yet attached to <obj>, a MultipleBinder
224   //! is created, empty. If a Binder is already set, it must
225   //! accept Multiple Binding.
226   //! Considers a category number, by default 0
227   Standard_EXPORT void BindMultiple (const Handle(Standard_Transient)& start);
228   
229   //! Adds an item to a list of results bound to a starting object.
230   //! Considers a category number, by default 0, for all results
231   Standard_EXPORT void AddMultiple (const Handle(Standard_Transient)& start, const Handle(Standard_Transient)& res);
232   
233   //! Searches for a transient result attached to a starting object,
234   //! according to its type, by criterium IsKind(atype)
235   //!
236   //! In case of multiple result, explores the list and gives in
237   //! <val> the first transient result IsKind(atype)
238   //! Returns True and fills <val> if found
239   //! Else, returns False (<val> is not touched, not even nullified)
240   //!
241   //! This syntactic form avoids to do DownCast : if a result is
242   //! found with the good type, it is loaded in <val> and can be
243   //! immediately used, well initialised
244   Standard_EXPORT Standard_Boolean FindTypedTransient (const Handle(Standard_Transient)& start, const Handle(Standard_Type)& atype, Handle(Standard_Transient)& val) const;
245   
246   //! Searches for a transient result recorded in a Binder, whatever
247   //! this Binder is recorded or not in <me>
248   //!
249   //! This is strictly equivalent to the class method GetTypedResult
250   //! from class SimpleBinderOfTransient, but is just lighter to call
251   //!
252   //! Apart from this, works as FindTypedTransient
253   Standard_EXPORT Standard_Boolean GetTypedTransient (const Handle(Transfer_Binder)& binder, const Handle(Standard_Type)& atype, Handle(Standard_Transient)& val) const;
254   
255   //! Returns the maximum possible value for Map Index
256   //! (no result can be bound with a value greater than it)
257   Standard_EXPORT Standard_Integer NbMapped() const;
258   
259   //! Returns the Starting Object bound to an Index,
260   Standard_EXPORT const Handle(Standard_Transient)& Mapped (const Standard_Integer num) const;
261   
262   //! Returns the Index value bound to a Starting Object, 0 if none
263   Standard_EXPORT Standard_Integer MapIndex (const Handle(Standard_Transient)& start) const;
264   
265   //! Returns the Binder bound to an Index
266   //! Considers a category number, by default 0
267   Standard_EXPORT Handle(Transfer_Binder) MapItem (const Standard_Integer num) const;
268   
269   //! Declares <obj> (and its Result) as Root. This status will be
270   //! later exploited by RootResult, see below (Result can be
271   //! produced at any time)
272   Standard_EXPORT void SetRoot (const Handle(Standard_Transient)& start);
273   
274   //! Enable (if <stat> True) or Disables (if <stat> False) Root
275   //! Management. If it is set, Transfers are considered as stacked
276   //! (a first Transfer commands other Transfers, and so on) and
277   //! the Transfers commanded by an external caller are "Root".
278   //! Remark : SetRoot can be called whatever this status, on every
279   //! object.
280   //! Default is set to True.
281   Standard_EXPORT void SetRootManagement (const Standard_Boolean stat);
282   
283   //! Returns the count of recorded Roots
284   Standard_EXPORT Standard_Integer NbRoots() const;
285   
286   //! Returns a Root Entity given its number in the list (1-NbRoots)
287   Standard_EXPORT const Handle(Standard_Transient)& Root (const Standard_Integer num) const;
288   
289   //! Returns the Binder bound with a Root Entity given its number
290   //! Considers a category number, by default 0
291   Standard_EXPORT Handle(Transfer_Binder) RootItem (const Standard_Integer num) const;
292   
293   //! Returns the index in the list of roots for a starting item,
294   //! or 0 if it is not recorded as a root
295   Standard_EXPORT Standard_Integer RootIndex (const Handle(Standard_Transient)& start) const;
296   
297   //! Returns Nesting Level of Transfers (managed by methods
298   //! TranscriptWith & Co). Starts to zero. If no automatic Transfer
299   //! is used, it remains to zero. Zero means Root Level.
300   Standard_EXPORT Standard_Integer NestingLevel() const;
301   
302   //! Resets Nesting Level of Transfers to Zero (Root Level),
303   //! whatever its current value.
304   Standard_EXPORT void ResetNestingLevel();
305   
306   //! Tells if <start> has been recognized as good candidate for
307   //! Transfer. i.e. queries the Actor and its Nexts
308   Standard_EXPORT Standard_Boolean Recognize (const Handle(Standard_Transient)& start) const;
309   
310   //! Performs the Transfer of a Starting Object, by calling
311   //! the method TransferProduct (see below).
312   //! Mapping and Roots are managed : nothing is done if a Result is
313   //! already Bound, an exception is raised in case of error.
314   Standard_EXPORT Handle(Transfer_Binder) Transferring (const Handle(Standard_Transient)& start,
315                                 const Message_ProgressRange& theProgress = Message_ProgressRange());
316   
317   //! Same as Transferring but does not return the Binder.
318   //! Simply returns True in case of success (for user call)
319   Standard_EXPORT Standard_Boolean Transfer (const Handle(Standard_Transient)& start,
320                                 const Message_ProgressRange& theProgress = Message_ProgressRange());
321   
322   //! Allows controls if exceptions will be handled
323   //! Transfer Operations
324   //! <err> False : they are not handled with try {} catch {}
325   //! <err> True  : they are
326   //! Default is False: no handling performed
327   Standard_EXPORT void SetErrorHandle (const Standard_Boolean err);
328   
329   //! Returns error handling flag
330   Standard_EXPORT Standard_Boolean ErrorHandle() const;
331   
332   //! Method called when trace is asked
333   //! Calls PrintTrace to display information relevant for starting
334   //! objects (which can be redefined)
335   //! <level> is Nesting Level of Transfer (0 = root)
336   //! <mode> controls the way the trace is done :
337   //! 0 neutral, 1 for Error, 2 for Warning message, 3 for new Root
338   Standard_EXPORT void StartTrace (const Handle(Transfer_Binder)& binder, const Handle(Standard_Transient)& start, const Standard_Integer level, const Standard_Integer mode) const;
339   
340   //! Prints a short information on a starting object. By default
341   //! prints its Dynamic Type. Can be redefined
342   Standard_EXPORT virtual void PrintTrace (const Handle(Standard_Transient)& start, Standard_OStream& S) const;
343   
344   //! Returns True if we are surely in a DeadLoop. Evaluation is not
345   //! exact, it is a "majorant" which must be computed fast.
346   //! This "majorant" is : <alevel> greater than NbMapped.
347   Standard_EXPORT Standard_Boolean IsLooping (const Standard_Integer alevel) const;
348   
349   //! Returns, as an iterator, the log of root transfer, i.e. the
350   //! created objects and Binders bound to starting roots
351   //! If withstart is given True, Starting Objets are also returned
352   Standard_EXPORT Transfer_IteratorOfProcessForTransient RootResult (const Standard_Boolean withstart = Standard_False) const;
353   
354   //! Returns, as an Iterator, the entire log of transfer (list of
355   //! created objects and Binders which can bring errors)
356   //! If withstart is given True, Starting Objets are also returned
357   Standard_EXPORT Transfer_IteratorOfProcessForTransient CompleteResult (const Standard_Boolean withstart = Standard_False) const;
358   
359   //! Returns Binders which are neither "Done" nor "Initial",
360   //! that is Error,Loop or Run (abnormal states at end of Transfer)
361   //! Starting Objects are given in correspondance in the iterator
362   Standard_EXPORT Transfer_IteratorOfProcessForTransient AbnormalResult() const;
363   
364   //! Returns a CheckList as a list of Check : each one is for a
365   //! starting entity which have either check (warning or fail)
366   //! messages are attached, or are in abnormal state : that case
367   //! gives a specific message
368   //! If <erronly> is True, checks with Warnings only are ignored
369   Standard_EXPORT Interface_CheckIterator CheckList (const Standard_Boolean erronly) const;
370   
371   //! Returns, as an Iterator, the log of transfer for one object
372   //! <level> = 0 : this object only
373   //! and if <start> is a scope owner (else, <level> is ignored) :
374   //! <level> = 1 : object plus its immediate scoped ones
375   //! <level> = 2 : object plus all its scoped ones
376   Standard_EXPORT Transfer_IteratorOfProcessForTransient ResultOne (const Handle(Standard_Transient)& start, const Standard_Integer level, const Standard_Boolean withstart = Standard_False) const;
377   
378   //! Returns a CheckList for one starting object
379   //! <level> interpreted as by ResultOne
380   //! If <erronly> is True, checks with Warnings only are ignored
381   Standard_EXPORT Interface_CheckIterator CheckListOne (const Handle(Standard_Transient)& start, const Standard_Integer level, const Standard_Boolean erronly) const;
382   
383   //! Returns True if no check message is attached to a starting
384   //! object. <level> interpreted as by ResultOne
385   //! If <erronly> is True, checks with Warnings only are ignored
386   Standard_EXPORT Standard_Boolean IsCheckListEmpty (const Handle(Standard_Transient)& start, const Standard_Integer level, const Standard_Boolean erronly) const;
387   
388   //! Removes Results attached to (== Unbinds) a given object and,
389   //! according <level> :
390   //! <level> = 0 : only it
391   //! <level> = 1 : it plus its immediately owned sub-results(scope)
392   //! <level> = 2 : it plus all its owned sub-results(scope)
393   Standard_EXPORT void RemoveResult (const Handle(Standard_Transient)& start, const Standard_Integer level, const Standard_Boolean compute = Standard_True);
394   
395   //! Computes a number to be associated to a starting object in
396   //! a check or a check-list
397   //! By default, returns 0; can be redefined
398   Standard_EXPORT virtual Standard_Integer CheckNum (const Handle(Standard_Transient)& start) const;
399
400
401
402   DEFINE_STANDARD_RTTI_INLINE(Transfer_ProcessForTransient,Standard_Transient)
403
404 protected:
405
406
407
408
409 private:
410
411   
412   //! Same as Find but stores the last access to the map, for a
413   //! faster access on next calls (as Bind does too)
414   //! Considers a category number, by default 0
415   //! C++ : return const &
416   Standard_EXPORT Handle(Transfer_Binder) FindAndMask (const Handle(Standard_Transient)& start);
417   
418   //! Internal action of Transfer, called by Transferring, with or
419   //! without ErrorHandle. It invokes the Actor to work (set by
420   //! SetActor), and tries its Nexts if no result is produced,
421   //! until a Non Null Binder is produced.
422   //! But keep in mind that a Null Binder can allways be returned
423   //! if a Starting Entity has not been recognized at all.
424   Standard_EXPORT Handle(Transfer_Binder) TransferProduct (const Handle(Standard_Transient)& start,
425                                    const Message_ProgressRange& theProgress = Message_ProgressRange());
426
427   Standard_Boolean theerrh;
428   Standard_Integer thetrace;
429   Handle(Message_Messenger) themessenger;
430   Standard_Integer thelevel;
431   Standard_Integer therootl;
432   Standard_Boolean therootm;
433   TColStd_IndexedMapOfInteger theroots;
434   Handle(Standard_Transient) thelastobj;
435   Handle(Transfer_Binder) thelastbnd;
436   Standard_Integer theindex;
437   Handle(Transfer_ActorOfProcessForTransient) theactor;
438   Transfer_TransferMapOfProcessForTransient themap;
439
440
441 };
442
443
444
445
446
447
448
449 #endif // _Transfer_ProcessForTransient_HeaderFile