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();
+
+  /**
+   * 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();
+}
+
+
 /**
  * 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();
+
+  /**
+   * 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).
  */
 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 359 matching lines @@
     }
     if (address != null) {
       sb.write(", address = ${address.host}");
     }
     if (port != null) {
       sb.write(", port = $port");
     }
     return sb.toString();
   }
 }