From 5b810c924da242632a04a2c44772cb892aa1b7c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 2 Jun 2018 22:44:16 +0200
Subject: Revamp the manual, one page per function/message

---
 doc/src/manual/gun_push.asciidoc | 90 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 doc/src/manual/gun_push.asciidoc

(limited to 'doc/src/manual/gun_push.asciidoc')

diff --git a/doc/src/manual/gun_push.asciidoc b/doc/src/manual/gun_push.asciidoc
new file mode 100644
index 0000000..e73c3b6
--- /dev/null
+++ b/doc/src/manual/gun_push.asciidoc
@@ -0,0 +1,90 @@
+= gun_push(3)
+
+== Name
+
+gun_push - Server-initiated push
+
+== Description
+
+[source,erlang]
+----
+{gun_push, ConnPid, StreamRef, NewStreamRef, Method, URI, Headers}
+
+ConnPid      :: pid()
+StreamRef    :: reference()
+NewStreamRef :: reference()
+Method       :: binary()
+URI          :: binary()
+Headers      :: [{binary(), binary()}]
+----
+
+Server-initiated push.
+
+This message informs the relevant process that the server
+is pushing a resource related to the effective target URI
+of the original request.
+
+A server-initiated push message always precedes the response
+to the original request.
+
+This message will not be sent when using the HTTP/1.1 protocol
+because it lacks the concept of server-initiated push.
+
+== Elements
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+StreamRef::
+
+Identifier of the stream for the original request.
+
+NewStreamRef::
+
+Identifier of the stream being pushed.
+
+Method::
+
+Method of the equivalent HTTP request.
+
+URI::
+
+URI of the resource being pushed.
+
+Headers::
+
+Headers of the equivalent HTTP request.
+
+== Changelog
+
+* *1.0*: Message introduced.
+
+== Examples
+
+.Receive a gun_push message in a gen_server
+[source,erlang]
+----
+handle_info({gun_push, ConnPid, _StreamRef,
+             _NewStreamRef, _Method, _URI, _Headers},
+            State=#state{conn_pid=ConnPid}) ->
+    %% Do something.
+    {noreply, State}.
+----
+
+.Cancel an unwanted push
+[source,erlang]
+----
+handle_info({gun_push, ConnPid, _StreamRef,
+             NewStreamRef, _Method, _URI, _Headers},
+            State=#state{conn_pid=ConnPid}) ->
+    gun:cancel(ConnPid, NewStreamRef),
+    {noreply, State}.
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:get(3)[gun:get(3)],
+link:man:gun:cancel(3)[gun:cancel(3)],
+link:man:gun_response(3)[gun_response(3)]
-- 
cgit v1.2.3