E-MailRelay

Classes | Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
G::LogOutput Class Reference

Controls and implements low-level logging output, as used by G::Log. More...

`#include <glogoutput.h>`

## Classes
struct | Config
| A configuration structure for G::LogOutput. More...
struct | Instance
| A set of convenience functions for calling LogOutput methods on LogOutput::instance(). More...

## Public Types
enum class | Severity { Debug , InfoMoreVerbose , InfoVerbose , InfoSummary , Warning , Error , Assertion }
enum class | SyslogFacility { User , Daemon , Mail , Cron , Local0 , Local1 , Local2 , Local3 , Local4 , Local5 , Local6 , Local7 }

## Public Member Functions
| LogOutput (const std::string &exename, const Config &config, const Path &logfile={})
| Constructor. More...
| LogOutput (const std::string &exename, const Config &config, int fd)
| Constructor overload taking a file descriptor. More...
| LogOutput (bool enabled, bool verbose=true, const G::Path &logfile={})
| Constructor overload for test programs. More...
| ~LogOutput ()
| Destructor. More...
Config | config () const noexcept
| Returns the current configuration. More...
int | fd () const noexcept
| Returns the output file descriptor. More...
void | configure (const Config &)
| Updates the current configuration. More...
bool | at (Severity) const noexcept
| Returns true if logging should occur for the given severity level. More...
void | context (std::string_view(*fn)(void *)=nullptr, void *fn_arg=nullptr) noexcept
| Sets a functor that is used to provide a context string for every log line, if configured. More...
void * | contextarg () noexcept
| Returns the functor argument as set by the last call to context(). More...
LogStream | start (Severity, const char *file, int line) noexcept
| Returns an ostream for a new log line. More...
void | output (LogStream &) noexcept
| Emits the current log line (see start()). More...
| LogOutput (const LogOutput &)=delete
| LogOutput (LogOutput &&)=delete
LogOutput & | operator= (const LogOutput &)=delete
LogOutput & | operator= (LogOutput &&)=delete

## Static Public Member Functions
static LogOutput * | instance () noexcept
| Returns a pointer to the controlling LogOutput object. More...
static void | assertion (LogOutput *, const char *file, int line, bool test, const char *test_string)
| Performs an assertion check. More...
static void | assertion (LogOutput *, const char *file, int line, void *test, const char *test_string)
| Performs an assertion check. More...
static void | assertionFailure (LogOutput *, const char *file, int line, const char *test_string) noexcept
| Reports an assertion failure. More...
static GDEF_NORETURN_LHS void | assertionAbort () GDEF_NORETURN_RHS
| Aborts the program when an assertion has failed. More...
static void | register_ (const Path &exe)
| Registers the given executable as a source of logging. More...

## Friends
struct | Instance

## Detailed Description

Controls and implements low-level logging output, as used by G::Log.

Applications should instantiate a LogOutput object in main() to enable and configure log output.

The implementation uses a file descriptor for osoutput() rather than a stream because windows file-sharing options are not accessible when building with mingw streams, and to avoid double buffering and mixed output from multiple threads.

See also
  G::Log

Definition at line 61 of file glogoutput.h.

## Member Enumeration Documentation

## ◆ Severity

enum class G::LogOutput::Severity
| strong

Definition at line 67 of file glogoutput.h.

## ◆ SyslogFacility

enum class G::LogOutput::SyslogFacility
| strong

Definition at line 78 of file glogoutput.h.

## Constructor & Destructor Documentation

## ◆ LogOutput() [1/3]

G::LogOutput::LogOutput | ( | const std::string & | exename,
|  | const Config & | config,
|  | const Path & | logfile = `{}`
| ) |  |

Constructor.

If there is no LogOutput object, or if 'config.output_enabled' is false, then there is no output at all except for assertions to stderr.

The 'exename' value is emitted as an additional prefix on each log line if it is non-empty. See also G::Arg::prefix().

The log-file path can contain substitution variables "%d" or "%h" for the current day and hour respectively. If no path is given then logging is sent to the standard error stream by default; stderr should be re-opened onto /dev/null if only syslog logging is required.

More than one LogOutput object may be created but only the first one controls output (see instance()).

Definition at line 86 of file glogoutput.cpp.

## ◆ LogOutput() [2/3]

G::LogOutput::LogOutput | ( | const std::string & | exename,
|  | const Config & | config,
|  | int | fd
| ) |  |

Constructor overload taking a file descriptor.

Typically used for non-main threads when instance() is thread-local.

Definition at line 95 of file glogoutput.cpp.

## ◆ LogOutput() [3/3]

G::LogOutput::LogOutput | ( | bool | enabled,
|  | bool | verbose = `true`,
|  | const G::Path & | logfile = `{}`
| ) |  |
| explicit

Constructor overload for test programs.

Definition at line 104 of file glogoutput.cpp.

## ◆ ~LogOutput()

G::LogOutput::~LogOutput | ( |  | ) |

Destructor.

Definition at line 138 of file glogoutput.cpp.

## Member Function Documentation

## ◆ assertion() [1/2]

void G::LogOutput::assertion | ( | LogOutput * | instance,
|  | const char * | file,
|  | int | line,
|  | bool | test,
|  | const char * | test_string
| ) |  |
| inline static

Performs an assertion check.

Definition at line 289 of file glogoutput.h.

## ◆ assertion() [2/2]

void G::LogOutput::assertion | ( | LogOutput * | instance,
|  | const char * | file,
|  | int | line,
|  | void * | test,
|  | const char * | test_string
| ) |  |
| inline static

Performs an assertion check.

This overload, using a test on a pointer, is motivated by MSVC warnings.

Definition at line 298 of file glogoutput.h.

## ◆ assertionAbort()

void G::LogOutput::assertionAbort | ( |  | ) |
| static

Aborts the program when an assertion has failed.

Definition at line 363 of file glogoutput.cpp.

## ◆ assertionFailure()

void G::LogOutput::assertionFailure | ( | LogOutput * | instance,
|  | const char * | file,
|  | int | line,
|  | const char * | test_string
| ) |  |
| static noexcept

Reports an assertion failure.

Definition at line 341 of file glogoutput.cpp.

## ◆ at()

bool G::LogOutput::at | ( | Severity | severity | ) | const
| noexcept

Returns true if logging should occur for the given severity level.

Definition at line 180 of file glogoutput.cpp.

## ◆ config()

G::LogOutput::Config G::LogOutput::config | ( |  | ) | const
| noexcept

Returns the current configuration.

Definition at line 121 of file glogoutput.cpp.

## ◆ configure()

void G::LogOutput::configure | ( | const Config & | config | ) |

Updates the current configuration.

Definition at line 133 of file glogoutput.cpp.

## ◆ context()

void G::LogOutput::context | ( | std::string_view(*)(void *) | fn = `nullptr`,
|  | void * | fn_arg = `nullptr`
| ) |  |
| noexcept

Sets a functor that is used to provide a context string for every log line, if configured.

The functor should return the context string with trailing punctuation, typically colon and space.

Definition at line 162 of file glogoutput.cpp.

## ◆ contextarg()

void * G::LogOutput::contextarg | ( |  | ) |
| noexcept

Returns the functor argument as set by the last call to context().

Definition at line 173 of file glogoutput.cpp.

## ◆ fd()

int G::LogOutput::fd | ( |  | ) | const
| noexcept

Returns the output file descriptor.

Definition at line 127 of file glogoutput.cpp.

## ◆ instance()

G::LogOutput * G::LogOutput::instance | ( |  | ) |
| static noexcept

Returns a pointer to the controlling LogOutput object.

Returns nullptr if none.

Non-main threads can do logging safely if the (private) instance pointer is declared 'thread_local' at build-time. Thread functions can then instantiate their own LogOutput object on the stack, typically with the Config object and file descriptor passed in from the main thread.

Definition at line 157 of file glogoutput.cpp.

## ◆ output()

void G::LogOutput::output | ( | LogStream & | s | ) |
| noexcept

Emits the current log line (see start()).

Does nothing if there is no LogOutput instance.

Definition at line 209 of file glogoutput.cpp.

## ◆ register_()

void G::LogOutput::register_ | ( | const Path & | exe | ) |
| static

Registers the given executable as a source of logging.

This is called from osinit(), but it might also need to be done as a program installation step with the necessary process permissions.

Definition at line 92 of file glogoutput_unix.cpp.

## ◆ start()

G::LogStream G::LogOutput::start | ( | Severity | severity,
|  | const char * | file,
|  | int | line
| ) |  |
| noexcept

Returns an ostream for a new log line.

The caller should stream out the rest of the log line into the ostream and then call output(). Calls to start() and output() should be in pairs.

Definition at line 194 of file glogoutput.cpp.

## Friends And Related Function Documentation

## ◆ Instance

friend struct Instance
| friend

Definition at line 264 of file glogoutput.h.

The documentation for this class was generated from the following files:

- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/glogoutput.h
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/glogoutput.cpp
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/glogoutput_unix.cpp
- /tmp/slackdce/slackrepo.HKsbdz/build_emailrelay/emailrelay-2.6/src/glib/glogoutput_win32.cpp