Add support for cloning server-sockets.

sdk/lib/io/socket.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 
 /**
  * [InternetAddressType] is the type an [InternetAddress]. Currently,
  * IP version 4 (IPv4) and IP version 6 (IPv6) are supported.
@@ skipping 226 matching lines @@
   /**
    * Returns the address used by this socket.
    */
   InternetAddress get address;
 
   /**
    * Closes the socket. The returned future completes when the socket
    * 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();
+}
+
+
 /**
  * A [ServerSocket] represents a listening socket, and provides a
  * stream of [Socket] objects, one for each connection made to the
  * listening socket.
  *
  * See [Socket] for more info.
  */
 abstract class ServerSocket implements Stream<Socket> {
   /**
    * Returns a future for a [:ServerSocket:]. When the future
@@ skipping 38 matching lines @@
   /**
    * Returns the address used by this socket.
    */
   InternetAddress get address;
 
   /**
    * Closes the socket. The returned future completes when the 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).
  */
 class SocketDirection {
   static const SocketDirection RECEIVE = const SocketDirection._(0);
   static const SocketDirection SEND = const SocketDirection._(1);
   static const SocketDirection BOTH = const SocketDirection._(2);
   final _value;
 
@@ skipping 355 matching lines @@
     }
     if (address != null) {
       sb.write(", address = ${address.host}");
     }
     if (port != null) {
       sb.write(", port = $port");
     }
     return sb.toString();
   }
 }