zeroc-ice 3.7.0 → 3.7.5

data/ext/ice/cpp/include/IceUtil/CountDownLatch.h

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) ZeroC, Inc. All rights reserved.
 //
-// This copy of Ice is licensed to you under the terms described in the
-// ICE_LICENSE file included in this distribution.
-//
-// **********************************************************************
 
 #ifndef ICE_UTIL_COUNT_DOWN_LATCH_H
 #define ICE_UTIL_COUNT_DOWN_LATCH_H

data/ext/ice/cpp/include/IceUtil/CtrlCHandler.h

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) ZeroC, Inc. All rights reserved.
 //
-// This copy of Ice is licensed to you under the terms described in the
-// ICE_LICENSE file included in this distribution.
-//
-// **********************************************************************
 
 #ifndef ICE_UTIL_CTRL_C_HANDLER_H
 #define ICE_UTIL_CTRL_C_HANDLER_H
@@ -16,49 +11,70 @@
 namespace IceUtil
 {
 
-// The CtrlCHandler provides a portable way to handle CTRL+C and
-// CTRL+C like signals
-// On Unix/POSIX, the CtrlCHandler handles SIGHUP, SIGINT and SIGTERM.
-// On Windows, it is essentially a wrapper for SetConsoleCtrlHandler().
-//
-// In a process, only one CtrlCHandler can exist at a given time:
-// the CtrlCHandler constructor raises CtrlCHandlerException if
-// you attempt to create a second CtrlCHandler.
-// On Unix/POSIX, it is essential to create the CtrlCHandler before
-// creating any thread, as the CtrlCHandler constructor masks (blocks)
-// SIGHUP, SIGINT and SIGTERM; by default, threads created later will
-// inherit this signal mask.
-//
-// When a CTRL+C or CTRL+C like signal is sent to the process, the
-// user-registered callback is called in a separate thread; it is
-// given the signal number. The callback must not raise exceptions.
-// On Unix/POSIX, the callback is NOT a signal handler and can call
-// functions that are not async-signal safe.
-//
-// The CtrCHandler destructor "unregisters" the callback. However
-// on Unix/POSIX it does not restore the old signal mask in any
-// thread, so SIGHUP, SIGINT and SIGTERM remain blocked.
-//
-// TODO: Maybe the behavior on Windows should be the same? Now we
-// just restore the default behavior (TerminateProcess).
-
+/**
+ * Invoked when a signal occurs. The callback must not raise exceptions.
+ * On Linux and macOS, the callback is NOT a signal handler and can call
+ * functions that are not async-signal safe.
+ * @param sig The signal number that occurred.
+ */
 #ifdef ICE_CPP11_MAPPING
-using CtrlCHandlerCallback = std::function<void(int)>;
+using CtrlCHandlerCallback = std::function<void(int sig)>;
 #else
-typedef void (*CtrlCHandlerCallback)(int);
+typedef void (*CtrlCHandlerCallback)(int sig);
 #endif
 
+/**
+ * Provides a portable way to handle Ctrl-C and Ctrl-C like signals.
+ * On Linux and macOS, the CtrlCHandler handles SIGHUP, SIGINT and SIGTERM.
+ * On Windows, it is essentially a wrapper for SetConsoleCtrlHandler().
+ *
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API CtrlCHandler
 {
 public:
 
-    explicit CtrlCHandler(CtrlCHandlerCallback = ICE_NULLPTR);
+     /**
+     * Registers a callback function that handles Ctrl-C like signals.
+     * On Linux and macOS, this constructor masks the SIGHUP, SIGINT and SIGTERM
+     * signals and then creates a thread that waits for these signals using sigwait.
+     * On Windows, this constructor calls SetConsoleCtrlCHandler to register a handler
+     * routine that calls the supplied callback function.
+     * Only a single CtrlCHandler object can exist in a process at a give time.
+     * @param cb The callback function to invoke when a signal is received.
+     */
+    explicit CtrlCHandler(CtrlCHandlerCallback cb = ICE_NULLPTR);
+
+     /**
+     * Unregisters the callback function.
+     * On Linux and macOS, this destructor joins and terminates the thread created
+     * by the constructor but does not "unmask" SIGHUP, SIGINT and SIGTERM. As a result,
+     * these signals are ignored after this destructor completes.
+     * On Windows, this destructor unregisters the SetConsoleCtrlHandler handler
+     * routine, and as a result a Ctrl-C or similar signal will terminate the application
+     * after this destructor completes.
+     */
     ~CtrlCHandler();
 
-    CtrlCHandlerCallback setCallback(CtrlCHandlerCallback);
+    /**
+     * Replaces the signal callback.
+     * @param cb The new callback.
+     * @return The old callback, or nil if no callback is currently set.
+     */
+    CtrlCHandlerCallback setCallback(CtrlCHandlerCallback cb);
+
+    /**
+     * Obtains the signal callback.
+     * @return The callback.
+     */
     CtrlCHandlerCallback getCallback() const;
 };
 
+/**
+ * Raised by the CtrlCHandler constructor if another CtrlCHandler already exists.
+ *
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API CtrlCHandlerException : public ExceptionHelper<CtrlCHandlerException>
 {
 public:

data/ext/ice/cpp/include/IceUtil/DisableWarnings.h

@@ -1,18 +1,12 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) ZeroC, Inc. All rights reserved.
 //
-// This copy of Ice is licensed to you under the terms described in the
-// ICE_LICENSE file included in this distribution.
-//
-// **********************************************************************
 
 #ifndef ICE_UTIL_DISABLEWARNINGS_H
 #define ICE_UTIL_DISABLEWARNINGS_H
 
 //
-// This header file disables or makes non-fatal various compiler warnings that
-// we don't want.
+// This header file disables various compiler warnings that we don't want.
 //
 // IMPORTANT: Do *not* include this header file in another public header file!
 //            Doing this may potentially disable the warnings in the source
@@ -25,11 +19,11 @@
 //
 #if defined(_MSC_VER)
 #    define _CRT_SECURE_NO_DEPRECATE 1  // C4996 '<C function>' was declared deprecated
-#    pragma warning( 4 : 4996 ) // C4996 '<function>' was declared deprecated
-#    pragma warning( 4 : 4800 ) // C4800 forcing value to bool 'true' or 'false' (performance warning)
+#    pragma warning(disable:4996) // C4996 '<function>' was declared deprecated
+#    pragma warning(disable:4800) // C4800 forcing value to bool 'true' or 'false' (performance warning)
 
 #    if (_MSC_VER < 1700)
-#       pragma warning( 4 : 4355 ) // C4355 'this' : used in base member initializer list
+#       pragma warning(disable:4355) // C4355 'this' : used in base member initializer list
 #    endif
 #endif
 

data/ext/ice/cpp/include/IceUtil/Exception.h

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) ZeroC, Inc. All rights reserved.
 //
-// This copy of Ice is licensed to you under the terms described in the
-// ICE_LICENSE file included in this distribution.
-//
-// **********************************************************************
 
 #ifndef ICE_UTIL_EXCEPTION_H
 #define ICE_UTIL_EXCEPTION_H
@@ -18,35 +13,97 @@
 namespace IceUtil
 {
 
+/**
+ * Abstract base class for all Ice exceptions. Use the Ice::Exception alias instead
+ * of IceUtil::Exception.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API Exception : public std::exception
 {
 public:
 
+    /**
+     * Constructs the exception. Equivalent to Exception(nullptr, 0).
+     */
     Exception();
-    Exception(const char*, int);
+
+    /**
+     * Constructs the exception.
+     * @param file The file where this exception is constructed.
+     * @param line The line where this exception is constructed.
+     */
+    Exception(const char* file, int line);
+
 #ifndef ICE_CPP11_COMPILER
     virtual ~Exception() throw() = 0;
 #endif
+
+    /**
+     * Returns the type ID of this exception. This corresponds to the Slice
+     * type ID for Slice-defined exceptions, and to a similar fully scoped name
+     * for other exceptions. For example "::IceUtil::SyscallException".
+     * @return The type ID of this exception
+     */
     virtual std::string ice_id() const = 0;
-    virtual void ice_print(std::ostream&) const;
+
+    /**
+     * Outputs a description of this exception to a stream.
+     * @param os The output stream.
+     */
+    virtual void ice_print(std::ostream& os) const;
+
+    /**
+     * Returns a description of this exception.
+     * @return The description.
+     */
     virtual const char* what() const ICE_NOEXCEPT;
 #ifdef ICE_CPP11_MAPPING
+
+    /**
+     * Returns a shallow polymorphic copy of this exception.
+     * @return A unique_ptr to the new shallow copy.
+     */
     std::unique_ptr<Exception> ice_clone() const;
 #else
+    /**
+     * Returns a shallow polymorphic copy of this exception.
+     * @return A pointer to the new shallow copy. The caller owns the returned object.
+     */
     virtual Exception* ice_clone() const = 0;
+
     ICE_DEPRECATED_API("ice_name() is deprecated, use ice_id() instead.")
     std::string ice_name() const;
 #endif
+
+    /**
+     * Throws this exception.
+     */
     virtual void ice_throw() const = 0;
 
+    /**
+     * Returns the name of the file where this exception was constructed.
+     * @return The file name.
+     */
     const char* ice_file() const;
+
+    /**
+     * Returns the line number where this exception was constructed.
+     * @return The line number.
+     */
     int ice_line() const;
+
+    /**
+     * Returns the stack trace at the point this exception was constructed
+     * @return The stack trace as a string.
+     */
     std::string ice_stackTrace() const;
 
 protected:
 
 #ifdef ICE_CPP11_MAPPING
