small documentation fixes

[senf.git] / Utils / Logger / Target.hh

diff --git a/Utils/Logger/Target.hh b/Utils/Logger/Target.hh
index 5b8dd1b..d8ed8d1 100644 (file)
--- a/Utils/Logger/Target.hh
+++ b/Utils/Logger/Target.hh
@@ -1,8 +1,8 @@
 // $Id$
 //
 // Copyright (C) 2007 
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// Fraunhofer Institute for Open Communication Systems (FOKUS) 
+// Competence Center NETwork research (NET), St. Augustin, GERMANY 
 //     Stefan Bund <g0dil@berlios.de>
 //
 // This program is free software; you can redistribute it and/or modify
@@ -51,12 +51,12 @@
 
 namespace senf {
 namespace log {
-
-    class TargetRegistry;
+    
+    namespace detail { class TargetRegistry; }
 
     /** \brief Logging target base class
         
-        Targets are the final destination of log messages. Every message is eventually routed to one
+        Targets are the final destination of %log messages. Every message is eventually routed to one
         or several targets.
 
         \section target_routing Routing
@@ -119,9 +119,6 @@ namespace log {
         cases messages might be lost but this cannot be avoided.
 
         \see \ref targets
-
-        \fixme optionally Integrate with Scheduler / ClockService to reduce number of gettimeofday()
-            calls.
       */
     class Target : private boost::noncopyable
     {
@@ -379,16 +376,14 @@ namespace log {
                                              somehow format and write the log message. 
 
                                              Every log message always possesses a complete set of
-                                             meta information (\a stream, \a area and \a level). The
-                                             \a area may be an empty string if the message was
-                                             written from the senf::log::DefaultArea.
+                                             meta information (\a stream, \a area and \a level).
 
                                              \note This member must \e not block since it may be
                                                  called from any unknown context. This prohibits
                                                  simple logging over NFS or many other network
                                                  protocols.
 
-                                             \param[in] timestamp log message timing information
+                                             \param[in] timestamp %log message timing information
                                              \param[in] stream message stream
                                              \param[in] area message area
                                              \param[in] level message level
@@ -401,8 +396,58 @@ namespace log {
         RIB rib_;
         
         friend class detail::AreaBase;
+        friend class detail::TargetRegistry;
+    };
+
+    /** \brief Log message time source abstract base class
+
+        Instances derived from TimeSource provide the Logging library with the current date/time
+        value. The \c operator() member must be implemented to return the current universal time
+        (UTC).
+
+        A new TimeSource may be installed using \ref senf::log::timeSource().
+
+        \ingroup config
+     */
+    struct TimeSource
+    {
+        virtual ~TimeSource();
+        virtual boost::posix_time::ptime operator()() const = 0;
+    };
+
+    /** \brief Default %log message time source
+
+        This time source is installed by default and uses gettimeofday() (via the Boost.DateTime
+        library) to get the current universal time.
+        
+        \ingroup config
+     */
+    struct SystemTimeSource : public TimeSource
+    {
+        virtual boost::posix_time::ptime operator()() const;
     };
 
+    /** \brief Change log message time source
+
+        Set the log message time source to \a source. The logging library will take ownership of \e
+        source and will take care to free it, if necessary.
+
+        Since the time source class will in almost all cases be default constructible, see the
+        template overload for a simpler interface.
+
+        \ingroup config
+     */
+    void timeSource(std::auto_ptr<TimeSource> source);
+
+    /** \brief Change log message time source
+
+        Set the log message time source to (an instance of) \a Source.  \a Source must be default
+        constructible, otherwise use the non-template senf::log::timeSource() overload.
+
+        \ingroup config
+     */
+    template <class Source> void timeSource();
+
 }}
 
 ///////////////////////////////hh.e////////////////////////////////////////