Message

Base class of the hierarchy of classes describing various situations occurring during execution of some algorithm or procedure.
Alert should provide unique text identifier that can be used to distinguish particular type of alerts, e.g. to get text message string describing it. See method GetMessageKey(); by default, dynamic type name is used.
Alert can contain some data. To avoid duplication of data, new alert can be merged with another one of the same type. Method SupportsMerge() should return true if merge is supported; method Merge() should do the merge if possible and return true in that case and false otherwise.

Inherited class of Message_Alert with some additional information. It has Message_Attributes to provide the alert name, and other custom information It has a container of composite alerts, if the alert might provide sub-alerts collecting.

Class Message_Algorithm is intended to be the base class for classes implementing algorithms or any operations that need to provide extended information on its execution to the caller / user.
It provides generic mechanism for management of the execution status, collection and output of messages.
The algorithm uses methods SetStatus() to set an execution status. It is possible to associate a status with a number or a string (second argument of SetStatus() methods) to indicate precisely the item (object, element etc.) in the input data which caused the problem.
Each execution status generated by the algorithm has associated text message that should be defined in the resource file loaded with call to Message_MsgFile::LoadFile().
The messages corresponding to the statuses generated during the algorithm execution are output to Message_Messenger using methods SendMessages(). If status have associated numbers or strings, they are included in the message body in place of "%s" placeholder which should be present in the message text.
The name of the message text in the resource file is constructed from name of the class and name of the status, separated by dot, for instance:
.TObj_CheckModel.Alarm2 Error: Some objects (s) have references to dead object(s)
If message for the status is not found with prefix of the current class type, the same message is searched for the base class(es) recursively.
Message can be set explicitly for the status; in this case the above procedure is not used and supplied message is used as is.
The messages are output to the messenger, stored in the field; though messenger can be changed, it is guaranteed to be non-null. By default, Message::DefaultMessenger() is used.

Additional information of extended alert attribute To provide other custom attribute container, it might be redefined.

Alert object storing alert metrics values. Start and stop values for each metric.

Alert object storing a transient object.

Alert object storing stream value.

Class providing container of alerts.

Tiny class for extended handling of error / execution status of algorithm in universal way.
It is in fact a set of integers represented as a collection of bit flags for each of four types of status; each status flag has its own symbolic name and can be set/tested individually.
The flags are grouped in semantic groups:

• No flags means nothing done
• Done flags correspond to some operation successfully completed
• Warning flags correspond to warning messages on some potentially wrong situation, not harming algorithm execution
• Alarm flags correspond to more severe warnings about incorrect user data, while not breaking algorithm execution
• Fail flags correspond to cases when algorithm failed to complete

This class is an instance of Sentry to create a level in a message report Constructor of the class add new (active) level in the report, destructor removes it While the level is active in the report, new alerts are added below the level root alert.
The first added alert is a root alert, other are added below the root alert
If alert has Message_AttributeMeter attribute, active metrics of the default report are stored in the attribute: start value of metric on adding alert, stop on adding another alert or closing (delete) the level in the report.
Processing of this class is implemented in Message_Report, it is used only inside it. Levels using should be only through using OCCT_ADD_MESSAGE_LEVEL_SENTRY only. No other code is required outside.

This class provides a tool for constructing the parametrized message basing on resources loaded by Message_MsgFile tool.
A Message is created from a keyword: this keyword identifies the message in a message file that should be previously loaded by call to Message_MsgFile::LoadFile().
The text of the message can contain placeholders for the parameters which are to be filled by the proper values when the message is prepared. Most of the format specifiers used in C can be used, for instance, s for string, d for integer etc. In addition, specifier f is supported for double numbers (for compatibility with previous versions).
User fills the parameter fields in the text of the message by calling corresponding methods Arg() or operators .
The resulting message, filled with all parameters, can be obtained by method Get(). If some parameters were not filled, the text UNKNOWN is placed instead.

A tool providing facility to load definitions of message strings from resource file(s).
The message file is an ASCII file which defines a set of messages. Each message is identified by its keyword (string).
All lines in the file starting with the exclamation sign (perhaps preceding by spaces and/or tabs) are ignored as comments.
Each line in the file starting with the dot character "." (perhaps preceding by spaces and/or tabs) defines the keyword. The keyword is a string starting from the next symbol after dot and ending at the symbol preceding ending newline character "\n".
All the lines in the file after the keyword and before next keyword (and which are not comments) define the message for that keyword. If the message consists of several lines, the message string will contain newline symbols "\n" between parts (but not at the end).
The experimental support of Unicode message files is provided. These are distinguished by two bytes FF.FE or FE.FF at the beginning.
The loaded messages are stored in static data map; all methods of that class are also static.

Abstract interface class defining printer as output context for text messages.
The message, besides being text string, has associated gravity level, which can be used by printer to decide either to process a message or ignore it.

Implementation of a message printer associated with an std::ostream The std::ostream may be either externally defined one (e.g. std::cout), or file stream maintained internally (depending on constructor).

Implementation of a message printer associated with Message_Report Send will create a new alert of the report. If string is sent, an alert is created by Eol only. The alerts are sent into set report or default report of Message.

Defines abstract interface from program to the user. This includes progress indication and user break mechanisms.
The progress indicator controls the progress scale with range from 0 to 1.
Method Start() should be called once, at the top level of the call stack, to reset progress indicator and get access to the root range:

occ::handle<Message_ProgressIndicator>aProgress=...; anAlgorithm.Perform(aProgress->Start());

To advance the progress indicator in the algorithm, use the class Message_ProgressScope that provides iterator-like interface for incrementing progress; see documentation of that class for details. The object of class Message_ProgressRange will automatically advance the indicator if it is not passed to any Message_ProgressScope.
The progress indicator supports concurrent processing and can be used in multithreaded applications.
The derived class should be created to connect this interface to actual implementation of progress indicator, to take care of visualization of the progress (e.g. show total position at the graphical bar, print scopes in text mode, or else), and for implementation of user break mechanism (if necessary).
See details in documentation of methods Show() and UserBreak().

Auxiliary class representing a part of the global progress scale allocated by a step of the progress scope, see Message_ProgressScope::Next().
A range object takes responsibility of advancing the progress by the size of allocated step, which is then performed depending on how it is used:

• If Message_ProgressScope object is created using this range as argument, then this respondibility is taken over by that scope.
• Otherwise, a range advances progress directly upon destruction.
  A range object can be copied, the responsibility for progress advancement is then taken by the copy. The same range object may be used (either copied or used to create scope) only once. Any consequent attempts to use range will give no result on the progress; in debug mode, an assert message will be generated.

Message_ProgressScope class provides convenient way to advance progress indicator in context of complex program organized in hierarchical way, where usually it is difficult (or even not possible) to consider process as linear with fixed step.
On every level (sub-operation) in hierarchy of operations the local instance of the Message_ProgressScope class is created. It takes a part of the upper-level scope (via Message_ProgressRange) and provides a way to consider this part as independent scale with locally defined range.
The position on the local scale may be advanced using the method Next(), which allows iteration-like advancement. This method can take argument to advance by the specified value (with default step equal to 1). This method returns Message_ProgressRange object that takes responsibility of making the specified step, either directly at its destruction or by delegating this task to another sub-scope created from that range object.
It is important that sub-scope must have life time less than the life time of its parent scope that provided the range. The usage pattern is to create scope objects as local variables in the functions that do the job, and pass range objects returned by Next() to the functions of the lower level, to allow them creating their own scopes.
The scope has a name that can be used in visualization of the progress. It can be null. Note that when C string literal is used as a name, then its value is not copied, just pointer is stored. In other variants (char pointer or a string class) the string is copied, which is additional overhead.
The same instance of the progress scope! must not be used concurrently from different threads. For the algorithm running its tasks in parallel threads, a common scope is created before the parallel execution, and the range objects produced by method Next() are used to initialise the data pertinent to each task. Then the progress is advanced within each task using its own range object. See example below.
Note that while a range of the scope is specified using double (double) parameter, it is expected to be a positive integer value. If the range is not an integer, method Next() shall be called with explicit step argument, and the rounded value returned by method Value() may be not coherent with the step and range.
A scope can be created with option "infinite". This is useful when the number of steps is not known by the time of the scope creation. In this case the progress will be advanced logarithmically, approaching the end of the scope at infinite number of steps. The parameter Max for infinite scope indicates number of steps corresponding to mid-range.
A progress scope created with empty constructor is not connected to any progress indicator, and passing the range created on it to any algorithm allows it executing safely without actual progress indication.
Example of preparation of progress indicator:

