zeroc-ice 3.7.11 → 3.8.1

data/dist/ice/cpp/include/Ice/Service.h

@@ -1,379 +1,219 @@
-//
-// Copyright (c) ZeroC, Inc. All rights reserved.
-//
+// Copyright (c) ZeroC, Inc.
 
 #ifndef ICE_SERVICE_H
 #define ICE_SERVICE_H
 
-#include <Ice/Initialize.h>
-#include <Ice/LoggerUtil.h>
+#include "Ice.h"
 
 #ifdef _WIN32
-#   include <winsvc.h>
+#    ifndef NOMINMAX
+#        define NOMINMAX
+#    endif
+#    include <windows.h>
+#    include <winsvc.h>
 #endif
 
 namespace Ice
 {
+    /// A singleton class that helps you write Windows services and Unix daemons using Ice.
+    /// @headerfile Ice/Ice.h
+    class ICE_API Service
+    {
+    public:
+        /// Default constructor.
+        Service();
+
+        virtual ~Service();
+
+        /// Shuts down the service. The default implementation calls Communicator::shutdown.
+        virtual bool shutdown();
+
+        /// Notifies the service that the program received a signal. The default implementation calls #shutdown.
+        /// @see Ice::CtrlCHandler
+        virtual void interrupt();
+
+        /// The primary entry point for services. This function examines @p argv for reserved options and takes the
+        /// appropriate action. The reserved options are shown below.
+        ///
+        /// Win32:
+        ///
+        /// --service NAME
+        ///
+        /// Unix:
+        ///
+        /// --daemon [--nochdir] [--noclose]
+        ///
+        /// If --service or --daemon are specified, the program runs as a service, otherwise the program runs as a
+        /// regular foreground process. Any service-specific (and Ice-specific) options are stripped from @p argv (just
+        /// as for ::Ice::initialize).
+        /// @param argc The number of arguments in @p argv.
+        /// @param argv The command-line arguments.
+        /// @param initData Configuration data for the new communicator.
+        /// @return The application's exit status: EXIT_FAILURE or EXIT_SUCCESS.
+        int main(int argc, const char* const argv[], InitializationData initData = {});
+
+#if defined(_WIN32) || defined(ICE_DOXYGEN)
+        /// @copydoc main(int, const char* const[], InitializationData)
+        /// @remarks Windows only.
+        int main(int argc, const wchar_t* const argv[], InitializationData initData = {});
+#endif
 
-/**
- * A singleton class comparable to Ice::Application but also provides the low-level, platform-specific
- * initialization and shutdown procedures common to system services.
- * \headerfile Ice/Ice.h
- */
-class ICE_API Service
-{
-public:
-
-    Service();
-    virtual ~Service();
-
-    /**
-     * Shutdown the service. The default implementation invokes shutdown()
-     * on the communicator.
-     */
-    virtual bool shutdown();
-
-    /**
-     * Notify the service about a signal interrupt. The default
-     * implementation invokes shutdown().
-     */
-    virtual void interrupt();
-
-    /**
-     * The primary entry point for services. This function examines
-     * the given argument vector for reserved options and takes the
-     * appropriate action. The reserved options are shown below.
-     *
-     * Win32:
-     *
-     * --service NAME
-     *
-     * Unix:
-     *
-     * --daemon [--nochdir] [--noclose]
-     *
-     * If --service or --daemon are specified, the program runs as
-     * a service, otherwise the program runs as a regular foreground
-     * process. Any service-specific (and Ice-specific) options
-     * are stripped from argv (just as for Ice::initialize()).
-     *
-     * @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: EXIT_FAILURE or EXIT_SUCCESS.
-     */
-    int main(int argc, const char* const argv[], const InitializationData& initData = InitializationData(),
-             int version = ICE_INT_VERSION);
+        /// The primary entry point for services. This function examines @p args for reserved options and takes the
+        /// appropriate action. The reserved options are shown below.
+        ///
+        /// Win32:
+        ///
+        /// --service NAME
+        ///
+        /// Unix:
+        ///
+        /// --daemon [--nochdir] [--noclose]
+        ///
+        /// If --service or --daemon are specified, the program runs as a service, otherwise the program runs as a
+        /// regular foreground process. Any service-specific (and Ice-specific) options are stripped from @p args (just
+        /// as for ::Ice::initialize).
+        /// @param args The command-line arguments.
+        /// @param initData Configuration data for the new communicator.
+        /// @return The application's exit status: EXIT_FAILURE or EXIT_SUCCESS.
+        int main(const StringSeq& args, InitializationData initData = {});
+
+        /// Gets the communicator created by the service.
+        /// @return The service's communicator.
+        [[nodiscard]] Ice::CommunicatorPtr communicator() const;
+
+        /// Gets the Service singleton.
+        /// @return A pointer to this service.
+        static Service* instance();
+
+        /// Indicates whether the program is running as a Win32 service or Unix daemon.
+        /// @return `true` if the program is running as a service, `false` otherwise.
+        [[nodiscard]] bool service() const;
+
+        /// Gets the program name. If the program is running as a Win32 service, the return value is the service name.
+        /// Otherwise the return value is the executable name (i.e., argv[0]).
+        /// @return The service name.
+        [[nodiscard]] std::string name() const;
+
+        /// Handles a signal.
+        /// @remarks The default implementation calls #interrupt unless the signal is SIGHUP or CTRL_LOGOFF_EVENT and
+        /// the property `Ice.Nohup` is greater than 0 (or not set at all).
+        /// @param sig The signal that was caught.
+        virtual void handleInterrupt(int sig);
 
 #ifdef _WIN32
-    /**
-     * The primary entry point for services. This function examines
-     * the given argument vector for reserved options and takes the
-     * appropriate action. The reserved options are shown below.
-     *
-     * Win32:
-     *
-     * --service NAME
-     *
-     * Unix:
-     *
-     * --daemon [--nochdir] [--noclose]
-     *
-     * If --service or --daemon are specified, the program runs as
-     * a service, otherwise the program runs as a regular foreground
-     * process. Any service-specific (and Ice-specific) options
-     * are stripped from argv (just as for Ice::initialize()).
-     *
-     * @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: EXIT_FAILURE or EXIT_SUCCESS.
-     */
-    int main(int argc, const wchar_t* const argv[], const InitializationData& initData = InitializationData(),
-             int version = ICE_INT_VERSION);
-#endif
+        /// @private
+        static void setModuleHandle(HMODULE);
 
-    /**
-     * The primary entry point for services. This function examines
-     * the given argument vector for reserved options and takes the
-     * appropriate action. The reserved options are shown below.
-     *
-     * Win32:
-     *
-     * --service NAME
-     *
-     * Unix:
-     *
-     * --daemon [--nochdir] [--noclose]
-     *
-     * If --service or --daemon are specified, the program runs as
-     * a service, otherwise the program runs as a regular foreground
-     * process. Any service-specific (and Ice-specific) options
-     * are stripped from argv (just as for Ice::initialize()).
-     *
-     * @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: EXIT_FAILURE or EXIT_SUCCESS.
-     */
-    int main(const StringSeq& args, const InitializationData& initData = InitializationData(),
-             int version = ICE_INT_VERSION);
-
-    /**
-     * Obtains the communicator created by the service.
-     * @return The service's communicator.
-     */
-    Ice::CommunicatorPtr communicator() const;
-
-    /**
-     * Obtains the Service singleton.
-     * @return A pointer to this service.
-     */
-    static Service* instance();
-
-    /**
-     * Indicates whether the program is running as a Win32 service or Unix daemon.
-     * @return True if the program is running as a service, false otherwise.
-     */
-    bool service() const;
-
-    /**
-     * Obtains the program name. If the program is running as a Win32
-     * service, the return value is the service name. Otherwise the
-     * return value is the executable name (i.e., argv[0]).
-     * @return The service name.
-     */
-    std::string name() const;
-
-    /**
-     * Determines whether the operating system supports running the
-     * program as a Win32 service or Unix daemon.
-     * @return True if the system supports services, false otherwise.
-     */
-    bool checkSystem() const;
+        /// @private
+        void serviceMain(int, const wchar_t* const[]);
 
-#ifdef _WIN32
-    /**
-     * Alternative entry point for services that use their own
-     * command-line options. Instead of invoking main(), the
-     * program processes its command-line options and invokes
-     * run(). To run as a Win32 service or Unix daemon, the
-     * program must first invoke configureService() or
-     * configureDaemon(), respectively.
-     *
-     * @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: EXIT_FAILURE or EXIT_SUCCESS.
-     */
-    int run(int argc, const wchar_t* const argv[], const InitializationData& initData = InitializationData(),
-            int version = ICE_INT_VERSION);
+        /// @private
+        void control(int);
 #endif
 
-    /**
-     * Alternative entry point for services that use their own
-     * command-line options. Instead of invoking main(), the
-     * program processes its command-line options and invokes
-     * run(). To run as a Win32 service or Unix daemon, the
-     * program must first invoke configureService() or
-     * configureDaemon(), respectively.
-     *
-     * @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: EXIT_FAILURE or EXIT_SUCCESS.
-     */
-    int run(int argc, const char* const argv[], const InitializationData& initData = InitializationData(),
-            int version = ICE_INT_VERSION);
+    protected:
+        /// Prepares a service for execution, including the creation and activation of object adapters and servants.
+        /// @param argc The number of arguments in @p argv.
+        /// @param argv The command-line arguments.
+        /// @param[out] status The exit status, which is returned by #main when `start` or `stop` returns `false`.
+        /// @return `true` if startup was successful, `false` otherwise.
+        virtual bool start(int argc, char* argv[], int& status) = 0;
 
-#ifdef _WIN32
+        /// Blocks until the service shuts down. The default implementation calls Communicator::waitForShutdown.
+        virtual void waitForShutdown();
 
-    /**
-     * Configures the program to run as a Win32 service with the given name.
-     * @param name The service name.
-     */
-    void configureService(const std::string& name);
+        /// Cleans up resources after shutting down.
+        virtual bool stop();
 
-    /// \cond INTERNAL
-    static void setModuleHandle(HMODULE);
-    /// \endcond
+        /// Initializes a communicator.
+        /// @param argc The number of arguments in @p argv.
+        /// @param argv The command-line arguments.
+        /// @param initData Configuration data for the new communicator.
+        /// @return The new communicator instance.
+        virtual Ice::CommunicatorPtr initializeCommunicator(int& argc, char* argv[], InitializationData initData);
 
-#else
+        /// Logs a system error, which includes a description of the current system error code.
+        /// @param msg The log message.
+        virtual void syserror(const std::string& msg);
 
-    /**
-     * Configures the program to run as a Unix daemon. The first
-     * argument indicates whether the daemon should change its
-     * working directory to the root directory. The second
-     * argument indicates whether extraneous file descriptors are
-     * closed. If the value of the last argument is not an empty
-     * string, the daemon writes its process ID to the given
-     * filename.
-     *
-     * @param changeDirectory True if the daemon should change its working directory to the root directory,
-     * false otherwise.
-     * @param closeFiles True if the daemon should close unnecessary file descriptors (i.e., stdin, stdout, etc.),
-     * false otherwise.
-     * @param pidFile If a non-empty string is provided, the daemon writes its process ID to the given file.
-     */
-    void configureDaemon(bool changeDirectory, bool closeFiles, const std::string& pidFile);
+        /// Logs an error.
+        /// @param msg The log message.
+        virtual void error(const std::string& msg);
 
-#endif
+        /// Logs a warning.
+        /// @param msg The log message.
+        virtual void warning(const std::string& msg);
 
-    /**
-     * Invoked by the signal handler when it catches a signal.
-     * @param sig The signal that was caught.
-     */
-    virtual void handleInterrupt(int sig);
-
-protected:
-
-    /**
-     * Prepares a service for execution, including the creation and
-     * activation of object adapters and servants.
-     * @param argc Specifies the number of arguments in argv.
-     * @param argv The command-line arguments.
-     * @param status The exit status, which is returned by main
-     * @return True if startup was successful, false otherwise.
-     */
-    virtual bool start(int argc, char* argv[], int& status) = 0;
-
-    /**
-     * Blocks until the service shuts down. The default implementation
-     * invokes waitForShutdown() on the communicator.
-     */
-    virtual void waitForShutdown();
-
-    /**
-     * Cleans up resources after shutting down.
-     */
-    virtual bool stop();
-
-    /**
-     * Initializes a communicator.
-     * @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 new communicator instance.
-     */
-    virtual Ice::CommunicatorPtr initializeCommunicator(int& argc, char* argv[], const InitializationData& initData,
-                                                        int version);
-
-    /**
-     * Logs a system error, which includes a description of the
-     * current system error code.
-     * @param msg The log message.
-     */
-    virtual void syserror(const std::string& msg);
-
-    /**
-     * Logs an error.
-     * @param msg The log message.
-     */
-    virtual void error(const std::string& msg);
-
-    /**
-     * Logs a warning.
-     * @param msg The log message.
-     */
-    virtual void warning(const std::string& msg);
-
-    /**
-     * Logs trace information.
-     * @param msg The log message.
-     */
-    virtual void trace(const std::string& msg);
-
-    /**
-     * Logs a literal message.
-     * @param msg The log message.
-     */
-    virtual void print(const std::string& msg);
-
-    /**
-     * Enables the signal handler to invoke interrupt() when a signal occurs.
-     */
-    void enableInterrupt();
-
-    /**
-     * Ignore signals.
-     */
-    void disableInterrupt();
-
-    /**
-     * Logger utility class for a system error.
-     */
-    typedef LoggerOutput<Service, Service*, &Service::syserror> ServiceSysError;
-
-    /**
-     * Logger utility class for an error.
-     */
-    typedef LoggerOutput<Service, Service*, &Service::error> ServiceError;
-
-    /**
-     * Logger utility class for a warning.
-     */
-    typedef LoggerOutput<Service, Service*, &Service::warning> ServiceWarning;
-
-    /**
-     * Logger utility class for a trace message.
-     */
-    typedef LoggerOutput<Service, Service*, &Service::trace> ServiceTrace;
-
-    /**
-     * Logger utility class for a literal message.
-     */
-    typedef LoggerOutput<Service, Service*, &Service::print> ServicePrint;
-
-private:
-
-    Ice::LoggerPtr _logger;
-    Ice::CommunicatorPtr _communicator;
-    bool _nohup;
-    bool _service;
-    std::string _name;
-
-    static Service* _instance;
+        /// Logs trace information.
+        /// @param msg The log message.
+        virtual void trace(const std::string& msg);
 
-#ifdef _WIN32
+        /// Logs a literal message.
+        /// @param msg The log message.
+        virtual void print(const std::string& msg);
 
-    int runService(int, const char* const[], const InitializationData&);
-    void terminateService(DWORD);
-    bool waitForServiceState(SC_HANDLE, DWORD, SERVICE_STATUS&);
-    void showServiceStatus(const std::string&, SERVICE_STATUS&);
+        /// Makes this service call #handleInterrupt when it receives a signal.
+        void enableInterrupt();
 
-    SERVICE_STATUS_HANDLE _statusHandle;
-    std::vector<std::string> _serviceArgs;
-    InitializationData _initData;
+        /// Ignores signals.
+        void disableInterrupt();
 
-public:
+        /// Logger utility class for a system error.
+        using ServiceSysError = LoggerOutput<Service, Service*, &Service::syserror>;
 
-    /// \cond INTERNAL
-    void serviceMain(int, const wchar_t* const[]);
-    void control(int);
-    /// \endcond
+        /// Logger utility class for an error.
+        using ServiceError = LoggerOutput<Service, Service*, &Service::error>;
 
-#else
+        /// Logger utility class for a warning.
+        using ServiceWarning = LoggerOutput<Service, Service*, &Service::warning>;
+
+        /// Logger utility class for a trace message.
+        using ServiceTrace = LoggerOutput<Service, Service*, &Service::trace>;
+
+        /// Logger utility class for a literal message.
+        using ServicePrint = LoggerOutput<Service, Service*, &Service::print>;
+
+    private:
+        Ice::LoggerPtr _logger;
+        Ice::CommunicatorPtr _communicator;
+        bool _nohup = true;
+        bool _service = false;
+        std::string _name;
 
-    int runDaemon(int, char*[], const InitializationData&, int);
+        static Service* _instance;
 
-    bool _changeDirectory;
-    bool _closeFiles;
-    std::string _pidFile;
+        int run(int argc, const char* const argv[], InitializationData initData = {});
 
+#ifdef _WIN32
+        /// Configures the program to run as a Windows service.
+        void configureService(const std::string& name);
+
+        int runService(int, const char* const[], InitializationData);
+        void terminateService(DWORD);
+        bool waitForServiceState(SC_HANDLE, DWORD, SERVICE_STATUS&);
+        void showServiceStatus(const std::string&, SERVICE_STATUS&);
+
+        SERVICE_STATUS_HANDLE _statusHandle;
+        std::vector<std::string> _serviceArgs;
+        InitializationData _initData;
+#else
+        /// Configures the program to run as a Unix daemon.
+        /// @param changeDirectory `true` if the daemon should change its working directory to the root directory,
+        /// `false` otherwise.
+        /// @param closeFiles `true` if the daemon should close unnecessary file descriptors (i.e., stdin, stdout,
+        /// etc.), `false` otherwise.
+        /// @param pidFile If a non-empty string is provided, the daemon writes its process ID to the given file.
+        /// @remarks Linux and macOS only.
+        void configureDaemon(bool changeDirectory, bool closeFiles, const std::string& pidFile);
+
+        int runDaemon(int, char*[], InitializationData);
+
+        bool _changeDirectory = true;
+        bool _closeFiles = true;
+        std::string _pidFile;
 #endif
-};
+    };
 
-} // End of namespace Ice
+}
 
 #endif

