nucleus/library/loggers/file_logger.h

   1 #ifndef FILE_LOGGER_CLASS
   2 #define FILE_LOGGER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : file_logger                                                       *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$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 //! Enables the printing of information to a log file.
  19 /*!
  20   The information can be conditionally printed using the filter support.
  21   The log file will automatically be truncated when it passes the size limit.
  22 */
  23
  24 #include "console_logger.h"
  25 #include "eol_aware.h"
  26 #include "filter_set.h"
  27
  28 #include <basis/astring.h>
  29 #include <basis/contracts.h>
  30 #include <basis/functions.h>
  31 #include <basis/mutex.h>
  32 #include <filesystem/byte_filer.h>
  33 #include <textual/parser_bits.h>
  34
  35 namespace loggers {
  36
  37 class file_logger : public virtual standard_log_base
  38 {
  39 public:
  40   file_logger();
  41     //!< creates a logger without a log file and with the default size limit.
  42     /*!< the log file name can be changed using filename(). */
  43
  44   file_logger(const basis::astring &filename, int limit = DEFAULT_LOG_FILE_SIZE);
  45     //!< constructs a logger using the "filename" for output.
  46     /*!< there will be no logging if the "filename" is empty.  the "limit"
  47     specifies how large the log file can be (in bytes). */
  48
  49   virtual ~file_logger();
  50
  51   DEFINE_CLASS_NAME("file_logger");
  52
  53   enum limits {
  54     //! this just defines the default for the log file size.
  55     DEFAULT_LOG_FILE_SIZE = 0x10F00D
  56   };
  57
  58   bool good() const;
  59     //!< returns true if the logger appears correctly hooked up to a file.
  60     /*!< note that we don't open the file when file_logger is constructed;
  61     it is only opened once the first logging is attempted. */
  62
  63   bool reopen();
  64     //!< closes the current file and attempts to reopen it.
  65     /*!< this is handy if the original opening of the file failed. */
  66
  67   basis::outcome log(const basis::base_string &info, int filter = basis::ALWAYS_PRINT);
  68     //!< writes information to the log file (if the filename is valid).
  69     /*!< the "filter" value is checked to see if it is in the current set
  70     of allowed filters.  a value of zero is always printed.  if the filename()
  71     has not been set, then the information is lost. */
  72
  73   basis::outcome log_bytes(const basis::byte_array &to_log, int filter = basis::ALWAYS_PRINT);
  74     //!< sends a stream of bytes "to_log" without interpretation into the log.
  75     /*!< if the "filter" is not enabled, then the info is just tossed out. */
  76
  77   basis::outcome format_bytes(const basis::byte_array &to_log, int filter = basis::ALWAYS_PRINT);
  78     //!< fancifully formats a stream of bytes "to_log" and sends them into log.
  79
  80   basis::astring name() const;
  81     //!< observes the filename where logged information is written.
  82   void name(const basis::astring &new_name);
  83     //!< modifies the filename where logged information will be written.
  84     /*!< if "new_name" is blank, then the logged information will not
  85     be saved. */
  86
  87   int limit() const { return int(_file_limit); }
  88     //!< observes the allowable size of the log file.
  89   void limit(int new_limit) { _file_limit = new_limit; }
  90     //!< modifies the allowable size of the log file.
  91
  92   void flush();
  93     //!< causes any pending writes to be sent to the output file.
  94
  95   void truncate(size_t new_size);
  96     //!< chops the file to ensure it doesn't go much over the file size limit.
  97     /*!< this can be used externally also, but be careful with it. */
  98
  99   //! returns a log file name for file_logger based on the program name.
 100   /*! for a program named myapp.exe, this will be in the form:
 101     {logging_dir}/myapp.log
 102   */
 103   static basis::astring log_file_for_app_name();
 104
 105 private:
 106   basis::astring *_filename;  //!< debugging output file.
 107   size_t _file_limit;  //!< maximum length of file before truncation.
 108   filesystem::byte_filer *_outfile;  //!< the object that points at our output file.
 109   basis::mutex *_flock;  //!< protects the file and other parameters.
 110
 111   int size_reduction() const;
 112     //!< returns the size of the chunk to truncate from the file.
 113     /*!< this is a percentage of the maximum size allowed. */
 114
 115   bool open_file();
 116     //!< if the opening of the file is successful, then true is returned.
 117     /*!< also, the _outfile member variable is non-zero. */
 118
 119   void close_file();
 120     //!< shuts down the file, if any, we had opened for logging.
 121
 122   // unavailable.
 123   file_logger(const file_logger &);
 124   file_logger &operator =(const file_logger &);
 125 };
 126
 127 //////////////
 128
 129 //! a macro that retasks the program-wide logger as a file_logger.
 130 #define SETUP_FILE_LOGGER { \
 131   loggers::standard_log_base *old_log = loggers::program_wide_logger::set \
 132     (new loggers::file_logger(loggers::file_logger::log_file_for_app_name())); \
 133   WHACK(old_log); \
 134 }
 135
 136 } //namespace.
 137
 138 #endif
 139