+    /// \cond INTERNAL
     virtual Exception* ice_cloneImpl() const = 0;
+    /// \endcond
 #endif
 
 private:
@@ -61,6 +118,11 @@ ICE_API std::ostream& operator<<(std::ostream&, const Exception&);
 
 #ifdef ICE_CPP11_MAPPING
 
+/**
+ * Helper template for the implementation of Ice::Exception.
+ * It implements ice_clone and ice_throw.
+ * \headerfile Ice/Ice.h
+ */
 template<typename E, typename B = Exception>
 class ExceptionHelper : public B
 {
@@ -80,14 +142,20 @@ public:
 
 protected:
 
+    /// \cond INTERNAL
     virtual Exception* ice_cloneImpl() const override
     {
         return new E(static_cast<const E&>(*this));
     }
+    /// \endcond
 };
 
 #else // C++98 mapping
 
+/**
+ * Helper template for the implementation of Ice::Exception. It implements ice_throw.
+ * \headerfile Ice/Ice.h
+ */
 template<typename E>
 class ExceptionHelper : public Exception
 {
@@ -109,6 +177,11 @@ public:
 
 #endif
 
+/**
+ * This exception indicates an attempt to dereference a null IceUtil::Handle or
+ * IceInternal::Handle.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API NullHandleException : public ExceptionHelper<NullHandleException>
 {
 public:
@@ -121,6 +194,12 @@ public:
 #endif
 };
 
+/**
+ * This exception indicates that a function was called with an illegal parameter
+ * value. It is used only by the Slice to C++98 mapping; std::invalid_argument is
+ * used by the Slice to C++11 mapping.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API IllegalArgumentException : public ExceptionHelper<IllegalArgumentException>
 {
 public:
@@ -139,6 +218,10 @@ public:
     virtual IllegalArgumentException* ice_clone() const;
 #endif
 
+    /**
+     * Provides the reason this exception was thrown.
+     * @return The reason.
+     */
     std::string reason() const;
 
 private:
@@ -146,9 +229,10 @@ private:
     const std::string _reason;
 };
 
-//
-// IllegalConversionException is raised to report a string conversion error
-//
+/**
+ * This exception indicates the failure of a string conversion.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API IllegalConversionException : public ExceptionHelper<IllegalConversionException>
 {
 public:
@@ -167,6 +251,10 @@ public:
     virtual IllegalConversionException* ice_clone() const;
 #endif
 
+    /**
+     * Provides the reason this exception was thrown.
+     * @return The reason.
+     */
     std::string reason() const;
 
 private:
@@ -174,6 +262,10 @@ private:
     const std::string _reason;
 };
 
+/**
+ * This exception indicates the failure of a system call.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API SyscallException : public ExceptionHelper<SyscallException>
 {
 public:
@@ -191,6 +283,10 @@ public:
     virtual SyscallException* ice_clone() const;
 #endif
 
+    /**
+     * Provides the error number returned by the system call.
+     * @return The error number.
+     */
     int error() const;
 
 private:
@@ -205,6 +301,11 @@ using SyscallExceptionHelper = ExceptionHelper<E, SyscallException>;
 
 #else // C++98 mapping
 
+/**
+* Helper template for the implementation of SyscallException. It implements
+* ice_throw.
+* \headerfile Ice/Ice.h
+*/
 template<typename E>
 class SyscallExceptionHelper : public SyscallException
 {
@@ -223,6 +324,10 @@ public:
 
 #endif
 
+/**
+ * This exception indicates the failure to lock a file.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API FileLockException : public ExceptionHelper<FileLockException>
 {
 public:
@@ -240,7 +345,16 @@ public:
     virtual FileLockException* ice_clone() const;
 #endif
 
+    /**
+     * Returns the path to the file.
+     * @return The file path.
+     */
     std::string path() const;
+
+    /**
+     * Returns the error number for the failed locking attempt.
+     * @return The error number.
+     */
     int error() const;
 
 private:
@@ -249,6 +363,11 @@ private:
     std::string _path;
 };
 
+/**
+ * This exception indicates an IceUtil::Optional is not set.
+ * Used only by the Slice to C++98 mapping.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API OptionalNotSetException : public ExceptionHelper<OptionalNotSetException>
 {
 public:

data/ext/ice/cpp/include/IceUtil/FileUtil.h

@@ -1,11 +1,6 @@
-// **********************************************************************
 //
-// Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+// Copyright (c) ZeroC, Inc. All rights reserved.
 //
-// This copy of Ice is licensed to you under the terms described in the
-// ICE_LICENSE file included in this distribution.
-//
-// **********************************************************************
 
 #ifndef ICE_FILE_UTIL_H
 #define ICE_FILE_UTIL_H