---
title: "Connection Establishment"
url: https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment
language: matlab
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Connection Establishment

Programming language: MATLAB. Other languages: [C++](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/js.md), [PHP](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/php.md), [Python](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/swift.md).

Ice establishes connections on demand. When an invocation on a proxy needs a connection, Ice reuses an existing connection if it can, and otherwise establishes a new connection to one of the [proxy's endpoints](https://docs.zeroc.com/ice/3.8/runtime/invocation/proxy-endpoints/matlab.md).

## Connection Reuse and Caching

Ice reuses connections at two levels:

- By default, a proxy caches the connection it obtains and uses it for its subsequent invocations.
- The communicator keeps the connections it establishes, and other proxies of this communicator share them.

When a proxy with connection caching enabled needs a connection, Ice prefers an endpoint that already has a connection. It reuses an existing connection that meets the following conditions, and establishes a new connection only when no existing connection does:

- The connection's remote endpoint matches one of the proxy's endpoints.
- The connection was established for the proxy's [connection ID](#connection-ids).

You disable connection caching with the `ice_connectionCached` proxy method or the [*name*.ConnectionCached](https://docs.zeroc.com/ice/3.8/property-reference/proxy-properties/matlab.md#name.connectioncached) property. Ice then selects an endpoint for each invocation on this proxy in the order set by the [endpoint selection policy](#endpoint-selection), and reuses an existing connection to this endpoint if there is one. With the default `Random` policy, disabling connection caching distributes a proxy's invocations across its endpoints.

The communicator manages the lifetime of its connections independently of the proxies that use them. Connections are long-lived: a healthy connection with regular activity stays open until the communicator is destroyed. The communicator closes a connection after a period of [inactivity](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/matlab.md#the-inactivity-check), 300 seconds by default, aborts a connection when a read or write fails or when the [idle check](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/matlab.md#the-idle-check) fails, and closes all its connections when it is destroyed. When the connection a proxy caches closes, the proxy obtains a connection again for its next invocation.

## Endpoint Selection

When a proxy needs a connection, Ice starts from the proxy's endpoints, or from the endpoints its [locator](https://docs.zeroc.com/ice/3.8/runtime/locators.md) returns for an [indirect proxy](https://docs.zeroc.com/ice/3.8/runtime/invocation/proxy-endpoints/matlab.md), and produces the list of endpoints it can connect to as follows:

1. It removes the endpoints of unknown transports.
2. It removes the endpoints that do not suit the proxy's invocation mode: datagram endpoints for twoway, oneway and batch oneway proxies, and non-datagram endpoints for datagram and batch datagram proxies. If no endpoint remains, the invocation fails with `NoEndpointException`. For example, a twoway proxy whose only endpoint is a UDP endpoint has no endpoint left.
3. It orders the endpoints according to the endpoint selection policy. `Random`, the default, shuffles the endpoints; `Ordered` keeps their order.
4. It resolves host names into IP addresses. When a host name resolves to several addresses, the list holds them in the order the DNS resolver returns them, with IPv4 addresses ahead of IPv6 addresses unless [Ice.PreferIPv6Address](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/matlab.md#ice.preferipv6address) is set.

You set the endpoint selection policy with the [Ice.Default.EndpointSelection](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/matlab.md#ice.default.endpointselection) property, the [*name*.EndpointSelection](https://docs.zeroc.com/ice/3.8/property-reference/proxy-properties/matlab.md#name.endpointselection) proxy property, or the `ice_endpointSelection` proxy method.

## Establishing the Connection

With connection caching enabled, Ice first reuses an existing connection to any endpoint in the list, so the connection it reuses is not necessarily to the first endpoint, even with the `Ordered` policy. When no existing connection qualifies, or when connection caching is disabled, Ice attempts to connect to each endpoint, and to each address of an endpoint, in order, until an attempt succeeds.

## Connection IDs

Each proxy has a connection ID, an empty string by default, and Ice reuses a connection for a proxy only if the connection was established for the same connection ID. The `ice_connectionId` proxy method returns a new proxy with the given connection ID. Proxies with the same connection ID form a group that shares connections, and Ice establishes a new connection for a group that has none to a suitable endpoint.

The following example establishes three connections:

```matlab
prx = SomePrx(communicator, 'ident:tcp -p 10000');
g1 = prx.ice_connectionId('group1');
g2 = prx.ice_connectionId('group2');
prx.ice_ping(); % Opens a new connection
g1.ice_ping(); % Opens a new connection
g2.ice_ping(); % Opens a new connection
i1 = AdminPrx.uncheckedCast(g1.ice_facet('admin'));
i1.ice_ping(); % Reuses g1's connection
i2 = AdminPrx.uncheckedCast(prx.ice_connectionId("group2").ice_facet("admin"));
i2.ice_ping(); % Reuses g2's connection
```

`prx`, `g1` and `g2` each establish a connection because their connection IDs differ. `i1` inherits its connection ID from `g1` and shares the `group1` connection; `i2` is configured with `group2` and shares the connection of `g2`.

## Failed Connection Attempts

When a connection attempt fails, Ice tries the next address or endpoint, until it establishes a connection or has tried them all.

When every attempt fails, the invocation fails. An [automatic retry](https://docs.zeroc.com/ice/3.8/runtime/invocation/automatic-retries/matlab.md) of the invocation goes through connection establishment again.

> **Tip**
>
> Set `Ice.Trace.Network=2` to log each failed connection attempt, and `Ice.Trace.Retry=1` to log the retries.

## Connection Establishment Timeout

A connection attempt fails with `ConnectTimeoutException` when it does not complete within the time set by [Ice.Connection.Client.ConnectTimeout](https://docs.zeroc.com/ice/3.8/property-reference/ice-connection-properties/matlab.md#ice.connection.name.connecttimeout), 10 seconds by default.

## Source Address for New Connections

Ice binds an outgoing connection to the source address of the endpoint it connects to. You set this address with the [--sourceAddress](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/matlab.md) endpoint option, and Ice gives the address set by [Ice.Default.SourceAddress](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/matlab.md#ice.default.sourceaddress) to the endpoints it parses without this option, such as those of a stringified proxy. An endpoint that Ice unmarshals, such as an endpoint returned by a locator, has no source address, and the operating system then selects the source address. Both settings take a numeric IP address.

## See Also

- [Proxy Endpoints](https://docs.zeroc.com/ice/3.8/runtime/invocation/proxy-endpoints/matlab.md)
- [The Ice Threading Model](https://docs.zeroc.com/ice/3.8/runtime/threading-model.md)
- [Automatic Retries](https://docs.zeroc.com/ice/3.8/runtime/invocation/automatic-retries/matlab.md)
- [IceGrid](https://docs.zeroc.com/ice/3.8/services/icegrid.md)
- [Ice.Default.\*](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/matlab.md)
- [Miscellaneous Ice.\* Properties](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/matlab.md)
