Runtime_message_detail

Classes

class  stk::RuntimeDoomedAdHoc
 Class RuntimeDoomedAdHoc reports an ad hoc doomed message to the report system. More...
class  stk::RuntimeDoomedSymmetric
 Class RuntimeDoomedSymmetric reports a fatal error message to the report system. More...
class  stk::RuntimeDoomedDeferred
 Class RuntimeDoomedDeferred reports a deferred fatal error message to the report system. More...
struct  stk::Throttle
 Class Throttle describes the cutoff limits for a message throttle. More...
struct  stk::MessageCode
 Class MessageCode declares a message identifier and throttle characteristics for a message. More...
class  stk::RuntimeWarningAdHoc
 Class RuntimeWarningAdHoc reports an ad hoc warning message to the report system. More...
class  stk::RuntimeWarningSymmetric
 Class RuntimeWarningSymmetric reports a symmetric warning message to the report system. More...
class  stk::RuntimeWarningDeferred
 Class RuntimeWarningDeferred reports a deferred warning message to the report system. More...

Files

file  RuntimeMessage.hpp

Defines

#define XSTR_TRACE_LINE(s)   STR_TRACE_LINE(s)
 Define statements to add __FILE___ and __LINE__.
#define STR_TRACE_LINE(s)   #s
#define COUT_TRACE   " File::Line="<<__FILE__<<":"<<__LINE__
#define STR_TRACE   (std::string(__FILE__) + ":" + XSTR_TRACE_LINE(__LINE__))
#define StackTrace   std::string(std::string(" exception thrown from ") + stk::source_relative_path(STR_TRACE))
#define ThrowAssert(expr)   ((expr) ? (void) 0 : throw std::runtime_error(std::string("Assertion ") + #expr + " failed\n" + StackTrace))
#define ThrowAssertMsg(expr, message)   ((expr) ? (void) 0 : throw std::runtime_error(std::string(message) + ", assertion " + #expr + " failed\n" + StackTrace))
#define ThrowRequire(expr)   ((expr) ? (void) 0 : throw std::runtime_error(std::string("Requirement ") + #expr + " failed\n" + StackTrace))
#define ThrowRequireMsg(expr, message)   ((expr) ? (void) 0 : throw std::runtime_error(std::string(message) + ", requirement " + #expr + " failed\n" + StackTrace))

Typedefs

typedef void(* stk::REH )(const char *message, int type)
 Type definition REH is a pointer to a function of type void that takes a const std::exception reference as a parameter.
typedef ptrdiff_t stk::MessageId
 Typedef MessageId defines a message identifier.

Enumerations

enum  stk::MessageType {
  stk::MSG_WARNING = 0,
  stk::MSG_DOOMED = 1,
  stk::MSG_EXCEPTION = 2,
  stk::MSG_INFORMATION = 3,
  stk::MSG_TYPE_MASK = 0x0FFFFFFF,
  stk::MSG_SYMMETRIC = 0x80000000,
  stk::MSG_DEFERRED = 0x40000000,
  MSG_UNUSED0 = 0x20000000,
  MSG_UNUSED1 = 0x10000000
}
 

Enumeration MessageType declares the global message types.

More...
enum  stk::ThrottleGroup {
  MSG_APPLICATION = 0,
  MSG_TIME_STEP = 1
}
 

Enumeration ThrottleGroup lists defined throttling groups.

More...

Functions

void stk::default_report_handler (const char *message, int type)
 Function default_report_handler is the default error reporter for sierra exceptions.
REH stk::set_report_handler (REH reh)
 Function set_report_handler sets the exception report function to be called when an report_exception() is called.
void stk::report (const char *message, int type)
 Function report calls the current exception reporter to report the message in x.
std::string stk::source_relative_path (const std::string &path)
 Function source_relative_path strips everything through "/src/", "/include/" or "/App_" so that error message output doesn't mention names.
unsigned int stk::get_doomed_count ()
 Function get_doomed_count returns the accumulated doomed count.
bool stk::is_doomed ()
 Function is_doomed returns true if get_doomed_count() > 0.
void stk::reset_doomed_count ()
 Function reset_doomed_count sets the accumulated doomed count to zero.
void stk::set_max_doomed_count (unsigned int max_messages)
 Function set_max_messages sets the maximum number of doomed before no more doomed will be displayed.
unsigned stk::get_max_doomed_count ()
 Function set_max_messages sets the maximum number of doomed and doomed messages displayed before the message is thrown as a RuntimeError exception.
void stk::report_doomed (const char *message, const MessageCode &message_code=MessageCode::s_defaultMessageCode)
 Function report_symmetric_doomed sends a doomed message to the reporter.
void stk::report_symmetric_doomed (const char *message, const MessageCode &message_code=MessageCode::s_defaultMessageCode)
 Function report_symmetric_doomed sends a doomed message to the reporter.
void stk::report_deferred_doomed (const char *message, const char *aggregate, const MessageCode &message_code)
 Member function report_deferred_doomed .
unsigned stk::get_message_count (unsigned message_type)
 Member function get_message_count .
void stk::reset_message_count (unsigned message_type)
 Member function reset_message_count .
void stk::set_max_message_count (unsigned message_type, unsigned max_count)
 Member function set_max_message_count .
unsigned stk::get_max_message_count (unsigned message_type)
 Member function get_max_message_count .
const std::string & stk::get_message_name (unsigned message_type)
 Member function get_message_name .
void stk::register_message_type (unsigned message_type, unsigned max_count, const char *name)
 Member function set_message_name .
void stk::reset_throttle_group (int throttle_group)
 Function reset_message_group sets the count to zero of all messages in the specified throttle group.
void stk::report_message (const char *message, unsigned message_type, const MessageCode &message_code)
 Member function report_message .
void stk::add_deferred_message (int message_type, MessageId message_id, size_t throttle_cutoff, int throttle_group, const char *header, const char *aggegrate)
 Function add_deferred_message adds a message to the deferred message queue.
void stk::report_deferred_messages (ParallelMachine comm)
 Function report_deferred_messages aggregates and reports the message on the root processor.
void stk::aggregate_messages (ParallelMachine comm, std::ostringstream &os, const char *separator=", ")
 Function aggregate_messages writes a message message to the output string by joining the messages from each processor, in order.
std::ostream & stk::operator<< (std::ostream &os, const MessageType &message_type)
 Function operator<< writes the message type name to the output stream.
unsigned stk::get_warning_count ()
 Function get_warning_count returns the accumulated warning count.
void stk::reset_warning_count ()
 Function reset_warning_count sets the accumulated warning count to zero.
void stk::set_max_warning_count (unsigned int max_messages)
 Function set_max_messages sets the maximum number of warning before no more warning will be displayed.
unsigned stk::get_max_warning_count ()
 Function set_max_messages sets the maximum number of warning and doomed messages displayed before the message is thrown as a RuntimeError exception.
void stk::report_warning (const char *message, const MessageCode &message_code=MessageCode::s_defaultMessageCode)
 Member function report_warning .
void stk::report_symmetric_warning (const char *message, const MessageCode &message_code=MessageCode::s_defaultMessageCode)
 Function report_symmetric_warning sends a warning message to the reporter.
void stk::report_deferred_warning (const char *message, const char *aggregate, const MessageCode &message_code)
 Member function report_deferred_warning .

Define Documentation

#define XSTR_TRACE_LINE (  )     STR_TRACE_LINE(s)

Define statements to add __FILE___ and __LINE__.

These just make it a little easier to add the __FILE__ and __LINE__ macros into the traceback functions. Inline functions do not work because the __FILE__ and __LINE__ expansions take place before the compiler inlining.

Definition at line 92 of file ReportHandler.hpp.


Typedef Documentation

typedef ptrdiff_t stk::MessageId

Typedef MessageId defines a message identifier.

Message identifiers must be consist from reference to reference, unique for each instance, and yet consist within each instance across multiple processors. To meet these criteria, the message identifier is implemented as a static memory location. It must be declared by the application developer as static. This results in the linker selecting an address for each instance, which never changes from reference to reference, is unique for each instance and the same regardless of executable (assuming the executable is mapped into the same memory location for each process). In order to remove the pointer-ness of the static memory location, the address is cast to a pointer difference type which is an integral type by subtracting the zero pointer from it.

Definition at line 41 of file RuntimeMessage.hpp.


Enumeration Type Documentation

Enumeration MessageType declares the global message types.

