Merge branch 'trac622'

src/lib/log/Makefile.am

@@ -23,6 +23,10 @@ liblog_la_SOURCES += message_types.h
 liblog_la_SOURCES += root_logger_name.cc root_logger_name.h
 liblog_la_SOURCES += strutil.h strutil.cc
 
+EXTRA_DIST   = README
+EXTRA_DIST  += logger_impl_log4cxx.cc logger_impl_log4cxx.h
+EXTRA_DIST  += xdebuglevel.cc xdebuglevel.h
+
 # Note: the ordering matters: -Wno-... must follow -Wextra (defined in
 # B10_CXXFLAGS)
 liblog_la_CXXFLAGS = $(AM_CXXFLAGS)

src/lib/log/documentation.txt

@@ -59,7 +59,7 @@ The steps in using the system are:
 
 2. Run it through the message compiler to produce the .h and .cc files.  It
    is intended that this step be included in the build process.  However,
-   for not run the compiler (found in the "compiler" subdirectory) manually.
+   for now run the compiler (found in the "compiler" subdirectory) manually.
    The only argument is the name of the message file: it will produce as
    output two files, having the same name as the input file but with file
    types of ".h" and ".cc".
@@ -74,7 +74,7 @@ The steps in using the system are:
 4. Declare loggers in your code and use them to log messages.  This is
    described in more detail below.
 
-5. To set the debug level and run-time message file, call runTimeInit (declared
+5. To set the debug level and run-time message file, call initLogger (declared
    in logger_support.h) in the main program unit.  This is a temporary solution
    for Year 2, and will be replaced at a later date, the information coming
    from the configuration database.
@@ -106,7 +106,7 @@ UNKNOWN     unknown message
 
 Points to note:
 * Leading and trailing space are trimmed from the line.  Although the above
-  exampl,e has every line starting at column 1, the lines could be indented
+  example has every line starting at column 1, the lines could be indented
   if desired.
 
 * Blank lines are ignored.
@@ -120,10 +120,8 @@ Points to note:
   * $PREFIX, which has one argument: the string used to prefix symbols.  If
     absent, there is no prefix to the symbols. (Prefixes are explained below.)
   * $NAMESPACE, which has one argument: the namespace in which the symbols are
-    created.  (Specifying the argument as a double colon - i.e. "$NAMESPACE
-    ::" puts the symbol definitions in the unnamed namespace.  And not
-    including a $NAMESPACE directive will result in the symbols note being
-    put in any namespace.
+    created.  In the absence of a $NAMESPACE directive, symbols will be put
+    in the global namespace.
 
 * Lines starting + indicate an explanation for the preceding message.  These
   are intended to be processed by a separate program and used to generate
@@ -151,13 +149,11 @@ The message compiler processes the message file to produce two files:
 the form:
 
    namespace <namespace> {
-   isc::log::MessageID PREFIX_IDENTIFIER = "IDENTIFIER";
+   extern const isc::log::MessageID PREFIX_IDENTIFIER;
       :
    }
 
-The symbols define the keys in the global message dictionary.  At present
-they are defined as std::strings, but a future implementation could redefine
-them as numeric values.
+The symbols define the keys in the global message dictionary.
 
 The namespace enclosing the symbols is set by the $NAMESPACE directive.
 
@@ -167,14 +163,18 @@ ABC with "MSG_" to give the symbol MSG_ABC.  Similarly "$PREFIX E" would
 prefix it with "E" to give the symbol EABC.  If no $PREFIX is given, no
 prefix appears (so the symbol in this example would be ABC).
 
-The header file also includes a couple of lines to ensure that the message
-text is included in the final program image.
+2) A C++ source file (called <message-file-name>.cc) that holds the definitions
+of the global symbols and code to insert the symbols and messages into the map.
 
+Symbols are defined to be equal to strings holding the identifier, e.g.
 
-2) A C++ source file (called <message-file-name>.cc) that holds the code to
-insert the symbols and messages into the map.
+   extern const isc::log::MessageID MSG_DUPLNS = "DUPLNS";
 
-This file declares an array of identifiers/messages in the form:
+(The implementation allows symbols to be compared.  However, use of strings
+should not be assumed - a future implementation may change this.)
+
+In addition, the file declares an array of identifiers/messages and an object
+to add them to the global dictionary:
 
     namespace {
     const char* values[] = {
@@ -183,20 +183,9 @@ This file declares an array of identifiers/messages in the form:
         :
         NULL
     };
-    }
-
-(A more complex structure to group identifiers and their messages could be
-imposed, but as the array is generated by code and will be read by code,
-it is not needed.)
 
-It then declares an object that will add information to the global dictionary:
-
-    MessageInitializer <message-file-name>_<time>(values);
-
-(Declaring the object as "static" or in the anonymous namespace runs the risk
-of it being optimised away when the module is compiled with optimisation.
-But giving it a standard name would cause a clash when multiple files are
-used, hence an attempt at disambiguation.)
+    const isc::log::MessageInitializer initializer(values);
+    }
 
 The constructor of the MessageInitializer object retrieves the singleton
 global Dictionary object (created using standard methods to avoid the
@@ -233,10 +222,10 @@ To use the current version of the logging:
 
        isc::log::Logger logger("myname", true);
 
-   The argument is ignored for underlying implementations other than log4cxx.
-   See below for the use of this argument.
+   (The argument is required to support a possible future implementation of
+   logging.  Currently it has no effect.)
 
-3. The main program unit should include a call to isc::log::runTimeInit()
+3. The main program unit should include a call to isc::log::initLogger()
    (defined in logger_support.h) to set the logging severity, debug log level,
    and external message file.
 
@@ -250,13 +239,13 @@ To use the current version of the logging:
         isc::log::NONE
 
    b) The debug log level is only interpreted when the severity is DEBUG and
-      is an integer raning from 0 to 99.  0 should be used for the highest-level
-      debug messages and 99 for the lowest-level (and typically more verbose)
-      messages.
+      is an integer ranging from 0 to 99.  0 should be used for the
+      highest-level debug messages and 99 for the lowest-level (and typically
+      more verbose) messages.
 
    c) Name of an external message file.  This is the same as a standard message
-      file, although it should not include the $PREFIX directive. (A single
-      $PREFIX directive will be ignored; multiple directives will cause the
+      file, although it should not include any directives. (A single directive
+      of a particular type will be ignored; multiple directives will cause the
       read of the file to fail with an error.)  If a message is replaced, the
       message should include the same printf-format directives in the same order
       as the original message.
@@ -340,7 +329,7 @@ Logging Sources v Logging Severities
 When logging events, make a distinction between events related to the server
 and events related to DNS messages received.  Caution needs to be exercised
 with the latter as, if the logging is enabled in the normal course of events,
-such logging could be a denoial of service vector. For example, suppose that
+such logging could be a denial of service vector. For example, suppose that
 the main authoritiative service logger were to log both zone loading and
 unloading as INFO and a warning message if it received an invalid packet. An
 attacker could make the INFO messages unusable by flooding the server with
@@ -353,7 +342,7 @@ DEBUG is not enabled by default, so these events will not be recorded unless
 DEBUG is specifically chosen.
 
 b) Record system-related and packet-related messages via different loggers
-(e.g.  in the example given, sever events could be logged using the logger
+(e.g.  in the example given, server events could be logged using the logger
 "auth" and packet-related events at that level logged using the logger
 "pkt-auth".)  As the loggers are independent and the severity levels
 independent, fine-tuning of what and what is not recorded can be achieved.
@@ -379,56 +368,9 @@ Outstanding Issues
 
 log4cxx Issues
 ==============
+Some experimental code to utilise log4cxx as an underlying implementation
+is present in the source code directory although it is not currently used.
+The files are:
 
-Second Argument in Logger Constructor
--------------------------------------
-As noted above, when using log4cxx as the underlying implementation, the
-argument to the logger's constructor should be set true if declaring the
-logger within a method and set false (or omitted) if declaring the logger
-external to an execution unit.
-
-This is due to an apparent bug in the underlying log4cxx, where the deletion
-of a statically-declared object at program termination can cause a segment
-fault. (The destruction of internal memory structures can sometimes happen
-out of order.)  By default the Logger class creates the structures in
-its constructor but does not delete them in the destruction.  The default
-behavious works because instead of reclaiming memory at program run-down,
-the operating system reclaims it when the process is deleted.
-
-Setting the second argument "true" causes the Logger's destructor to delete
-the log4cxx structures.  This does not cause a problem if the program is
-not terminating.  So use the second form when declaring an automatic instance
-of isc::log::Logger on the stack.
-
-Building with log4cxx
----------------------
-Owing to issues with versions of log4cxx on different systems, log4cxx was
-temporarily disabled.  To use log4cxx on your system:
-
-* Uncomment the log4cxx lines in configure.ac
-* In src/lib/log, replace the logger_impl.{cc,h} files with their log4cxx
-  equivalents, i.e.
-
-  cp logger_impl_log4cxx.h logger_impl.h
-  cp logger_impl_log4cxx.cc logger_impl.cc
-
-* In src/lib/log/Makefile.am, uncomment the lines:
-
-  # AM_CPPFLAGS += $(LOG4CXX_INCLUDES)
-
-  # liblog_la_SOURCES += xdebuglevel.cc xdebuglevel.h
-
-  # liblog_la_LDFLAGS = $(LOG4CXX_LDFLAGS)
-
-* In src/lib/log/test, re-enable testing of the log4cxx implementation
-  class, i.e.
-
-  cp logger_impl_log4cxx_unittest.cc logger_impl_unittest.cc
-
-  ... and uncomment the following lines in Makefile.am:
-
-  # run_unittests_SOURCES += logger_impl_unittest.cc
-
-  # run_unittests_SOURCES += xdebuglevel_unittest.cc
-
-Then rebuild the system from scratch.
+   logger_impl_log4cxx.{cc,h}
+   xdebuglevel.{cc,h}