From d52e84bdd97b93d7d9cea827de57bd4a0edea9a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 10 Oct 2019 11:33:35 +0200 Subject: Add shutdown_reason Websocket command This allows changing the normal exit reason of Websocket processes, providing a way to signal other processes of why the exit occurred. --- doc/src/guide/migrating_from_2.6.asciidoc | 6 ++++++ doc/src/manual/cowboy_websocket.asciidoc | 15 +++++++++++++-- 2 files changed, 19 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/src/guide/migrating_from_2.6.asciidoc b/doc/src/guide/migrating_from_2.6.asciidoc index a582ee4..91d1588 100644 --- a/doc/src/guide/migrating_from_2.6.asciidoc +++ b/doc/src/guide/migrating_from_2.6.asciidoc @@ -81,6 +81,12 @@ Cowboy 2.7 requires Erlang/OTP 20.0 or greater. is now considered stable and has been documented. The old interface is now deprecated. +* A new Websocket handler command `shutdown_reason` + can be used to change the normal exit reason of + Websocket processes. By default `normal` is used; + with this command the exit reason can be changed + to `{shutdown, ShutdownReason}`. + * The experimental stream handlers `cowboy_metrics_h` and `cowboy_tracer_h` are now considered stable and have been documented. diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc index 440a0e8..59d412d 100644 --- a/doc/src/manual/cowboy_websocket.asciidoc +++ b/doc/src/manual/cowboy_websocket.asciidoc @@ -141,6 +141,7 @@ commands() :: [Command] Command :: {active, boolean()} | {deflate, boolean()} | {set_options, #{idle_timeout => timeout()}} + | {shutdown_reason, any()} | Frame :: cow_ws:frame() ---- @@ -163,6 +164,15 @@ set_options:: Set Websocket options. Currently only the option `idle_timeout` may be updated from a Websocket handler. +shutdown_reason:: + +Change the shutdown reason. The Websocket process will exit +with reason `normal` by default. This command can be used to +exit with reason `{shutdown, ShutdownReason}` under normal +conditions. This command has no effect when the Websocket +process exits abnormally, for example following a crash in a +handler callback. + Frame:: Send the corresponding Websocket frame. @@ -266,8 +276,9 @@ normal circumstances if necessary. == Changelog -* *2.7*: The commands based interface has been added. The old - interface is now deprecated. +* *2.7*: The commands based interface has been documented. + The old interface is now deprecated. +* *2.7*: The command `shutdown_reason` was introduced. * *2.7*: The option `validate_utf8` has been added. * *2.6*: Deflate options can now be configured via `deflate_opts`. * *2.0*: The Req object is no longer passed to Websocket callbacks. -- cgit v1.2.3