toast logging library


Detailed Description

Introduction

Motivation

Using the library

Introduction

The toast logging library is intended to be 'the one logging library to rule them all'. If parts of your system already have logging through another facility, the toast logging library can be adapted to work with it seamlessly. This allows slow, iterative migration to the toast logging library.

Once a system is completely converted, the toast logging library provides almost infinite flexibility as to what can be done. If, for example, you suddenly need to log to a database instead of a file, it should be as easy as changing the OutputPolicy. If you change your application to be multithreaded, simply change the Thread Policy. Need special buffering? It should be simple to write new Policies to customize the logging.

Motivation

The toast logging library was designed to stop the proliferation of logging solutions in our trading software. Alternatives like log4cpp were tried, but failed to meet the performance requirements of real time automatic trading. Many developers have simply roled their own to meet their specific performance requirements, but these solutions have not shown themselves to be flexible enough to spread throughout our system.

The toast logging library is designed to be almost infinitely flexible at compile time to provide the highest possible performance at runtime.

Using the library

The heart of this library is the toast::logger class. It is a very simple thin wrapper made simply to hold a number of relevant policies. The policies do the actual work while the toast::logger simply coordinates them. The toast::logger takes three policies as template arguments. They are the VerbosityPolicy, OutputPolicy and ThreadPolicy. Respectively they meet the requirements of the following concepts: toast::log::VerbosityPolicyConcept, toast::log::OutputPolicyConcept, toast::log::ThreadPolicyConcept.

A policy has no restrictions on its implementation so long as it meets the requirements of its concept class. You may create your own policies, but a number of policies have been provided in this library for your convenience.

Some of the OutputPolicy's provided are themselves wrappers of further policies. Some take HeaderPolicies and FooterPolicies, and some also take StreamPolicies. These policies are also defined by their concepts: toast::log::HeaderPolicyConcept, toast::log::FooterPolicyConcept, toast::log::StreamPolicyConcept.

Please take the time to look over the concepts, each will have links to the provided policies implemented in this library.

As you use the toast::logger, you'll find that in many places you really don't want to have to know the full type of the toast::logger. In these cases you can turn to the toast::log_handle. The toast::log_handle can be thought of as a kind of abstract interface to any toast::logger. Just like any other abstract inteface it does impose some overhead on each function call. In the cases where that is unacceptable, you have no choice but to know the full type of the toast::logger.

Another convenience is to be able to use a log as a stream. The toast::logstream class exists for this purpose. It has the same overhead as the toast::log_handle, and also checks the verbosity level with every call to operator<<. Again, if this overhead is unacceptable you cannot take advantage of this convenience. A future version may provide for forced messages leaving the verbosity checking to the user.

Please be sure to peruse the examples. If you have any questions, don't hesitate to post them to toast-users@lists.sourceforge.net .


Files

file  log.hpp
 log.hpp contains the toast::logger class and includes all other relevant headers.
file  log_handle.hpp
 log_handle.hpp contains the toast::log_handle class.
file  footer_policies.hpp
 This file describes the toast::log::FooterPolicyConcept and contains some possible implementations.
file  header_policies.hpp
 This file describes the toast::log::HeaderPolicyConcept and contains some possible implementations.
file  output_policies.hpp
 This file describes the toast::log::OutputPolicyConcept and contains some possible implementations.
file  rotation_policies.hpp
 This file describes the toast::log::RotationCheckPolicyConcept, the toast::log::RotationImplPolicyConcept, and the aggregating concept of these, the toast::log::RotationPolicyConcept, and contains some possible implementations.
file  severity.hpp
 This file contains toast::log::severity enum.
file  thread_policies.hpp
 This file describes the toast::log::ThreadPolicyConcept and contains some possible implementations.
file  verbosity_policies.hpp
 This file describes the toast::log::VerbosityPolicyConcept and contains some possible implementations.

Classes

class  toast::logger< VerbosityPolicy, OutputPolicy, ThreadPolicy >
 All log messages go through here. More...
class  toast::basic_log_handle< CharT >
 A handle for a logger. More...
class  toast::basic_logbuf< CharT, Traits, Alloc >
 logbuf Warning: ignores the Alloc template parameter. Will always allocate internal buffer with new. More...
class  toast::basic_logstream< CharT, Traits, Alloc >
 logstream More...
struct  toast::log::FooterPolicyConcept< Policy >
 The FooterPolicyConcept describes the interface of a FooterPolicy. More...
struct  toast::log::no_footer
 This FooterPolicy tells the logger not to print a footer. More...
struct  toast::log::newline
 This FooterPolicy tells the logger to append a newline to each message. More...
struct  toast::log::footer_policy_aggregator< FirstFooterPolicy, SecondFooterPolicy >
struct  toast::log::HeaderPolicyConcept< Policy >
 The HeaderPolicyConcept describes the interface of a HeaderPolicy. Currently the library provides three HeaderPolicies: toast::log::no_header, toast::log::microseconds, and toast::log::severity. More...
struct  toast::log::no_header
 This HeaderPolicy tells the logger not to print a header. More...
struct  toast::log::microseconds
 This HeaderPolicy tells the logger to print a microsecond timestamp before each message. More...
struct  toast::log::severity_header
 This HeaderPolicy tells the logger to print the severity of the event being logged before each message. More...
struct  toast::log::header_policy_aggregator< FirstHeaderPolicy, SecondHeaderPolicy >
class  toast::log::ConsumingOutputPolicy
 OutputPolicy's should subclass this to indicate that they support message consumption. More...
struct  toast::log::OutputPolicyConcept< Policy >
 The OutputPolicyConcept describes the interface of a OutputPolicy. Currently the library provides five OutputPolicies: toast::log::to_stdout, toast::log::to_stderr, toast::log::to_stderr_buffered, toast::log::to_stream, and toast::log::to_file. More...
struct  toast::log::to_stream< HeaderPolicy, FooterPolicy, StreamPolicy >
 This OutputPolicy directs the loggers output to a user provided stream. More...
struct  toast::log::to_stream< HeaderPolicy, no_footer, StreamPolicy >
struct  toast::log::to_stream< no_header, FooterPolicy, StreamPolicy >
struct  toast::log::to_stream< no_header, no_footer, StreamPolicy >
struct  toast::log::to_stderr_buffered< HeaderPolicy, FooterPolicy >
 This OutputPolicy buffers the loggers output and directs it to stderr. More...
struct  toast::log::to_file< HeaderPolicy, FooterPolicy, RotationPolicy >
 This OutputPolicy directs the loggers output to a file based on a user provided file name. More...
struct  toast::log::to_stdout< HeaderPolicy, FooterPolicy >
 This OutputPolicy directs the loggers output to stdout. More...
struct  toast::log::to_stderr< HeaderPolicy, FooterPolicy >
 This OutputPolicy directs the loggers output to stderr. More...
struct  toast::log::output_policy_aggregator< FirstOutputPolicy, SecondOutputPolicy >
struct  toast::log::RotationCheckPolicyConcept< Policy >
struct  toast::log::never_rotate
struct  toast::log::message_limit
struct  toast::log::max_file_size
struct  toast::log::RotationImplPolicyConcept< Policy >
struct  toast::log::roll_rotation
struct  toast::log::RotationPolicyConcept< Policy >
struct  toast::log::rotation_policy< RotationCheckPolicy, RotationImplPolicy >
struct  toast::log::StreamPolicyConcept< Policy >
 The StreamPolicyConcept describes the interface of a StreamPolicy. Currently the library provides five StreamPolicies: toast::log::any_stream, toast::log::cout_stream, toast::log::cerr_stream, toast::log::clog_stream, and toast::log::file_stream. More...
struct  toast::log::basic_any_stream< CharT, Traits >
struct  toast::log::cout_stream
struct  toast::log::cerr_stream
struct  toast::log::clog_stream
struct  toast::log::basic_file_stream< CharT, Traits >
struct  toast::log::ThreadPolicyConcept< Policy >
 The ThreadPolicyConcept describes the interface of a ThreadPolicy. Currently the library provides one ThreadPolicy: toast::log::neutral. More...
struct  toast::log::neutral
 This ThreadPolicy causes the logger to ignore threads and locking. More...
struct  toast::log::VerbosityPolicyConcept< Policy >
 The VerbosityPolicyConcept describes the interface of a VerbosityPolicy. Currently the library provides three VerbosityPolicies: toast::log::always_output, toast::log::never_output, and toast::log::check_verbosity. More...
struct  toast::log::always_output
 This VerbosityPolicy causes the logger to output log messages regardless of their severity. More...
struct  toast::log::never_output
 This VerbosityPolicy causes the logger to suppress log messages regardless of their severity. This also allows the compiler to generate very little if any code with minimal optimizations turned on. More...
struct  toast::log::check_verbosity
 This VerbosityPolicy causes the logger to output log messages based on their severity compared to the level of verbosity set by the user. More...
typedef basic_logbuf< char > toast::logbuf
 typedef for most commonly used basic_logbuf
typedef basic_logstream< char > toast::logstream
 typedef for most commonly used basic_logstream

Typedefs

typedef basic_log_handle< char > toast::log_handle
 typedef for most commonly used basic_log_handle
typedef Alloc toast::basic_logbuf::allocator_type
typedef CharT toast::basic_logbuf::char_type
typedef Traits toast::basic_logbuf::traits_type
typedef traits_type::int_type toast::basic_logbuf::int_type
typedef traits_type::off_type toast::basic_logbuf::off_type
typedef traits_type::pos_type toast::basic_logbuf::pos_type
typedef basic_log_handle< CharT > toast::basic_logbuf::log_handle_type
typedef basic_logbuf< CharT,
Traits, Alloc > 
toast::basic_logstream::streambuf_type
typedef
streambuf_type::log_handle_type 
toast::basic_logstream::log_handle_type
typedef
header_policy_aggregator
< microseconds,
severity_header > 
toast::log::default_header_policy
typedef rotation_policy
< max_file_size, roll_rotation > 
toast::log::default_rotation_policy
typedef basic_any_stream< char > toast::log::any_stream
typedef basic_file_stream< char > toast::log::file_stream

Enumerations

enum  toast::log::severity {
  toast::log::DEFAULT, toast::log::FATAL, toast::log::ALERT, toast::log::CRITICAL,
  toast::log::ERROR, toast::log::WARNING, toast::log::NOTICE, toast::log::INFO,
  toast::log::DEBUG, toast::log::TRACE
}
 severity enumeration More...

Functions

 toast::basic_logbuf::basic_logbuf (log::severity s=log::DEFAULT)
 toast::basic_logbuf::basic_logbuf (log_handle_type const &log, log::severity s=log::DEFAULT)
void toast::basic_logbuf::log (log_handle_type const &log)
log_handle_type toast::basic_logbuf::log () const
log::severity toast::basic_logbuf::severity () const
void toast::basic_logbuf::severity (log::severity s)
bool toast::basic_logbuf::check (log::severity s) const
virtual int toast::basic_logbuf::sync ()
virtual std::streamsize toast::basic_logbuf::xsputn (char_type const *s, std::streamsize n)
virtual int_type toast::basic_logbuf::overflow (int_type meta=traits_type::eof())
 toast::basic_logstream::basic_logstream (log::severity s=log::DEFAULT)
 toast::basic_logstream::basic_logstream (log_handle_type const &logger, log::severity s=log::DEFAULT)
streambuf_type const * toast::basic_logstream::rdbuf () const
streambuf_type * toast::basic_logstream::rdbuf ()
void toast::basic_logstream::log (log_handle_type const &logger)
log_handle_type toast::basic_logstream::log () const
log::severity toast::basic_logstream::severity () const
void toast::basic_logstream::severity (log::severity s)
bool toast::basic_logstream::check (log::severity s) const
 toast::detail::proxy_logstream::proxy_logstream (real_logstream_t &stream, bool active)
 toast::detail::proxy_logstream::operator real_logstream_t & ()
proxy_logstream & toast::detail::proxy_logstream::operator<< (log::severity s)
proxy_logstream & toast::detail::proxy_logstream::operator<< (std::basic_ostream< CharT, Traits > &(*pf)(std::basic_ostream< CharT, Traits > &))
template<typename T>
proxy_logstream & toast::detail::proxy_logstream::operator<< (T const &toStream)
template<typename CharT, typename Traits, typename Alloc>
detail::proxy_logstream< CharT,
Traits, Alloc > 
toast::operator<< (basic_logstream< CharT, Traits, Alloc > &os, log::severity s)
template<typename CharT, typename Traits, typename Alloc, typename T>
detail::proxy_logstream< CharT,
Traits, Alloc > 
toast::operator<< (basic_logstream< CharT, Traits, Alloc > &stream, T const &toStream)

Friends

template<typename T>
detail::proxy_logstream< CharT,
Traits, Alloc > & 
toast::basic_logbuf::detail::proxy_logstream (T const &toStream)


Enumeration Type Documentation

severity enumeration

Enumerator:
DEFAULT  No severity has been set, all messages will output
FATAL  program will likely abort after this message
ALERT  human intervention is needed, or severity will become fatal
CRITICAL  program is crippled and likely should be exited
ERROR  something's wrong
WARNING  something might be wrong
NOTICE  a normal but interesting event
INFO  FYI
DEBUG  Only useful if debugging
TRACE  programmers like to pretend they're watching the matrix go by on their screen when running a program they wrote


SourceForge.net Logo