summaryrefslogtreecommitdiff
path: root/cpp/include/Ice/Application.h
diff options
context:
space:
mode:
Diffstat (limited to 'cpp/include/Ice/Application.h')
-rw-r--r--cpp/include/Ice/Application.h308
1 files changed, 233 insertions, 75 deletions
diff --git a/cpp/include/Ice/Application.h b/cpp/include/Ice/Application.h
index 6843c6a65f4..498b6054c51 100644
--- a/cpp/include/Ice/Application.h
+++ b/cpp/include/Ice/Application.h
@@ -22,133 +22,291 @@ using IceUtil::CtrlCHandler;
using IceUtil::CtrlCHandlerCallback;
#ifdef ICE_CPP11_MAPPING
+/**
+ * Determines how the Application class handles signals.
+ */
enum class SignalPolicy : unsigned char
#else
enum SignalPolicy
#endif
-{ HandleSignals, NoSignalHandling };
+{
+ /** Enables signal handling. */
+ HandleSignals,
+ /** Disables signal handling, meaning signals retain their default behavior. */
+ NoSignalHandling
+};
+/**
+ * Singleton helper class that simplifies Ice initialization, finalization and signal handling.
+ * An application uses this class by writing a subclass and implementing the run method.
+ * \headerfile Ice/Ice.h
+ */
class ICE_API Application
{
public:
- Application(SignalPolicy = ICE_ENUM(SignalPolicy, HandleSignals));
+ /**
+ * The constructor configures the signal handling behavior.
+ * @param policy Specifies whether to handle signals. If not specified, the default behavior
+ * is to handle signals.
+ */
+ Application(SignalPolicy policy = ICE_ENUM(SignalPolicy, HandleSignals));
#ifdef ICE_CPP11_MAPPING
+ /// \cond IGNORE
Application(const Application&) = delete;
Application& operator=(const Application&) = delete;
+ /// \endcond
#endif
virtual ~Application();
- // This main() must be called by the global main(). main()
- // initializes the Communicator, calls run() and destroys the
- // the Communicator upon return from run(). It handles all
- // exceptions properly, i.e., error message are printed if
- // exceptions propagate to main(), and the Communicator is always
- // destroyed, regardless of exceptions.
- //
- int main(int, const char* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
- int main(int, const char* const[], ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION);
+ /**
+ * Call this main() from the global main(). main()
+ * initializes the Communicator, calls run() and destroys the
+ * the Communicator upon return from run(). It handles all
+ * exceptions properly, i.e., error message are printed if
+ * exceptions propagate to main(), and the Communicator is always
+ * destroyed, regardless of exceptions.
+ * @param argc Specifies the number of arguments in argv.
+ * @param argv The command-line arguments.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The application's exit status.
+ */
+ int main(int argc, const char* const argv[], const InitializationData& initData = InitializationData(),
+ int version = ICE_INT_VERSION);
+
+ /**
+ * Call this main() from the global main(). main()
+ * initializes the Communicator, calls run() and destroys the
+ * the Communicator upon return from run(). It handles all
+ * exceptions properly, i.e., error message are printed if
+ * exceptions propagate to main(), and the Communicator is always
+ * destroyed, regardless of exceptions.
+ * @param argc Specifies the number of arguments in argv.
+ * @param argv The command-line arguments.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The application's exit status.
+ */
+ int main(int argc, const char* const argv[], ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION);
#ifdef _WIN32
- int main(int, const wchar_t* const[], const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
- int main(int, const wchar_t* const[], ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION);
+ /**
+ * Call this main() from the global main(). main()
+ * initializes the Communicator, calls run() and destroys the
+ * the Communicator upon return from run(). It handles all
+ * exceptions properly, i.e., error message are printed if
+ * exceptions propagate to main(), and the Communicator is always
+ * destroyed, regardless of exceptions.
+ * @param argc Specifies the number of arguments in argv.
+ * @param argv The command-line arguments.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The application's exit status.
+ */
+ int main(int argc, const wchar_t* const argv[], const InitializationData& initData = InitializationData(),
+ int version = ICE_INT_VERSION);
+
+ /**
+ * Call this main() from the global main(). main()
+ * initializes the Communicator, calls run() and destroys the
+ * the Communicator upon return from run(). It handles all
+ * exceptions properly, i.e., error message are printed if
+ * exceptions propagate to main(), and the Communicator is always
+ * destroyed, regardless of exceptions.
+ * @param argc Specifies the number of arguments in argv.
+ * @param argv The command-line arguments.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The application's exit status.
+ */
+ int main(int argc, const wchar_t* const argv[], ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION);
#endif
- int main(const StringSeq&, const InitializationData& = InitializationData(), int = ICE_INT_VERSION);
- int main(const StringSeq&, ICE_CONFIG_FILE_STRING, int = ICE_INT_VERSION);
+ /**
+ * Call this main() from the global main(). main()
+ * initializes the Communicator, calls run() and destroys the
+ * the Communicator upon return from run(). It handles all
+ * exceptions properly, i.e., error message are printed if
+ * exceptions propagate to main(), and the Communicator is always
+ * destroyed, regardless of exceptions.
+ * @param args The command-line arguments.
+ * @param initData Configuration data for the new Communicator.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The application's exit status.
+ */
+ int main(const StringSeq& args, const InitializationData& initData = InitializationData(),
+ int version = ICE_INT_VERSION);
- //
- // run is given a copy of the remaining argc/argv arguments,
- // after the communicator initialization in the caller (main)
- // has removed all Ice-related arguments.
- //
- virtual int run(int, char*[]) = 0;
+ /**
+ * Call this main() from the global main(). main()
+ * initializes the Communicator, calls run() and destroys the
+ * the Communicator upon return from run(). It handles all
+ * exceptions properly, i.e., error message are printed if
+ * exceptions propagate to main(), and the Communicator is always
+ * destroyed, regardless of exceptions.
+ * @param args The command-line arguments.
+ * @param configFile The name of an Ice configuration file.
+ * @param version Indicates the Ice version with which the application is compatible. If not
+ * specified, the version of the Ice installation is used.
+ * @return The application's exit status.
+ */
+ int main(const StringSeq& args, ICE_CONFIG_FILE_STRING configFile, int version = ICE_INT_VERSION);
- //
- // Override this to provide a custom application interrupt
- // hook. You must call callbackOnInterrupt for this method to
- // be called. Note that the interruptCallback can be called
- // concurrently with any other thread (including main) in your
- // application and thus must take appropriate concurrency
- // precautions.
- //
- virtual void interruptCallback(int);
+ /**
+ * run is given a copy of the remaining argc/argv arguments,
+ * after the communicator initialization in the caller (main)
+ * has removed all Ice-related arguments.
+ * @param argc Specifies the number of arguments in argv.
+ * @param argv The command-line arguments.
+ * @return The application's exit status.
+ */
+ virtual int run(int argc, char* argv[]) = 0;
- //
- // Return the application name, i.e., argv[0].
- //
+ /**
+ * Override this method to provide a custom application interrupt
+ * hook. You must call callbackOnInterrupt for this method to
+ * be called. Note that the interruptCallback can be called
+ * concurrently with any other thread (including main) in your
+ * application and thus must take appropriate concurrency
+ * precautions.
+ * @param signal The signal identifier.
+ */
+ virtual void interruptCallback(int signal);
+
+ /**
+ * Obtains the application name, i.e., argv[0].
+ * @return The application's name.
+ */
static const char* appName();
- //
- // One limitation of this class is that there can only be one
- // Application instance, with one global Communicator, accessible
- // with this communicator() operation. This limitation is due to
- // how the signal handling functions below operate. If you require
- // multiple Communicators, then you cannot use this Application
- // framework class.
- //
+ /**
+ * Obtains the application's Communicator instance.
+ * One limitation of this class is that there can only be one
+ * Application instance, with one global Communicator, accessible
+ * with this communicator() operation. This limitation is due to
+ * how the signal handling functions below operate. If you require
+ * multiple Communicators, then you cannot use this Application
+ * framework class.
+ * @return The application's communicator.
+ */
static CommunicatorPtr communicator();
- //
- // These methods can be used to set a Ctrl+C Handler callback.
- //
+ /**
+ * Configures the application to destroy the communicator when one of the
+ * monitored signals is raised. This is the default behavior.
+ */
static void destroyOnInterrupt();
+
+ /**
+ * Configures the application to shut down the communicator when one of the
+ * monitored signals is raised.
+ */
static void shutdownOnInterrupt();
+
+ /**
+ * Configures the application to ignore signals.
+ */
static void ignoreInterrupt();
+
+ /**
+ * Configures the application to invoke interruptCallback when a signal occurs,
+ * thereby giving the subclass responsibility for handling the signal.
+ */
static void callbackOnInterrupt();
- //
- // These methods can be used to temporarily block a signal and
- // arrange for delivery of a pending signal later. Any signal that
- // is received after holdInterrupt() was called is remembered and
- // delivered when releaseInterupt() is called. That signal is then
- // handled according to the signal disposition established with
- // destroyOnInterrupt(), shutdownOnInterrupt() or
- // ignoreInterrupt().
- //
+ /**
+ * Configures the application to ignore (but remember) a signal.
+ * A stored signal (if any) can be handled later by calling releaseInterrupt.
+ */
static void holdInterrupt();
+
+ /**
+ * Processes a stored signal (if any) using the current signal handling configuration.
+ */
static void releaseInterrupt();
- //
- // This method returns true if a signal handler was triggered,
- // false otherwise. This can be used once
- // Communicator::waitForShutdown() returns to test whether the
- // shutdown was due to an interrupt (interrupted() returns true in
- // that case) or because Communicator::shutdown() was called
- // (interrupted() returns false in that case).
- //
+ /**
+ * Indicates whether a signal handler was triggered.
+ * This can be used once Communicator::waitForShutdown() returns to
+ * test whether the shutdown was due to an interrupt (returns true)
+ * or because Communicator::shutdown() was called (returns false).
+ * @return True if a signal handler was triggered, false otherwise.
+ */
static bool interrupted();
protected:
+ /**
+ * Helper function that implements the application logic.
+ */
virtual int doMain(int, char*[], const InitializationData&, Int);
- //
- // _mutex and _condVar are used to synchronize the main thread and
- // the CtrlCHandler thread
- //
+ /**
+ * Used to synchronize the main thread and the CtrlCHandler thread.
+ */
static IceUtil::Mutex _mutex;
+
+ /**
+ * Used to synchronize the main thread and the CtrlCHandler thread.
+ */
static IceUtil::Cond _condVar;
- //
- // Variables than can change while run() and communicator->destroy()
- // are running!
- //
+ /**
+ * True if a signal handling callback is currently executing.
+ * Can change while run() and communicator->destroy() are running!
+ */
static bool _callbackInProgress;
+
+ /**
+ * True if the communicator has been destroyed.
+ * Can change while run() and communicator->destroy() are running!
+ */
static bool _destroyed;
+
+ /**
+ * True if an interrupt signal was received.
+ * Can change while run() and communicator->destroy() are running!
+ */
static bool _interrupted;
- //
- // Variables that are immutable during run() and until
- // communicator->destroy() has returned, before and after run(), and
- // once communicator->destroy() has returned, we assume that
- // only the main thread and CtrlCHandler threads are running.
- //
+ /**
+ * The application's name.
+ * Immutable during run() and until communicator->destroy() has returned.
+ * Before and after run(), and once communicator->destroy() has returned,
+ * we assume that only the main thread and CtrlCHandler threads are running.
+ */
static std::string _appName;
+
+ /**
+ * The application's communicator.
+ * Immutable during run() and until communicator->destroy() has returned.
+ * Before and after run(), and once communicator->destroy() has returned,
+ * we assume that only the main thread and CtrlCHandler threads are running.
+ */
static CommunicatorPtr _communicator;
+
+ /**
+ * The signal-handling policy specified at construction.
+ * Immutable during run() and until communicator->destroy() has returned.
+ * Before and after run(), and once communicator->destroy() has returned,
+ * we assume that only the main thread and CtrlCHandler threads are running.
+ */
static SignalPolicy _signalPolicy;
+
+ /**
+ * The singleton instance.
+ * Immutable during run() and until communicator->destroy() has returned.
+ * Before and after run(), and once communicator->destroy() has returned,
+ * we assume that only the main thread and CtrlCHandler threads are running.
+ */
static Application* _application;
private: