zeroc-ice 3.8.2 → 3.8.3

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

@@ -28,7 +28,6 @@ namespace Ice
     /// - managing properties (configuration), retries, logging, instrumentation, and more.
     /// You create a communicator with `Ice::initialize`, and it's usually the first object you create when programming
     /// with Ice. You can create multiple communicators in a single program, but this is not common.
-    /// @see ::initialize(int&, const char*[])
     /// @see ::initialize(InitializationData)
     /// @headerfile Ice/Ice.h
     class ICE_API Communicator final : public std::enable_shared_from_this<Communicator>
@@ -43,8 +42,8 @@ namespace Ice
         void destroy() noexcept;
 
         /// Destroys this communicator asynchronously.
-        /// @param completed The callback to call when the destruction is complete. This function must not throw any
-        /// exception.
+        /// @param completed If not @c nullptr, this callback is called when the destruction is complete. It must not
+        /// throw any exception.
         /// @remark This function starts a thread to call #destroy and @p completed unless you call this function on a
         /// communicator that has already been destroyed, in which case @p completed is called by the current thread.
         /// @see #destroy
@@ -65,8 +64,8 @@ namespace Ice
         /// Waits until this communicator is shut down.
         /// @param completed The callback to call when the shutdown is complete. This function must not throw any
         /// exception.
-        /// @remark If you call this function on a communicator that has already been shut down, the callback is called
-        /// immediately by the current thread.
+        /// @remark The callback is usually called by a dedicated background thread. It can also be called by the
+        /// current thread when the shutdown has already completed.
         /// @see #shutdown
         void waitForShutdownAsync(std::function<void()> completed) noexcept;
 
@@ -80,6 +79,7 @@ namespace Ice
         /// @param str The stringified proxy to convert into a proxy.
         /// @return The proxy, or nullopt if @p str is an empty string.
         /// @throws ParseException Thrown when @p str is not a valid proxy string.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #proxyToString
         template<typename Prx = ObjectPrx, std::enable_if_t<std::is_base_of_v<ObjectPrx, Prx>, bool> = true>
         std::optional<Prx> stringToProxy(std::string_view str) const
@@ -107,6 +107,8 @@ namespace Ice
         /// @tparam Prx The type of the proxy to return.
         /// @param property The base property name.
         /// @return The proxy, or nullopt if the property is not set.
+        /// @throws ParseException Thrown when the property value is not a valid proxy string.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         template<typename Prx = ObjectPrx, std::enable_if_t<std::is_base_of_v<ObjectPrx, Prx>, bool> = true>
         std::optional<Prx> propertyToProxy(std::string_view property) const
         {
@@ -139,6 +141,7 @@ namespace Ice
         /// @param name The object adapter name.
         /// @param serverAuthenticationOptions The SSL options for server connections.
         /// @return The new object adapter.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #createObjectAdapterWithEndpoints
         /// @see ObjectAdapter
         /// @see Properties
@@ -156,6 +159,7 @@ namespace Ice
         /// @param endpoints The endpoints of the object adapter.
         /// @param serverAuthenticationOptions The SSL options for server connections.
         /// @return The new object adapter.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #createObjectAdapter
         /// @see Properties
         /// @see SSL::OpenSSLServerAuthenticationOptions
@@ -171,6 +175,7 @@ namespace Ice
         /// @param name The object adapter name.
         /// @param rtr The router.
         /// @return The new object adapter.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #createObjectAdapter
         /// @see Properties
         ObjectAdapterPtr createObjectAdapterWithRouter(std::string name, RouterPrx rtr);
@@ -186,6 +191,7 @@ namespace Ice
         /// Sets the object adapter that will be associated with new outgoing connections created by this
         /// communicator. This function has no effect on existing outgoing connections, or on incoming connections.
         /// @param adapter The object adapter to associate with new outgoing connections.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see Connection::setAdapter
         void setDefaultObjectAdapter(ObjectAdapterPtr adapter);
 
@@ -223,6 +229,7 @@ namespace Ice
         /// Sets the default router of this communicator. All newly created proxies will use this default router. This
         /// function has no effect on existing proxies.
         /// @param rtr The new default router. Use `nullopt` to remove the default router.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #getDefaultRouter
         /// @see #createObjectAdapterWithRouter
         /// @see Router
@@ -230,6 +237,7 @@ namespace Ice
 
         /// Gets the default locator of this communicator.
         /// @return The default locator of this communicator.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #setDefaultLocator
         /// @see Locator
         [[nodiscard]] std::optional<Ice::LocatorPrx> getDefaultLocator() const;
@@ -237,6 +245,7 @@ namespace Ice
         /// Sets the default locator of this communicator. All newly created proxies will use this default locator.
         /// This function has no effect on existing proxies or object adapters.
         /// @param loc The new default locator. Use `nullopt` to remove the default locator.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #getDefaultLocator
         /// @see Locator
         /// @see ObjectAdapter#setLocator
@@ -253,6 +262,7 @@ namespace Ice
         /// are ignored.
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         void flushBatchRequests(CompressBatch compress);
 
         /// Flushes any pending batch requests of this communicator. This means all batch requests invoked on fixed
@@ -260,9 +270,16 @@ namespace Ice
         /// are ignored.
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
-        /// @param exception The exception callback.
-        /// @param sent The sent callback.
+        /// @param exception The exception callback. The Ice runtime never calls this function: errors that occur
+        /// while flushing a connection are ignored.
+        /// @param sent The sent callback. The Ice runtime calls this function when the flush completes for all
+        /// connections; since errors are ignored, a flush that fails on a connection is complete for this connection.
+        /// When the flush completes synchronously, the Ice runtime calls this function from the current thread and
+        /// passes `true` as argument. Otherwise, the Ice runtime calls this function from an Ice thread pool thread
+        /// and passes `false` as argument. If you set InitializationData::executor, the executor determines the
+        /// thread that executes this function in the asynchronous case.
         /// @return A function that can be called to cancel the flush.
+        /// @throws CommunicatorDestroyedException Thrown synchronously when the communicator has been destroyed.
         std::function<void()> flushBatchRequestsAsync(
             CompressBatch compress,
             std::function<void(std::exception_ptr)> exception,
@@ -274,6 +291,7 @@ namespace Ice
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
         /// @return A future that becomes available when all batch requests have been sent.
+        /// @throws CommunicatorDestroyedException Thrown synchronously when the communicator has been destroyed.
         [[nodiscard]] std::future<void> flushBatchRequestsAsync(CompressBatch compress);
 
         /// Adds the Admin object with all its facets to the provided object adapter. If `Ice.Admin.ServerId`
@@ -285,6 +303,7 @@ namespace Ice
         /// @param adminId The identity of the Admin object.
         /// @return A proxy to the main ("") facet of the Admin object.
         /// @throws InitializationException Thrown when this function is called more than once.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #getAdmin
         ObjectPrx createAdmin(const ObjectAdapterPtr& adminAdapter, const Identity& adminId);
 
@@ -302,18 +321,21 @@ namespace Ice
         /// @param servant The servant that implements the new Admin facet.
         /// @param facet The name of the new Admin facet.
         /// @throws AlreadyRegisteredException Thrown when a facet with the same name is already registered.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         void addAdminFacet(ObjectPtr servant, std::string facet);
 
         /// Removes a facet from the Admin object.
         /// @param facet The name of the Admin facet.
         /// @return The servant associated with this Admin facet.
         /// @throws NotRegisteredException Thrown when no facet with the given name is registered.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         ObjectPtr removeAdminFacet(std::string_view facet);
 
         /// Returns a facet of the Admin object.
         /// @tparam T The type of the facet to return.
         /// @param facet The name of the Admin facet.
         /// @return The servant associated with this Admin facet, or null if no facet is registered with the given name.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         template<typename T = Object, std::enable_if_t<std::is_base_of_v<Object, T>, bool> = true>
         std::shared_ptr<T> findAdminFacet(std::string_view facet)
         {
@@ -322,6 +344,7 @@ namespace Ice
 
         /// Returns a map of all facets of the Admin object.
         /// @return A collection containing all the facet names and servants of the Admin object.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         /// @see #findAdminFacet
         FacetMap findAllAdminFacets();
 
@@ -386,7 +409,7 @@ namespace Ice
         CommunicatorHolder& operator=(CommunicatorHolder&& holder) noexcept;
 
         /// Determines whether this holder holds a communicator.
-        /// @return `true` if the holder currently a holds communicator, `false` otherwise.
+        /// @return `true` if the holder currently holds a communicator, `false` otherwise.
         explicit operator bool() const noexcept { return _communicator != nullptr; }
 
         ~CommunicatorHolder();

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

@@ -35,8 +35,8 @@
 #endif
 
 // The Ice version.
-#define ICE_STRING_VERSION "3.8.2" // "A.B.C", with A=major, B=minor, C=patch
-#define ICE_INT_VERSION 30802      // AABBCC, with AA=major, BB=minor, CC=patch
+#define ICE_STRING_VERSION "3.8.3" // "A.B.C", with A=major, B=minor, C=patch
+#define ICE_INT_VERSION 30803      // AABBCC, with AA=major, BB=minor, CC=patch
 #define ICE_SO_VERSION "38"        // "ABC", with A=major, B=minor, C=patch
 
 #if defined(_MSC_VER) && !defined(ICE_BUILDING_SLICE_COMPILERS) // Not using the IceUtil static build

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

@@ -62,7 +62,8 @@ namespace Ice
         /// @remark The response and exception callbacks may be called synchronously (from the calling thread); in
         /// particular, this occurs when you call `close` on a connection that is already closed. The implementation
         /// always calls one of the two callbacks once; it never calls both. If closing the connection takes longer than
-        /// the configured close timeout, the connection is aborted with a CloseTimeoutException.
+        /// the configured close timeout, the connection is aborted with a CloseTimeoutException. The response and
+        /// exception callbacks must not throw any exception.
         virtual void
         close(std::function<void()> response, std::function<void(std::exception_ptr)> exception) noexcept = 0;
 
@@ -74,6 +75,7 @@ namespace Ice
         /// @tparam Prx The type of the proxy to create.
         /// @param id The identity of the target object.
         /// @return A fixed proxy with the provided identity.
+        /// @throws CommunicatorDestroyedException Thrown when the communicator has been destroyed.
         template<typename Prx = ObjectPrx, std::enable_if_t<std::is_base_of_v<ObjectPrx, Prx>, bool> = true>
         [[nodiscard]] Prx createProxy(Identity id) const
         {
@@ -86,6 +88,8 @@ namespace Ice
         /// The default object adapter of an incoming connection is the object adapter that created this connection;
         /// the default object adapter of an outgoing connection is the communicator's default object adapter.
         /// @param adapter The object adapter to associate with this connection.
+        /// @throws std::logic_error Thrown when this connection is an incoming connection: you can only call this
+        /// function on outgoing (client) connections.
         /// @see Communicator::getDefaultObjectAdapter
         /// @see #getAdapter
         virtual void setAdapter(const ObjectAdapterPtr& adapter) = 0;
@@ -103,15 +107,25 @@ namespace Ice
         /// This means all batch requests invoked on fixed proxies associated with the connection.
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
+        /// @throws LocalException Thrown when the flush fails. For example, this function throws
+        /// CommunicatorDestroyedException when the communicator has been destroyed.
         void flushBatchRequests(CompressBatch compress);
 
         /// Flushes any pending batch requests for this connection.
         /// This means all batch requests invoked on fixed proxies associated with the connection.
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
-        /// @param exception The exception callback.
-        /// @param sent The sent callback.
+        /// @param exception The exception callback. The Ice runtime calls this function from an Ice thread pool
+        /// thread. If you set InitializationData::executor, the executor determines the thread that executes this
+        /// function.
+        /// @param sent The sent callback. The Ice runtime calls this function when the batch requests are accepted by
+        /// the transport. When the batch requests are accepted synchronously, the Ice runtime calls this function from
+        /// the current thread and passes `true` as argument. When the batch requests are accepted asynchronously, the
+        /// Ice runtime calls this function from an Ice thread pool thread and passes `false` as argument. If you set
+        /// InitializationData::executor, the executor determines the thread that executes this function in the
+        /// asynchronous case.
         /// @return A function that can be called to cancel the invocation locally.
+        /// @throws CommunicatorDestroyedException Thrown synchronously when the communicator has been destroyed.
         virtual std::function<void()> flushBatchRequestsAsync(
             CompressBatch compress,
             std::function<void(std::exception_ptr)> exception,
@@ -122,6 +136,7 @@ namespace Ice
         /// @param compress Specifies whether or not the queued batch requests should be compressed before being sent
         /// over the wire.
         /// @return A future that becomes available when the flush completes.
+        /// @throws CommunicatorDestroyedException Thrown synchronously when the communicator has been destroyed.
         [[nodiscard]] std::future<void> flushBatchRequestsAsync(CompressBatch compress);
 
         /// Sets a close callback on the connection. The callback is called by the connection when it's closed.
@@ -150,10 +165,10 @@ namespace Ice
         /// @param sndSize The size of the send buffer.
         virtual void setBufferSize(int rcvSize, int sndSize) = 0;
 
-        /// Throws an exception that provides the reason for the closure of this connection. For example, this function
-        /// throws CloseConnectionException when the connection was closed gracefully by the peer; it throws
-        /// ConnectionAbortedException when the connection is aborted with #abort. This function does nothing if the
-        /// connection is not yet closed.
+        /// Throws the exception that provides the reason for the closure of this connection. Does nothing if the
+        /// connection is not yet closing or closed.
+        /// @throws CloseConnectionException Thrown when the connection was closed gracefully by the peer.
+        /// @throws ConnectionAbortedException Thrown when the connection was aborted, for example with #abort.
         virtual void throwException() const = 0;
 
     protected:
@@ -341,7 +356,8 @@ namespace Ice
         WSConnectionInfo(const WSConnectionInfo&) = delete;
         WSConnectionInfo& operator=(const WSConnectionInfo&) = delete;
 
-        /// The headers from the HTTP upgrade request.
+        /// The HTTP headers from the WebSocket upgrade handshake: the request headers for an incoming connection, and
+        /// the response headers for an outgoing connection.
         const HeaderDict headers;
 
         /// @private

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

@@ -27,7 +27,7 @@ namespace Ice
 
         /// Constructs a CtrlCHandler. Only one instance of this class can exist in a program at any point in time.
         /// 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
+        /// that waits for these signals using sigwait. On Windows, this constructor calls SetConsoleCtrlHandler to
         /// register a handler routine that calls the supplied callback function.
         /// @param cb The callback function to invoke when a signal is received.
         explicit CtrlCHandler(CtrlCHandlerCallback cb);

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

@@ -8,7 +8,7 @@
 
 namespace IceInternal
 {
-    /// Demangles a C++ type type.
+    /// Demangles a C++ type name.
     /// @param name The possibly mangled type name, as returned by typeid().name().
     /// @return The demangled name.
     ICE_API std::string demangle(const char* name);

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

@@ -123,7 +123,7 @@ namespace Ice
         }
     };
 
-    /// Provides access to a TCP endpoint information.
+    /// Provides access to a TCP endpoint's information.
     /// @see Endpoint
     /// @headerfile Ice/Ice.h
     class ICE_API TCPEndpointInfo final : public IPEndpointInfo
@@ -155,7 +155,7 @@ namespace Ice
         const bool _secure;
     };
 
-    /// Provides access to a UDP endpoint information.
+    /// Provides access to a UDP endpoint's information.
     /// @see Endpoint
     /// @headerfile Ice/Ice.h
     class ICE_API UDPEndpointInfo final : public IPEndpointInfo
@@ -189,7 +189,7 @@ namespace Ice
         }
     };
 
-    /// Provides access to a WebSocket endpoint information.
+    /// Provides access to a WebSocket endpoint's information.
     /// @headerfile Ice/Ice.h
     class ICE_API WSEndpointInfo final : public EndpointInfo
     {
@@ -209,7 +209,7 @@ namespace Ice
         }
     };
 
-    /// Provides access to an IAP endpoint information.
+    /// Provides access to an IAP endpoint's information.
     /// @headerfile Ice/Ice.h
     class IAPEndpointInfo final : public EndpointInfo
     {

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

@@ -112,13 +112,13 @@ namespace Ice
         return initialize(std::move(initData));
     }
 
-    /// Gets the per-process logger. This logger is used by all communicators that do not have their own specific logger
-    /// configured at the time the communicator is created.
+    /// Gets the per-process logger.
     /// @return The current per-process logger instance.
+    /// @see setProcessLogger
     ICE_API LoggerPtr getProcessLogger();
 
-    /// Sets the per-process logger. This logger is used by all communicators that do not have their own specific logger
-    /// configured at the time the communicator is created.
+    /// Sets the per-process logger. Communicators created after this call use this logger unless a logger is set in
+    /// InitializationData or configured through logger properties such as `Ice.LogFile`.
     /// @param logger The new per-process logger instance.
     ICE_API void setProcessLogger(const LoggerPtr& logger);
 

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

@@ -202,7 +202,7 @@ namespace Ice
         /// @param[out] v A pointer into the internal marshaling buffer representing the start of the encoded
         /// encapsulation.
         /// @param[out] sz The number of bytes in the encapsulation.
-        /// @return encoding The encapsulation's encoding version.
+        /// @return The encapsulation's encoding version.
         EncodingVersion readEncapsulation(const std::byte*& v, std::int32_t& sz);
 
         /// Gets the current encoding version.
@@ -270,7 +270,7 @@ namespace Ice
         }
 
         /// Reads and validates a sequence size.
-        /// @param minSize The minimum size required by the sequence type.
+        /// @param minSize The minimum number of bytes required to encode each element of the sequence.
         /// @return The extracted size.
         std::int32_t readAndCheckSeqSize(int minSize);
 
@@ -510,7 +510,7 @@ namespace Ice
         void read(std::vector<std::int32_t>& v);
 
         /// Reads a long from the stream.
-        /// @param[out]v The extracted long.
+        /// @param[out] v The extracted long.
         void read(std::int64_t& v);
 
         /// Reads a sequence of longs from the stream.
@@ -610,7 +610,7 @@ namespace Ice
 
         /// Reads a user exception from the stream and throws it.
         /// @param factory The factory function that creates the exception instance. When null, the exception is created
-        /// using helper functions generated by the Slice compiler.
+        /// by this stream's Slice loader.
         /// @throws UserException The user exception that was unmarshaled.
         void throwException(UserExceptionFactory factory = nullptr);
 
@@ -625,7 +625,7 @@ namespace Ice
         /// @param size The number of bytes to skip.
         void skip(size_type size)
         {
-            if (i + size > b.end())
+            if (size > static_cast<size_type>(b.end() - i))
             {
                 throwUnmarshalOutOfBoundsException(__FILE__, __LINE__);
             }

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

@@ -37,7 +37,7 @@ namespace Ice::Instrumentation
     class ObserverUpdater;
     class CommunicatorObserver;
 
-    /// A shared point to an Observer.
+    /// A shared pointer to an Observer.
     using ObserverPtr = std::shared_ptr<Observer>;
 
     /// A shared pointer to a ThreadObserver.
@@ -103,6 +103,9 @@ namespace Ice::Instrumentation
     };
 
     /// The base class for Ice observers.
