= gun:await(3)

== Name

gun:await - Wait for a response

== Description

[source,erlang]
----
await(ConnPid, StreamRef)
    -> await(ConnPid, StreamRef, 5000, MonitorRef)

await(ConnPid, StreamRef, MonitorRef)
    -> await(ConnPid, StreamRef, 5000, MonitorRef)

await(ConnPid, StreamRef, Timeout)
    -> await(ConnPid, StreamRef, Timeout, MonitorRef)

await(ConnPid, StreamRef, Timeout, MonitorRef)
    -> Result

ConnPid    :: pid()
StreamRef  :: gun:stream_ref()
MonitorRef :: reference()
Timeout    :: timeout()
Result     :: tuple() - see below
----

Wait for a response.

This function waits for a message from the given stream and
returns it as a tuple. An error will be returned should the
process fail or a relevant message is not received within
the specified duration.

== Arguments

ConnPid::

The pid of the Gun connection process.

StreamRef::

Identifier of the stream for the original request.

Timeout::

How long to wait for a message, in milliseconds.

MonitorRef::

Monitor for the Gun connection process.
+
A monitor is automatically created for the duration of this
call when one is not provided.

== Return value

A number of different tuples can be returned. They correspond
to the message of the same name and they contain the same
elements minus the pid and stream reference. Error tuples
may also be returned when a timeout or an error occur.

[source,erlang]
----
Result :: {inform, Status, Headers}
        | {response, IsFin, Status, Headers}
        | {data, IsFin, Data}
        | {trailers, Trailers}
        | {push, NewStreamRef, Method, URI, Headers}
        | {upgrade, Protocols, Headers}
        | {ws, Frame}
        | {error, Reason}

Reason :: {stream_error | connection_error | down, any()}
        | timeout
----

Because the messages and returned tuples are equivalent,
please refer to the manual pages for each message for
further information:

* link:man:gun_inform(3)[gun_inform(3)] - Informational response
* link:man:gun_response(3)[gun_response(3)] - Response
* link:man:gun_data(3)[gun_data(3)] - Response body
* link:man:gun_trailers(3)[gun_trailers(3)] - Response trailers
* link:man:gun_push(3)[gun_push(3)] - Server-initiated push
* link:man:gun_upgrade(3)[gun_upgrade(3)] - Successful protocol upgrade
* link:man:gun_ws(3)[gun_ws(3)] - Websocket frame

== Changelog

* *2.0*: `upgrade` and `ws` tuples can now be returned.
* *2.0*: The error tuple type now includes the type of error.
* *1.0*: Function introduced.

== Examples

.Wait for a response
[source,erlang]
----
StreamRef = gun:get(ConnPid, "/articles", [
    {<<"accept">>, <<"text/html;q=1.0, application/xml;q=0.1">>}
]).
{response, nofin, 200, _Headers} = gun:await(ConnPid, StreamRef).
{data, fin, <<"Hello world!">>} = gun:await(ConnPid, StreamRef).
----

== See also

link:man:gun(3)[gun(3)],
link:man:gun:get(3)[gun:get(3)],
link:man:gun:head(3)[gun:head(3)],
link:man:gun:options(3)[gun:options(3)],
link:man:gun:patch(3)[gun:patch(3)],
link:man:gun:post(3)[gun:post(3)],
link:man:gun:put(3)[gun:put(3)],
link:man:gun:delete(3)[gun:delete(3)],
link:man:gun:headers(3)[gun:headers(3)],
link:man:gun:request(3)[gun:request(3)],
link:man:gun:await_body(3)[gun:await_body(3)]