Sierra Toolkit Version of the Day
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. THESE MUST BE DECLARED STATIC. 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 ThrowGenericCond(expr, message, handler)
#define ThrowGeneric(message, handler)
#define ThrowRequireMsg(expr, message)   ThrowGenericCond(expr, message, handle_assert)
#define ThrowRequire(expr)   ThrowRequireMsg(expr, "")
#define ThrowAssert(expr)   ThrowRequire(expr)
#define ThrowAssertMsg(expr, message)   ThrowRequireMsg(expr,message)
#define ThrowErrorMsgIf(expr, message)   ThrowGenericCond( !(expr), message, handle_error)
#define ThrowErrorIf(expr)   ThrowErrorMsgIf(expr, "")
#define ThrowErrorMsg(message)   ThrowGeneric( message, handle_error )
#define ThrowInvalidArgMsgIf(expr, message)   ThrowGenericCond( !(expr), message, handle_invalid_arg)
#define ThrowInvalidArgIf(expr)   ThrowInvalidArgMsgIf(expr, "")

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 void(* stk::ErrorHandler )(const char *expr, const std::string &location, std::ostringstream &message)
 ErrorHandler defines the signature of functions that can be used to handle errors. expr is the expression of the failing error-check, location is a raw code location (something like file:line, no prose), and message is the error message.
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. Note that it is implemented in Fmwk_sierra.C so that it can participate.
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/", "/App_", or "/stk_" so that error message output doesn't mention names.
void stk::default_assert_handler (const char *expr, const std::string &location, std::ostringstream &message)
void stk::default_error_handler (const char *expr, const std::string &location, std::ostringstream &message)
void stk::default_invalid_arg_handler (const char *expr, const std::string &location, std::ostringstream &message)
ErrorHandler stk::set_assert_handler (ErrorHandler handler)
ErrorHandler stk::set_error_handler (ErrorHandler handler)
ErrorHandler stk::set_invalid_arg_handler (ErrorHandler handler)
void stk::handle_assert (const char *expr, const std::string &location, std::ostringstream &message)
void stk::handle_error (const char *expr, const std::string &location, std::ostringstream &message)
void stk::handle_invalid_arg (const char *expr, const std::string &location, std::ostringstream &message)
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. Each message is separated by the specified 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.
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 (   s)    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 169 of file ReportHandler.hpp.

#define ThrowGenericCond (   expr,
  message,
  handler 
)
Value:
do {                                                                  \
    if ( !(expr) ) {                                                    \
      std::ostringstream stk_util_internal_throw_require_oss;           \
      stk_util_internal_throw_require_oss << message;                   \
      stk::handler( #expr,                                              \
                    STR_TRACE,                                          \
                    stk_util_internal_throw_require_oss );              \
    }                                                                   \
  } while (false)

Definition at line 194 of file ReportHandler.hpp.

#define ThrowGeneric (   message,
  handler 
)
Value:
do {                                                                  \
    std::ostringstream stk_util_internal_throw_require_oss;             \
    stk_util_internal_throw_require_oss << message;                     \
    stk::handler( "",                                                   \
                  STR_TRACE,                                            \
                  stk_util_internal_throw_require_oss );                \
} while (false)

Definition at line 208 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 42 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 53 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 75 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:
messagea char const pointer to the message to be displayed.
typean int value of the type of message from the enumeration type

Definition at line 65 of file ReportHandler.cpp.

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:
reha REH of the new exception reporter.
Returns:
a REH to the previous exception reporter.

Definition at line 82 of file ReportHandler.cpp.

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

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

Parameters:
messagea char const pointer to the message to report.
typean int value of the type of message.

Definition at line 73 of file ReportHandler.cpp.

std::string stk::source_relative_path ( const std::string &  path)

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

Parameters:
patha std::string const reference to the original path.
Returns:
a std::string value of the stripped path.

Definition at line 97 of file ReportHandler.cpp.

void stk::default_assert_handler ( const char *  expr,
const std::string &  location,
std::ostringstream &  message 
)

A function used to create and throw nice-looking exceptions for assertion failures.

Definition at line 115 of file ReportHandler.cpp.

void stk::default_error_handler ( const char *  expr,
const std::string &  location,
std::ostringstream &  message 
)

A function used to create and throw nice-looking exceptions for runtime errors.

Definition at line 122 of file ReportHandler.cpp.

void stk::default_invalid_arg_handler ( const char *  expr,
const std::string &  location,
std::ostringstream &  message 
)

A function used to create and throw nice-looking exceptions for invalid argument errors.

Definition at line 129 of file ReportHandler.cpp.

ErrorHandler stk::set_assert_handler ( ErrorHandler  handler)

Change the error handler for ThrowAssert and ThrowRequire.

Returns:
The previous error handler (useful if you want to restore it later)

Definition at line 136 of file ReportHandler.cpp.

ErrorHandler stk::set_error_handler ( ErrorHandler  handler)

Change the error handler for ThrowError.

Returns:
The previous error handler (useful if you want to restore it later)

Definition at line 147 of file ReportHandler.cpp.

ErrorHandler stk::set_invalid_arg_handler ( ErrorHandler  handler)

