nucleus/library/application/application_shell.h

   1 #ifndef APPLICATION_SHELL_CLASS
   2 #define APPLICATION_SHELL_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : application_shell                                                 *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2000-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "base_application.h"
  19
  20 #include <basis/contracts.h>
  21 #include <mathematics/chaos.h>
  22
  23 namespace application {
  24
  25 //! The application_shell is a base object for console programs.
  26 /*!
  27   It is generally used in that context (console mode), but can be employed as the root of windowed
  28   programs also.  The application_shell provides a few features, such as logging functionality,
  29   that make it a bit easier than starting up a program from scratch every time.
  30 */
  31
  32 class application_shell : public base_application
  33 {
  34 public:
  35   application_shell();
  36     //!< constructs an application_shell to serve as the root of the program.
  37
  38   virtual ~application_shell();
  39
  40   DEFINE_CLASS_NAME("application_shell")
  41
  42   static application_shell *single_instance();
  43     //!< in a program with a single application_shell extant, this gives out the instance.
  44     /*!< if there are more than one application_shells floating around a program, then this
  45     will only give out the most recently registered.  note that this pointer is not the
  46     slightest bit thread safe if it's changing after the application shell has been constructed,
  47     and that it cannot be relied upon until that's happened either.  be careful.  do not use
  48     it in any function that might be invoked during program shutdown. */
  49
  50   virtual int execute_application();
  51     //!< runs the base class's execute() method and catches any exceptions due to it.
  52     /*!< you can override this method, but generally should never need to.  the derived class's
  53     method should catch exceptions and deal with them meaningfully also. */
  54
  55   int exit_value() const { return c_exit_value; }
  56     //!< once the application has finished executing, this will contain the exit value.
  57
  58   const mathematics::chaos &randomizer() const { return c_rando; }
  59     //!< provides access to the random number generator owned by this app.
  60
  61 //  static basis::astring application_name();
  62     //!< returns the full name of the current application.
  63
  64 //  static basis::u_int process_id();
  65     //!< returns the process id for this task, if that's relevant on the OS.
  66
  67 //  static basis::astring current_directory();
  68     //!< returns the current directory as reported by the operating system.
  69
  70   virtual basis::outcome log(const basis::base_string &to_print, int filter = basis::ALWAYS_PRINT);
  71     //!< as above, logs a line "to_print" but only if the "filter" is enabled.
  72     /*!< the second version uses the filter value to assess whether to print
  73     the string or not.  the string will not print if that filter is not
  74     enabled for the program wide logger. */
  75
  76 #ifdef __UNIX__
  77 //  static basis::astring get_cmdline_from_proc();
  78     //!< retrieves the command line from the /proc hierarchy on linux.
  79 //  static basis::astring query_for_process_info();
  80     //!< seeks out process info for a particular process.
  81 #endif
  82
  83 protected:
  84   virtual int execute() = 0;
  85     //!< forwards base_application responsibility upwards to derived objects.
  86     /*!< this should not be invoked by anyone in general; it is automatically called from
  87     the constructor of this class. */
  88
  89 private:
  90   mathematics::chaos c_rando;  //!< random number generator.
  91   int c_exit_value;  //!< how did things end up for the app?
  92
  93   // not applicable.
  94   application_shell(const application_shell &);
  95   application_shell &operator =(const application_shell &);
  96 };
  97
  98 } //namespace.
  99
 100 #endif // outer guard.
 101