Merge branch 'develop' into feature/bounds-checks
This commit is contained in:
Daviw Williams
commit
61dd59c9bc
@ -7,31 +7,43 @@ Logging
|
||||
=======
|
||||
PolyVox has a simple logging mechanism which allows it to write messages with an associated severity (from Debug up to Fatal). It is possible to redirect the output of these logging functions so you can integrate them with your applications logging framework or suppress them completely.
|
||||
|
||||
The following functions are called at various points in the PolyVox codebase:
|
||||
The following functions are used as follows within PolyVox (note that newlines are appended automatically):
|
||||
|
||||
.. sourcecode :: c++
|
||||
|
||||
void logDebug (const std::string& message);
|
||||
void logInfo (const std::string& message);
|
||||
void logWarning(const std::string& message);
|
||||
void logError (const std::string& message);
|
||||
void logFatal (const std::string& message);
|
||||
logTrace() << "Trace Message";
|
||||
logDebug() << "Debug Message";
|
||||
logInfo() << "Info Message";
|
||||
logWarning() << "Warning Message";
|
||||
logError() << "Error Message";
|
||||
logFatal() << "Fatal Message";
|
||||
|
||||
Fatal messages are only issued in non-recoverable scenarios when the application is about to crash, and may provide the last peice of information you have about what went wrong. Error messages are issued when something has happened which prevents sucessful completion of a task, for example if you provide invalid parameters to a function (Error messages are also issued whenever an exception is thrown). Warning messages mean the system was able to continue but the results may not be what you expected. Info and Debug messages are both used for general information about what PolyVox is doing. The differentiating factor is that Debug is used if the output is very frequent so that it can be easily suppressed.
|
||||
Fatal messages are only issued in non-recoverable scenarios when the application is about to crash, and may provide the last peice of information you have about what went wrong. Error messages are issued when something has happened which prevents sucessful completion of a task, for example if you provide invalid parameters to a function (error messages are also issued whenever an exception is thrown). Warning messages mean the system was able to continue but the results may not be what you expected. Info messages are used for general information about what PolyVox is doing. Debug and trace messages produce very verbose output and a lot of detail about what PolyVox is doing internally. In general, debug messages are used for tasks the user has directly initiated (e.g. they might provide time information for surface extraction) while trace messages are used for things which happen spontaneously (such as data being paged out of memory). Trace messages are most likely to clutter up your logs and so are most easily suppressed.
|
||||
|
||||
PolyVox defines a LogHandler function pointer which looks like this:
|
||||
To redirect log messages you can provide an implementation of std::ostream and apply it with one of the functions below:
|
||||
|
||||
.. sourcecode :: c++
|
||||
|
||||
typedef void (*LogHandler)(const std::string& message, LogLevel logLevel);
|
||||
setTraceStream(&myOutputStream);
|
||||
setDebugStream(&myOutputStream);
|
||||
setInfoStream(&myOutputStream);
|
||||
setWarningStream(&myOutputStream);
|
||||
setErrorStream(&myOutputStream);
|
||||
setFatalStream(&myOutputStream);
|
||||
|
||||
There is a function called 'defaultLogHandler()' which matches this signature and writes the messages to cout/cerr (note that it suppresses Debug messages). To redirect log messages you can write your own fuction which matches this signature and the apply it with setLogHandler:
|
||||
PolyVox provides a function called 'getNullStream()' which returns a stream which consumes all input without writing it anywhere. You can use this to supress particular log streams. For example, you can suppress the Trace stream with:
|
||||
|
||||
.. sourcecode :: c++
|
||||
|
||||
setLogHandler(&myLogHandler);
|
||||
setTraceStream(getNullStream());
|
||||
|
||||
Note that you can disable logging completely by passing a value of '0' to setLogHandler().
|
||||
Or you could direct it to std::cout with:
|
||||
|
||||
.. sourcecode :: c++
|
||||
|
||||
setTraceStream(&(std::cout)));
|
||||
|
||||
Note that by default the fatal, error and warning streams go to std::cerr, the info stream goes to std:cout, and the debug and trace streams are suppressed.
|
||||
|
||||
Exceptions
|
||||
==========
|
||||
|
||||
@ -376,7 +376,6 @@ namespace PolyVox
|
||||
{
|
||||
//Should never happen
|
||||
POLYVOX_THROW(std::invalid_argument, "Wrap mode parameter has an unrecognised value.");
|
||||
return VoxelType();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -62,36 +62,117 @@ freely, subject to the following restrictions:
|
||||
* PolyVox provides basic logging facilities which can be redirected by your application.
|
||||
*/
|
||||
|
||||
#define LOG_DECLARATION(name) \
|
||||
std::ostream& log(name)(void); \
|
||||
void set(name)Stream(std::ostream& nameStream);
|
||||
|
||||
namespace PolyVox
|
||||
{
|
||||
class LogLevels
|
||||
namespace Impl
|
||||
{
|
||||
public:
|
||||
enum LogLevel
|
||||
std::ostream*& getTraceStreamInstance();
|
||||
std::ostream*& getDebugStreamInstance();
|
||||
std::ostream*& getInfoStreamInstance();
|
||||
std::ostream*& getWarningStreamInstance();
|
||||
std::ostream*& getErrorStreamInstance();
|
||||
std::ostream*& getFatalStreamInstance();
|
||||
}
|
||||
|
||||
/// Get a stream which will consume all input without outputting anything.
|
||||
std::ostream* getNullStream(void);
|
||||
|
||||
// These take pointers rather than references to emphasise that the
|
||||
// user needs to keep the target alive as long as PolyVox is writing data.
|
||||
void setTraceStream(std::ostream* pStream);
|
||||
void setDebugStream(std::ostream* pStream);
|
||||
void setInfoStream(std::ostream* pStream);
|
||||
void setWarningStream(std::ostream* pStream);
|
||||
void setErrorStream(std::ostream* pStream);
|
||||
void setFatalStream(std::ostream* pStream);
|
||||
|
||||
// Automatically appending 'std::endl' as described here: http://stackoverflow.com/a/2179782
|
||||
struct logTrace
|
||||
{
|
||||
Debug,
|
||||
Info,
|
||||
Warning,
|
||||
Error,
|
||||
Fatal
|
||||
logTrace(){}
|
||||
~logTrace(){*(Impl::getTraceStreamInstance()) << std::endl;}
|
||||
|
||||
template<class T>
|
||||
logTrace &operator<<(const T &x)
|
||||
{
|
||||
*(Impl::getTraceStreamInstance()) << x;
|
||||
return *this;
|
||||
}
|
||||
};
|
||||
|
||||
// Automatically appending 'std::endl' as described here: http://stackoverflow.com/a/2179782
|
||||
struct logDebug
|
||||
{
|
||||
logDebug(){}
|
||||
~logDebug(){*(Impl::getDebugStreamInstance()) << std::endl;}
|
||||
|
||||
template<class T>
|
||||
logDebug &operator<<(const T &x)
|
||||
{
|
||||
*(Impl::getDebugStreamInstance()) << x;
|
||||
return *this;
|
||||
}
|
||||
};
|
||||
typedef LogLevels::LogLevel LogLevel;
|
||||
|
||||
typedef void (*LogHandler)(const std::string& message, LogLevel logLevel);
|
||||
// Automatically appending 'std::endl' as described here: http://stackoverflow.com/a/2179782
|
||||
struct logInfo
|
||||
{
|
||||
logInfo(){}
|
||||
~logInfo(){*(Impl::getInfoStreamInstance()) << std::endl;}
|
||||
|
||||
LogHandler getLogHandler();
|
||||
void setLogHandler(LogHandler newHandler);
|
||||
template<class T>
|
||||
logInfo &operator<<(const T &x)
|
||||
{
|
||||
*(Impl::getInfoStreamInstance()) << x;
|
||||
return *this;
|
||||
}
|
||||
};
|
||||
|
||||
// The actual logging function
|
||||
void log(const std::string& message, LogLevel logLevel);
|
||||
// Automatically appending 'std::endl' as described here: http://stackoverflow.com/a/2179782
|
||||
struct logWarning
|
||||
{
|
||||
logWarning(){}
|
||||
~logWarning(){*(Impl::getWarningStreamInstance()) << std::endl;}
|
||||
|
||||
// Some handy wrappers
|
||||
void logDebug (const std::string& message);
|
||||
void logInfo (const std::string& message);
|
||||
void logWarning(const std::string& message);
|
||||
void logError (const std::string& message);
|
||||
void logFatal (const std::string& message);
|
||||
template<class T>
|
||||
logWarning &operator<<(const T &x)
|
||||
{
|
||||
*(Impl::getWarningStreamInstance()) << x;
|
||||
return *this;
|
||||
}
|
||||
};
|
||||
|
||||
// Automatically appending 'std::endl' as described here: http://stackoverflow.com/a/2179782
|
||||
struct logError
|
||||
{
|
||||
logError(){}
|
||||
~logError(){*(Impl::getErrorStreamInstance()) << std::endl;}
|
||||
|
||||
template<class T>
|
||||
logError &operator<<(const T &x)
|
||||
{
|
||||
*(Impl::getErrorStreamInstance()) << x;
|
||||
return *this;
|
||||
}
|
||||
};
|
||||
|
||||
// Automatically appending 'std::endl' as described here: http://stackoverflow.com/a/2179782
|
||||
struct logFatal
|
||||
{
|
||||
logFatal(){}
|
||||
~logFatal(){*(Impl::getFatalStreamInstance()) << std::endl;}
|
||||
|
||||
template<class T>
|
||||
logFatal &operator<<(const T &x)
|
||||
{
|
||||
*(Impl::getFatalStreamInstance()) << x;
|
||||
return *this;
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
/*
|
||||
@ -114,14 +195,13 @@ namespace PolyVox
|
||||
{ \
|
||||
if (!(condition)) \
|
||||
{ \
|
||||
std::stringstream ss; \
|
||||
ss << std::endl << std::endl; \
|
||||
ss << " PolyVox Assertion Failed!" << std::endl; \
|
||||
ss << " =========================" << std::endl; \
|
||||
ss << " Condition: " << #condition << std::endl; \
|
||||
ss << " Message: " << (message) << std::endl; \
|
||||
ss << " Location: " << "Line " << __LINE__ << " of " << __FILE__ << std::endl << std::endl; \
|
||||
PolyVox::logFatal(ss.str()); \
|
||||
PolyVox::logFatal() << "\n"; \
|
||||
PolyVox::logFatal() << " PolyVox Assertion Failed!"; \
|
||||
PolyVox::logFatal() << " ========================="; \
|
||||
PolyVox::logFatal() << " Condition: " << #condition; \
|
||||
PolyVox::logFatal() << " Message: " << (message); \
|
||||
PolyVox::logFatal() << " Location: " << "Line " << __LINE__ << " of " << __FILE__; \
|
||||
PolyVox::logFatal() << "\n"; \
|
||||
POLYVOX_HALT(); \
|
||||
} \
|
||||
} while(0) \
|
||||
@ -176,7 +256,7 @@ namespace PolyVox
|
||||
*/
|
||||
#ifdef POLYVOX_THROW_ENABLED
|
||||
#define POLYVOX_THROW(type, message) \
|
||||
PolyVox::logError(message); \
|
||||
PolyVox::logError() << (message); \
|
||||
throw type((message))
|
||||
#else
|
||||
namespace PolyVox
|
||||
@ -188,7 +268,7 @@ namespace PolyVox
|
||||
}
|
||||
|
||||
#define POLYVOX_THROW(type, message) \
|
||||
PolyVox::logError(message); \
|
||||
PolyVox::logError() << (message); \
|
||||
type except = (type)((message)); \
|
||||
getThrowHandler()((except), __FILE__, __LINE__)
|
||||
#endif
|
||||
|
||||
@ -243,7 +243,6 @@ namespace PolyVox
|
||||
{
|
||||
//Should never happen
|
||||
POLYVOX_THROW(std::invalid_argument, "Wrap mode parameter has an unrecognised value.");
|
||||
return VoxelType();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -201,7 +201,6 @@ namespace PolyVox
|
||||
{
|
||||
//Should never happen
|
||||
POLYVOX_THROW(std::invalid_argument, "Wrap mode parameter has an unrecognised value.");
|
||||
return VoxelType();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -201,7 +201,6 @@ namespace PolyVox
|
||||
{
|
||||
//Should never happen
|
||||
POLYVOX_THROW(std::invalid_argument, "Wrap mode parameter has an unrecognised value.");
|
||||
return VoxelType();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -25,116 +25,118 @@ freely, subject to the following restrictions:
|
||||
|
||||
namespace PolyVox
|
||||
{
|
||||
void defaultLogHandler(const std::string& message, LogLevel logLevel)
|
||||
/**
|
||||
* \return A pointer to the null stream.
|
||||
*/
|
||||
std::ostream* getNullStream(void)
|
||||
{
|
||||
switch(logLevel)
|
||||
{
|
||||
case LogLevels::Debug:
|
||||
{
|
||||
// Debug messages are not output by this default log handler.
|
||||
// Provide a custom handler if you want to process them.
|
||||
break;
|
||||
// Passing zero to the stream constructor guarentees it will discard all input. See
|
||||
// here http://stackoverflow.com/a/8244052 and here http://stackoverflow.com/a/6240980
|
||||
static std::ostream s_NullStream(0);
|
||||
return &s_NullStream;
|
||||
}
|
||||
case LogLevels::Info:
|
||||
|
||||
// These create the global stream instances, created on demand.
|
||||
namespace Impl
|
||||
{
|
||||
std::cout << "Info: " << message.c_str() << std::endl;
|
||||
break;
|
||||
}
|
||||
case LogLevels::Warning:
|
||||
std::ostream*& getTraceStreamInstance()
|
||||
{
|
||||
std::cerr << "Warning: " << message.c_str() << std::endl;
|
||||
break;
|
||||
static std::ostream* s_pTraceStream = getNullStream();
|
||||
return s_pTraceStream;
|
||||
}
|
||||
case LogLevels::Error:
|
||||
|
||||
std::ostream*& getDebugStreamInstance()
|
||||
{
|
||||
std::cerr << "Error: " << message.c_str() << std::endl;
|
||||
break;
|
||||
static std::ostream* s_pDebugStream = getNullStream();
|
||||
return s_pDebugStream;
|
||||
}
|
||||
case LogLevels::Fatal:
|
||||
|
||||
std::ostream*& getInfoStreamInstance()
|
||||
{
|
||||
std::cerr << "Fatal: " << message.c_str() << std::endl;
|
||||
break;
|
||||
static std::ostream* s_pInfoStream = &(std::cout);
|
||||
return s_pInfoStream;
|
||||
}
|
||||
|
||||
std::ostream*& getWarningStreamInstance()
|
||||
{
|
||||
static std::ostream* s_pWarningStream = &(std::cerr);
|
||||
return s_pWarningStream;
|
||||
}
|
||||
|
||||
std::ostream*& getErrorStreamInstance()
|
||||
{
|
||||
static std::ostream* s_pErrorStream = &(std::cerr);
|
||||
return s_pErrorStream;
|
||||
}
|
||||
|
||||
std::ostream*& getFatalStreamInstance()
|
||||
{
|
||||
static std::ostream* s_pFatalStream = &(std::cerr);
|
||||
return s_pFatalStream;
|
||||
}
|
||||
}
|
||||
|
||||
LogHandler& getLogHandlerInstance()
|
||||
void setTraceStream(std::ostream* pStream)
|
||||
{
|
||||
static LogHandler s_fLogHandler = &defaultLogHandler;
|
||||
return s_fLogHandler;
|
||||
Impl::getTraceStreamInstance() = pStream;
|
||||
}
|
||||
|
||||
LogHandler getLogHandler()
|
||||
void setDebugStream(std::ostream* pStream)
|
||||
{
|
||||
return getLogHandlerInstance();
|
||||
Impl::getDebugStreamInstance() = pStream;
|
||||
}
|
||||
|
||||
void setLogHandler(LogHandler fNewHandler)
|
||||
void setInfoStream(std::ostream* pStream)
|
||||
{
|
||||
getLogHandlerInstance() = fNewHandler;
|
||||
Impl::getInfoStreamInstance() = pStream;
|
||||
}
|
||||
|
||||
void log(const std::string& message, LogLevel logLevel)
|
||||
void setWarningStream(std::ostream* pStream)
|
||||
{
|
||||
LogHandler logHandler = getLogHandler();
|
||||
if(logHandler)
|
||||
{
|
||||
logHandler(message, logLevel);
|
||||
}
|
||||
Impl::getWarningStreamInstance() = pStream;
|
||||
}
|
||||
|
||||
// Some handy wrappers
|
||||
void logDebug(const std::string& message)
|
||||
void setErrorStream(std::ostream* pStream)
|
||||
{
|
||||
log(message, LogLevels::Debug );
|
||||
Impl::getErrorStreamInstance() = pStream;
|
||||
}
|
||||
|
||||
void logInfo(const std::string& message)
|
||||
// Fatal stream for logging
|
||||
std::ostream*& getFatalStreamInstance()
|
||||
{
|
||||
log(message, LogLevels::Info);
|
||||
static std::ostream* s_pFatalStream = &(std::cerr);
|
||||
return s_pFatalStream;
|
||||
}
|
||||
|
||||
void logWarning(const std::string& message)
|
||||
void setFatalStream(std::ostream* pStream)
|
||||
{
|
||||
log(message, LogLevels::Warning);
|
||||
}
|
||||
|
||||
void logError(const std::string& message)
|
||||
{
|
||||
log(message, LogLevels::Error);
|
||||
}
|
||||
|
||||
void logFatal(const std::string& message)
|
||||
{
|
||||
log(message, LogLevels::Fatal);
|
||||
getFatalStreamInstance() = pStream;
|
||||
}
|
||||
|
||||
#ifndef POLYVOX_THROW_ENABLED
|
||||
void defaultThrowHandler(std::exception& e, const char* file, int line)
|
||||
{
|
||||
std::stringstream ss; \
|
||||
ss << std::endl << std::endl; \
|
||||
ss << " PolyVox exception thrown!" << std::endl; \
|
||||
ss << " =========================" << std::endl; \
|
||||
ss << " PolyVox has tried to throw an exception but it was built without support" << std::endl; \
|
||||
ss << " for exceptions. In this scenario PolyVox will call a 'throw handler'" << std::endl; \
|
||||
ss << " and this message is being printed by the default throw handler." << std::endl << std::endl; \
|
||||
|
||||
ss << " If you don't want to enable exceptions then you should try to determine why" << std::endl; \
|
||||
ss << " this exception was thrown and make sure it doesn't happen again. If it was" << std::endl; \
|
||||
ss << " due to something like an invalid argument to a function then you should be" << std::endl; \
|
||||
ss << " able to fix it quite easily by validating parameters as appropriate. More" << std::endl; \
|
||||
ss << " complex exception scenarios (out of memory, etc) might be harder to fix and" << std::endl; \
|
||||
ss << " you should replace this default handler with something which is more" << std::endl; \
|
||||
ss << " meaningful to your users." << std::endl << std::endl; \
|
||||
|
||||
ss << " Exception details" << std::endl; \
|
||||
ss << " -----------------" << std::endl; \
|
||||
ss << " Line: " << line << std::endl; \
|
||||
ss << " File: " << file << std::endl; \
|
||||
ss << " Message: " << e.what() << std::endl << std::endl; \
|
||||
PolyVox::logFatal(ss.str()); \
|
||||
|
||||
logFatal() << "\n"; \
|
||||
logFatal() << " PolyVox exception thrown!"; \
|
||||
logFatal() << " ========================="; \
|
||||
logFatal() << " PolyVox has tried to throw an exception but it was built without support"; \
|
||||
logFatal() << " for exceptions. In this scenario PolyVox will call a 'throw handler'"; \
|
||||
logFatal() << " and this message is being printed by the default throw handler."; \
|
||||
logFatal() << "\n"; \
|
||||
logFatal() << " If you don't want to enable exceptions then you should try to determine why"; \
|
||||
logFatal() << " this exception was thrown and make sure it doesn't happen again. If it was"; \
|
||||
logFatal() << " due to something like an invalid argument to a function then you should be"; \
|
||||
logFatal() << " able to fix it quite easily by validating parameters as appropriate. More"; \
|
||||
logFatal() << " complex exception scenarios (out of memory, etc) might be harder to fix and"; \
|
||||
logFatal() << " you should replace this default handler with something which is more"; \
|
||||
logFatal() << " meaningful to your users."; \
|
||||
logFatal() << "\n"; \
|
||||
logFatal() << " Exception details"; \
|
||||
logFatal() << " -----------------"; \
|
||||
logFatal() << " Line: " << line; \
|
||||
logFatal() << " File: " << file; \
|
||||
logFatal() << " Message: " << e.what(); \
|
||||
logFatal() << "\n"; \
|
||||
POLYVOX_HALT(); \
|
||||
}
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user