gun:ping(3)

Name

gun:ping - Check the health or RTT of the connection

Description

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

PingRef = gun:ping(ConnPid).
{notify, ping_ack, PingRef} = gun:await(ConnPid, undefined).

See also

gun(3), gun:await(3), gun_notify(3)