Currently warning and doomed (error) message types are defined. Additional type may be added after MSG_DOOMED. The MSG_SYMMETRIC bit indicates that the message was generated identically across all processors.

Enumerator:
MSG_WARNING 

Message is a warning.

MSG_DOOMED 

Message is a fatal error.

MSG_EXCEPTION 

Message is an exception.

MSG_INFORMATION 

Message is informational.

MSG_TYPE_MASK 

Mask of levels.

MSG_SYMMETRIC 

Message is symmetrical.

MSG_DEFERRED 

Message is deferred.

Definition at line 52 of file RuntimeMessage.hpp.

Enumeration ThrottleGroup lists defined throttling groups.

When messages are throttled, the throttle count may be reset at varior points during an application run. Some throttles defined for the application, while other may be reset at each time step or other interval. This allows warnings to be repeated at each time step rather than cut off.

Definition at line 74 of file RuntimeMessage.hpp.


Function Documentation

void stk::default_report_handler ( const char *  message,
int  type 
)

Function default_report_handler is the default error reporter for sierra exceptions.

Note that it is implemented in Fmwk_sierra.C so that it can participate

Parameters:
message a char const pointer to the message to be displayed.
type an int value of the type of message from the enumeration type
REH stk::set_report_handler ( REH  reh  ) 

Function set_report_handler sets the exception report function to be called when an report_exception() is called.

Parameters:
reh a REH of the new exception reporter.
Returns:
a REH to the previous exception reporter.
void stk::report ( const char *  message,
int  type 
)

Function report calls the current exception reporter to report the message in x.

Parameters:
message a char const pointer to the message to report.
type an int value of the type of message.
std::string stk::source_relative_path ( const std::string &  path  ) 

Function source_relative_path strips everything through "/src/", "/include/" or "/App_" so that error message output doesn't mention names.

Parameters:
s a std::string const reference to the original path.
Returns:
a std::string value of the stripped path.
bool stk::is_doomed (  )  [inline]

Function is_doomed returns true if get_doomed_count() > 0.

Returns:
a bool value of true if get_doomed_count() > 0.

Definition at line 37 of file RuntimeDoomed.hpp.

void stk::set_max_doomed_count ( unsigned int  max_messages  ) 

Function set_max_messages sets the maximum number of doomed before no more doomed will be displayed.

Parameters:
max_messages an int variable ...
void stk::report_doomed ( const char *  message,
const MessageCode &  message_code = MessageCode::s_defaultMessageCode 
)

Function report_symmetric_doomed sends a doomed message to the reporter.

Since the issue causing the doomed error may occur thousands of times during a run, it is desirable to throttle the number of times that a message is displayed. If you desire to limit the number of times a message is displayed, obtain a unique id via the get_next_message_id() function. This function allows you to assign the maximum display count. When the count of messages reported with this message id exceeds the display count, it is no longer displayed. The default id zero (0) is assigned which has an extremely large display count.

Parameters:
message a char const pointer to a message that is to be displayed.
message_code a MessageCode const pointer to a cross-processor unique identification of this message.
void stk::report_symmetric_doomed ( const char *  message,
const MessageCode &  message_code = MessageCode::s_defaultMessageCode 
)

Function report_symmetric_doomed sends a doomed message to the reporter.

Since the issue causing the doomed error may occur thousands of times during a run, it is desirable to throttle the number of times that a message is displayed. If you desire to limit the number of times a message is displayed, obtain a unique id via the get_next_message_id() function. This function allows you to assign the maximum display count. When the count of messages reported with this message id exceeds the display count, it is no longer displayed. The default id zero (0) is assigned which has an extremely large display count.

Parameters:
message a char const pointer to a message that is to be displayed.
message_code a MessageCode const pointer to a cross-processor unique identification of this message.
void stk::report_deferred_doomed ( const char *  message,
const char *  aggregate,
const MessageCode &  message_code 
)

Member function report_deferred_doomed .

..

Parameters:
message a std::string const ...
aggregate a std::string const ...
message_code a MessageCode const ...
unsigned stk::get_message_count ( unsigned  message_type  ) 

Member function get_message_count .

..

Parameters:
message_type an unsigned int ...
Returns:
an unsigned int ...
void stk::reset_message_count ( unsigned  message_type  ) 

Member function reset_message_count .

..

Parameters:
message_type an unsigned int ...
void stk::set_max_message_count ( unsigned  message_type,
unsigned  max_count 
)

Member function set_max_message_count .

..

Parameters:
message_type an unsigned int ...
max_count an unsigned int ...
unsigned stk::get_max_message_count ( unsigned  message_type  ) 

Member function get_max_message_count .

..

Parameters:
message_type an unsigned int ...
Returns:
an unsigned int ...
const std::string & stk::get_message_name ( unsigned  message_type  ) 

Member function get_message_name .

..

Parameters:
message_type an unsigned int ...
Returns:
a std::string ...
void stk::register_message_type ( unsigned  message_type,
unsigned  max_count,
const char *  name 
)

Member function set_message_name .

..

Parameters:
message_type an unsigned int ...
max_count an unsigned int ...
name a std::string const ...
void stk::reset_throttle_group ( int  throttle_group  ) 

Function reset_message_group sets the count to zero of all messages in the specified throttle group.

Parameters:
throttle_group an int value of the throttle group to reset.
void stk::report_message ( const char *  message,
unsigned  message_type,
const MessageCode &  message_code 
)

Member function report_message .

..

Parameters:
message an char const pointer ...
message_type an unsigned int ...
message_code a MessageCode ...
Returns:
an unsigned int ...
void stk::add_deferred_message ( int  message_type,
MessageId  message_id,
size_t  throttle_cutoff,
int  throttle_group,
const char *  header,
const char *  aggegrate 
)

Function add_deferred_message adds a message to the deferred message queue.

Parameters:
message_type an int value of the message type, usually WARNING or DOOMED
message_id a MessageId value of the message identifier
throttle_cutoff a size_t value to display before the message is no longer displayed.
throttle_group an int value to identify the throttle group that this message belongs to.
header a char const pointer to the message header string.
aggegrate a char const pointer to the message aggregation string.
void stk::report_deferred_messages ( ParallelMachine  comm  ) 

Function report_deferred_messages aggregates and reports the message on the root processor.

Todo:
REFACTOR Should the message counts be broadcast to the other processors?
Parameters:
comm a ParallelMachine communicator.
void stk::aggregate_messages ( ParallelMachine  comm,
std::ostringstream &  os,
const char *  separator = ", " 
)

Function aggregate_messages writes a message message to the output string by joining the messages from each processor, in order.

Each message is separated by the specified separation string.

Parameters:
comm a ParallelMachine communicator.
os a std::ostream reference to the output stream to receive the aggregated message.
separator a char const pointer to the separation string.
std::ostream & stk::operator<< ( std::ostream &  os,
const MessageType &  message_type 
)

Function operator<< writes the message type name to the output stream.

If the symmetric bit is set, "parallel" is prefixed to the name.

Parameters:
os a std::ostream reference to the output stream.
message_type a MessageType const reference to write the name of.
Returns:
a std::ostream reference to os
void stk::set_max_warning_count ( unsigned int  max_messages  ) 

Function set_max_messages sets the maximum number of warning before no more warning will be displayed.

Parameters:
max_messages an int variable ...
void stk::report_warning ( const char *  message,
const MessageCode &  message_code = MessageCode::s_defaultMessageCode 
)

Member function report_warning .

..

Parameters:
message a char const pointer ...
message_code a MessageCode const ...
void stk::report_symmetric_warning ( const char *  message,
const MessageCode &  message_code = MessageCode::s_defaultMessageCode 
)

Function report_symmetric_warning sends a warning message to the reporter.

Since the issue causing the warnign may occure thousands of times during a run, it is desirable to throttle the number of times that a message is displayed. If you desire to limit the number of times a message is displayed, obtain a unique id via the get_next_message_id() function. This function allows you to assign the maximum display count. When the count of messages reported with this message id exceeds the display count, it is no longer displayed. The default id zero (0) is assigned which has an extremely large display count.

Parameters:
message a char const pointer to a message that is to be displayed.
message_code a size_t value of the message id for the message.
void stk::report_deferred_warning ( const char *  message,
const char *  aggregate,
const MessageCode &  message_code 
)

Member function report_deferred_warning .

..

Parameters:
message a std::string const ...
aggregate a std::string const ...
message_code a MessageCode const ...
Generated on Wed Apr 13 10:05:49 2011 for Sierra Toolkit by  doxygen 1.6.3