data/dist/ice/cpp/include/Ice/SliceLoader.h

@@ -0,0 +1,67 @@
+// Copyright (c) ZeroC, Inc.
+
+#ifndef ICE_SLICE_LOADER_H
+#define ICE_SLICE_LOADER_H
+
+#include "Config.h"
+#include "ValueF.h"
+
+#include <exception>
+#include <memory>
+#include <string_view>
+#include <vector>
+
+namespace Ice
+{
+    /// Creates class and exception instances from Slice type IDs.
+    /// @remark The implementation of newClassInstance and newExceptionInstance in the base class always returns
+    /// nullptr.
+    /// @headerfile Ice/Ice.h
+    class ICE_API SliceLoader
+    {
+    public:
+        virtual ~SliceLoader();
+
+        /// Creates an instance of a class mapped from a Slice class based on a Slice type ID.
+        /// @param typeId The Slice type ID or compact type ID.
+        /// @return A new instance of the class identified by @p typeId, or nullptr if the implementation cannot find
+        /// the corresponding class.
+        /// @throws MarshalException Thrown when the corresponding class was found but its instantiation failed.
+        [[nodiscard]] virtual ValuePtr newClassInstance(std::string_view typeId) const;
+
+        /// Creates an instance of a class mapped from a Slice exception based on a Slice type ID.
+        /// @param typeId The Slice type ID.
+        /// @return A new instance of the exception class identified by @p typeId, or nullptr if the implementation
+        /// cannot find the corresponding class.
+        /// @throws MarshalException Thrown when the corresponding class was found but its instantiation failed.
+        [[nodiscard]] virtual std::exception_ptr newExceptionInstance(std::string_view typeId) const;
+
+    protected:
+        SliceLoader() = default;
+    };
+
+    /// A shared pointer to a SliceLoader.
+    using SliceLoaderPtr = std::shared_ptr<SliceLoader>;
+
+    /// Implements SliceLoader by combining multiple SliceLoader instances.
+    class ICE_API CompositeSliceLoader final : public SliceLoader
+    {
+    public:
+        ~CompositeSliceLoader() final;
+
+        /// Adds a SliceLoader instance to this CompositeSliceLoader.
+        /// @param loader The SliceLoader to add.
+        void add(SliceLoaderPtr loader) noexcept;
+
+        [[nodiscard]] ValuePtr newClassInstance(std::string_view typeId) const final;
+        [[nodiscard]] std::exception_ptr newExceptionInstance(std::string_view typeId) const final;
+
+    private:
+        std::vector<SliceLoaderPtr> _loaders;
+    };
+
+    /// A shared pointer to a CompositeSliceLoaderPtr.
+    using CompositeSliceLoaderPtr = std::shared_ptr<CompositeSliceLoader>;
+}
+
+#endif