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