zeroc-ice 3.8.1 → 3.8.3

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()

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

@@ -64,7 +64,8 @@ namespace Ice
         /// Gets the exception ID of the response.
         /// @return The exception ID of the response. It's empty when #replyStatus is ReplyStatus::Ok or
         /// ReplyStatus::UserException. Otherwise, this ID is the value returned by LocalException#ice_id. For other
-        /// exceptions, this ID is the value returned by `std::exception::what()`.
+        /// exceptions, this ID is the demangled name of the exception type, or `"unknown"` when the dispatch throws a
+        /// value that is not derived from `std::exception`.
         [[nodiscard]] const std::string& exceptionId() const noexcept { return _exceptionId; }
 
         /// Gets the full details of the exception marshaled into the response.

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

@@ -42,8 +42,9 @@ namespace Ice
         /// Constructs an OutputStream.
         /// @param encoding The encoding version to use.
         /// @param format The class format to use.
-        /// @param stringConverter The narrow string converter to use.
-        /// @param wstringConverter The wide string converter to use.
+        /// @param stringConverter The narrow string converter to use. @c nullptr means do not perform any conversion.
+        /// @param wstringConverter The wide string converter to use. @c nullptr is equivalent to the process wstring
+        /// converter.
         OutputStream(
             EncodingVersion encoding = Encoding_1_1,
             FormatType format = FormatType::CompactFormat,
@@ -66,8 +67,9 @@ namespace Ice
         /// stream will reallocate if the size of the marshaled data exceeds the application's buffer.
         /// @param encoding The encoding version to use.
         /// @param format The class format to use.
-        /// @param stringConverter The narrow string converter to use.
-        /// @param wstringConverter The wide string converter to use.
+        /// @param stringConverter The narrow string converter to use. @c nullptr means do not perform any conversion.
+        /// @param wstringConverter The wide string converter to use. @c nullptr is equivalent to the process wstring
+        /// converter.
         OutputStream(
             std::pair<const std::byte*, const std::byte*> bytes,
             EncodingVersion encoding = Encoding_1_1,
@@ -120,8 +122,8 @@ namespace Ice
         void resize(Container::size_type sz) { b.resize(sz); }
 
         /// Marks the start of a class instance.
-        /// @param data Contains the marshaled form of unknown slices from the class instance. If not nullptr, these
-        /// slices will be marshaled with the instance.
+        /// @param data Contains the marshaled form of unknown slices from the class instance. These slices are
+        /// marshaled with the instance only when this stream uses the sliced format; otherwise they are ignored.
         void startValue(const SlicedDataPtr& data)
         {
             assert(_currentEncaps && _currentEncaps->encoder);
@@ -149,7 +151,8 @@ namespace Ice
             _currentEncaps->encoder->endInstance();
         }
 
-        /// Writes the start of an encapsulation using the default encoding version and class encoding format.
+        /// Writes the start of an encapsulation. A nested encapsulation uses the encoding version and class format of
+        /// the enclosing encapsulation; a top-level encapsulation uses the stream's encoding version and class format.
         void startEncapsulation();
 
         /// Writes the start of an encapsulation using the specified encoding version and class encoding format.
@@ -260,7 +263,7 @@ namespace Ice
             {
                 Container::size_type position = b.size();
                 resize(position + sz);
-                memcpy(&b[position], &v[0], sz);
+                memcpy(&b[position], v, sz);
             }
         }
 
@@ -281,7 +284,7 @@ namespace Ice
         /// @tparam Te The types of the values in the tuple, starting at index @p I.
         /// @param tuple The tuple to marshal.
         // Declared here because the actual definition below breaks doxygen 1.13.2.
-        template<size_t I = 0, typename... Te >> writeAll(std::tuple<Te...> tuple);
+        template<size_t I = 0, typename... Te> void writeAll(std::tuple<Te...> tuple);
 #endif
 
         /// Writes a value (single element list) to the stream.
@@ -399,7 +402,7 @@ namespace Ice
             }
             else
             {
-                write(&v[0], &v[0] + v.size());
+                write(v.data(), v.data() + v.size());
             }
         }
 
