logging

The contents of this module can be included with the header hpx/modules/logging.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/logging.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

Header hpx/logging/format/destinations.hpp

namespace hpx
namespace util
namespace logging
namespace destination

Destination is a manipulator. It contains a place where the message, after being formatted, is to be written to.

Some viable destinations are : the console, a file, a socket, etc.

struct cerr : public hpx::util::logging::destination::manipulator
#include <destinations.hpp>

Writes the string to cerr.

Public Functions

~cerr()

Public Static Functions

static std::unique_ptr<cerr> make()

Protected Functions

cerr()
struct cout : public hpx::util::logging::destination::manipulator
#include <destinations.hpp>

Writes the string to console.

Public Functions

~cout()

Public Static Functions

static std::unique_ptr<cout> make()

Protected Functions

cout()
struct dbg_window : public hpx::util::logging::destination::manipulator
#include <destinations.hpp>

Writes the string to output debug window.

For non-Windows systems, this is the console.

Public Functions

~dbg_window()

Public Static Functions

static std::unique_ptr<dbg_window> make()

Protected Functions

dbg_window()
struct file : public hpx::util::logging::destination::manipulator
#include <destinations.hpp>

Writes the string to a file.

Public Functions

~file()

Public Static Functions

static std::unique_ptr<file> make(std::string const &file_name, file_settings set = {})

constructs the file destination

Parameters

  • file_name: name of the file

  • set: [optional] file settings - see file_settings class, and dealing_with_flags

Protected Functions

file(std::string const &file_name, file_settings set)

Protected Attributes

std::string name
file_settings settings
struct file_settings
#include <destinations.hpp>

settings for when constructing a file class. To see how it’s used, see dealing_with_flags.

Public Functions

file_settings()

Public Members

bool flush_each_time : 1

if true (default), flushes after each write

bool initial_overwrite : 1
bool do_append : 1
std::ios_base::openmode extra_flags

just in case you have some extra flags to pass, when opening the file

struct stream : public hpx::util::logging::destination::manipulator
#include <destinations.hpp>

writes to stream.

Note

: The stream must outlive this object! Or, clear() the stream, before the stream is deleted.

Public Functions

~stream()
void set_stream(std::ostream *stream_ptr)

resets the stream. Further output will be written to this stream

void clear()

clears the stream. Further output will be ignored

Public Static Functions

static std::unique_ptr<stream> make(std::ostream *stream_ptr)

Protected Functions

stream(std::ostream *stream_ptr)

Protected Attributes

std::ostream *ptr

Header hpx/logging/format/formatters.hpp

namespace hpx
namespace util
namespace logging
namespace formatter

Formatter is a manipulator. It allows you to format the message before writing it to the destination(s)

Examples of formatters are : prepend the time, prepend high-precision time, prepend the index of the message, etc.

struct high_precision_time : public hpx::util::logging::formatter::manipulator
#include <formatters.hpp>

Prefixes the message with a high-precision time (. You pass the format string at construction. 

#include <hpx/logging/format/formatter/high_precision_time.hpp>

Internally, it uses hpx::util::date_time::microsec_time_clock. So, our precision matches this class.

The format can contain escape sequences: $dd - day, 2 digits $MM - month, 2 digits $yy - year, 2 digits $yyyy - year, 4 digits $hh - hour, 2 digits $mm - minute, 2 digits $ss - second, 2 digits $mili - milliseconds $micro - microseconds (if the high precision clock allows; otherwise, it pads zeros) $nano - nanoseconds (if the high precision clock allows; otherwise, it pads zeros)

Example:

high_precision_time("$mm:$ss:$micro");

Parameters

  • convert: [optional] In case there needs to be a conversion between std::(w)string and the string that holds your logged message. See convert_format.

Public Functions

~high_precision_time()

Public Static Functions

static std::unique_ptr<high_precision_time> make(std::string const &format)

Protected Functions

high_precision_time(std::string const &format)
struct idx : public hpx::util::logging::formatter::manipulator
#include <formatters.hpp>

prefixes each message with an index.

Example: 

L_ << "my message";
L_ << "my 2nd message";

This will output something similar to:

[1] my message
[2] my 2nd message

Public Functions

~idx()

Public Static Functions

static std::unique_ptr<idx> make()

Protected Functions

idx()
struct thread_id : public hpx::util::logging::formatter::manipulator
#include <formatters.hpp>

Writes the thread_id to the log.

Parameters

  • convert: [optional] In case there needs to be a conversion between std::(w)string and the string that holds your logged message. See convert_format.

Public Functions

~thread_id()

Public Static Functions

static std::unique_ptr<thread_id> make()

Protected Functions

thread_id()

Header hpx/logging/format/named_write.hpp

namespace hpx
namespace util
namespace logging
namespace writer
struct named_write
#include <named_write.hpp>

Composed of a named formatter and a named destinations. Thus, you can specify the formatting and destinations as strings. 

#include <hpx/logging/format/named_write.hpp>

Contains a very easy interface for using formatters and destinations:

  • at construction, specify 2 params: the formatter string and the destinations string

Setting the formatters and destinations to write to is extremely simple:

// Set the formatters (first param) and destinatins (second step) in one step
g_l()->writer().write("%time%($hh:$mm.$ss.$mili) [%idx%] |\n",
"cout file(out.txt) debug");

// set the formatter(s)
g_l()->writer().format("%time%($hh:$mm.$ss.$mili) [%idx%] |\n");

// set the destination(s)
g_l()->writer().destination("cout file(out.txt) debug");

Public Functions

named_write()
void format(std::string const &format_str)

sets the format string: what should be before, and what after the original message, separated by “|”

Example:

“[%idx%] |\n” - this writes “[%idx%] ” before the message, and “\n” after the message

If “|” is not present, the whole message is prepended to the message

void destination(std::string const &destination_str)

sets the destinations string - where should logged messages be outputted

void write(std::string const &format_str, std::string const &destination_str)

Specifies the formats and destinations in one step.

void operator()(message const &msg) const
template<typename Formatter>
void set_formatter(std::string const &name, Formatter fmt)

Replaces a formatter from the named formatter.

You can use this, for instance, when you want to share a formatter between multiple named writers.

template<typename Formatter, typename ...Args>
void set_formatter(std::string const &name, Args&&... args)
template<typename Destination>
void set_destination(std::string const &name, Destination dest)

Replaces a destination from the named destination.

You can use this, for instance, when you want to share a destination between multiple named writers.

template<typename Destination, typename ...Args>
void set_destination(std::string const &name, Args&&... args)

Private Functions

void configure_formatter(std::string const &format)
void configure_destination(std::string const &format)

Private Members

detail::named_formatters m_format
detail::named_destinations m_destination
std::string m_format_str
std::string m_destination_str

Header hpx/logging/level.hpp

namespace hpx
namespace util
namespace logging

Enums

enum level

Handling levels - classes that can hold and/or deal with levels.

  • filters and level holders

By default we have these levels: 

- debug (smallest level),
- info,
- warning ,
- error ,
- fatal (highest level)

Depending on which level is enabled for your application, some messages will reach the log: those messages having at least that level. For instance, if info level is enabled, all logged messages will reach the log. If warning level is enabled, all messages are logged, but the warnings. If debug level is enabled, messages that have levels debug, error, fatal will be logged.

Values:

disable_all = static_cast<unsigned int>(-1)
enable_all = 0
debug = 1000
info = 2000
warning = 3000
error = 4000
fatal = 5000
always = 6000

Functions

void format_value(std::ostream &os, boost::string_ref spec, level value)

Header hpx/logging/logging.hpp

Include this file when you’re using the logging lib, but don’t necessarily want to use formatters and destinations. If you want to use formatters and destinations, then you can include this one instead:

#include <hpx/logging/format.hpp>

Header hpx/logging/manipulator.hpp

namespace hpx
namespace util
namespace logging
namespace destination

Destination is a manipulator. It contains a place where the message, after being formatted, is to be written to.

Some viable destinations are : the console, a file, a socket, etc.

struct manipulator
#include <manipulator.hpp>

What to use as base class, for your destination classes.

Subclassed by hpx::util::logging::destination::cerr, hpx::util::logging::destination::cout, hpx::util::logging::destination::dbg_window, hpx::util::logging::destination::file, hpx::util::logging::destination::stream

Public Functions

virtual void operator()(message const &val) = 0
virtual void configure(std::string const&)

Override this if you want to allow configuration through scripting.

That is, this allows configuration of your manipulator at run-time.

virtual ~manipulator()

Protected Functions

manipulator()
namespace formatter

Formatter is a manipulator. It allows you to format the message before writing it to the destination(s)

Examples of formatters are : prepend the time, prepend high-precision time, prepend the index of the message, etc.

struct manipulator
#include <manipulator.hpp>

What to use as base class, for your formatter classes.

Subclassed by hpx::util::logging::formatter::high_precision_time, hpx::util::logging::formatter::idx, hpx::util::logging::formatter::thread_id

Public Functions

virtual void operator()(std::ostream &to) const = 0
virtual void configure(std::string const&)

Override this if you want to allow configuration through scripting.

That is, this allows configuration of your manipulator at run-time.

virtual ~manipulator()

Protected Functions

manipulator()

Friends

void format_value(std::ostream &os, boost::string_ref, manipulator const &value)

Header hpx/logging/message.hpp

namespace hpx
namespace util
namespace logging
class message
#include <message.hpp>

Optimizes the formatting for prepending and/or appending strings to the original message.

It keeps all the modified message in one string. Useful if some formatter needs to access the whole string at once.

reserve() - the size that is reserved for prepending (similar to string::reserve function)

Note : as strings are prepended, reserve() shrinks.

Public Functions

message()
message(std::stringstream msg)

Parameters

  • msg: - the message that is originally cached

message(message &&other)
template<typename T>
message &operator<<(T &&v)
template<typename ...Args>
message &format(boost::string_ref format_str, Args const&... args)
std::string const &full_string() const

returns the full string

bool empty() const

Private Members

std::stringstream m_str
bool m_full_msg_computed
std::string m_full_msg

Friends

std::ostream &operator<<(std::ostream &os, message const &value)

Header hpx/modules/logging.hpp

Defines

LAGAS_(lvl)
LPT_(lvl)
LTIM_(lvl)
LPROGRESS_
LHPX_(lvl, cat)
LAPP_(lvl)
LDEB_
LTM_(lvl)
LRT_(lvl)
LOSH_(lvl)
LERR_(lvl)
LLCO_(lvl)
LPCS_(lvl)
LAS_(lvl)
LBT_(lvl)
LFATAL_
LAGAS_CONSOLE_(lvl)
LPT_CONSOLE_(lvl)
LTIM_CONSOLE_(lvl)
LHPX_CONSOLE_(lvl)
LAPP_CONSOLE_(lvl)
LDEB_CONSOLE_
LAGAS_ENABLED(lvl)
LPT_ENABLED(lvl)
LTIM_ENABLED(lvl)
LHPX_ENABLED(lvl)
LAPP_ENABLED(lvl)
LDEB_ENABLED

Functions

template<typename T>
bootstrap_logging const &operator<<(bootstrap_logging const &l, T&&)

Variables

constexpr bootstrap_logging lbt_
struct bootstrap_logging
#include <logging.hpp>

Public Functions

constexpr bootstrap_logging()