From d86d55c1f90b37d991e20ad0f1ac37b1e38b36e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 26 Sep 2019 10:43:12 +0200
Subject: Add a function to change the connection owner

While at it the gun:info/1 function has been fixed to work
even when we are in the not_connected state, and the owner
is now also returned.
---
 doc/src/manual/gun.asciidoc           |  1 +
 doc/src/manual/gun.info.asciidoc      |  2 ++
 doc/src/manual/gun.set_owner.asciidoc | 57 +++++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+)
 create mode 100644 doc/src/manual/gun.set_owner.asciidoc

(limited to 'doc')

diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 478d40b..9670e2e 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -16,6 +16,7 @@ Connection:
 
 * link:man:gun:open(3)[gun:open(3)] - Open a connection to the given host and port
 * link:man:gun:open_unix(3)[gun:open_unix(3)] - Open a connection to the given Unix domain socket
+* link:man:gun:set_owner(3)[gun:set_owner(3)] - Set a new owner for the connection
 * link:man:gun:shutdown(3)[gun:shutdown(3)] - Gracefully close the connection
 * link:man:gun:close(3)[gun:close(3)] - Brutally close the connection
 * link:man:gun:info(3)[gun:info(3)] - Obtain information about the connection
diff --git a/doc/src/manual/gun.info.asciidoc b/doc/src/manual/gun.info.asciidoc
index cf861c9..edd97f6 100644
--- a/doc/src/manual/gun.info.asciidoc
+++ b/doc/src/manual/gun.info.asciidoc
@@ -12,6 +12,7 @@ info(ConnPid) -> Info
 
 ConnPid :: pid()
 Info :: #{
+    owner          => pid(),
     socket         => inet:socket() | ssl:sslsocket(),
     transport      => tcp | tls,
     protocol       => http | http2 | socks | ws,
@@ -45,6 +46,7 @@ the connection.
 
 == Changelog
 
+* *2.0*: The value `owner` was added.
 * *1.3*: The values `socket`, `transport`, `protocol`, `origin_host`,
          `origin_port` and `intermediaries` were added.
 * *1.0*: Function introduced.
diff --git a/doc/src/manual/gun.set_owner.asciidoc b/doc/src/manual/gun.set_owner.asciidoc
new file mode 100644
index 0000000..ee12a67
--- /dev/null
+++ b/doc/src/manual/gun.set_owner.asciidoc
@@ -0,0 +1,57 @@
+= gun:set_owner(3)
+
+== Name
+
+gun:set_owner - Set a new owner for the connection
+
+== Description
+
+[source,erlang]
+----
+set_owner(ConnPid, OwnerPid) -> ok
+
+ConnPid  :: pid()
+OwnerPid :: pid()
+----
+
+Set a new owner for the connection.
+
+Only the current owner of the connection can set a new
+owner.
+
+Gun monitors the owner of the connection and automatically
+shuts down gracefully when the owner exits.
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+OwnerPid::
+
+The pid of the new owner for the connection.
+
+== Return value
+
+The atom `ok` is returned.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Set a new owner for the connection
+[source,erlang]
+----
+ok = gun:set_owner(ConnPid, OwnerPid).
+----
+
+== 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:shutdown(3)[gun:shutdown(3)],
+link:man:gun:close(3)[gun:close(3)]
-- 
cgit v1.2.3