The entries below contain brief descriptions of the changes in each release, in no particular order. Some of the entries reflect significant new additions, while others represent minor corrections. Although this list is not a comprehensive report of every change we made in a release, it does provide details on the changes we feel Ice users might need to be aware of.
We recommend that you use the release notes as a guide for migrating your applications to this release, and the manual for complete details on a particular aspect of Ice.
These are the changes since the Ice 3.7.10 release in CHANGELOG-3.7.md.
-
Replaced ACM and connection timeouts by idle, inactivity, connect, and close timeouts.
- Idle timeout
Once a connection is established, this connection is considered healthy as long as it does not wait for more than idle timeout to read a byte. If a connection waits for more than idle timeout to read a byte, it's deemed idle and aborted. Idle is never a good state. To prevent connections from becoming idle, Ice ensures there is regular write activity on established connections: if there is no write on a connection for idle timeout / 2, Ice sends a heartbeat on this connection. A heartbeat is a one-way, unacknowledged, ValidateConnection message. The default idle timeout is 60 seconds. You can change this value with the configuration propertyIce.Connection.Client.IdleTimeout
(for client connections) orIce.Connection.Server.IdleTimeout
(for server connections). The unit for this timeout is seconds. You can also override this value for a specific object adapter with the configuration propertyAdapterName.Connection.IdleTimeout
. Our general recommendation is to keep things simple: use the same value (typically the default) for all your Ice applications. In particular, the idle timeout is not negotiated during connection establishment and an idle timeout mismatch may result in untimely connection aborts.- Interop with Ice 3.7 and earlier releases
If your Ice 3.8 application connects to an older Ice server or accepts a connection from an older Ice client, you need to change the configuration of your older Ice application to send regular heartbeats. Otherwise, your Ice 3.8 application can deem the connection idle (after idle timeout) and abort this connection. With Ice 3.7 and Ice 3.6, you can set the propertyIce.ACM.Heartbeat
to 3, and make sure theIce.ACM.Timeout
property matches your idle timeout (the default for the ACM timeout is 60 seconds, just like the default idle timeout). If you are unable to change the configuration of your older Ice application, you can switch off the idle detection on the Ice 3.8 side by settingIce.Connection.Client.EnableIdleCheck
orIce.Connection.Server.EnableIdleCheck
to 0. You can also switch off the idle check for just a specific object adapter by settingAdapterName.Connection.EnableIdleCheck
to
- Interop with IceRPC
IceRPC uses the same idle timeout and idle check mechanism for connections that use theice
protocol.
- Interop with Ice 3.7 and earlier releases
- Inactivity timeout
A connection is considered inactive when there is no application-level activity on this connection: there is no outstanding invocation (we're not waiting for a response for a request we've sent), there is no outstanding dispatch, and no request or response is being sent or received. Sending or receiving a heartbeat (see above) does not count as application-level activity. When a connection remains inactive for more than the inactivity timeout, this connection is closed gracefully. Inactive is a good state: the connection is healthy but unused, so we shut it down to reclaim resources. The default inactivity timeout is 300 seconds. You can change this default by settingIce.Connection.Client.InactivityTimeout
(for client connections) orIce.Connection.Server.InactivityTimeout
(for server connections). The unit for this timeout is seconds. You can also override this value for a specific object adapter with the configuration propertyAdapterName.Connection.InactivityTimeout
.
Note: make sure your inactivity timeout is greater than your idle timeout, as the implementation of the inactivity timeout relies on a smaller idle timeout value. If you disable your idle timeout by setting it to 0 or very large value (not something we recommend), you will effectively disable your inactivity timeout as well. - Connect timeout
A connection establishment fails if it takes more than connect timeout to complete. The default connect timeout is 10 seconds. You can change this value by settingIce.Connection.Client.ConnectTimeout
(for client connections) orIce.Connection.Server.ConnectTimeout
(for server connections). The unit for this timeout is seconds. You can also override this value for a specific object adapter with the configuration propertyAdapterName.Connection.ConnectTimeout
. - Close timeout
A graceful connection closure transitions to connection abort if it takes more than close timeout to complete. The default close timeout is 10 seconds. You can change this value by settingIce.Connection.Client.CloseTimeout
(for client connections) orIce.Connection.Server.CloseTimeout
(for server connections). The unit for this timeout is seconds, as usual. You can also override this value for a specific object adapter with the configuration propertyAdapterName.Connection.CloseTimeout
.
- Idle timeout
-
Simplify proxy creation. You can now create a typed proxy directly from a communicator and a string in all languages. For example:
// C++ GreeterPrx greeter{communicator, "greeter:tcp -h localhost -p 4061"};
// C# var greeter = GreeterPrxHelper.createProxy(communicator, "greeter:tcp -h localhost -p 4061");
// Java var greeter = GreeterPrx.createProxy(communicator, "greeter:tcp -h localhost -p 4061");
// JavaScript const greeter = new GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061");
% MATLAB greeter = GreeterPrx(communicator, 'greeter:tcp -h localhost -p 4061');
// PHP $greeter = GreeterPrx::createProxy($communicator, 'greeter:tcp -h localhost -p 4061');
# Python greeter = GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")
# Ruby greeter = GreeterPrx.new(communicator, "greeter:tcp -h localhost -p 4061")
// Swift let greeter = try makeProxy( communicator: communicator, proxyString: "greeter:tcp -h localhost -p 4061", type: GreeterPrx.self)
// TypeScript const greeter = new GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061");
The existing
stringToProxy
operation onCommunicator
remains available. However, the new syntax is now the preferred way to create a proxy from a string. -
Consolidate and refactor the exceptions derived from LocalException.
Local exception in Ice 3.7 Replacement Notes BadMagicException ProtocolException (base) CFNetworkException SocketException (base) CloneNotImplementedException std::logic_error C++ only CompressionException ProtocolException (base) ConnectionManuallyClosedException ConnectionAbortedException, ConnectionClosedException ConnectionNotValidatedException ProtocolException (base) EncapsulationException MarshalException (base) EndpointParseException ParseException EndpointSelectionTypeParseException ParseException IllegalIdentityException ArgumentException (C#), std::invalid_argument (C++), IllegalArgumentException (Java) IllegalMessageSizeException MarshalException IllegalServantException ArgumentNullException (C#), std::invalid_argument (C++), IllegalArgumentException (Java) IdentityParseException ParseException MemoryLimitException MarshalException (base) NoValueFactoryException MarshalException (base) ProxyParseException ParseException ProxyUnmarshalException MarshalException (base) StringConversionException MarshalException (base) UnexpectedObjectException MarshalException (base) UnknownMessageException ProtocolException (base) UnknownReplyStatusException MarshalException UnmarshalOutOfBoundsException MarshalException (base) UnsupportedEncodingException MarshalException UnsupportedProtocolException MarshalException, FeatureNotSupportedException VersionMismatchException InitializationException VersionParseException ParseException base = was existing base class
New local exceptions:
ConnectionAbortedException, ConnectionClosedException, ParseException
-
Removed local Slice.
local
is no longer a Slice keyword. -
Removed support for the
["preserve-slice"]
metadata. Slice classes encoded in the Sliced-format are now always full-preserved. -
Exceptions are now always encoded in the sliced format and no longer support preservation of unknown type slices.
-
Slice classes can no longer define operations or implement interfaces, and
implements
is no longer a Slice keyword. This feature has been deprecated since Ice 3.7. -
Slice classes no longer represent remote Ice objects; the syntax
MyClass*
(a proxy to a class) is now invalid. -
An interface can no longer be used as a type. This feature, known as "interface by value", has been deprecated since Ice 3.7. You can still define proxies with the usual syntax,
Greeter*
, whereGreeter
represents an interface.
- Removed
IceSSL.SchannelStrongCrypto
. Strong crypto is now enabled by default.
-
There is now a single C++ mapping, based on the C++11 mapping provided by Ice 3.7. This new C++ mapping requires a C++ compiler with support for std=c++17 or higher.
-
All functions that create proxies, including
Communicator::stringToProxy
,ObjectAdapter::add
,Connection::createProxy
and more, are now template functions that allow you to choose the type of the returned proxy. The default proxy type isIce::ObjectPrx
for backwards compatibility. We recommend you always specify the desired proxy type explicitly. For example:// widget is a std::optional<WidgetPrx> auto widget = communicator->propertyToProxy<WidgetPrx>("MyWidget");
-
When unmarshaling an array of short, int, long, float, or double, you can now choose to use unaligned unmarshaling by defining ICE_UNALIGNED when building your application. This optimization requires the non-default array mapping for Slice sequences, enabled by the
cpp:array
metadata directive, and a compatible little endian platform. In Ice 3.7 and earlier releases, this unaligned unmarshaling was turned on automatically on x86 and x64 CPUs, and turned off on all other CPUs.
- The thread pools created by Ice no longer set a synchronization context. As a result, the continuation from an async
invocation made from an Ice thread pool thread executes in a .NET thread pool thread; previously, this continuation
was executed in a thread managed by the same Ice thread pool unless you specified
.ConfigureAwait(false)
.
- The Objective-C mapping was removed.
- Removed the flattened mapping deprecated in 3.7.
- Removed deprecated server and application distributions in IceGrid. These distributions relied on the IcePatch2 service.
- The IcePatch2 service was removed.