new home directory
[feisty_meow.git] / 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