32.15 Datagram Invocations

Datagram invocations are the equivalent of oneway invocations for datagram transports. As for oneway invocations, datagram invocations can be sent only for operations that have a void return type and do not have out-parameters or an exception specification. (Attempts to use a datagram invocation with an operation that does not meet these criteria result in a TwowayOnlyException.) In addition, datagram invocations can only be used if the proxy’s endpoints include at least one UDP transport; otherwise, the Ice run time throws a NoEndpointException.

The semantics of datagram invocations are similar to oneway invocations: no return traffic flows from the server to the client and proceed asynchronously with respect to the client; a datagram invocation completes as soon as the client’s transport has accepted the invocation into its buffers. However, datagram invocations differ in one respect from oneway invocations in that datagram invocations optionally support multicast semantics. Furthermore, datagram invocations have additional error semantics:

• Individual invocations may be lost or received out of order.

On the wire, datagram invocations are sent as true datagrams, that is, individual datagrams may be lost, or arrive at the server out of order. As a result, not only may operations be dispatched out of order, an individual invocation out of a series of invocations may be lost. (This cannot happen for oneway invocations because, if a connection fails, all invocations are lost once the connection breaks down.)

• UDP packets may be duplicated by the transport.

Because of the nature of UDP routing, it is possible for datagrams to arrive in duplicate at the server. This means that, for datagram invocations, Ice does not guarantee at-most-once semantics (see page 18): if UDP datagrams are duplicated, the same invocation may be dispatched more than once in the server.

• UDP packets are limited in size.

The maximum size of an IP datagram is 65,535 bytes. Of that, the IP header consumes 20 bytes, and the UDP header consumes 8 bytes, leaving 65,507 bytes as the maximum payload. If the marshaled form of an invocation, including the Ice request header (see Chapter 38) exceeds that size, the invocation is lost. (Exceeding the size limit for a UDP datagram is indicated to the application by a DatagramLimitException.)

Because of their unreliable nature, datagram invocations are best suited to simple update messages that are otherwise stateless. In addition, due to the high probability of loss of datagram invocations over wide area networks, you should restrict use of datagram invocations to local area networks, where they are less likely to be lost. (Of course, regardless of the probability of loss, you must design your application such that it can tolerate lost or duplicated messages.)

Creating Datagram Proxies

To create a datagram proxy, you must call ice_datagram on the proxy, for example:

Ice::ObjectPrx o = communicator‑>stringToProxy(/* ... */);

// Get a datagram proxy.
//
Ice::ObjectPrx datagram;
try {
    datagram = o‑>ice_datagram();
} catch (const Ice::NoEndpointException&) {
    cerr << "No endpoint for datagram invocations" << endl;
}

// Down‑cast to actual type.
//
PersonPrx datagramPerson = PersonPrx::uncheckedCast(datagram);

// Invoke an operation as a datagram.
//
try {
    datagramPerson‑>someOp();
} catch (const Ice::TwowayOnlyException&) {
    cerr << "someOp() is not oneway" << endl;
}

As for the oneway example in Section 32.14, you can choose to first do a safe down-cast to the actual type of interface and then obtain the datagram proxy, rather than relying on an unsafe down-cast, as shown here. However, doing so may be disadvantageous for two reasons:

• Safe down-casts are sent via a stream-oriented transport. This means that using a safe down-cast will result in opening a connection for the sole purpose of verifying that the target object has the correct type. This is expensive if all the other traffic to the object is sent via datagrams.

• If the proxy does not offer a stream-oriented transport, the checkedCast fails with a NoEndpointException, so you can use this approach only for proxies that offer both a UDP endpoint and a TCP/IP and/or SSL endpoint.