vos/applibs/daemon/vosdaemon.hh

Go to the documentation of this file.

/* $Id: vosdaemon.hh,v 1.8 2003/07/22 05:09:56 tetron Exp $ */


/** @file vosdaemon.cc
    @author Reed Hedges (reed@zerohour.net)

    TODO:
        * use site callbacks for periodic save state instead of SIGALRM
        * Special option spit out Docbook <cmdsynopsis> text for help: 
            also change <foo> to <replacable>foo</replacable> in output.

    Copyright 2003 Reed Hedges

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef VOSDAEMON_HH

#include <vos/corelibs/vos/vos.hh>
#include <fstream>

/** 
    This class contains many convenient features useful for running a 
    background service, a.k.a. a daemon.  

    @ingroup applibs
    @ingroup vosdaemon

    It will fork and run in the background automatically.
    To use it for your daemon, simply subclass this class, and instantiate
    it from your program. 
    You can add and check for command-line arguments with addArg, addFlag, getArg 
    and getFlag.
    You can also turn on automatic saving, loading and periodic saving by 
    enabling the Save and Load built in command line parameters.
    Then call checkArgs, and run. 
    You can override loop() to do something every program loop, or you can use 
    a site callback. Other virtual methods may be overridden, but be sure
    to call the method in the parent class (VOSDaemon::) from your method.

    VOSDaemon will automatically handle the following arguments:
    <dl>
        <dt>--help, -h and -?</dt>  <dd>Print help message and quit</dd>
        <dt>--log, -L</dt>          <dd>Set log file</dd>
        <dt>--loglevel, -E</dt>     <dd>Set log level</dd>
        <dt>--save, -s</dt>         <dd>Reserved for a future autosave feature</dd>
        <dt>--safe-feq, -S</dt>     <dd>Reserved for a future autosave feature</dd>
        <dt>--load, -l</dt>         <dd>Reserved for a future COD loading feature</dd>
        <dt>--name</dt>             <dd>Reserved for a future COD loading feature</dd>
    </dl>

    
    Here is an example of use:

    @code
    #include <iostream> // for cerr
    #include <vos/corelibs/vos/vos.hh>
    #include <vos/metaobjects/property/property.hh>
    #include <vosdaemon.hh>

    class MyDaemon : public virtual VOSDaemon {
    public:
        MyDaemon() : VOSDaemon("example") {
        }

        void setup() {
            addArg("example", "value", "Example argument. <value> is any string.", 'e', "VOSDAEMON_EXAMPLE");
            addFlag("test", "Test flag.", 't', "VOSDAEMON_TEST_FLAG");
        }

        void preRun() {
            if(argGiven("example"))
                cerr << "example arg is: " << getArg("example") << endl;
            if(argGiven("test"))
                cerr << "test flag was given.\n";
            else
                cerr << "test flag was not given.\n";
        }

        virtual void loop() {
            cerr << "loop!\n";
        }
    };

    int main(int argc, char** argv) {
        Property::registerExtenders();
        MyDaemon myDaemon("mydaemon");
        myDaemon->setup();
        myDaemon->checkArgs(argc, argv);
        myDaemon->preRun();
        cerr << "Now running in the background...\n";
        myDaemon->run();
    }
    @endcode


*/
class VOSDaemon {


private:
    vRef<LocalSite> site;
    char*   saveFile;
    int     saveFreq;
    Vobject*    rootObj;
    char*   programName;
    char*   rootName;
    char*   logFile;
    bool    mayLoad, maySave, mayNameRoot;
    ofstream*   logStream;

    char* loadfile;
    bool dontFork;

    typedef struct {
        string  argName;
        string  valueLabel;
        string  value;
        char    argChar;
        bool    isFlag;
        string  description;
        bool    given;
        string  envVar;
    } ArgInfo;
    typedef map <string, ArgInfo> ArgMap;
    typedef map <char, ArgInfo*>  ShortArgMap;
    ArgMap  args;
    ShortArgMap shortArgs;

    bool checkBuiltinArgs(char o, char* val);

public:

    /** Constructor.  If site is omitted, a LocalSlocketSite
     *  will be created with select timeout -1. (You can dynamic_cast
     *  the LocalSite (returned by getSite()) to LocalSocketSite) once its created */
    VOSDaemon(char* progName, LocalSite* site = 0);

    /** Destructor */
    virtual ~VOSDaemon();

    /** Get the site. */
    LocalSite* getSite() {
        return &site;
    }

