senf/Utils/Daemon/Mainpage.dox

   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 /** \mainpage Daemon process management
  24
  25     The Daemon class provides the infrastructure to implement robust daemon processes. A daemon
  26     process is implemented by deriving from senf::Daemon and implementing the necessary (virtual)
  27     member functions.
  28     \code
  29     #include <senf/Utils/Daemon.hh>
  30
  31     class MyDaemon : public senf::Daemon
  32     {
  33         void configure() {
  34             // Set configuration parameters like daemonize(), pidFile() etc
  35             consoleLog("MyDaemon.log");
  36             // The default version provided by senf::Daemon will parse some special command line
  37             // parameters to configure the daemon manager. You may optionally call this version
  38             // here after setting default parameters
  39             senf::Daemon::configure();
  40         }
  41
  42         void init() {
  43             // Initialize application. Setup all necessary objects. After init()
  44             // has completed, the startup should not fail
  45         }
  46
  47         void run() {
  48             // Main application code should be called here.
  49         }
  50     };
  51
  52     // Provide main() function
  53     SENF_DAEMON_MAIN(MyDaemon);
  54     \endcode
  55
  56     The startup procedure is divided into three steps:
  57     \li First, configure() is called. configure() should be as simple as possible. It just needs to
  58         set the daemon parameters. No further setup should be done here.
  59     \li init() is called after fork() but while still connected to the terminal. init() should do
  60         all necessary application setup. Here, all configuration or user errors should be detected
  61         and properly diagnosed.
  62     \li After init() returns, the application will detach from the terminal. Now run() is called to
  63         enter the application main loop.
  64
  65     Since there are times, where separating init() and run() into two separate functions is
  66     difficult, instead of defining init() and run(), the member main() may be defined. This member
  67     must call detach() as soon as initialization is completed to detach from the foreground
  68     terminal.
  69     \code
  70     #include <senf/Utils/Daemon.hh>
  71
  72     class MyDaemon : public senf::Daemon
  73     {
  74         // 'configure()' like above. Don't implement 'init()' or 'run()' if you implement 'main()'.
  75
  76         void main() {
  77             // Initialize application. Setup all necessary objects. When implementing main(), the
  78             // objects will most often live on the stack.
  79
  80             MyAppObject app;
  81
  82             if (some_error)
  83                 // Call Daemon::exit() to terminate execution prematurely
  84                 exit(1);
  85
  86             // After initialization is complete, you *must* call 'detach()'.
  87
  88             detach()
  89
  90             // Now we can start the application main loop
  91
  92             app.run();
  93         }
  94     };
  95
  96     // Provide main() function
  97     SENF_DAEMON_MAIN(MyDaemon);
  98     \endcode
  99
 100     \see
 101         \ref senf::Daemon class \n
 102         \ref SENF_DAEMON_MAIN() main() implementation macro
 103  */
 104
 105 \f
 106 // Local Variables:
 107 // mode: c++
 108 // fill-column: 100
 109 // comment-column: 40
 110 // c-file-style: "senf"
 111 // indent-tabs-mode: nil
 112 // ispell-local-dictionary: "american"
 113 // compile-command: "scons -u test"
 114 // mode: flyspell
 115 // mode: auto-fill
 116 // End: