From 7cbc7fed32940a4aa7beedec9cac23376a19a8c0 Mon Sep 17 00:00:00 2001
From: "j.uhlig" <j.uhlig@mailingwork.de>
Date: Thu, 3 May 2018 15:38:46 +0200
Subject: Remove socket option

---
 doc/src/guide/listeners.asciidoc | 22 ++++++++++++++++------
 doc/src/manual/ranch.asciidoc    | 10 +---------
 2 files changed, 17 insertions(+), 15 deletions(-)

(limited to 'doc')

diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index e8ca694..4885c6d 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -162,12 +162,22 @@ solutions is however out of the scope of this guide.
 
 === Accepting connections on an existing socket
 
-If you want to accept connections on an existing socket, you can use the
-`socket` transport option, which should just be the relevant data returned
-from the connect function for the transport or the underlying socket library
-(`gen_tcp:connect`, `ssl:connect`). The accept function will then be
-called on the passed in socket. You should connect the socket in
-`{active, false}` mode, as well.
+If you want to accept connections on an existing socket, you can write
+a custom `ranch_transport` implementation that fetches or otherwise
+acquires a listening socket in the `listen/1` callback and returns it
+in the form of `{ok, ListenSocket}`.
+
+The custom `listen/1` function must ensure that the listener process
+(usually the process calling it) is also made the controlling process
+of the socket it returns. Failing to do so will result in stop/start
+and suspend/resume not working properly for that listener.
+
+While it might be tempting to pass in an existing socket to your
+custom transport by way of the transport options, thereby mimicking
+a deprecated ranch behavior, this is considered dangerous and was removed
+for that very reason. In general, it should be ensured that the socket
+to be returned from a custom `listen/1` function really is a listening
+socket and that it is operational.
 
 === Limiting the number of concurrent connections
 
diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index 61b4021..01de75f 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -73,7 +73,6 @@ opt() = {ack_timeout, timeout()}
       | {max_connections, max_conns()}
       | {num_acceptors, pos_integer()}
       | {shutdown, timeout() | brutal_kill}
-      | {socket, any()}
 ----
 
 Deprecated form for Ranch-specific options.
@@ -93,7 +92,6 @@ opts() = any() | #{
     logger            => module(),
     num_acceptors     => pos_integer(),
     shutdown          => timeout() | brutal_kill,
-    socket            => any(),
     socket_opts       => any()
 }
 ----
@@ -135,13 +133,6 @@ shutdown (5000)::
 
 Maximum allowed time for children to stop on listener shutdown.
 
-socket::
-
-Listening socket opened externally to be used instead of
-calling `Transport:listen/1`. This option will be removed
-in Ranch 2.0. Use a custom transport module acting as a
-wrapper for `ranch_tcp` or `ranch_ssl` instead.
-
 socket_opts::
 
 Socket options given to `Transport:listen/1`. Please refer to the
@@ -158,6 +149,7 @@ Unique name used to refer to a listener.
 
 == Changelog
 
+* *2.0*: The `socket` option was removed.
 * *1.6*: The `logger` option was added.
 * *1.6*: The `opt()` type was deprecated in favor of the new `opts()` type.
 
-- 
cgit v1.2.3