diff options
Diffstat (limited to 'doc/src')
-rw-r--r-- | doc/src/manual/gun.asciidoc | 4 | ||||
-rw-r--r-- | doc/src/manual/gun.ping.asciidoc | 43 | ||||
-rw-r--r-- | doc/src/manual/gun_notify.asciidoc | 17 |
3 files changed, 40 insertions, 24 deletions
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc index 212cc60..163040e 100644 --- a/doc/src/manual/gun.asciidoc +++ b/doc/src/manual/gun.asciidoc @@ -17,6 +17,7 @@ Connection: * link:man:gun:open(3)[gun:open(3)] - Open a connection to the given host and port * link:man:gun:open_unix(3)[gun:open_unix(3)] - Open a connection to the given Unix domain socket * link:man:gun:set_owner(3)[gun:set_owner(3)] - Set a new owner for the connection +* link:man:gun:ping(3)[gun:ping(3)] - Check the health or RTT of the connection * link:man:gun:shutdown(3)[gun:shutdown(3)] - Gracefully close the connection * link:man:gun:close(3)[gun:close(3)] - Brutally close the connection * link:man:gun:info(3)[gun:info(3)] - Obtain information about the connection @@ -450,7 +451,8 @@ Request headers. req_opts() :: #{ flow => pos_integer(), reply_to => pid() | {module(), atom(), list()} - | fun((_) -> _) | {fun(), list()} + | fun((_) -> _) | {fun(), list()}, + tunnel => gun:stream_ref() } ---- diff --git a/doc/src/manual/gun.ping.asciidoc b/doc/src/manual/gun.ping.asciidoc index 96fd8b8..b312e9f 100644 --- a/doc/src/manual/gun.ping.asciidoc +++ b/doc/src/manual/gun.ping.asciidoc @@ -2,8 +2,7 @@ == Name -gun:ping - Check the health or the round-trip time of a connection -without sending a request. +gun:ping - Check the health or RTT of the connection == Description @@ -17,20 +16,32 @@ ping(ConnPid, ReqOpts) ConnPid :: pid() ReqOpts :: gun:req_opts() -PingRef :: gun:stream_ref() +PingRef :: reference() ---- -Send a ping. +Check the health or round-trip time of the connection. -A ping can be sent to check the health or to measure the -round-trip time of a connection, without sending a request. +On protocols that support it, Gun will send a PING +frame and wait for its corresponding acknowledgement. +When it receives that acknowledgement the user process +gets notified via a `gun_notify` message. -The function `ping/1,2` sends a ping immediately, if the -protocol supports pings. The server responds with a ping ack. -A call to `gun:await/2,3` returns `ping_ack` when the ping -ack has been received from the server. +As this happens asynchronously and multiple pings +can be sent concurrently, Gun returns a unique +reference to the caller that can be used to identify +the related acknowledgement. -Currently, explicit ping is supported only for HTTP/2. +The following protocols implement PING mechanisms +and are supported by this function: HTTP/2. + +The following protocols implement PING mechanisms +but are not yet supported by this function: HTTP/3 +and Websocket. Note that in the case of Websocket, +the user can set `silence_pings` to `false` and +send and receive PING frames. + +The following protocols do not implement PING +mechanisms: HTTP/1.1, raw and SOCKS5. == Arguments @@ -41,7 +52,7 @@ The pid of the Gun connection process. ReqOpts:: Request options. Only the `reply_to` and `tunnel` options -can be used. +are relevant. == Return value @@ -55,17 +66,15 @@ a ping ack is received from the server. == Examples -.Perform a request +.Send a ping and receive an ack [source,erlang] ---- PingRef = gun:ping(ConnPid). -receive - {gun_notify, ConnPid, ping_ack, PingRef} -> - ok -end. +{notify, ping_ack, PingRef} = gun:await(ConnPid, undefined). ---- == See also link:man:gun(3)[gun(3)], link:man:gun:await(3)[gun:await(3)], +link:man:gun_notify(3)[gun_notify(3)] diff --git a/doc/src/manual/gun_notify.asciidoc b/doc/src/manual/gun_notify.asciidoc index 5f268ab..90daee8 100644 --- a/doc/src/manual/gun_notify.asciidoc +++ b/doc/src/manual/gun_notify.asciidoc @@ -16,9 +16,13 @@ Settings :: map() Optional event notification. -Only one event notification currently exists, for HTTP/2. -This message informs the relevant process that the server -has modified the connection settings. +Only two event notifications currently exist: + +* `settings_changed` informs the user that the server has + modified its connection settings. + +* `ping_ack` informs the user that acknowledgement for a + user ping was received. == Elements @@ -29,12 +33,12 @@ The pid of the Gun connection process. Event:: Identifier for the event. Currently can only be -`settings_changed`. +`settings_changed` or `ping_ack`. Data:: Data for the event. Currently can only be the -new connection settings. +new connection settings, or the ping reference. == Changelog @@ -53,4 +57,5 @@ handle_info({gun_notify, ConnPid, settings_changed, Settings}, == See also -link:man:gun(3)[gun(3)] +link:man:gun(3)[gun(3)], +link:man:gun:ping(3)[gun:ping(3)] |