Merge branch 'main' of feistymeow.org:feisty_meow
[feisty_meow.git] / loggers / program_wide_logger.h
1 #ifndef PROGRAM_WIDE_LOGGER_FACILITY
2 #define PROGRAM_WIDE_LOGGER_FACILITY
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : program_wide_logger facility                                      *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
9 *******************************************************************************
10 * Copyright (c) 1992-$now By Author.  This program is free software; you can  *
11 * redistribute it and/or modify it under the terms of the GNU General Public  *
12 * License as published by the Free Software Foundation; either version 2 of   *
13 * the License or (at your option) any later version.  This is online at:      *
14 *     http://www.fsf.org/copyleft/gpl.html                                    *
15 * Please send any updates to: fred@gruntose.com                               *
16 \*****************************************************************************/
17
18 #include "logging_macros.h"
19   // it seems reasonable to provide the logging macros to any file that is also using
20   // the program-wide logger.
21
22 #include <basis/contracts.h>
23 #include <basis/definitions.h>
24 #include <loggers/standard_log_base.h>
25
26 namespace loggers {
27
28 //! A class that provides logging facilities vertically to all of hoople.
29 /*!
30   Provides a per-program logging subsystem that can be used from almost
31   anywhere in the source code.
32   The program wide logger feature is a globally defined object that
33   can be switched out to perform different types of logging.
34   Note: this facility is not thread-safe.  The coder must guarantee
35   that the appropriate logger is set up before cranking up a bunch of
36   threads that use logging.
37 */
38
39 class program_wide_logger
40 {
41 public:
42   static loggers::standard_log_base &get();
43     //!< Provided by the startup code within each application for logging.
44     /*!< This can be used like any base_logger object, but the diagnostic items
45     will be stored into one log file (or other logging mechanism) per
46     program. */
47
48   static loggers::standard_log_base *set(loggers::standard_log_base *new_log);
49     //!< replaces the current program-wide logger with the "new_log".
50     /*! The "new_log" must be a valid base_logger object.  The responsibility
51     for maintaining "new_log" is taken over by the program-wide logger.
52     In return, the old program-wide logger is handed back to you and it is
53     now your responsibility.  Be very careful with it if it's owned by other
54     code and not totally managed by you. */
55
56 private:
57   static loggers::standard_log_base *c_the_wide_log;  //!< the actual logger.
58 };
59
60 //////////////
61
62 //! a trash can for logging; throws away all entries.
63 /*!
64   Provides a logger that throws away all of the strings that are logged to it.
65   This is useful when an interface requires a base_logger but one does not
66   wish to generate an output file.  This object is similar to /dev/null in Unix
67   (or Linux) and to nul: in Win32.
68 */
69
70 class null_logger : public virtual standard_log_base
71 {
72 public:
73   virtual ~null_logger() {}
74   DEFINE_CLASS_NAME("null_logger");
75   virtual basis::outcome log(const basis::base_string &formal(info), int formal(filter)) {
76     /* if (filter || !(&info)) {} */
77     return basis::common::OKAY;
78   }
79 };
80
81 } //namespace.
82
83 #endif // outer guard.
84