X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Utils%2FDaemon%2FDaemon.hh;h=dc3fb2942a67d36c5eda906b03a4cb13d1aedadc;hb=b41b8147c7a2d40e2f69471e183840be8a0b95da;hp=3526cb3f760d698807b07d2ffba9c96e343af468;hpb=9e69297ff7a7bcd9d952a38e35bbf124cb7f1dda;p=senf.git

diff --git a/Utils/Daemon/Daemon.hh b/Utils/Daemon/Daemon.hh
index 3526cb3..dc3fb29 100644
--- a/Utils/Daemon/Daemon.hh
+++ b/Utils/Daemon/Daemon.hh
@@ -36,40 +36,69 @@ namespace senf {
 
     /** \brief Daemon process
 
-        This class provides the infrastructure to implement robust daemon processes. A daemon
-        process is implemented by deriving from senf::Daemon and implementing the necessary
-        (virtual) member functions.
-        \code
-        class MyDaemon : public senf::Daemon
-        {
-            void configure() {
-                // Set configuration parameters like daemonize(), pidFile() etc.
-            }
-
-            void init() {
-                // Initialize application. Setup all necessary objects. After init()
-                // has completed, is startup should not fail anymore
-            }
-
-            void run() {
-                // Main application code should be called here.
-            }
-        };
-        \endcode
-
-        The startup procedure is divided into three steps:
-        \li First, configure() is called. configure() should be as simple as possible. It just needs
-            to set the daemon parameters. No further setup should be done here.
-        \li init() is called after fork() but while still connected to the terminal. init() should
-            do all necessary application setup. Here, all configuration or user errors should be
-            detected and properly diagnosed.
-        \li After init() returns, the application will detach from the terminal. Now run() is called
-            to enter the application main loop.
-
-        Since there are times, where separating init() and run() into two separate functions is
-        difficult, instead of defining init() and run(), the member main() may be defined. This
-        member must call detach() as soon as initialization is completed to detach from the
-        foreground terminal.
+        senf::Daemon provides simple management for daemon processes. Specifically, the Daemon class
+        implements
+        \li <i>Safe startup.</i> If the startup fails, the foreground process which launches the
+            daemon will terminate with an appropriate error exit code.
+        \li <i>Straight forward application initialization.</i> The daemon process is forked before
+            even initializing the application. The initialization procedure must not cater for a
+            later fork().
+        \li <i>Automatic pid file management.</i> The daemon will not be started, if a valid pid file is
+            found. Stale pid files are automatically removed.
+        \li <i>Console log management.</i> It is possible, to redirect standard output and error to
+            one or two log files. Messages pertaining to application initialization will be written
+            to both the console and the log file whereas later messages will be directed to the log
+            file only.
+        \li <i>Optional foreground execution.</i> The daemon may be started in the foreground for
+            debugging purposes. In this case, the console log file(s) is/are automatically
+            suppressed.
+        
+        Starting the daemon process proceeds along the following steps:
+        \li The daemon is started by calling the daemon class instances start() member. This
+            normally happens from the \c main() function generated by \ref SENF_DAEMON_MAIN().
+        \li configure() is called. This (virtual) member configures the daemon manager by calling
+            the Daemon class parameter members.
+        \li The log files are opened, \c fork() is called and the pid file is checked and
+            created. The parent (foreground) process keeps running overseeing the daemon process.
+        \li main() is called. This virtual member may optionally be overridden in the derived
+            class. Here we assume, main() is not overridden so the default implementation is used.
+        \li main() calls init(). 
+        \li after init() returns, main() calls detach().
+        \li detach() signals successful startup to the parent process. The parent process terminates
+            leaving the daemon process running in the background.
+        \li main() calls run()
+        \li If run() ever returns, the daemon process terminates.
+        \li Whenever the process terminates normally (not necessarily successfully), the pid file is
+            automatically removed.
+
+        The parameter members are used from configure() to configure the daemon manager. See below
+        for details. The \e default configure() implementation will scan the command line arguments
+        to check for the following parameters:
+
+        <table class="senf">
+
+        <tr><td><tt>--no-daemon</tt></td><td>Run in foreground</td></tr>
+
+        <tr><td><tt>--console-log=</tt><i>stdout</i>[<tt>,</tt><i>stderr</i>]</td><td>Set the
+        console log file(s). If only \a stdout is specified (with no comma), the same log file
+        configuration will be applied to the standard output and error stream. Otherwise each stream
+        is assigned it's own log file. If either log file name is empty, the command will not change
+        the log file of that stream, the default log file will be used. If the log file name is set
+        to 'none', the log file will be disabled.</td></tr>
+
+        <tr><td><tt>--pid-file=</tt><i>pidfile</i></td><td>Set pid file path</td></tr>
+
+        </table>
+
+        The default configure() implementation will use whatever parameters have been set beforehand
+        as default values. These default values should be set in a derived class configure()
+        implementation. After setting the default values, the configure() implementation may choose
+        to call this default configure() implementation to scan for command line parmeters.  The
+        default configure() implementation does \e not completely parse the command line
+        arguments. It just checks, if any of above arguments are present and precesses them. Other
+        arguments are completely ignored. The command line parameters should be completely processed
+        within init().
+        
       */
     class Daemon : boost::noncopyable
     {
@@ -108,6 +137,9 @@ namespace senf {
                                              ignored. */
 
         void pidFile(std::string const &); ///< Configure pid file
+                                        /**< If a pid file is configured it will be checked on
+                                             daemon startup. If another running instance of the
+                                             daemon is detected, starting the daemon will fail. */
 
         ///\}
         ///\name Auxiliary helpers
@@ -124,7 +156,7 @@ namespace senf {
         int argc();                     ///< Access command line parameter count
         char const ** argv();           ///< Access command line parameters
 
-        void fail(int code=1);          ///< Terminate startup with failure
+        void fail(unsigned code=1);     ///< Terminate daemon with failure
 
         ///\}
         
@@ -136,6 +168,8 @@ namespace senf {
         Daemon();
 
         virtual void configure();       ///< Called before forking to configure the daemon class
+                                        /**< This default implementation will parser some command
+                                             line parameters. See the class documentation above. */
 
 #   ifdef DOXYGEN
     protected: