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 b0ace925da5328b64820a84f8cc77ae5b874168d..1f5f5d4a9f94764a1c62d8239e3fdc5f0fe4018e 100644
--- a/sdk/lib/io/socket.dart
+++ b/sdk/lib/io/socket.dart
@@ -244,6 +244,33 @@ abstract class RawServerSocket implements Stream<RawSocket> {
    * is fully closed and is no longer bound.
    */
   Future<RawServerSocket> close();
+
+  /**
+   * Get the [RawServerSocketReference].
+   *
+   * The reference can be used to clone this [RawServerSocket] onto multiple
+   * isolates. See [RawServerSocketReference] for more information.
+   *
+   * All cloned [RawServerSocket]s will receive incoming [RawSocket]s using a
+   * round-robin approach.
+   *
+   * WARNING: This feature is highly *experimental* and currently only works on

[Søren Gjesse, 2014/05/06 08:47:39]

Move the WARNING up as the first line of the comment.

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+   * Linux. The API is most likely going to change in the near future.
+   */
+  RawServerSocketReference get reference;
+}
+
+
+/**

[Søren Gjesse, 2014/05/06 08:47:39]

Add a WARNING here as well.

WARNING: This class is used with RawServerSocket.reference which is highly
*experimental* ...

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+ * A [RawServerSocketReference].
+ *
+ * See [RawServerSocket.reference] for more information.
+ */
+abstract class RawServerSocketReference {
+  /**
+   * Create a new [RawServerSocket], from this reference.
+   */
+  Future<RawServerSocket> create();
 }
 
 
@@ -305,8 +332,36 @@ abstract class ServerSocket implements Stream<Socket> {
    * is fully closed and is no longer bound.
    */
   Future<ServerSocket> close();
+
+  /**
+   * Get the [ServerSocketReference].
+   *
+   * The reference can be used to clone this [ServerSocket] onto multiple
+   * isolates. See [ServerSocketReference] for more information.

[Lasse Reichstein Nielsen, 2014/05/06 09:04:20]

ServerSocketReference doesn't really have more information.

How about:

The returned [ServerSocketReference] can be used to create other `ServerSocket`s
listening on the same port using [ServerSocketReference.create]. 
Incoming connections on the port will be distributed fairly between the active
server sockets.
The [ServerSocketReference] can be distributed to other isolates through a
[SendPort].

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+   *
+   * All cloned [ServerSocket]s will receive incoming [Socket]s using a

[Lasse Reichstein Nielsen, 2014/05/06 09:04:20]

Will they get sockets before you listen on the ServerSocket?

[Anders Johnsen, 2014/05/06 12:34:32]

Yes

+   * round-robin approach.

[Lasse Reichstein Nielsen, 2014/05/06 09:04:20]

It's not round-robin unless they have a circular order, and each only gets one
event in each round. Is this the case?
Otherwise we need a different wording here.

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+   *
+   * WARNING: This feature is highly *experimental* and currently only works on

[Søren Gjesse, 2014/05/06 08:47:39]

Move WARNING up.

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+   * Linux. The API is most likely going to change in the near future.

[Lasse Reichstein Nielsen, 2014/05/06 09:04:20]

I'd put "*" around "highly" too.

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+   */
+  RawServerSocketReference get reference;

[Søren Gjesse, 2014/05/06 08:47:39]

Return type ServerSockerReference

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+}
+
+
+/**

[Søren Gjesse, 2014/05/06 08:47:39]

Add WARNING

[Anders Johnsen, 2014/05/06 12:34:32]

Done.

+ * A [ServerSocketReference].
+ *
+ * See [ServerSocket.reference] for more information.
+ */
+abstract class ServerSocketReference {
+  /**
+   * Create a new [ServerSocket], from this reference.
+   */
+  Future<ServerSocket> create();
 }
 
+
 /**
  * The [SocketDirection] is used as a parameter to [Socket.close] and
  * [RawSocket.close] to close a socket in the specified direction(s).