nucleus/library/application/hoople_service.h

   1 #ifndef HOOPLE_SERVICE_CLASS
   2 #define HOOPLE_SERVICE_CLASS
   3
   4 //////////////
   5 // Name   : hoople_service
   6 // Author : Chris Koeritz
   7 //////////////
   8 // Copyright (c) 2000-$now By Author.  This program is free software; you can
   9 // redistribute it and/or modify it under the terms of the GNU General Public
  10 // License as published by the Free Software Foundation:
  11 //     http://www.gnu.org/licenses/gpl.html
  12 // or under the terms of the GNU Library license:
  13 //     http://www.gnu.org/licenses/lgpl.html
  14 // at your preference.  Those licenses describe your legal rights to this
  15 // software, and no other rights or warranties apply.
  16 // Please send updates for this code to: fred@gruntose.com -- Thanks, fred.
  17 //////////////
  18
  19 #include <basis/astring.h>
  20 #include <basis/definitions.h>
  21 #include <timely/timer_driver.h>
  22
  23 namespace application {
  24
  25 //! A platform-independent way to alert a program that it should shut down immediately.
  26 /*!
  27   This can provide a service management feature for graceful shutdown of an
  28   application, allowing it a chance to close its objects cleanly, rather than
  29   just being whacked in the middle of whatever it's doing.
  30     Only one of these objects should be instantiated per program, but the
  31   static methods can be used from anywhere in the program.
  32 */
  33
  34 class hoople_service
  35 : public virtual basis::root_object, public timely::timeable
  36 {
  37 public:
  38   hoople_service();
  39     //!< constructor does very little; setup() is what begins operation.
  40
  41   virtual ~hoople_service();
  42
  43   DEFINE_CLASS_NAME("hoople_service");
  44
  45   bool setup(const basis::astring &app_name, int timer_period = 0);
  46     //!< constructs a hoople_service for the "app_name" specified.
  47     /*!< this can be any string, although it might be processed for certain
  48     operating systems.  also, for close_this_program() to work properly, it
  49     must be the application's basename.  the "timer_period" specifies how
  50     frequently to invoke the handle_timer() method during runtime.  if it's
  51     zero, then no timer will be used. */
  52
  53   static bool is_defunct() { return _defunct(); }
  54     //!< returns true if the object has been marked as defunct.
  55     /*!< this means that it is either shutting down or soon will be. */
  56
  57   static void make_defunct();
  58     //!< used by the derived class to mark that this object is about to exit.
  59     /*!< note that this can be used anywhere in the program to initiate an
  60     exit of the program. */
  61
  62   bool saw_interrupt() { return _saw_interrupt(); }
  63     //!< reports whether the process saw an interrupt from the user.
  64
  65   // these virtual methods can be overridden by applications derived from the
  66   // hoople_service.  they support a graceful shutdown process by which
  67   // applications can be alerted that they must shutdown, allowing them to take
  68   // care of releasing resources beforehand.
  69
  70   virtual void handle_startup();
  71     //!< this function is called once the program has begun operation.
  72
  73   virtual void handle_shutdown();
  74     //!< called during the program's shutdown process.
  75     /*!< this is invoked just prior to the destruction of this class which is
  76     also just before the shutdown of the program overall.  in this method,
  77     the derived object must ensure that any threads the program started get
  78     stopped, that any opened files get closed, and that any other resources
  79     are released.  this is the application's last chance to clean up. */
  80
  81   virtual void handle_timer();
  82     //!< called periodically if a timer period was specified.
  83
  84   // static methods that can be used by the program for starting up or for
  85   // graceful shutdown.
  86
  87 //why?
  88   static bool launch_console(hoople_service &alert, const basis::astring &app_name,
  89           int timer_period = 0);
  90     //!< this is used to begin execution of a console mode application.
  91     /*!< this method does not do anything except sit while the extant threads
  92     are in play.  it will not return until the program must exit, as caused
  93     by close_this_program() or close_application(). */
  94
  95 #if 0  //not implemented.
  96 #ifdef __WIN32__
  97   static bool launch_event_loop(hoople_service &alert,
  98           const basis::astring &app_name, int timer_period = 0);
  99     //!< launches by starting up a windowing event loop.
 100     /*!< this is appropriate for programs that are windowed and must
 101     continually process window events. */
 102 #endif
 103 #endif
 104
 105   static void close_this_program();
 106     //!< causes this particular application to begin shutting down.
 107     /*!< this is a static method available for programs that support the
 108     hoople_service's graceful shutdown process.  it causes the application
 109     to begin the shutdown. */
 110
 111   static bool close_application(const basis::astring &app_name);
 112     //!< attempts to close the application named "app_name".
 113     /*!< this can only be done if this program possesses sufficient rights to
 114     zap that program. */
 115
 116   // internal methods not to be used by outside objects.
 117
 118   static void handle_OS_signal(int sig_id);
 119     //!< processes the signal from the OS when its time to shut down.
 120
 121 private:
 122   static bool &_saw_interrupt();  //!< did we see a break from the user?
 123   static basis::astring &_app_name();  //!< the of this application.
 124   static bool &_defunct();  //!< is the program shutting down?
 125   static int &_timer_period();  //!< rate at which timer goes off.
 126
 127   virtual void handle_timer_callback();  //!< invoked by the timer driver.
 128
 129   // not appropriate.
 130   hoople_service(const hoople_service &);
 131   hoople_service &operator =(const hoople_service &);
 132 };
 133
 134 } //namespace.
 135
 136 #endif // outer guard.
 137