Mojo UDP socket API definition review.

mojo/services/public/interfaces/network/udp_socket.mojom

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 import "mojo/services/public/interfaces/network/net_address.mojom"
 import "mojo/services/public/interfaces/network/network_error.mojom"
 
 module mojo {
 
 // UDPSocket and UDPSocketClient represent a UDP socket and its client. The
 // typical flow of using the interfaces is:
 // - Acquire a UDPSocket interface pointer and set a UDPSocketClient instance.
 // - (optional) Set options which are allowed prior to Bind().
 // - Bind the socket.
 // - (optional) Set options which are allowed after Bind().
 // - Send / request to receive packets. Received packets will be delivered to
 //   UDPSocketClient.OnReceived().
+
 [Client=UDPSocketClient]
 interface UDPSocket {
   // Allows the socket to share the local address to which it will be bound with
   // other processes. Should be called before Bind().
   // (This is equivalent to SO_REUSEADDR of the POSIX socket API.)
   AllowAddressReuse() => (NetworkError result);
 
   // Binds the socket to the given address.
   // |bound_addr| is non-NULL on success. It might not be the same as |addr|.
   // For example, if port 0 is used in |addr|, a random port is picked and
   // returned in |bound_addr|.
   Bind(NetAddress addr) => (NetworkError result, NetAddress? bound_addr);
 
   // Sets the send buffer size (in bytes) for the socket. The socket must be
   // bound.
   //
   // Note: This is only treated as a hint. Even if it succeeds, the service

[willchan no longer on Chromium, 2014/09/30 22:17:33]

What does this note mean?

It's not obvious if the send buffer here refers to the OS kernel send buffer or
the mojo service send buffer (if one exists, does it?).

How are you handling backpressure (kernel buffers filling up, and notifying when
they have space again)?

[yzshen1, 2014/09/30 22:55:09]

This is a note copied from the Pepper API, because Ryan mentioned that we
actually cannot guarantee that the buffer size setting is respected on all
platforms (IIRC). Therefore, it basically means "I will try my best but I don't
guarantee anything". :)
It is the OS buffer.

The mojo service currently does has a queue for packets that are waiting to be
passed to net::UDPServerSocket::SendTo(). I didn't expose that setting -- it is
(randomly set as) 32 packets currently. I have a comment for SendTo() (The
comment hasn't been landed.):

"""ERR_INSUFFICIENT_RESOURCES (-12): The service doesn't have sufficient
resource to complete the operation. One possible cause is that the client tries
to send too many packets in a short period of time."""

https://codereview.chromium.org/596383002/diff/40001/mojo/services/public/int...
Do you mean the callback of net::UDPServerSocket::SendTo() won't be run until
kernel buffer has some available space?

When net::UDPServerSocket::SendTo() is pending, incoming packets from the mojo
client will be stored in the mojo service's pending-send-request queue. If that
queue reaches a certain length, new packets from the mojo client will be
discarded and an "insufficient resource" error is returned to the client side.

I think it would be nicer if we help the client to figure out how fast it could
send packets instead of just discarding packets. But I haven't got a very
elegant way to do that yet. Do you have any good idea? Thanks!

[willchan no longer on Chromium, 2014/10/01 00:56:45]

Do you think it's worthwhile to clarify that in the comments? I suspect so,
since I imagine there will be Mojo services that do their own buffering atop the
OS.
Discarding packets at the client is a very poor option :) So I agree we should
do something about this. In a single-process non-blocking world, what you would
do is watch the file descriptor for it to become writable. At that point, you'd
write the message to the UDP socket, and it wouldn't get discarded.

The way we handle this in Chromium's network stack is we don't have asynchronous
I/O completion (the proactor model), but instead we use the reactor model. We
synchronously tell the client whether or not the write() will succeed, and have
asynchronous notification of _writability_ (as opposed to asynchronous write
_completion_).

You can emulate this by making the client a bit thicker so it can handle the
reactor model. It can buffer messages in the client, and the IPC messages just
do ACKs to signal when the Mojo service has consumed the message. The thick
client can keep accepting messages until its buffer fills up, and it can fire a
"writable" event after receiving an ACK from the service.

Of course, this means having a thick client on top of the raw Mojo client.

   // doesn't guarantee it will conform to the size.
   SetSendBufferSize(uint32 size) => (NetworkError result);
 
   // Sets the receive buffer size (in bytes) for the socket. The socket must be
   // bound.
   //
   // Note: This is only treated as a hint. Even if it succeeds, the service
   // doesn't guarantee it will conform to the size.
   SetReceiveBufferSize(uint32 size) => (NetworkError result);
 
@@ skipping 15 matching lines @@
 
   // Sends data to the specified destination. The socket must be bound.
   // The method doesn't report the result of the operation.
   SendToAndForget(NetAddress addr, uint8[] data);
 
   // Sends data to the specified destination. The socket must be bound.
   SendTo(NetAddress addr, uint8[] data) => (NetworkError result);
 };
 
 interface UDPSocketClient {
   // |addr| and |data| are non-NULL on success.

[wtc, 2014/10/02 02:00:52]

Nit: document what |addr| is, or rename it |peer_addr| or |sender_addr| to be
more descriptive.

[yzshen1, 2014/10/02 19:15:27]

Done. I used "src_addr" and also changed the parameter of
SendTo/SendToAndForget() to "dest_addr".

Thanks!

   OnReceived(NetworkError result, NetAddress? addr, uint8[]? data);
 };
 
 }