32.13 Connection Timeouts

A synchronous remote invocation does not complete on the client side until the server has finished processing it. Occasionally, it is useful to be able to force an invocation to terminate after some time, even if it has not completed. Proxies provide the ice_timeout operation for this purpose:

namespace IceProxy {
    namespace Ice {
        class Object : /* ... */ {
        public:
            Ice::ObjectPrx ice_timeout(Ice::Int t) const;
            // ...
        };
    }
}

For Java (and, analogously, for C#), the corresponding method is:

package Ice;

public interface ObjectPrx {
    ObjectPrx ice_timeout(int t);
    // ...
}

The ice_timeout operation creates a proxy with a timeout from an existing proxy. For example:

Filesystem::FilePrx myFile = ...;
FileSystem::FilePrx timeoutFile
    = FileSystem::FilePrx::uncheckedCast(
        myFile‑>ice_timeout(5000));

try {
    Lines text = timeoutFile‑>read();   // Read with timeout
} catch(const Ice::TimeoutException&) {
    cerr << "invocation timed out" << endl;
}

Lines text = myFile‑>read();            // Read without timeout

The parameter to ice_timeout determines the timeout value in milliseconds. A value of −1 indicates no timeout. In the preceding example, the timeout is set to five seconds; if an invocation of read via the timeoutFile proxy does not complete within five seconds, the operation terminates with an Ice::TimeoutException. On the other hand, invocations via the myFile proxy are unaffected by the timeout, that is, ice_timeout sets the timeout on a per-proxy basis.

The timeout value set on a proxy affects all networking operations: reading and writing of data as well as opening and closing of connections. If any of these operations does not complete within the timeout, the client receives an exception. Note that, if the Ice run time encounters a recoverable error condition and trans­parently retries an invocation, this means that the timeout applies separately to each attempt. Similarly, if a large amount of data is sent with an operation invoca­tion in several write system calls, the timeout applies to each write, not to the invocation overall.

Timeouts that expire during reading or writing of data are indicated by a TimeoutException. For opening and closing of connections, the Ice run time reserves separate exceptions:

• ConnectTimeoutException

This exception indicates that a connection could not be established within the specified time.

• CloseTimeoutException

This exception indicates that a connection could not be closed within the spec­ified time.

An application normally configures a proxy’s timeout using the ice_timeout method. However, a proxy that originated from a string may already have a timeout specified, as shown in the following example:

// C++
string s = "ident:tcp -h somehost -t 5000:ssl -h somehost -t 5000";

In this case, both the TCP and SSL endpoints define a timeout of five seconds. When the Ice run time establishes a connection using one of these endpoints, it uses the endpoint’s timeout unless one was specified explicitly via ice_timeout.

The Ice run time also supports two configuration properties that override the timeouts of every proxy regardless of the settings established via ice_timeout or defined in stringified proxies:

• Ice.Override.ConnectTimeout

This property defines a timeout that is only used for connection establishment. If not defined, its default value is −1 (no timeout). If a proxy has multiple endpoints, the timeout applies to each endpoint separately.

• Ice.Override.Timeout

This property defines the timeout for invocations. If no value is defined for Ice.Override.ConnectTimeout, the value of Ice.Over­ride.Timeout is also used as the timeout for connection establishment. If not defined, the default value is −1 (no timeout).

Note that timeouts are “soft” timeouts, in the sense that they are not precise, real-time timeouts. (The precision is limited by the capabilities of the underlying oper­ating system.) You should also be aware that timeouts are considered fatal error conditions by the Ice run time and result in connection closure on the client side. Furthermore, any other requests pending on the same connection also fail with an exception. Timeouts are meant to be used to prevent a client from blocking indefi­nitely in case something has gone wrong with the server; they are not meant as a mechanism to routinely abort requests that take longer than intended.