+    /// @remark The Ice runtime calls observers from contexts where exceptions cannot be handled, such as destructors
+    /// and `noexcept` functions. Implementations of this interface and its derived interfaces must not throw
+    /// exceptions: a thrown exception can terminate the process.
     /// @headerfile Ice/Ice.h
     class Observer
     {
@@ -222,14 +225,14 @@ namespace Ice::Instrumentation
     public:
         virtual ~ObserverUpdater() = default;
 
-        /// Updates connection observers associated with each of the Ice connection from the communicator and its object
-        /// adapters.
+        /// Updates connection observers associated with each of the Ice connections from the communicator and its
+        /// object adapters.
         /// When called, this method goes through all the connections and for each connection
         /// CommunicatorObserver::getConnectionObserver is called. The implementation of getConnectionObserver
         /// has the possibility to return an updated observer if necessary.
         virtual void updateConnectionObservers() = 0;
 
-        /// Updates thread observers associated with each of the Ice thread from the communicator and its object
+        /// Updates thread observers associated with each of the Ice threads from the communicator and its object
         /// adapters. When called, this method goes through all the threads and for each thread
         /// CommunicatorObserver::getThreadObserver is called. The implementation of getThreadObserver has the
         /// possibility to return an updated observer if necessary.
@@ -238,8 +241,11 @@ namespace Ice::Instrumentation
 
     /// The communicator observer interface used by the Ice runtime to obtain and update observers for its observable
     /// objects. This interface should be implemented by add-ins that wish to observe Ice objects in order to collect
-    /// statistics. An instance of this interface can be provided to the Ice run-time through the Ice communicator
+    /// statistics. An instance of this interface can be provided to the Ice runtime through the Ice communicator
     /// initialization data.
+    /// @remark The Ice runtime calls this interface from contexts where exceptions cannot be handled, such as
+    /// `noexcept` functions. An implementation of this interface must not throw exceptions: a thrown exception can
+    /// terminate the process.
     /// @headerfile Ice/Ice.h
     class CommunicatorObserver
     {
@@ -262,7 +268,7 @@ namespace Ice::Instrumentation
         /// @return The observer to instrument the endpoint lookup.
         virtual ObserverPtr getEndpointLookupObserver(const EndpointPtr& endpt) = 0;
 
-        /// Gets an observer for the given connection. The Ice run-time calls this method for each new connection and
+        /// Gets an observer for the given connection. The Ice runtime calls this method for each new connection and
         /// for all the Ice communicator connections when ObserverUpdater::updateConnectionObservers is called.
         /// @param c The connection information.
         /// @param e The connection endpoint.
@@ -305,7 +311,7 @@ namespace Ice::Instrumentation
         virtual DispatchObserverPtr getDispatchObserver(const Current& c, int size) = 0;
 
         /// Sets the observer updater. The Ice runtime calls this method when the communicator is initialized. The
-        /// add-in implementing this interface can use this object to get the Ice run-time to re-obtain observers for
+        /// add-in implementing this interface can use this object to get the Ice runtime to re-obtain observers for
         /// observed objects.
         /// @param updater The observer updater object.
         virtual void setObserverUpdater(const ObserverUpdaterPtr& updater) = 0;

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

@@ -568,15 +568,15 @@ namespace Ice
     class ICE_API AlreadyRegisteredException final : public LocalException
     {
     public:
-        /// Constructs a AlreadyRegisteredException.
+        /// Constructs an AlreadyRegisteredException.
         /// @param file The file where this exception is constructed. This C string is not copied.
         /// @param line The line where this exception is constructed.
         /// @param kindOfObject The kind of object that is already registered.
         /// @param id The ID (or name) of the object that is already registered.
         AlreadyRegisteredException(const char* file, int line, std::string kindOfObject, std::string id);
 
-        /// Gets the kind of object that is already registered: "servant", "facet", "object", "default servant",
-        /// "servant locator", "plugin", "object adapter", "object adapter with router", "replica group".
+        /// Gets the kind of object that is already registered: "servant", "facet", "default servant",
+        /// "servant locator", "plugin", "object adapter", "object adapter with router".
         [[nodiscard]] const std::string& kindOfObject() const noexcept { return *_kindOfObject; }
 
         /// Gets the ID (or name) of the object that is already registered.
@@ -684,7 +684,7 @@ namespace Ice
         [[nodiscard]] const char* ice_id() const noexcept final;
     };
 
-    /// The exception that is thrown when communicator initialization fails.
+    /// The exception that is thrown when a failure occurs during initialization.
     /// @headerfile Ice/Ice.h
     class ICE_API InitializationException final : public LocalException
     {
@@ -718,7 +718,7 @@ namespace Ice
         /// Constructs a NoEndpointException.
         /// @param file The file where this exception is constructed. This C string is not copied.
         /// @param line The line where this exception is constructed.
-        /// @param proxy The proxy used to create the message return by what().
+        /// @param proxy The proxy used to create the message returned by what().
         NoEndpointException(const char* file, int line, const ObjectPrx& proxy);
 
         [[nodiscard]] const char* ice_id() const noexcept final;

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

@@ -17,6 +17,9 @@ namespace Ice
 
     /// Represents Ice's abstraction for logging and tracing. Applications can provide their own logger by
     /// implementing this abstraction and setting a logger on the communicator.
+    /// @remark The Ice runtime calls #print, #trace, #warning and #error from contexts where exceptions cannot be
+    /// handled, such as destructors and `noexcept` functions. Implementations of these functions must not throw
+    /// exceptions: a thrown exception can terminate the process.
     /// @see InitializationData
     /// @headerfile Ice/Ice.h
     class ICE_API Logger
@@ -31,20 +34,24 @@ namespace Ice
         /// Prints a message.
         /// The message is printed literally, without any decorations such as executable name or timestamp.
         /// @param message The message to log.
+        /// @remark An implementation of this function must not throw exceptions.
         virtual void print(const std::string& message) = 0;
 
         /// Logs a trace message.
         /// @param category The trace category.
         /// @param message The trace message to log.
+        /// @remark An implementation of this function must not throw exceptions.
         virtual void trace(const std::string& category, const std::string& message) = 0;
 
         /// Logs a warning message.
         /// @param message The warning message to log.
+        /// @remark An implementation of this function must not throw exceptions.
         /// @see #error
         virtual void warning(const std::string& message) = 0;
 
         /// Logs an error message.
         /// @param message The error message to log.
+        /// @remark An implementation of this function must not throw exceptions.
         /// @see #warning
         virtual void error(const std::string& message) = 0;
 

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

@@ -94,7 +94,7 @@ namespace Ice
 
         ~LoggerOutput() { flush(); }
 
-        /// Flushes the colleted output to the logger method.
+        /// Flushes the collected output to the logger method.
         void flush()
         {
             std::string s = _stream().str();

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

@@ -36,12 +36,12 @@ namespace Ice
         /// not throw any exception and any @p sendResponse wrapper must not throw any exception. @p sendResponse can be
         /// called by the thread that called dispatch (the "dispatch thread") or by another thread. The implementation
         /// must call @p sendResponse exactly once or throw an exception.
-        /// @remark Calling @p sendResponse can be thought as returning the outgoing response. Just like when you return
-        /// a value from a remote operation, you can only return it once and you don't know if the client receives this
-        /// value. In practice, the Ice-provided @p sendResponse attempts to send the response to the client
-        /// synchronously, but may send it asynchronously. It can also silently fail to send the response back to the
-        /// client. This function is the main building block for the Ice dispatch pipeline. The implementation provided
-        /// by the base class (Object) dispatches incoming requests to the four `Object` operations (`ice_isA`,
+        /// @remark Calling @p sendResponse can be thought of as returning the outgoing response. Just like when you
+        /// return a value from a remote operation, you can only return it once and you don't know if the client
+        /// receives this value. In practice, the Ice-provided @p sendResponse attempts to send the response to the
+        /// client synchronously, but may send it asynchronously. It can also silently fail to send the response back to
+        /// the client. This function is the main building block for the Ice dispatch pipeline. The implementation
+        /// provided by the base class (Object) dispatches incoming requests to the four `Object` operations (`ice_isA`,
         /// `ice_ping`, `ice_ids` and `ice_id`), and throws OperationNotExistException for all other operations. This
         /// base implementation is trivial and should be overridden and fully replaced by all derived classes.
         virtual void dispatch(IncomingRequest& request, std::function<void(OutgoingResponse)> sendResponse);
@@ -93,7 +93,8 @@ namespace Ice
     public:
         /// Dispatches an incoming request.
         /// @param inEncaps An encapsulation containing the encoded in-parameters for the operation.
-        /// @param outEncaps An encapsulation containing the encoded result for the operation.
+        /// @param outEncaps An encapsulation containing the encoded result for the operation. You can leave it empty
+        /// when the operation returns no results; the Ice runtime then marshals an empty encapsulation.
         /// @param current The Current object of the incoming request.
         /// @return `true` if the dispatch completes successfully, `false` if the dispatch completes with a user
         /// exception encoded in @p outEncaps.
@@ -133,7 +134,8 @@ namespace Ice
         /// @param response The response callback. It accepts:
         /// - `returnValue` `true` if the operation completed successfully, `false` if it completed with a user
         ///   exception encoded in @p outEncaps.
-        /// - `outEncaps` An encapsulation containing the encoded result.
+        /// - `outEncaps` An encapsulation containing the encoded result. You can pass an empty byte sequence when
+        ///   the operation returns no results; the Ice runtime then marshals an empty encapsulation.
         /// @param exception The exception callback.
         /// @param current The Current object of the incoming request.
         virtual void ice_invokeAsync(

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

@@ -290,7 +290,7 @@ namespace Ice
         virtual void setLocator(std::optional<LocatorPrx> loc) = 0;
 
         /// Gets the Ice locator used by this object adapter.
-        /// @return The locator used by this object adapter, or nullptr if no locator is used by this object adapter.
+        /// @return The locator used by this object adapter, or nullopt if no locator is used by this object adapter.
         [[nodiscard]] virtual std::optional<LocatorPrx> getLocator() const noexcept = 0;
 
         /// Gets the set of endpoints configured on this object adapter.

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

@@ -25,7 +25,6 @@
 #    pragma warning(disable : 4251) // class ... needs to have dll-interface to be used by clients of class ...
 #elif defined(__clang__)
 #    pragma clang diagnostic push
-// See #2747
 #    pragma clang diagnostic ignored "-Wshadow-uncaptured-local"
 #    pragma clang diagnostic ignored "-Wweak-vtables"
 #endif
@@ -143,7 +142,7 @@ namespace IceInternal
     //
     // Base class for proxy based invocations. This class handles the
     // retry for proxy invocations. It also ensures the child observer is
-    // correct notified of failures and make sure the retry task is
+    // correctly notified of failures and makes sure the retry task is
     // correctly canceled when the invocation completes.
     //
     class ICE_API ProxyOutgoingAsyncBase : public OutgoingAsyncBase, public TimerTask
@@ -155,7 +154,11 @@ namespace IceInternal
         bool exception(std::exception_ptr) override;
 
         void retryException();
+
+        // Retries the invocation; when the retry attempt fails, completes the invocation with the exception. This
+        // function never throws.
         void retry();
+
         void abort(std::exception_ptr);
 
         std::shared_ptr<ProxyOutgoingAsyncBase> shared_from_this()