From 611f9a9b78cab4005892e13dffb7a2c8e44580ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 2 Aug 2019 14:30:08 +0200 Subject: Add flow control Flow control is disabled by default. The initial flow value must be set to enable it (either for the entire connection or on a per-request basis). Flow applies to all HTTP streams as well as Websocket. HTTP/2 pushed streams receive the same value as their originating stream. --- doc/src/manual/gun.asciidoc | 28 ++++++++++++++ doc/src/manual/gun.update_flow.asciidoc | 67 +++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 doc/src/manual/gun.update_flow.asciidoc (limited to 'doc') diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc index da5548b..acc1454 100644 --- a/doc/src/manual/gun.asciidoc +++ b/doc/src/manual/gun.asciidoc @@ -46,6 +46,7 @@ Messages: Streams: +* link:man:gun:update_flow(3)[gun:update_flow(3)] - Update a stream's flow control value * link:man:gun:cancel(3)[gun:cancel(3)] - Cancel the given stream * link:man:gun:stream_info(3)[gun:stream_info(3)] - Obtain information about a stream @@ -143,6 +144,7 @@ Handshake timeout for tunneled TLS connections. [source,erlang] ---- http_opts() :: #{ + flow => pos_integer(), keepalive => timeout(), transform_header_name => fun((binary()) -> binary()), version => 'HTTP/1.1' | 'HTTP/1.0' @@ -155,6 +157,11 @@ The default value is given next to the option name: // @todo Document content_handlers and gun_sse_h. +flow - see below:: + +The initial flow control value for all HTTP/1.1 streams. +By default flow control is disabled. + keepalive (infinity):: Time between pings in milliseconds. Since the HTTP protocol has @@ -181,6 +188,7 @@ HTTP version to use. [source,erlang] ---- http2_opts() :: #{ + flow => pos_integer(), keepalive => timeout() } ---- @@ -191,6 +199,11 @@ The default value is given next to the option name: // @todo Document content_handlers and gun_sse_h. +flow - see below:: + +The initial flow control value for all HTTP/2 streams. +By default flow control is disabled. + keepalive (5000):: Time between pings in milliseconds. @@ -328,6 +341,7 @@ Request headers. [source,erlang] ---- req_opts() :: #{ + flow => pos_integer(), reply_to => pid() } ---- @@ -336,6 +350,11 @@ Configuration for a particular request. The default value is given next to the option name: +flow - see below:: + +The initial flow control value for the stream. By default +flow control is disabled. + reply_to (`self()`):: The pid of the process that will receive the response messages. @@ -346,6 +365,7 @@ The pid of the process that will receive the response messages. ---- ws_opts() :: #{ compress => boolean(), + flow => pos_integer(), protocols => [{binary(), module()}] } ---- @@ -360,6 +380,11 @@ Whether to enable permessage-deflate compression. This does not guarantee that compression will be used as it is the server that ultimately decides. Defaults to false. +flow - see below:: + +The initial flow control value for the Websocket connection. +By default flow control is disabled. + protocols ([]):: A non-empty list enables Websocket protocol negotiation. The @@ -378,6 +403,9 @@ undocumented and must be set to `gun_ws_h`. implement different reconnect strategies. * *2.0*: The `transport_opts` option has been split into two options: `tcp_opts` and `tls_opts`. +* *2.0*: Function `gun:update_flow/3` introduced. The `flow` + option was added to request options and HTTP/1.1, + HTTP/2 and Websocket options as well. * *2.0*: Introduce the type `req_headers()` and extend the types accepted for header names for greater interoperability. Header names are automatically diff --git a/doc/src/manual/gun.update_flow.asciidoc b/doc/src/manual/gun.update_flow.asciidoc new file mode 100644 index 0000000..c7990f2 --- /dev/null +++ b/doc/src/manual/gun.update_flow.asciidoc @@ -0,0 +1,67 @@ += gun:update_flow(3) + +== Name + +gun:update_flow - Update a stream's flow control value + +== Description + +[source,erlang] +---- +update_flow(ConnPid, StreamRef, Flow) -> ok + +ConnPid :: pid() +StreamRef :: reference() +Flow :: pos_integer() +---- + +Update a stream's flow control value. + +The flow value can only ever be incremented. + +This function does nothing for streams that have flow +control disabled (which is the default). + +== Arguments + +ConnPid:: + +The pid of the Gun connection process. + +StreamRef:: + +Identifier of the stream for the original request. + +Flow:: + +Flow control value increment. + +== Return value + +The atom `ok` is returned. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Update a stream's flow control value +[source,erlang] +---- +gun:update_flow(ConnPid, StreamRef, 10). +---- + +== See also + +link:man:gun(3)[gun(3)], +link:man:gun:get(3)[gun:get(3)], +link:man:gun:head(3)[gun:head(3)], +link:man:gun:options(3)[gun:options(3)], +link:man:gun:patch(3)[gun:patch(3)], +link:man:gun:post(3)[gun:post(3)], +link:man:gun:put(3)[gun:put(3)], +link:man:gun:delete(3)[gun:delete(3)], +link:man:gun:headers(3)[gun:headers(3)], +link:man:gun:request(3)[gun:request(3)], +link:man:gun:ws_upgrade(3)[gun:ws_upgrade(3)] -- cgit v1.2.3