Change the error handler for ThrowInvalidArg.

Returns:
The previous error handler (useful if you want to restore it later)

Definition at line 158 of file ReportHandler.cpp.

void stk::handle_assert ( const char *  expr,
const std::string &  location,
std::ostringstream &  message 
)

Makes the call to the current assert handler

Definition at line 169 of file ReportHandler.cpp.

void stk::handle_error ( const char *  expr,
const std::string &  location,
std::ostringstream &  message 
)

Makes the call to the current error handler

Definition at line 176 of file ReportHandler.cpp.

void stk::handle_invalid_arg ( const char *  expr,
const std::string &  location,
std::ostringstream &  message 
)

Makes the call to the current invalid_arg handler

Definition at line 183 of file ReportHandler.cpp.

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_messagesan int variable ...

Definition at line 32 of file RuntimeDoomed.cpp.

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:
messagea char const pointer to a message that is to be displayed.
message_codea MessageCode const pointer to a cross-processor unique identification of this message.

Definition at line 47 of file RuntimeDoomed.cpp.

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:
messagea char const pointer to a message that is to be displayed.
message_codea MessageCode const pointer to a cross-processor unique identification of this message.

Definition at line 56 of file RuntimeDoomed.cpp.

void stk::report_deferred_doomed ( const char *  message,
const char *  aggregate,
const MessageCode &  message_code 
)

Member function report_deferred_doomed ...

Parameters:
messagea std::string const ...
aggregatea std::string const ...
message_codea MessageCode const ...

Definition at line 65 of file RuntimeDoomed.cpp.

unsigned stk::get_message_count ( unsigned  message_type)

Member function get_message_count ...

Parameters:
message_typean unsigned int ...
Returns:
an unsigned int ...

Definition at line 169 of file RuntimeMessage.cpp.

void stk::reset_message_count ( unsigned  message_type)

Member function reset_message_count ...

Parameters:
message_typean unsigned int ...

Definition at line 185 of file RuntimeMessage.cpp.

void stk::set_max_message_count ( unsigned  message_type,
unsigned  max_count 
)

Member function set_max_message_count ...

Parameters:
message_typean unsigned int ...
max_countan unsigned int ...

Definition at line 201 of file RuntimeMessage.cpp.

unsigned stk::get_max_message_count ( unsigned  message_type)

Member function get_max_message_count ...

Parameters:
message_typean unsigned int ...
Returns:
an unsigned int ...

Definition at line 210 of file RuntimeMessage.cpp.

const std::string & stk::get_message_name ( unsigned  message_type)

Member function get_message_name ...

Parameters:
message_typean unsigned int ...
Returns:
a std::string ...

Definition at line 193 of file RuntimeMessage.cpp.

void stk::register_message_type ( unsigned  message_type,
unsigned  max_count,
const char *  name 
)

Member function set_message_name ...

Parameters:
message_typean unsigned int ...
max_countan unsigned int ...
namea std::string const ...

Definition at line 156 of file RuntimeMessage.cpp.

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_groupan int value of the throttle group to reset.

Definition at line 257 of file RuntimeMessage.cpp.

void stk::report_message ( const char *  message,
unsigned  message_type,
const MessageCode &  message_code 
)

Member function report_message ...

Parameters:
messagean char const pointer ...
message_typean unsigned int ...
message_codea MessageCode ...
Returns:
an unsigned int ...

Definition at line 218 of file RuntimeMessage.cpp.

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_typean int value of the message type, usually WARNING or DOOMED
message_ida MessageId value of the message identifier
throttle_cutoffa size_t value to display before the message is no longer displayed.
throttle_groupan int value to identify the throttle group that this message belongs to.
headera char const pointer to the message header string.
aggegratea char const pointer to the message aggregation string.

Definition at line 267 of file RuntimeMessage.cpp.

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:
comma ParallelMachine communicator.

Definition at line 291 of file RuntimeMessage.cpp.

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:
comma ParallelMachine communicator.
osa std::ostream reference to the output stream to receive the aggregated message.
separatora char const pointer to the separation string.

Definition at line 398 of file RuntimeMessage.cpp.

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:
osa std::ostream reference to the output stream.
message_typea MessageType const reference to write the name of.
Returns:
a std::ostream reference to os

Definition at line 478 of file RuntimeMessage.cpp.

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_messagesan int variable ...

Definition at line 29 of file RuntimeWarning.cpp.

void stk::report_warning ( const char *  message,
const MessageCode &  message_code = MessageCode::s_defaultMessageCode 
)

Member function report_warning ...

Parameters:
messagea char const pointer ...
message_codea MessageCode const ...

Definition at line 44 of file RuntimeWarning.cpp.

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:
messagea char const pointer to a message that is to be displayed.
message_codea size_t value of the message id for the message.

Definition at line 53 of file RuntimeWarning.cpp.

void stk::report_deferred_warning ( const char *  message,
const char *  aggregate,
const MessageCode &  message_code 
)

Member function report_deferred_warning ...

Parameters:
messagea std::string const ...
aggregatea std::string const ...
message_codea MessageCode const ...

Definition at line 62 of file RuntimeWarning.cpp.

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends