Redesign uncaught exception handling to allow external reporters

[libs/core.git] / source / core / application.h

diff --git a/source/core/application.h b/source/core/application.h
index c7a1af137a93cacdc921e28c58419cf70947bb16..e1d3a8b5e2be95d0c2fd0ffce151a1347264f080 100644 (file)
--- a/source/core/application.h
+++ b/source/core/application.h
@@ -1,11 +1,12 @@
 #ifndef MSP_CORE_APPLICATION_H_
 #define MSP_CORE_APPLICATION_H_
 
+#include <stdexcept>
+
 namespace Msp {
 
 /**
-Base class for applications.  Inherit the main class from this and add a static
-member of type RegApp<MainClass>.
+Base class for applications.  See also RegisteredApplication.
 */
 class Application
 {
@@ -35,20 +36,43 @@ protected:
 public:
        virtual ~Application() { }
 
+       /** Constructs an instance of the registered application class and runs it.
+       If the application throws a usage_error, a help message is printed.  The
+       GetOpt class will throw such exceptions automatically in error conditions.
+
+       This function can only be called once.  The global main() function provided
+       by the library normally does it automatically at program startup. */
        static int run(int, char **, void * =0);
+
        static void *get_data() { return data_; }
 
 protected:
+       /** Default main loop.  Calls tick() repeatedly until exit() is called.  A
+       custom main loop should monitor the done member variable and return
+       exit_code. */
        virtual int main();
+
+       /** Sets the specified signal to be delivered to the sighandler member
+       function. */
        void catch_signal(int);
+
+       /** Causes the application to exit gracefully with the given exit code. */
        void exit(int);
+
        virtual void tick() { }
        virtual void sighandler(int) { }
+
 private:
+       /** Static wrapper function to call a member function of the Application
+       instance. */
        static void sighandler_(int);
 };
 
 
+/**
+Registers the class to be used for program startup.  The main application class
+should be derived from this.
+*/
 template<typename T>
 class RegisteredApplication: public Application
 {