Add functions await_up/{1,2,3} for sync open

2 files changed, 44 insertions, 1 deletions

diff --git a/doc/src/guide/connect.asciidoc b/doc/src/guide/connect.asciidoc
index 8de8184..f734680 100644
--- a/doc/src/guide/connect.asciidoc
+++ b/doc/src/guide/connect.asciidoc
@@ -52,12 +52,25 @@ form of a map.
 [source,erlang]
 {ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}).
 
-=== Connection up and down messages
+=== Waiting for the connection to be established
 
 When Gun successfully connects to the server, it sends a
 `gun_up` message with the protocol that has been selected
 for the connection.
 
+Gun provides the functions `gun:await_up/{1,2,3}` that wait
+for the `gun_up` message. They can optionally take a monitor
+reference and/or timeout value. If no monitor is provided,
+one will be created for the duration of the function call.
+
+.Synchronous opening of a connection
+
+[source,erlang]
+{ok, ConnPid} = gun:open("example.org", 443),
+{ok, Protocol} = gun:await_up(ConnPid).
+
+=== Handling connection loss
+
 When the connection is lost, Gun will send a `gun_down`
 message indicating the current protocol, the reason the
 connection was lost and two list of stream references.
diff --git a/src/gun.erl b/src/gun.erl
index b3623eb..074b121 100644
--- a/src/gun.erl
+++ b/src/gun.erl
@@ -48,6 +48,9 @@
 -export([await_body/2]).
 -export([await_body/3]).
 -export([await_body/4]).
+-export([await_up/1]).
+-export([await_up/2]).
+-export([await_up/3]).
 
 %% Flushing gun messages.
 -export([flush/1]).
@@ -333,6 +336,33 @@ await_body(ServerPid, StreamRef, Timeout, MRef, Acc) ->
 		{error, timeout}
 	end.
 
+-spec await_up(pid()) -> {ok, http | spdy} | {error, atom()}.
+await_up(ServerPid) ->
+	MRef = monitor(process, ServerPid),
+	Res = await_up(ServerPid, 5000, MRef),
+	demonitor(MRef, [flush]),
+	Res.
+
+-spec await_up(pid(), reference() | timeout()) -> {ok, http | spdy} | {error, atom()}.
+await_up(ServerPid, MRef) when is_reference(MRef) ->
+	await_up(ServerPid, 5000, MRef);
+await_up(ServerPid, Timeout) ->
+	MRef = monitor(process, ServerPid),
+	Res = await_up(ServerPid, Timeout, MRef),
+	demonitor(MRef, [flush]),
+	Res.
+
+-spec await_up(pid(), timeout(), reference()) -> {ok, http | spdy} | {error, atom()}.
+await_up(ServerPid, Timeout, MRef) ->
+	receive
+		{gun_up, ServerPid, Protocol} ->
+			{ok, Protocol};
+		{'DOWN', MRef, process, ServerPid, Reason} ->
+			{error, Reason}
+	after Timeout ->
+		{error, timeout}
+	end.
+
 -spec flush(pid() | reference()) -> ok.
 flush(ServerPid) when is_pid(ServerPid) ->
 	flush_pid(ServerPid);