aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorj.uhlig <[email protected]>2018-05-03 15:38:46 +0200
committerLoïc Hoguin <[email protected]>2019-04-29 14:39:20 +0200
commit7cbc7fed32940a4aa7beedec9cac23376a19a8c0 (patch)
tree0cbab7739b16681188096491d27562ecd4f2b03e /doc/src
parentdabf62792c2af08c4c6d36177546695356c33b3a (diff)
downloadranch-7cbc7fed32940a4aa7beedec9cac23376a19a8c0.tar.gz
ranch-7cbc7fed32940a4aa7beedec9cac23376a19a8c0.tar.bz2
ranch-7cbc7fed32940a4aa7beedec9cac23376a19a8c0.zip
Remove socket option
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/guide/listeners.asciidoc22
-rw-r--r--doc/src/manual/ranch.asciidoc10
2 files changed, 17 insertions, 15 deletions
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.