= gun_down(3)

== Name

gun_down - The connection is down

== Description

[source,erlang]
----
{gun_down, ConnPid, Protocol, Reason, KilledStreams}

ConnPid            :: pid()
Protocol           :: http | http2 | socks | ws
Reason             :: any()
KilledStreams      :: [gun:stream_ref()]
----

The connection is down.

This message informs the owner process that the connection
was lost. Depending on the `retry` and `retry_timeout`
options Gun may automatically attempt to reconnect.

When the connection goes back up, Gun will not attempt to retry
requests. It will also not upgrade to Websocket automatically
if that was the protocol in use when the connection was lost.

== Elements

ConnPid::

The pid of the Gun connection process.

Protocol::

The protocol that was selected for this connection
or upgraded to during the course of the connection.

Reason::

The reason for the loss of the connection.
+
It is present for debugging purposes only. You should not
rely on this value to perform operations programmatically.

KilledStreams::

List of streams that have been brutally terminated.
+
They are active streams that did not complete before the closing
of the connection. Whether they can be retried safely depends
on the protocol used and the idempotence property of the requests.

== Changelog

* *2.0*: The last element of the message's tuple, `UnprocessedStreams`
         has been removed.
* *1.0*: Message introduced.

== Examples

.Receive a gun_down message in a gen_server
[source,erlang]
----
handle_info({gun_down, ConnPid, _Protocol, _Reason, _Killed},
            State=#state{conn_pid=ConnPid}) ->
    %% Do something.
    {noreply, State}.
----

== See also

link:man:gun(3)[gun(3)],
link:man:gun:open(3)[gun:open(3)],
link:man:gun:open_unix(3)[gun:open_unix(3)],
link:man:gun_up(3)[gun_up(3)],
link:man:gun_tunnel_up(3)[gun_tunnel_up(3)],
link:man:gun_error(3)[gun_error(3)]