= 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)]