    /** Set the save file. Must be called before run. */
    void setSaveFile(char* savefile);

    /** Set the save frequency. Must be called before run. */
    void setSaveFrequency(int freq);

    /** Set the root object (for saving). Must be called before run. */
    void setRootObject(Vobject* rood);

    /** Set the name of the root object (for loading). Must be called before
     * run. */
    void setRootName(char* name);

    /** Set the log level  */
    void setLogLevel(int lev);

    /** Log to the named file. Must be called before run. */
    void setLogFile(char* file);

    /** Parse the command line arguments. Some built in arguments may
     * override any previously set settings.  Any arguments you added
     * with addArg will also be recognized, and after a call to this
     * function, will be available from getArg.
     *
     *  The following built in  command line arguments may override some settings:
     *      -L  Log file
     *      -E  Log level
     *      -s  Save file   (if enabled)
     *      -S  Save Frequency  (if save is enabled)
     *      -l  Load state from this file   (if enabled)
     *      -N  don't fork  (if fork is available on this platform)
     */
    virtual void checkArgs(int argc, char** argv);

    /** Start running the daemon in the background. */
    virtual void run();

    /** Virtual method called right after flushIncomingBuffers. Subclasses can
     *  use this to perform actions during the run loop. Note that the frequency
     *  with which this gets called depends on the select timeout (see 
     *  setTimeoutOnSelect()).
     */
    virtual void loop() {}


    /* Enable or disable availability of some of the built in command-line arguments */
    //@{
    //void enableArg_load(bool p);
    //void enableArg_save(bool p);
    //void enableArg_nameRoot(bool p);
    //@}
    
    /** Add command line arguments. If found, they will be available
     *  by calling getArg or getFlag(). This functiow must 
     *  be called before calling run(). 
     *  @param argName long name of argument. 
     *  @param valueLabel label for the argument's value (used in help text).
     *  @param description  A description of the argument (used in help text).
     *  @param defaultValue If supplied, then use this value if argument is not  given.
     *  @param argChar short one-character name of argument. (note that long arguments are
     *  unavailable on some platforms, so always give a non-empty char for this)
     *  @param envVar  If supplied, then an environment variable with this name
     *  may be used to supply a default value. (Command-line arguments always
     *  override environment variables)
     *
     *  @example addArg("example", "value", "An example", 'x');    // for --example or -x
     *  @example addArg("example", "value", "An example");         
     *  @example addArg("example", "value", "An example", "default value", 'e', "VOSDAEMON_EXAMPLE");
     *  @example addArg("example", "value", "An example", "default");
     *  @note The built in options are: 
     *      <ul>
     *          <li>"help" or 'h' to generate help text</li>
     *          <li>"loglevel" or 'E' to set the log level</li>
     *          <li>"log" or 'L' to set the log file</li>
     *          <li>"name" or 'n' to set the root object name (if enabled)</li>
     *          <li>"load" or 'l' to load a saved file (if enabled)</li>
     *          <li>"save" or 's' to set save-file name (if enabled)</li>
     *          <li>"save-freq" or 'S' to set save frequency (if enabled and possible on this platform)</li>
     *      </ul>
     *      
     */
      
    //@{
    void addArg(string argName, string valueLabel, string description, char argChar, string envVar = "");
    void addArg(string argName, string valueLabel, string description, string defaultValue, char argChar, string envVar = "");
    //@}

    

    /** Add flag argument . This function must be called before calling 
     * run().
     */
    void addFlag(string flagName, string description, char flagChar, string envVar);


    /** Get value of a command line argument. If it wasn't given then
     * the default value is returned. If it wasn't added using addArg(), or it
     * was added using addFlag(), then
     * a runtime_error exception will be thrown. */
    string getArg(string argName);

    /** Get presence of a command line option with no argiment (ie, a flag).
     *  If it was given, true will be returned. If it wasn't then false
     *  will be returned. If it wasn't added using addArg, then a
     *  runtime_error exception will be thrown.
     */
    bool argGiven(string argName);

    /** Same as argGiven */
    inline bool getFlag(string argName) {
        return argGiven(argName);
    }

    /** Print out help for command-line arguments. */
    virtual void printHelp();

    /** Save current state of the site and it's objects to the file previously
        set by setSaveFile or command line arguments. */
    virtual void save();


    /** Print the internal command-line argument map to stderr. */
    void debugArgs();
};

#endif //VOSDAEMON_HH

---