From 38100182914ca3ec84afbdf32ca84b8b78c40973 Mon Sep 17 00:00:00 2001 From: Jan Uhlig Date: Thu, 21 Nov 2024 10:43:22 +0100 Subject: Add optional callback ranch_transport:format_error/1 --- doc/src/guide/transports.asciidoc | 5 +++++ doc/src/manual/ranch_transport.asciidoc | 13 +++++++++++++ 2 files changed, 18 insertions(+) (limited to 'doc') diff --git a/doc/src/guide/transports.asciidoc b/doc/src/guide/transports.asciidoc index 73747fd..bdccfc9 100644 --- a/doc/src/guide/transports.asciidoc +++ b/doc/src/guide/transports.asciidoc @@ -175,3 +175,8 @@ implement the `{active, once}` and the `{active, true}` options. If the transport handler doesn't have a native implementation of `sendfile/5` a fallback is available, `ranch_transport:sendfile/6`. The extra first argument is the transport's module. See `ranch_ssl` for an example. + +It is highly recommended for a custom transport handler to implement the +optional `format_error/1` callback, in order to provide a human-readable +diagnostic string. Implementing this callback will become mandatory in +Ranch 3.0. diff --git a/doc/src/manual/ranch_transport.asciidoc b/doc/src/manual/ranch_transport.asciidoc index c26d91c..4717281 100644 --- a/doc/src/manual/ranch_transport.asciidoc +++ b/doc/src/manual/ranch_transport.asciidoc @@ -47,6 +47,19 @@ Assign a new controlling process to the socket. The controlling process is the process that is linked to and receives messages from the socket. +=== format_error + +[source,erlang] +---- +format_error(Reason :: term()) + -> ReasonString :: string() +---- + +Format a listen error into a human-readable diagnostic string. + +This callback is optional, but implementing it is highly +recommended. It will become mandatory in Ranch 3.0. + === getopts [source,erlang] -- cgit v1.2.3