senf/Utils/Daemon/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 //
  24 // Contributor(s):
  25 //   Stefan Bund <g0dil@berlios.de>
  26
  27
  28 /** \mainpage Daemon process management
  29
  30     The Daemon class provides the infrastructure to implement robust daemon processes. A daemon
  31     process is implemented by deriving from senf::Daemon and implementing the necessary (virtual)
  32     member functions.
  33     \code
  34     #include <senf/Utils/Daemon.hh>
  35
  36     class MyDaemon : public senf::Daemon
  37     {
  38         void configure() {
  39             // Set configuration parameters like daemonize(), pidFile() etc
  40             consoleLog("MyDaemon.log");
  41             // The default version provided by senf::Daemon will parse some special command line
  42             // parameters to configure the daemon manager. You may optionally call this version
  43             // here after setting default parameters
  44             senf::Daemon::configure();
  45         }
  46
  47         void init() {
  48             // Initialize application. Setup all necessary objects. After init()
  49             // has completed, the startup should not fail
  50         }
  51
  52         void run() {
  53             // Main application code should be called here.
  54         }
  55     };
  56
  57     // Provide main() function
  58     SENF_DAEMON_MAIN(MyDaemon);
  59     \endcode
  60
  61     The startup procedure is divided into three steps:
  62     \li First, configure() is called. configure() should be as simple as possible. It just needs to
  63         set the daemon parameters. No further setup should be done here.
  64     \li init() is called after fork() but while still connected to the terminal. init() should do
  65         all necessary application setup. Here, all configuration or user errors should be detected
  66         and properly diagnosed.
  67     \li After init() returns, the application will detach from the terminal. Now run() is called to
  68         enter the application main loop.
  69
  70     Since there are times, where separating init() and run() into two separate functions is
  71     difficult, instead of defining init() and run(), the member main() may be defined. This member
  72     must call detach() as soon as initialization is completed to detach from the foreground
  73     terminal.
  74     \code
  75     #include <senf/Utils/Daemon.hh>
  76
  77     class MyDaemon : public senf::Daemon
  78     {
  79         // 'configure()' like above. Don't implement 'init()' or 'run()' if you implement 'main()'.
  80
  81         void main() {
  82             // Initialize application. Setup all necessary objects. When implementing main(), the
  83             // objects will most often live on the stack.
  84
  85             MyAppObject app;
  86
  87             if (some_error)
  88                 // Call Daemon::exit() to terminate execution prematurely
  89                 exit(1);
  90
  91             // After initialization is complete, you *must* call 'detach()'.
  92
  93             detach()
  94
  95             // Now we can start the application main loop
  96
  97             app.run();
  98         }
  99     };
 100
 101     // Provide main() function
 102     SENF_DAEMON_MAIN(MyDaemon);
 103     \endcode
 104
 105     \see
 106         \ref senf::Daemon class \n
 107         \ref SENF_DAEMON_MAIN() main() implementation macro
 108  */
 109
 110 \f
 111 // Local Variables:
 112 // mode: c++
 113 // fill-column: 100
 114 // comment-column: 40
 115 // c-file-style: "senf"
 116 // indent-tabs-mode: nil
 117 // ispell-local-dictionary: "american"
 118 // compile-command: "scons -u test"
 119 // mode: flyspell
 120 // mode: auto-fill
 121 // End: