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. The ice_timeout
factory method is provided for this purpose. The Slice definition of ice_timeout
would look as follows:
{zcode:slice} Object* ice_timeout(int t); {zcode} |
This method returns a new proxy with the configured timeout. For example:
{zcode:cpp} Filesystem::FilePrx myFile = ...; FileSystem::FilePrx timeoutFile = 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 {zcode} |
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 uses more specific exceptions:
ConnectTimeoutException
CloseTimeoutException
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:
{zcode:cpp} string s = "ident:tcp -h somehost -t 5000:ssl -h somehost -t 5000"; {zcode} |
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 the options defined in stringified proxies:
Ice.Override.ConnectTimeout
-1
(no timeout). If a proxy has multiple endpoints, the timeout applies to each endpoint separately.Ice.Override.Timeout
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).If you are considering the use of timeouts, please keep the following limitations in mind: