zeroc-ice 3.7.0 → 3.7.5

data/ext/ValueFactoryManager.cpp

@@ -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.
-//
-// **********************************************************************
 
 #include <ValueFactoryManager.h>
 #include <Types.h>
@@ -102,7 +97,7 @@ IceRuby::ValueFactoryManager::add(const Ice::ValueFactoryPtr& f, const string& i
 }
 
 Ice::ValueFactoryPtr
-IceRuby::ValueFactoryManager::find(const string& id) const
+IceRuby::ValueFactoryManager::find(const string& id) const ICE_NOEXCEPT
 {
     Lock lock(*this);
 

data/ext/ValueFactoryManager.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_RUBY_OBJECT_FACTORY_H
 #define ICE_RUBY_OBJECT_FACTORY_H
@@ -71,7 +66,7 @@ public:
     ~ValueFactoryManager();
 
     virtual void add(const Ice::ValueFactoryPtr&, const std::string&);
-    virtual Ice::ValueFactoryPtr find(const std::string&) const;
+    virtual Ice::ValueFactoryPtr find(const std::string&) const ICE_NOEXCEPT;
 
     void addValueFactory(VALUE, const std::string&);
     VALUE findValueFactory(const std::string&) const;

data/ext/extconf.rb

@@ -1,10 +1,9 @@
-# **********************************************************************
 #
-# Copyright (c) 2003-2017 ZeroC, Inc. All rights reserved.
+# Copyright (c) ZeroC, Inc. All rights reserved.
 #
-# **********************************************************************
 
 require "mkmf"
+require "rbconfig"
 
 if RUBY_PLATFORM =~ /mswin|mingw/
     puts "MinGW is not supported with Ice for Ruby."
@@ -32,6 +31,9 @@ end
 #
 if RUBY_PLATFORM =~ /darwin/
     $ARCH_FLAG = "-arch x86_64"
+    # Make sure to use the SDK from Xcode (required for Sierra where old system headers can be used otherwise)
+    RbConfig::MAKEFILE_CONFIG['CC'] = 'xcrun -sdk macosx clang'
+    RbConfig::MAKEFILE_CONFIG['CXX'] = 'xcrun -sdk macosx clang++'
 end
 
 $INCFLAGS << ' -Iice/cpp/include'

data/ext/ice/cpp/include/Ice/Application.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_APPLICATION_H
 #define ICE_APPLICATION_H
@@ -22,133 +17,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:

data/ext/ice/cpp/include/Ice/AsyncResult.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_ASYNC_RESULT_H
 #define ICE_ASYNC_RESULT_H
@@ -23,34 +18,107 @@
 namespace Ice
 {
 
+/**
+ * Represents the result of an asynchronous invocation using the C++98 mapping.
+ * \headerfile Ice/Ice.h
+ */
 class ICE_API AsyncResult : private IceUtil::noncopyable, public Ice::LocalObject
 {
 public:
 
     virtual ~AsyncResult();
 
+    /**
+     * Prevents a queued invocation from being sent or, if the invocation has already been sent,
+     * ignores a reply if the server sends one. cancel is a local operation and has no effect
+     * on the server. A canceled invocation is considered to be completed, meaning isCompleted
+     * returns true, and the result of the invocation is an InvocationCanceledException.
+     */
     virtual void cancel() = 0;
 
+    /**
+     * Allows you to create ordered or hashed collections of pending asynchronous invocations.
+     * @return A unique hash code for this object.
+     */
     virtual Int getHash() const = 0;
 
+    /**
+     * Obtains the communicator that sent the invocation.
+     * @return A reference to the communicator.
+     */
     virtual CommunicatorPtr getCommunicator() const = 0;
+
+    /**
+     * Obtains the connection that was used for the invocation. Note that, for typical asynchronous
+     * proxy invocations, this method returns a nil value because the possibility of automatic retries
+     * means the connection that is currently in use could change unexpectedly. The getConnection
+     * method only returns a non-nil value when the AsyncResult object is obtained by calling
+     * Connection::begin_flushBatchRequests.
+     * @return A reference to the connection.
+     */
     virtual ConnectionPtr getConnection() const = 0;
+
+    /**
+     * Obtains the proxy that was used to call the begin_ method, or nil if the AsyncResult object was
+     * not obtained via an asynchronous proxy invocation.
+     * @return A reference to the proxy.
+     */
     virtual ObjectPrxPtr getProxy() const = 0;
 
+    /**
+     * Obtains the completion status of the invocation.
+     * @return True if, at the time it is called, the result of an invocation is available, indicating
+     * that a call to the end_ method will not block the caller. Otherwise, if the result is not yet
+     * available, the method returns false.
+     */
     virtual bool isCompleted() const = 0;
+
+    /**
+     * Blocks the caller until the result of an invocation becomes available.
+     */
     virtual void waitForCompleted() = 0;
 
+    /**
+     * Obtains the sent status of the invocation.
+     * @return True if, at the time it is called, the request has been written to the local transport
+     * (whether it was initially queued or not). Otherwise, if the request is still queued or an
+     * exception occurred before the request could be sent, this method returns false.
+     */
     virtual bool isSent() const = 0;
+
+    /**
+     * Blocks the calling thread until a request has been written to the client-side transport,
+     * or an exception occurs.
+     */
     virtual void waitForSent() = 0;
 
+    /**
+     * Throws the local exception that caused the invocation to fail. If no exception has occurred yet,
+     * this method does nothing.
+     */
     virtual void throwLocalException() const = 0;
 
+    /**
+     * Determines whether the request was sent synchronously.
+     * @return True if a request was written to the client-side transport without first being queued.
+     * If the request was initially queued, sentSynchronously returns false (independent of whether
+     * the request is still in the queue or has since been written to the client-side transport).
+     */
     virtual bool sentSynchronously() const = 0;
 
+    /**
+     * Obtains the cookie that was passed to the begin_ method.
+     * @return The cookie, or nil if you did not pass a cookie to the begin_ method.
+     */
     virtual LocalObjectPtr getCookie() const = 0;
 
+    /**
+     * Obtains the name of the operation.
+     * @return The operation name.
+     */
     virtual const std::string& getOperation() const = 0;
 
+    /// \cond INTERNAL
     virtual bool _waitForResponse() = 0;
     virtual Ice::InputStream* _startReadParams() = 0;
     virtual void _endReadParams() = 0;
@@ -71,10 +139,13 @@ public:
     typedef IceUtil::Handle<Callback> CallbackPtr;
 
     virtual void _scheduleCallback(const CallbackPtr&) = 0;
+    /// \endcond
 
 protected:
 
+    /// \cond INTERNAL
     static void check(const AsyncResultPtr&, const ::std::string&);
+    /// \endcond
 };
 
 }