Utils/Daemon/Daemon.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief Daemon public header */
  25
  26 #ifndef HH_Daemon_
  27 #define HH_Daemon_ 1
  28
  29 // Custom includes
  30 #include <boost/utility.hpp>
  31 #include "../Logger/SenfLog.hh"
  32
  33 //#include "Daemon.mpp"
  34 ///////////////////////////////hh.p////////////////////////////////////////
  35
  36 namespace senf {
  37
  38     /** \brief %Daemon process
  39
  40         %senf::Daemon provides simple management for daemon processes. Specifically, the %Daemon class
  41         implements
  42         \li <i>Safe startup.</i> If the startup fails, the foreground process which launches the
  43             daemon will terminate with an appropriate error exit code.
  44         \li <i>Straight forward application initialization.</i> The daemon process is forked before
  45             even initializing the application. The initialization procedure must not cater for a
  46             later fork().
  47         \li <i>Automatic pid file management.</i> The daemon will not be started, if a valid pid file is
  48             found. Stale pid files are automatically removed.
  49         \li <i>Console log management.</i> It is possible, to redirect standard output and error to
  50             one or two log files. Messages pertaining to application initialization will be written
  51             to both the console and the log file whereas later messages will be directed to the log
  52             file only.
  53         \li <i>Optional foreground execution.</i> The daemon may be started in the foreground for
  54             debugging purposes. In this case, the console log file(s) is/are automatically
  55             suppressed.
  56
  57         Starting the daemon process proceeds along the following steps:
  58         \li The daemon is started by calling the daemon class instances start() member. This
  59             normally happens from the \c main() function generated by \ref SENF_DAEMON_MAIN().
  60         \li configure() is called. This (virtual) member configures the daemon manager by calling
  61             the Daemon class parameter members.
  62         \li The log files are opened, \c fork() is called and the pid file is checked and
  63             created. The parent (foreground) process keeps running overseeing the daemon process.
  64         \li main() is called. This virtual member may optionally be overridden in the derived
  65             class. Here we assume, main() is not overridden so the default implementation is used.
  66         \li main() calls init().
  67         \li after init() returns, main() calls detach().
  68         \li detach() signals successful startup to the parent process. The parent process terminates
  69             leaving the daemon process running in the background.
  70         \li main() calls run()
  71         \li If run() ever returns, the daemon process terminates.
  72         \li Whenever the process terminates normally (not necessarily successfully), the pid file is
  73             automatically removed.
  74
  75         The parameter members are used from configure() to configure the daemon manager. See below
  76         for details. The \e default configure() implementation will scan the command line arguments
  77         to check for the following parameters:
  78
  79         <table class="senf">
  80
  81         <tr><td><tt>--no-daemon</tt></td><td>Run in foreground</td></tr>
  82
  83         <tr><td><tt>--console-log=</tt><i>stdout</i>[<tt>,</tt><i>stderr</i>]</td><td>Set the
  84         console log file(s). If only \a stdout is specified (with no comma), the same log file
  85         configuration will be applied to the standard output and error stream. Otherwise each stream
  86         is assigned it's own log file. If either log file name is empty, the command will not change
  87         the log file of that stream, the default log file will be used. If the log file name is set
  88         to 'none', the log file will be disabled.</td></tr>
  89
  90         <tr><td><tt>--pid-file=</tt><i>pidfile</i></td><td>Set pid file path</td></tr>
  91
  92         </table>
  93
  94         The default configure() implementation will use whatever parameters have been set beforehand
  95         as default values. These default values should be set in a derived class configure()
  96         implementation. After setting the default values, the configure() implementation may choose
  97         to call this default configure() implementation to scan for command line parmeters.  The
  98         default configure() implementation does \e not completely parse the command line
  99         arguments. It just checks, if any of above arguments are present and precesses them. Other
 100         arguments are completely ignored. The command line parameters should be completely processed
 101         within init().
 102
 103       */
 104     class Daemon : boost::noncopyable
 105     {
 106     public:
 107         SENF_LOG_CLASS_AREA();
 108
 109         ///////////////////////////////////////////////////////////////////////////
 110         // Types
 111
 112         /// Select standard stream to redirect
 113         enum StdStream {
 114             StdOut  /** Standard output stream */
 115         ,   StdErr  /** Standard error stream */
 116         ,   Both    /** Both, standard output and error stream */
 117         };
 118
 119         ///////////////////////////////////////////////////////////////////////////
 120         ///\name Structors and default members
 121         ///\{
 122
 123         virtual ~Daemon();
 124
 125         ///\}
 126         ///\name Parameters
 127         ///\{
 128
 129         void daemonize(bool);           ///< Configure whether to run in fore- or background
 130         bool daemon();                  ///< \c true, if running as daemon
 131
 132         void consoleLog(std::string const &, StdStream which = Both);
 133                                         ///< Configure console log file
 134                                         /**< May be called multiple times to set the log file
 135                                              for stdout and stderr seperately. Any standard stream
 136                                              not assigned to a log file will be redirected to
 137                                              <tt>/dev/null</tt>.
 138
 139                                              When running in the foreground, the log files will be
 140                                              ignored. */
 141
 142         void pidFile(std::string const &); ///< Configure pid file
 143                                         /**< If a pid file is configured it will be checked on
 144                                              daemon startup. If another running instance of the
 145                                              daemon is detected, starting the daemon will fail. */
 146
 147         ///\}
 148         ///\name Auxiliary helpers
 149         ///\{
 150
 151         void detach();                  ///< Detach into background now
 152                                         /**< This is \e not the same as forking. The process will
 153                                              already have forked into the background but until
 154                                              detach() is called (either automatically after init()
 155                                              returns or manually), the front end (foreground)
 156                                              process will wait for the background process to ensure
 157                                              successful startup. */
 158
 159         int argc();                     ///< Access command line parameter count
 160         char ** argv();                 ///< Access command line parameters
 161
 162         static void exit(unsigned code=0); ///< Terminate daemon with failure
 163
 164         void logReopen();               ///< Reopen the log files
 165                                         /**< This is used when rotating the logs. By default,
 166                                              SIGHUP calls logReopen. */
 167
 168         ///\}
 169
 170         int start(int argc, char ** argv); ///< Called from main() to launch daemon.
 171                                         /**< Normally not called directly but from the
 172                                              \ref SENF_DAEMON_MAIN macro. */
 173
 174         static Daemon & instance();     ///< Return the Daemon instance
 175
 176     protected:
 177         Daemon();
 178
 179         virtual void configure();       ///< Called before forking to configure the daemon class
 180                                         /**< This default implementation will parser some command
 181                                              line parameters. See the class documentation above. */
 182
 183 #   ifdef DOXYGEN
 184     protected:
 185 #   else
 186     private:
 187 #   endif
 188
 189         virtual void main();            ///< Called after forking to execute the main application
 190                                         /**< The default implementation will call init(), detach()
 191                                              and then run(). It is preferred to override init() and
 192                                              run() if possible. */
 193         virtual void init();            ///< Called to initialize the main application
 194                                         /**< While init() is running, the application still is
 195                                              connected to the controlling terminal. Error messages
 196                                              will be shown to the user.
 197
 198                                              This member is only called, if the default main()
 199                                              implementation is not overridden. */
 200         virtual void run();             ///< Called to execute main application
 201                                         /**< Called after detaching from the controlling
 202                                              terminal.
 203
 204                                              This member is only called, if the default main()
 205                                              implementation is not overridden. */
 206     private:
 207         void openLog();
 208         void fork();
 209         bool pidfileCreate();
 210         void installSighandlers();
 211
 212         int argc_;
 213         char ** argv_;
 214
 215         bool daemonize_;
 216         std::string stdoutLog_;
 217         std::string stderrLog_;
 218         int stdout_;
 219         int stderr_;
 220         std::string pidfile_;
 221         bool pidfileCreated_;
 222
 223         bool detached_;
 224
 225         static Daemon * instance_;
 226     };
 227
 228     /** \brief Provide \c main() function
 229
 230         This macro will provide a \c main() function to launch the daemon process defined in \a
 231         klass. \a klass must be a class derived from senf::Daemon.
 232
 233         \ingroup process
 234      */
 235 #   define SENF_DAEMON_MAIN(klass)                                                                \
 236         int main(int argc, char ** argv)                                                    \
 237         {                                                                                         \
 238             klass instance;                                                                       \
 239             return instance.start(argc, argv);                                                    \
 240         }
 241
 242 }
 243
 244 ///////////////////////////////hh.e////////////////////////////////////////
 245 //#include "Daemon.cci"
 246 //#include "Daemon.ct"
 247 //#include "Daemon.cti"
 248 #endif
 249
 250 \f
 251 // Local Variables:
 252 // mode: c++
 253 // fill-column: 100
 254 // comment-column: 40
 255 // c-file-style: "senf"
 256 // indent-tabs-mode: nil
 257 // ispell-local-dictionary: "american"
 258 // compile-command: "scons -u test"
 259 // End: