aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/gun_down.asciidoc
blob: 67c7796854d86c2f6490a9cc095592087c724045 (plain) (blame)
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
81
82
83
84
85
86
= gun_down(3)

== Name

gun_down - The connection is down

== Description

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

ConnPid            :: pid()
Protocol           :: http | http2 | ws
Reason             :: any()
KilledStreams      :: [reference()]
UnprocessedStreams :: [reference()]
----

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.

UnprocessedStreams::

List of streams that have not been processed by the server.
+
They are streams that the server did not start processing yet.
They may be retried safely depending on whether related streams
were killed.

== Changelog

* *1.0*: Message introduced.

== Examples

.Receive a gun_down message in a gen_server
[source,erlang]
----
handle_info({gun_down, ConnPid, _Protocol,
             _Reason, _Killed, _Unprocessed},
            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_error(3)[gun_error(3)]