occ::handle<Message_ProgressIndicator>aProgress=...;//assumeitcanbenull func(Message_ProgressIndicator::Start(aProgress));

Example of usage in sequential process:

Message_ProgressScopeaWholePS(aRange,"Wholeprocess",100); //doonesteptaking20% func1(aWholePS.Next(20));//func1willtake20%ofthewholescope if(aWholePS.UserBreak())//exitprematurelyiftheuserrequestedbreak return; //...donextsteptaking50% func2(aWholePS.Next(50)); if(aWholePS.UserBreak()) return;

Example of usage in nested cycle:

//Outercycle Message_ProgressScopeanOuter(theProgress,"Outer",nbOuter); for(inti=0;i<nbOuter&&anOuter.More();i++) { //Innercycle Message_ProgressScopeanInner(anOuter.Next(),"Inner",nbInner); for(intj=0;j<nbInner&&anInner.More();j++) { //Cyclebody func(anInner.Next()); } }

Example of use in function:

func(constMessage_ProgressRange&theProgress) { //Createlocalscopecoveringthegivenprogressrange. //SetthisscopetocountaNbStepssteps. Message_ProgressScopeaScope(theProgress,"",aNbSteps); for(inti=0;i<aNbSteps&&aScope.More();i++) { //Optional:passrangereturnedbymethodNext()tothenestedalgorithm //toallowittoshowitsprogresstoo(bycreatingitsownscopeobject). //Inanycasetheprogresswilladvancetothenextstepbytheendofthefunc2call. func2(aScope.Next()); } }

Example of usage in parallel process:

structTask { Data&Data; Message_ProgressRangeRange; Task(constData&theData,constMessage_ProgressRange&theRange) :Data(theData),Range(theRange){} }; structFunctor { voidoperator()(Task&theTask)const { //Note:itisessentialthatthismethodisexecutedonlyonceforthesameTaskobject Message_ProgressScopeaPS(theTask.Range,NULL,theTask.Data.NbItems); for(inti=0;i<theTask.Data.NbSteps&&aPS.More();i++) { do_job(theTask.Data.Item[i],aPS.Next()); } } }; ... { std::vector<Data>aData=...; std::vector<Task>aTasks; Message_ProgressScopeaPS(aRootRange,"Dataprocessing",aData.size()); for(inti=0;i<aData.size();++i) aTasks.push_back(Task(aData[i],aPS.Next())); OSD_Parallel::ForEach(aTasks.begin(),aTasks.end(),Functor()); }

For lightweight algorithms that do not need advancing the progress within individual tasks the code can be simplified to avoid inner scopes:

structFunctor { voidoperator()(Task&theTask)const { if(theTask.Range.More()) { do_job(theTask.Data); //advancetheprogress theTask.Range.Close(); } } };

Functionality of this class (Message_ProgressSentry) has been superseded by Message_ProgressScope. This class is kept just to simplify transition of an old code and will be removed in future.

Container for alert messages, sorted according to their gravity.
For each gravity level, alerts are stored in simple list. If alert being added can be merged with another alert of the same type already in the list, it is merged and not added to the list.
This class is intended to be used as follows:

• In the process of execution, algorithm fills report by alert objects using methods AddAlert()
• The result can be queried for presence of particular alert using methods HasAlert()
• The reports produced by nested or sequentially executed algorithms can be collected in one using method Merge()
• The report can be shown to the user either as plain text with method Dump() or in more advanced way, by iterating over lists returned by GetAlerts()
• Report can be cleared by methods Clear() (usually after reporting)
  Message_PrinterToReport is a printer in Messenger to convert data sent to messenger into report