32.12 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 transparently 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 invocation 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 specified time.

If no timeout is established for a proxy via ice_timeout, the Ice run time uses default values that you can change with the following configuration properties:

• Ice.Override.ConnectTimeout

This property defines the default timeout 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 default timeout for invocations. If no value is defined for Ice.Override.ConnectTimeout, the value of Ice.Override.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 operating 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 indefinitely 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.

For information on using timeouts with asynchronous requests, refer to Section 33.3.5.