Add support for cloning server-sockets.

sdk/lib/io/socket.dart

Index: sdk/lib/io/socket.dart
diff --git a/sdk/lib/io/socket.dart b/sdk/lib/io/socket.dart
index b1e5be77eb44703edbc16661c1da61c9bf270376..5728284d52da10befcdb554892922718ecdccfad 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -244,6 +244,37 @@ abstract class RawServerSocket implements Stream<RawSocket> {
    * is fully closed and is no longer bound.
    */
   Future<RawServerSocket> close();
+
+  /**
+   * Clone a [RawServerSocket].
+   *
+   * Returns a [RawServerSocketHandle] that can be sent to other isolates. To

[Lasse Reichstein Nielsen, 2014/04/24 12:46:47]

This feels wrong.

It seems there is some underlying concept, the "real socket" that receives
connections. These are then forwarded to currently registered receivers for that
socket.
These receivers are what we currently call "RawServerSocket", but they are not,
in fact, *raw* server sockets. There is a layer in-between.

The RawServerSocketHandle is not a "Handle". It is the *real* socket.

Is this a workaround to avoid changing the name of RawServerSocket?
Could we do that? I.e.:
 RawServerSocketReceiver mySock = new RawServerSocketReceiver();
 RawServerSocket realSock = mySock.rawSocket;  // instead of clone()
 RawServerSocketReceiver mySock2 = realSock.createReceiver();

The "Handle" name is meaningless in any case, and should be improved. To what
depends on what it really means.

[Søren Gjesse, 2014/04/25 12:24:44]

We already discussed that the naming is difficult. Clone dosen't realy clone,
but provides a "token" to "attach" to attach to a listening socket - given that
it was not already closed. Acquire doen not really "acquire" the socket.

Starting backwards the "acquire" method should maybe be named "attach" as it
uses a "token" to attach to an existing server socket. What to call the token
and the method to get it I currently have no realy good idea.

RawServerSocketToken
RawServerSocketLocater
RawServerSocketProxy (no)

+   * listen on the cloned [RawServerSocket], first call
+   * [ServerSocketHandle.acquire] to get the actual [RawServerSocket].
+   *
+   * All cloned [RawServerSocket]s will receive incoming [Socket]s using a
+   * round-robin approach.
+   *
+   * WARNING: This feature is highly *experimental* and currently only works on
+   * Linux. The API is most likely going to change in the near future.
+   */
+  RawServerSocketHandle clone();
+}
+
+
+/**
+ * A [RawServerSocketHandle].
+ *
+ * See [RawServerSocket.clone] for more information.
+ */
+abstract class RawServerSocketHandle {
+  /**
+   * Acquire the cloned [RawServerSocket].
+   *
+   * After a call to [acquire], the [RawServerSocketHandle] object is no longer
+   * valid.
+   */
+  Future<RawServerSocket> acquire();
 }
 
 
@@ -305,8 +336,40 @@ abstract class ServerSocket implements Stream<Socket> {
    * is fully closed and is no longer bound.
    */
   Future<ServerSocket> close();
+
+  /**
+   * Clone a [ServerSocket].
+   *
+   * Returns a [ServerSocketHandle] that can be sent to other isolates. To
+   * listen on the cloned [ServerSocket], first call
+   * [ServerSocketHandle.acquire] to get the actual [ServerSocket].
+   *
+   * All cloned [ServerSocket]s will receive incoming [Socket]s using a
+   * round-robin approach.
+   *
+   * WARNING: This feature is highly *experimental* and currently only works on
+   * Linux. The API is most likely going to change in the near future.
+   */
+  ServerSocketHandle clone();
 }
 
+
+/**
+ * A [ServerSocketHandle].
+ *
+ * See [ServerSocket.clone] for more information.
+ */
+abstract class ServerSocketHandle {
+  /**
+   * Acquire the cloned [ServerSocket].
+   *
+   * After a call to [acquire], the [ServerSocketHandle] object is no longer
+   * valid.
+   */
+  Future<ServerSocket> acquire();
+}
+
+
 /**
  * The [SocketDirection] is used as a parameter to [Socket.close] and
  * [RawSocket.close] to close a socket in the specified direction(s).