@@ -697,7 +700,7 @@ namespace Ice
         }
 
         StringConverterPtr _stringConverter;
-        WstringConverterPtr _wstringConverter;
+        WstringConverterPtr _wstringConverter; // never null
 
         //
         // The public stream API needs to attach data to a stream.

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

@@ -25,7 +25,7 @@ namespace Ice
                                           const StringSeq& args);
 
     /// Represents a plug-in factory.
-    /// @see InitializeData::pluginFactories
+    /// @see InitializationData::pluginFactories
     struct PluginFactory
     {
         /// The default and preferred name for plug-ins created by this factory.

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

@@ -188,7 +188,7 @@ namespace Ice
         /// Gets a property as a list of strings. The strings must be separated by whitespace or comma. The strings in
         /// the list can contain whitespace and commas if they are enclosed in single or double quotes. If quotes are
         /// mismatched, an empty list is returned. Within single quotes or double quotes, you can escape the quote in
-        /// question with a backslash, e.g. O'Reilly can be written as O'Reilly, "O'Reilly" or 'O\'Reilly'.
+        /// question with a backslash, e.g. O'Reilly can be written as "O'Reilly" or 'O\'Reilly'.
         /// @param key The property key.
         /// @return The property value interpreted as a list of strings, or an empty list if the property is not set.
         /// @see #setProperty
@@ -197,7 +197,7 @@ namespace Ice
         /// Gets an Ice property as a list of strings. The strings must be separated by whitespace or comma. The strings
         /// in the list can contain whitespace and commas if they are enclosed in single or double quotes. If quotes are
         /// mismatched, the default list is returned. Within single quotes or double quotes, you can escape the quote
-        /// in question with a backslash, e.g. O'Reilly can be written as O'Reilly, "O'Reilly" or 'O\'Reilly'.
+        /// in question with a backslash, e.g. O'Reilly can be written as "O'Reilly" or 'O\'Reilly'.
         /// @param key The property key.
         /// @return The property value interpreted as a list of strings, or the default value if the property is not
         ///     set.
@@ -208,7 +208,7 @@ namespace Ice
         /// Gets a property as a list of strings. The strings must be separated by whitespace or comma. The strings in
         /// the list can contain whitespace and commas if they are enclosed in single or double quotes. If quotes are
         /// mismatched, the default list is returned. Within single quotes or double quotes, you can escape the quote
-        /// in question with a backslash, e.g. O'Reilly can be written as O'Reilly, "O'Reilly" or 'O\'Reilly'.
+        /// in question with a backslash, e.g. O'Reilly can be written as "O'Reilly" or 'O\'Reilly'.
         /// @param key The property key.
         /// @param value The default value to use if the property is not set.
         /// @return The property value interpreted as a list of strings, or the default value if the property is not

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

@@ -14,10 +14,13 @@
 #include "RequestHandlerF.h"
 
 #include <chrono>
+#include <cstdint>
 #include <functional>
 #include <future>
 #include <iosfwd>
+#include <limits>
 #include <optional>
+#include <stdexcept>
 #include <string_view>
 #include <type_traits>
 
@@ -144,7 +147,8 @@ namespace Ice
         }
 
         /// Creates a proxy that is identical to this proxy, except for the invocation timeout.
-        /// @param timeout The new invocation timeout (in milliseconds).
+        /// @param timeout The new invocation timeout (in milliseconds). Zero or any negative value means infinite
+        /// and is normalized to -1.
         /// @return A proxy with the new timeout.
         [[nodiscard]] Prx ice_invocationTimeout(int timeout) const
         {
@@ -152,13 +156,27 @@ namespace Ice
         }
 
         /// Creates a proxy that is identical to this proxy, except for the invocation timeout.
-        /// @param timeout The new invocation timeout.
+        /// @param timeout The new invocation timeout. Zero or any negative duration means infinite and is
+        /// normalized to -1 millisecond; a duration that is not a whole number of milliseconds is rounded up to the
+        /// next whole number of milliseconds.
         /// @return A proxy with the new timeout.
+        /// @throws std::invalid_argument Thrown when @p timeout is greater than
+        /// `std::numeric_limits<std::int32_t>::max()` milliseconds.
         template<class Rep, class Period>
         [[nodiscard]] Prx ice_invocationTimeout(const std::chrono::duration<Rep, Period>& timeout) const
         {
-            return fromReference(
-                asPrx()._invocationTimeout(std::chrono::duration_cast<std::chrono::milliseconds>(timeout)));
+            if (timeout <= std::chrono::duration<Rep, Period>::zero())
+            {
+                return fromReference(asPrx()._invocationTimeout(std::chrono::milliseconds(-1)));
+            }
+            // Compare in a double-based representation that cannot overflow. The limit is a whole number of
+            // milliseconds, so a timeout that passes this check still fits after rounding up.
+            // The extra parentheses prevent the expansion of the max macro from Windows headers.
+            if (timeout > std::chrono::duration<double, std::milli>{(std::numeric_limits<std::int32_t>::max)()})
+            {
+                throw std::invalid_argument("the invocation timeout cannot be greater than 2147483647 milliseconds");
+            }
+            return fromReference(asPrx()._invocationTimeout(std::chrono::ceil<std::chrono::milliseconds>(timeout)));
         }
 
         /// Creates a proxy that is identical to this proxy, except for the locator.
@@ -170,7 +188,8 @@ namespace Ice
         }
 
         /// Creates a proxy that is identical to this proxy, except for the locator cache timeout.
-        /// @param timeout The new locator cache timeout (in seconds).
+        /// @param timeout The new locator cache timeout (in seconds). Any negative value means infinite and is
+        /// normalized to -1.
         /// @return A proxy with the new timeout.
         [[nodiscard]] Prx ice_locatorCacheTimeout(int timeout) const
         {
@@ -178,13 +197,27 @@ namespace Ice
         }
 
         /// Creates a proxy that is identical to this proxy, except for the locator cache timeout.
-        /// @param timeout The new locator cache timeout.
+        /// @param timeout The new locator cache timeout. Any negative duration means infinite and is normalized to
+        /// -1 second; a duration that is not a whole number of seconds is rounded up to the next whole number of
+        /// seconds.
         /// @return A proxy with the new timeout.
+        /// @throws std::invalid_argument Thrown when @p timeout is greater than
+        /// `std::numeric_limits<std::int32_t>::max()` seconds.
         template<class Rep, class Period>
         [[nodiscard]] Prx ice_locatorCacheTimeout(const std::chrono::duration<Rep, Period>& timeout) const
         {
-            return fromReference(
-                asPrx()._locatorCacheTimeout(std::chrono::duration_cast<std::chrono::seconds>(timeout)));
+            if (timeout < std::chrono::duration<Rep, Period>::zero())
+            {
+                return fromReference(asPrx()._locatorCacheTimeout(std::chrono::seconds(-1)));
+            }
+            // Compare in a double-based representation that cannot overflow. The limit is a whole number of
+            // seconds, so a timeout that passes this check still fits after rounding up.
+            // The extra parentheses prevent the expansion of the max macro from Windows headers.
+            if (timeout > std::chrono::duration<double>{(std::numeric_limits<std::int32_t>::max)()})
+            {
+                throw std::invalid_argument("the locator cache timeout cannot be greater than 2147483647 seconds");
+            }
+            return fromReference(asPrx()._locatorCacheTimeout(std::chrono::ceil<std::chrono::seconds>(timeout)));
         }
 
         /// Creates a proxy that is identical to this proxy, but uses oneway invocations.
@@ -266,11 +299,19 @@ namespace Ice
 
         /// Tests whether this object supports a specific Slice interface.
         /// @param typeId The type ID of the Slice interface to test against.
-        /// @param response The response callback. It accepts:
+        /// @param response The response 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.
+        /// It accepts:
         /// - `true` if the target object implements the Slice interface specified by @p typeId or implements a
         /// derived interface, `false` otherwise.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param ex 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 request is accepted by the
+        /// transport. When the request is accepted synchronously, the Ice runtime calls this function from the current
+        /// thread and passes `true` as argument. When the request is 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.
         /// @param context The request context.
         /// @return A function that can be called to cancel the invocation locally.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
@@ -299,11 +340,22 @@ namespace Ice
         void ice_ping(const Ice::Context& context = Ice::noExplicitContext) const;
 
         /// Tests whether the target object of this proxy can be reached.
-        /// @param response The response callback.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param response The response 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 ex 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 request is accepted by the
+        /// transport. When the request is accepted synchronously, the Ice runtime calls this function from the current
+        /// thread and passes `true` as argument. When the request is 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.
         /// @param context The request context.
         /// @return A function that can be called to cancel the invocation locally.
+        /// @remark When this proxy is a oneway or datagram proxy, the Ice runtime does not call the response
+        /// callback: a successful invocation completes with the sent callback. When this proxy is a batch proxy, this
+        /// function only adds the request to the batch: the Ice runtime calls none of the callbacks, and the request
+        /// is sent later, by a flush.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
         std::function<void()> ice_pingAsync(
             std::function<void()> response,
@@ -325,10 +377,18 @@ namespace Ice
         [[nodiscard]] std::vector<std::string> ice_ids(const Ice::Context& context = Ice::noExplicitContext) const;
 
         /// Gets the Slice interfaces supported by this object as a list of Slice type IDs.
-        /// @param response The response callback. It accepts:
+        /// @param response The response 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.
+        /// It accepts:
         /// - The Slice type IDs of the interfaces supported by this object, in alphabetical order.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param ex 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 request is accepted by the
+        /// transport. When the request is accepted synchronously, the Ice runtime calls this function from the current
+        /// thread and passes `true` as argument. When the request is 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.
         /// @param context The request context.
         /// @return A function that can be called to cancel the invocation locally.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
@@ -356,10 +416,18 @@ namespace Ice
         [[nodiscard]] std::string ice_id(const Ice::Context& context = Ice::noExplicitContext) const;
 
         /// Gets the type ID of the most-derived Slice interface supported by this object.
-        /// @param response The response callback. It accepts:
+        /// @param response The response 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.
+        /// It accepts:
         /// - The type ID of the most-derived interface.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param ex 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 request is accepted by the
+        /// transport. When the request is accepted synchronously, the Ice runtime calls this function from the current
+        /// thread and passes `true` as argument. When the request is 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.
         /// @param context The request context.
         /// @return A function that can be called to cancel the invocation locally.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
@@ -381,10 +449,14 @@ namespace Ice
         /// Invokes an operation.
         /// @param operation The name of the operation to invoke.
         /// @param mode The operation mode (normal or idempotent).
-        /// @param inParams An encapsulation containing the encoded in-parameters for the operation.
+        /// @param inParams An encapsulation containing the encoded in-parameters for the operation. You can pass an
+        /// empty byte sequence when the operation takes no in-parameters; the Ice runtime then marshals an empty
+        /// encapsulation.
         /// @param outParams An encapsulation containing the encoded result.
         /// @param context The request context.
         /// @return `true` if the operation completed successfully, `false` if it completed with a user exception.
+        /// @remark When this proxy is a oneway, datagram, or batch proxy, this function returns `true` and an empty
+        /// @p outParams as soon as the request is accepted by the transport or added to the batch.
         bool ice_invoke(
             std::string_view operation,
             Ice::OperationMode mode,
@@ -395,12 +467,16 @@ namespace Ice
         /// Invokes an operation asynchronously.
         /// @param operation The name of the operation to invoke.
         /// @param mode The operation mode (normal or idempotent).
-        /// @param inParams An encapsulation containing the encoded in-parameters for the operation.
+        /// @param inParams An encapsulation containing the encoded in-parameters for the operation. You can pass an
+        /// empty byte sequence when the operation takes no in-parameters; the Ice runtime then marshals an empty
+        /// encapsulation.
         /// @param context The request context.
         /// @return A future that becomes available when the invocation completes. This future holds:
         /// - `returnValue` `true` if the operation completed successfully, `false` if it completed with a user
         ///    exception.
         /// - `outParams` An encapsulation containing the encoded result.
+        /// @remark When this proxy is a oneway, datagram, or batch proxy, the future completes with `returnValue`
+        /// `true` and an empty `outParams` as soon as the request is accepted by the transport or added to the batch.
         [[nodiscard]] std::future<std::tuple<bool, std::vector<std::byte>>> ice_invokeAsync(
             std::string_view operation,
             Ice::OperationMode mode,
@@ -410,15 +486,29 @@ namespace Ice
         /// Invokes an operation asynchronously.
         /// @param operation The name of the operation to invoke.
         /// @param mode The operation mode (normal or idempotent).
-        /// @param inParams An encapsulation containing the encoded in-parameters for the operation.
-        /// @param response The response callback. It accepts:
+        /// @param inParams An encapsulation containing the encoded in-parameters for the operation. You can pass an
+        /// empty byte sequence when the operation takes no in-parameters; the Ice runtime then marshals an empty
+        /// encapsulation.
+        /// @param response The response 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.
+        /// It accepts:
         /// - `returnValue` `true` if the operation completed successfully, `false` if it completed with a user
         ///    exception.
         /// - `outParams` An encapsulation containing the encoded result.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param ex 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 request is accepted by the
+        /// transport. When the request is accepted synchronously, the Ice runtime calls this function from the current
+        /// thread and passes `true` as argument. When the request is 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.
         /// @param context The request context.
         /// @return A function that can be called to cancel the invocation locally.
+        /// @remark When this proxy is a oneway or datagram proxy, the Ice runtime does not call the response
+        /// callback: a successful invocation completes with the sent callback. When this proxy is a batch proxy, this
+        /// function only adds the request to the batch: the Ice runtime calls none of the callbacks, and the request
+        /// is sent later, by a flush.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
         std::function<void()> ice_invokeAsync(
             std::string_view operation,
@@ -432,10 +522,14 @@ namespace Ice
         /// Invokes an operation.
         /// @param operation The name of the operation to invoke.
         /// @param mode The operation mode (normal or idempotent).
-        /// @param inParams An encapsulation containing the encoded in-parameters for the operation.
+        /// @param inParams An encapsulation containing the encoded in-parameters for the operation. You can pass an
+        /// empty byte sequence when the operation takes no in-parameters; the Ice runtime then marshals an empty
+        /// encapsulation.
         /// @param outParams An encapsulation containing the encoded result.
         /// @param context The request context.
         /// @return `true` if the operation completed successfully, `false` if it completed with a user exception.
+        /// @remark When this proxy is a oneway, datagram, or batch proxy, this function returns `true` and an empty
+        /// @p outParams as soon as the request is accepted by the transport or added to the batch.
         bool ice_invoke(
             std::string_view operation,
             Ice::OperationMode mode,
@@ -446,12 +540,16 @@ namespace Ice
         /// Invokes an operation asynchronously.
         /// @param operation The name of the operation to invoke.
         /// @param mode The operation mode (normal or idempotent).
-        /// @param inParams An encapsulation containing the encoded in-parameters for the operation.
+        /// @param inParams An encapsulation containing the encoded in-parameters for the operation. You can pass an
+        /// empty byte sequence when the operation takes no in-parameters; the Ice runtime then marshals an empty
+        /// encapsulation.
         /// @param context The request context.
         /// @return A future that becomes available when the invocation completes. This future holds:
         /// - `returnValue` `true` if the operation completed successfully, `false` if it completed with a user
         ///    exception.
         /// - `outParams` An encapsulation containing the encoded result.
+        /// @remark When this proxy is a oneway, datagram, or batch proxy, the future completes with `returnValue`
+        /// `true` and an empty `outParams` as soon as the request is accepted by the transport or added to the batch.
         [[nodiscard]] std::future<std::tuple<bool, std::vector<std::byte>>> ice_invokeAsync(
             std::string_view operation,
             Ice::OperationMode mode,
@@ -461,15 +559,29 @@ namespace Ice
         /// Invokes an operation asynchronously.
         /// @param operation The name of the operation to invoke.
         /// @param mode The operation mode (normal or idempotent).
-        /// @param inParams An encapsulation containing the encoded in-parameters for the operation.
-        /// @param response The response callback. It accepts:
+        /// @param inParams An encapsulation containing the encoded in-parameters for the operation. You can pass an
+        /// empty byte sequence when the operation takes no in-parameters; the Ice runtime then marshals an empty
+        /// encapsulation.
+        /// @param response The response 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.
+        /// It accepts:
         /// - `returnValue` `true` if the operation completed successfully, `false` if it completed with a user
         ///    exception.
         /// - `outParams` An encapsulation containing the encoded result.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param ex 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 request is accepted by the
+        /// transport. When the request is accepted synchronously, the Ice runtime calls this function from the current
+        /// thread and passes `true` as argument. When the request is 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.
         /// @param context The request context.
         /// @return A function that can be called to cancel the invocation locally.
+        /// @remark When this proxy is a oneway or datagram proxy, the Ice runtime does not call the response
+        /// callback: a successful invocation completes with the sent callback. When this proxy is a batch proxy, this
+        /// function only adds the request to the batch: the Ice runtime calls none of the callbacks, and the request
+        /// is sent later, by a flush.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
         std::function<void()> ice_invokeAsync(
             std::string_view operation,
@@ -480,47 +592,76 @@ namespace Ice
             std::function<void(bool)> sent = nullptr,
             const Ice::Context& context = Ice::noExplicitContext) const;
 
-        /// Gets the connection for this proxy. If the proxy does not yet have an established connection,
-        /// it first attempts to create a connection.
+        /// Gets the connection for this proxy. If the proxy does not yet have an established connection or its
+        /// connection is closed or being closed, it first attempts to create a new connection. For a fixed proxy,
+        /// this function returns the connection this proxy is bound to, even when this connection is closed.
         /// @return The connection for this proxy.
         /// @remark You can call this function to establish a connection or associate the proxy with an existing
         /// connection and ignore the return value.
+        /// @remark When this proxy reaches its target object through collocation optimization (see
+        /// #ice_collocationOptimized), this function returns a null connection: collocated invocations don't use a
+        /// connection.
         Ice::ConnectionPtr ice_getConnection() const; // NOLINT(modernize-use-nodiscard)
 
-        /// Gets the connection for this proxy. If the proxy does not yet have an established connection,
-        /// it first attempts to create a connection.
-        /// @param response The response callback. It accepts:
+        /// Gets the connection for this proxy. If the proxy does not yet have an established connection or its
+        /// connection is closed or being closed, it first attempts to create a new connection. For a fixed proxy,
+        /// this function returns the connection this proxy is bound to, even when this connection is closed.
+        /// @param response The response 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.
+        /// It accepts:
         /// - The connection for this proxy.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param ex 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 never calls this function: no request is sent to get a
+        /// connection.
         /// @return A function that can be called to cancel the invocation locally.
+        /// @remark When this proxy reaches its target object through collocation optimization (see
+        /// #ice_collocationOptimized), the response callback receives a null connection: collocated invocations don't
+        /// use a connection.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
         std::function<void()> ice_getConnectionAsync(
             std::function<void(Ice::ConnectionPtr)> response,
             std::function<void(std::exception_ptr)> ex = nullptr,
             std::function<void(bool)> sent = nullptr) const;
 
-        /// Gets the connection for this proxy. If the proxy does not yet have an established connection,
-        /// it first attempts to create a connection.
-        /// @return A future that becomes available when the invocation completes. This future holds:
+        /// Gets the connection for this proxy. If the proxy does not yet have an established connection or its
+        /// connection is closed or being closed, it first attempts to create a new connection. For a fixed proxy,
+        /// this function returns the connection this proxy is bound to, even when this connection is closed.
+        /// @return A future that becomes available when the connection is established. This future holds:
         /// - The connection for this proxy.
+        /// @remark When this proxy reaches its target object through collocation optimization (see
+        /// #ice_collocationOptimized), the future holds a null connection: collocated invocations don't use a
+        /// connection.
         [[nodiscard]] std::future<Ice::ConnectionPtr> ice_getConnectionAsync() const;
 
         /// @private
         void _iceI_getConnection(const std::shared_ptr<IceInternal::ProxyGetConnection>&) const;
 
-        /// Gets the cached Connection for this proxy. If the proxy does not yet have an established connection, it does
-        /// not attempt to create a connection.
-        /// @return The cached connection for this proxy, or nullptr if the proxy does not have an established
-        /// connection.
+        /// Gets the Connection cached by this proxy. Once this proxy has been associated with a connection
+        /// (typically during its first invocation), it caches this connection and continues using it for subsequent
+        /// invocations, until an invocation on this proxy fails. This function never attempts to establish a
+        /// connection. For a fixed proxy, this function returns the connection this proxy is bound to, even when
+        /// this connection is closed.
+        /// @return The cached connection, or nullptr if this proxy doesn't have a cached connection. The returned
+        /// connection can be closed.
+        /// @remark A proxy with connection caching disabled (see #ice_connectionCached) never caches a connection: for
+        /// such a proxy, this function always returns nullptr. This function also returns nullptr when this proxy
+        /// reaches its target object through collocation optimization (see #ice_collocationOptimized): collocated
+        /// invocations don't use a connection.
         [[nodiscard]] Ice::ConnectionPtr ice_getCachedConnection() const noexcept;
 
         /// Flushes any pending batched requests for this proxy. The call blocks until the flush is complete.
         void ice_flushBatchRequests() const;
 
         /// Flushes any pending batched requests for this proxy asynchronously.
-        /// @param ex The exception callback.
-        /// @param sent The sent callback.
+        /// @param ex 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.
         // NOLINTNEXTLINE(modernize-use-nodiscard)
         std::function<void()> ice_flushBatchRequestsAsync(
@@ -594,8 +735,9 @@ namespace Ice
         /// @return The locator for this proxy. If no locator is configured, the return value is nullopt.
         [[nodiscard]] std::optional<LocatorPrx> ice_getLocator() const noexcept;
 
-        /// Determines whether this proxy uses collocation optimization.
-        /// @return `true` if the proxy uses collocation optimization, `false` otherwise.
+        /// Determines whether this proxy has collocation optimization enabled.
+        /// @return `true` if this proxy has collocation optimization enabled, `false` otherwise.
+        /// @see #ice_collocationOptimized
         [[nodiscard]] bool ice_isCollocationOptimized() const noexcept;
 
         /// Gets the invocation timeout of this proxy.

data/dist/ice/cpp/include/Ice/SSL/ClientAuthenticationOptions.h

@@ -43,8 +43,8 @@ namespace Ice::SSL
         /// @param host The target host name.
         /// @return The client SSL credentials.
         ///
-        /// Example of setting `clientCertificateSelectionCallback`:
-        /// @snippet Ice/SSL/SchannelClientAuthenticationOptions.cpp clientCertificateSelectionCallback
+        /// Example of setting `clientCredentialsSelectionCallback`:
+        /// @snippet Ice/SSL/SchannelClientAuthenticationOptions.cpp clientCredentialsSelectionCallback
         ///
         /// @see [SCH_CREDENTIALS]
         /// @see [AcquireCredentialsHandle]
@@ -150,7 +150,7 @@ namespace Ice::SSL
         /// [SecTrustSetAnchorCertificatesOnly] with the `anchorCertificatesOnly` parameter set to true.
         ///
         /// Example of setting `trustedRootCertificates`:
-        /// @snippet Ice/SSL/SecureTransportServerAuthenticationOptions.cpp trustedRootCertificates
+        /// @snippet Ice/SSL/SecureTransportClientAuthenticationOptions.cpp trustedRootCertificates
         ///
         /// [SecTrustSetAnchorCertificates]:
         /// https://developer.apple.com/documentation/security/1396098-sectrustsetanchorcertificates?language=objc

data/dist/ice/cpp/include/Ice/SSL/EndpointInfo.h

@@ -15,7 +15,7 @@
 
 namespace Ice::SSL
 {
-    /// Provides access to an SSL endpoint information.
+    /// Provides access to an SSL endpoint's information.
     class ICE_API EndpointInfo final : public Ice::EndpointInfo
     {
     public: