1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
= gun:ping(3)
== Name
gun:ping - Check the health or RTT of the connection
== Description
[source,erlang]
----
ping(ConnPid)
-> ping(ConnPid, #{})
ping(ConnPid, ReqOpts)
-> PingRef
ConnPid :: pid()
ReqOpts :: gun:req_opts()
PingRef :: reference()
----
Check the health or round-trip time of the connection.
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.
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.
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
ConnPid::
The pid of the Gun connection process.
ReqOpts::
Request options. Only the `reply_to` and `tunnel` options
are relevant.
== Return value
A reference that identifies the ping is returned. This
reference is included in the notification received when
a ping ack is received from the server.
== Changelog
* *2.2*: Function introduced.
== Examples
.Send a ping and receive an ack
[source,erlang]
----
PingRef = gun:ping(ConnPid).
{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)]
|
