ACE/ace/Logging_Strategy.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Logging_Strategy.h
   6  *
   7  *  @author Prashant Jain <pjain@cs.wustl.edu>
   8  *  @author Orlando Ribeiro <oribeiro@inescporto.pt>
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_LOGGING_STRATEGY_H
  13 #define ACE_LOGGING_STRATEGY_H
  14
  15 #include "ace/Service_Object.h"
  16 #include "ace/Log_Category.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #if !defined (ACE_DEFAULT_LOGFILE_POLL_INTERVAL)
  23 #define ACE_DEFAULT_LOGFILE_POLL_INTERVAL 600 /* Seconds */
  24 #endif /* ACE_DEFAULT_LOGFILE_POLL_INTERVAL */
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 /**
  29  * @class ACE_Logging_Strategy
  30  *
  31  * @brief
  32  * This class provides a way to dynamically configure the ACE logging
  33  * mechanism at run time as well as enable the mechanisms for limiting
  34  * log file size and log file backup/rotation capability.
  35  *
  36  * Depending upon when this service is invoked and with what
  37  * flags, the output of other network services can be
  38  * controlled. The output can be streamed to stderr, to a file,
  39  * to a logging daemon, or it can be set to be "silent".
  40  * If logging records are output to a file, the file can be set
  41  * to a maximum size and repeatedly split into new files.  The
  42  * log file size can be limited at any logging point (i.e.,
  43  * application, client logging daemon, or server logging daemon)
  44  * by specifying the -i @param sample_interval_in_secs and -m
  45  * @param max_size_in_KB options for the Logging_Strategy class in a
  46  * svc.conf file.
  47  *
  48  * By default, two logfiles are generated.  It's possible, however, to
  49  * generate as many logfiles as necessary to store all the
  50  * information.  To achieve this, it is only necessary to indicate the
  51  * maximum size of the logfiles via the -m option and the process will
  52  * generate automatically the logfiles.  You can control the total
  53  * number of logfiles created via the -n option.
  54  *
  55  * By using the -o option we can also choose the mode of organization
  56  * of the files, e.g., the first one is the normal used in Unix
  57  * systems (when cron rotates the logs it keeps the lowest number the
  58  * most recent one), the second is for increasing speed (we only
  59  * create a new log file, and don't rotate the others (fewer accesses
  60  * to disk)).
  61  *
  62  * By default, the @c ACE_Logging_Strategy uses the singleton reactor,
  63  * i.e., what's returned by @c ACE_Reactor::instance().  If you want
  64  * to set the reactor used by @c ACE_Logging_Strategy to something
  65  * other than the singleton reactor you'll need to get a pointer to
  66  * the @c ACE_Logging_Strategy instance and do this
  67  *
  68  * ACE_Reactor my_reactor;
  69  * ACE_Logging_Strategy *logging_strategy = ...... // Get instance.
  70  *
  71  * logging_strategy->reactor (&my_reactor);
  72  *
  73  * and then logging_strategy will use your reactor.  If you're
  74  * dynamically linking the @c ACE_Logging_Strategy then you can use
  75  * the @c ACE_Dynamic_Service template to get a pointer to the
  76  * @c ACE_Logging_Strategy.
  77  */
  78 class ACE_Export ACE_Logging_Strategy : public ACE_Service_Object
  79 {
  80 public:
  81   /// Constructor.
  82   ACE_Logging_Strategy ();
  83
  84   /// Destructor.
  85   ~ACE_Logging_Strategy ();
  86
  87   /// Dynamic linking initialization hook.
  88   virtual int init (int argc, ACE_TCHAR *argv[]);
  89
  90   /// Dynamic linking termination hook.
  91   virtual int fini ();
  92
  93   /**
  94    * Timeout handler which tests logfile size.  If the current logfile
  95    * size exceeds @c max_size_, the current logfile is closed, saved to
  96    * logfile.old, and a new logfile is reopened.
  97    */
  98   virtual int handle_timeout (const ACE_Time_Value& tv,
  99                               const void* arg);
 100
 101   /**
 102    * This function helps to cancel timer events for this logging strategy
 103    * in reactor during shutdown.
 104    */
 105   virtual int handle_close (ACE_HANDLE,
 106                             ACE_Reactor_Mask);
 107
 108   /**
 109    * Reactor accessors. If reactor changes then we need remove this
 110    * event handler from previous reactor and scheduler for timer events
 111    * in a new one.
 112    */
 113   virtual void reactor (ACE_Reactor *r);
 114
 115   virtual ACE_Reactor * reactor () const;
 116
 117   /**
 118    * Parse arguments provided in svc.conf file.
 119    * @arg '-f' Pass in the flags (such as OSTREAM, STDERR, LOGGER, VERBOSE,
 120    *           SILENT, VERBOSE_LITE) used to control logging.
 121    * @arg '-i' The interval (in seconds) at which the logfile size is sampled
 122    *           (default is 0, i.e., do not sample by default).
 123    * @arg '-k' Set the logging key.
 124    * @arg '-m' Maximum logfile size in Kbytes.
 125    * @arg '-n' Set the program name for the %n format specifier.
 126    * @arg '-N' The maximum number of logfiles that we want created.
 127    * @arg '-o' Specifies that we want the no standard logfiles ordering
 128    *           (fastest processing in handle_timeout()).  Default is not to
 129    *           order logfiles.
 130    * @arg '-p' Pass in the process-wide priorities to either enable (e.g.,
 131    *           DEBUG, INFO, WARNING, NOTICE, ERROR, CRITICAL, ALERT,
 132    *           EMERGENCY) or to disable (e.g., ~DEBUG, ~INFO, ~WARNING,
 133    *           ~NOTICE, ~ERROR, ~CRITICAL, ~ALERT, ~EMERGENCY).
 134    * @arg '-s' Ensure that the OSTREAM flag is set and log to the @a filename.
 135    * @arg '-t' Pass in the thread-wide priorities to either enable (e.g.,
 136    *           DEBUG, INFO, WARNING, NOTICE, ERROR, CRITICAL, ALERT,
 137    *           EMERGENCY) or to disable (e.g., ~DEBUG, ~INFO, ~WARNING,
 138    *           ~NOTICE, ~ERROR, ~CRITICAL, ~ALERT, ~EMERGENCY).
 139    * @arg '-w' Cause the logfile to be wiped out, both on startup and on
 140    *           reconfiguration.
 141    */
 142   int parse_args (int argc, ACE_TCHAR *argv[]);
 143
 144   void log_msg (ACE_Log_Msg *log_msg);
 145
 146 protected:
 147   /// Tokenize to set all the flags
 148   void tokenize (ACE_TCHAR *flag_string);
 149
 150   /// Tokenize to set priorities (either process or thread one).
 151   void priorities (ACE_TCHAR *priority_string,
 152                    ACE_Log_Msg::MASK_TYPE mask);
 153
 154   /// Current thread's priority mask set by @c priorities
 155   u_long thread_priority_mask_;
 156
 157   /// Process-wide priority mask set by @c priorities
 158   u_long process_priority_mask_;
 159
 160   /// Flags we keep track of.
 161   u_long flags_;
 162
 163   /// File name we're logging to.
 164   ACE_TCHAR *filename_;
 165
 166   /// Logger key for distributed logging.
 167   ACE_TCHAR *logger_key_;
 168
 169   /// Program name to be used for %n format specifier.
 170   ACE_TCHAR *program_name_;
 171
 172   /// If true then wipeout the logfile, otherwise append to it.
 173   /// Default value is false.
 174   bool wipeout_logfile_;
 175
 176   /// If true we have a maximum number of log files we can write.
 177   /// Default value is false, i.e., no maximum number.
 178   bool fixed_number_;
 179
 180   /// If true we order the files as we rotate them.  Default value
 181   /// is false, i.e., we do not rotate files by default.
 182   bool order_files_;
 183
 184   /// This tells us in what file we last wrote. It will be increased
 185   /// to enable multiple log files
 186   int count_;
 187
 188   /// Tells us what is the maximum log file to write. We will write
 189   /// @c max_file_number_ + 1 files (includes the current log file).
 190   /// Default value is 1, i.e., 2 files by default.
 191   int max_file_number_;
 192
 193   /// If non-zero, sampling interval (in secs) at which maximum logfile
 194   /// size is checked, otherwise logfile size can grow indefinitely.
 195   /// Default value is 0.
 196   u_long interval_;
 197
 198   /// Maximum logfile size (in KB).  Default value is
 199   /// ACE_DEFAULT_MAX_LOGFILE_SIZE.
 200   u_long max_size_;
 201
 202   /// ACE_Log_Msg instance to work with
 203   ACE_Log_Msg *log_msg_;
 204 };
 205
 206 ACE_STATIC_SVC_DECLARE_EXPORT(ACE, ACE_Logging_Strategy)
 207
 208 ACE_FACTORY_DECLARE (ACE, ACE_Logging_Strategy)
 209
 210 ACE_END_VERSIONED_NAMESPACE_DECL
 211
 212 #endif /* ACE_LOGGING_STRATEGY_H */