gun:await(3)

Name

gun:await - Wait for a response

Description

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.

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:

• gun_inform(3) - Informational response
• gun_response(3) - Response
• gun_data(3) - Response body
• gun_trailers(3) - Response trailers
• gun_push(3) - Server-initiated push
• gun_upgrade(3) - Successful protocol upgrade
• 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

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

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